Skip to content

[DOCS] Reformat rollup API docs #49397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 20, 2019
Merged

[DOCS] Reformat rollup API docs #49397

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/reference/rollup/apis/get-job.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ experimental[]
[[rollup-get-job-prereqs]]
==== {api-prereq-title}

* You must have `monitor`, `monitor_rollup`, `manage` or `manage_rollup` cluster
privileges to use this API. For more information, see
<<security-privileges>>.
* If the {es} {security-features} are enabled, you must have `monitor`,
`monitor_rollup`, `manage` or `manage_rollup` cluster privileges to use this API.
For more information, see <<security-privileges>>.

[[rollup-get-job-desc]]
==== {api-description-title}
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/rollup/apis/put-job.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Jobs are created in a `STOPPED` state. You can start them with the
[[rollup-put-job-api-path-params]]
==== {api-path-parms-title}

`job_id`::
`<job_id>`::
(Required, string) Identifier for the {rollup-job}.

[[rollup-put-job-api-request-body]]
Expand Down
94 changes: 52 additions & 42 deletions docs/reference/rollup/apis/rollup-caps.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,32 @@
[role="xpack"]
[testenv="basic"]
[[rollup-get-rollup-caps]]
=== Get rollup job capabilities API
=== Get {rollup-job} capabilities API
++++
<titleabbrev>Get rollup caps</titleabbrev>
++++

Returns the capabilities of any {rollup-jobs} that have been configured for a
specific index or index pattern.

experimental[]

This API returns the capabilities of any rollup jobs that have been configured
for a specific index or index pattern.
[[rollup-get-rollup-caps-request]]
==== {api-request-title}

`GET _rollup/data/<index>`

[[rollup-get-rollup-caps-prereqs]]
==== {api-prereq-title}

This API is useful because a rollup job is often configured to rollup only a
* If the {es} {security-features} are enabled, you must have `monitor`,
`monitor_rollup`, `manage` or `manage_rollup` cluster privileges to use this API.
For more information, see <<security-privileges>>.

[[rollup-get-rollup-caps-desc]]
==== {api-description-title}

This API is useful because a {rollup-job} is often configured to rollup only a
subset of fields from the source index. Furthermore, only certain aggregations
can be configured for various fields, leading to a limited subset of
functionality depending on that configuration.
Expand All @@ -22,33 +37,20 @@ This API enables you to inspect an index and determine:
2. If yes to the first question, what fields were rolled up, what aggregations
can be performed, and where does the data live?

==== Request

`GET _rollup/data/{index}`

//===== Description

==== Path Parameters

`index`::
(string) Index, indices or index-pattern to return rollup capabilities for. `_all` may be used to fetch
rollup capabilities from all jobs


==== Request Body

There is no request body for the Get Rollup Caps API.
[[rollup-get-rollup-path-params]]
==== {api-path-parms-title}

==== Authorization
`<index>`::
(string) Index, indices or index-pattern to return rollup capabilities for.
`_all` may be used to fetch rollup capabilities from all jobs.

You must have `monitor`, `monitor_rollup`, `manage` or `manage_rollup` cluster privileges to use this API.
For more information, see
<<security-privileges>>.

==== Examples
[[rollup-get-rollup-example]]
==== {api-examples-title}

Imagine we have an index named `sensor-1` full of raw data. We know that the data will grow over time, so there
will be a `sensor-2`, `sensor-3`, etc. Let's create a Rollup job that targets the index pattern `sensor-*` to accommodate
Imagine we have an index named `sensor-1` full of raw data. We know that the
data will grow over time, so there will be a `sensor-2`, `sensor-3`, etc. Let's
create a {rollup-job} that targets the index pattern `sensor-*` to accommodate
this future scaling:

[source,console]
Expand Down Expand Up @@ -83,7 +85,8 @@ PUT _rollup/job/sensor
--------------------------------------------------
// TEST[setup:sensor_index]

We can then retrieve the rollup capabilities of that index pattern (`sensor-*`) via the following command:
We can then retrieve the rollup capabilities of that index pattern (`sensor-*`)
via the following command:

[source,console]
--------------------------------------------------
Expand Down Expand Up @@ -139,17 +142,21 @@ Which will yield the following response:
}
----

The response that is returned contains information that is similar to the original Rollup configuration, but formatted
differently. First, there are some house-keeping details: the Rollup job's ID, the index that holds the rolled data,
the index pattern that the job was targeting.
The response that is returned contains information that is similar to the
original rollup configuration, but formatted differently. First, there are some
house-keeping details: the {rollup-job} ID, the index that holds the rolled data,
and the index pattern that the job was targeting.

Next it shows a list of fields that contain data eligible for rollup searches. Here we see four fields: `node`, `temperature`,
`timestamp` and `voltage`. Each of these fields list the aggregations that are possible. For example, you can use a min, max
or sum aggregation on the `temperature` field, but only a `date_histogram` on `timestamp`.
Next it shows a list of fields that contain data eligible for rollup searches.
Here we see four fields: `node`, `temperature`, `timestamp` and `voltage`. Each
of these fields list the aggregations that are possible. For example, you can
use a min, max or sum aggregation on the `temperature` field, but only a
`date_histogram` on `timestamp`.

Note that the `rollup_jobs` element is an array; there can be multiple, independent jobs configured for a single index
or index pattern. Each of these jobs may have different configurations, so the API returns a list of all the various
configurations available.
Note that the `rollup_jobs` element is an array; there can be multiple,
independent jobs configured for a single index or index pattern. Each of these
jobs may have different configurations, so the API returns a list of all the
various configurations available.

We could also retrieve the same information with a request to `_all`:

Expand All @@ -159,7 +166,8 @@ GET _rollup/data/_all
--------------------------------------------------
// TEST[continued]

But note that if we use the concrete index name (`sensor-1`), we'll retrieve no rollup capabilities:
But note that if we use the concrete index name (`sensor-1`), we'll retrieve no
rollup capabilities:

[source,console]
--------------------------------------------------
Expand All @@ -174,7 +182,9 @@ GET _rollup/data/sensor-1
}
----

Why is this? The original rollup job was configured against a specific index pattern (`sensor-*`) not a concrete index
(`sensor-1`). So while the index belongs to the pattern, the rollup job is only valid across the entirety of the pattern
not just one of it's containing indices. So for that reason, the Rollup Capabilities API only returns information based
on the originally configured index name or pattern.
Why is this? The original {rollup-job} was configured against a specific index
pattern (`sensor-*`) not a concrete index (`sensor-1`). So while the index
belongs to the pattern, the {rollup-job} is only valid across the entirety of
the pattern not just one of it's containing indices. So for that reason, the
get rollup capabilities API only returns information based on the originally
configured index name or pattern.
83 changes: 47 additions & 36 deletions docs/reference/rollup/apis/rollup-index-caps.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,41 +6,48 @@
<titleabbrev>Get rollup index caps</titleabbrev>
++++

experimental[]

This API returns the rollup capabilities of all jobs inside of a rollup index (e.g. the index where rollup data is stored).
A single rollup index may store the data for multiple rollup jobs, and may have a variety of capabilities depending on those jobs.
Returns the rollup capabilities of all jobs inside of a rollup index (e.g. the
index where rollup data is stored).

This API will allow you to determine:
experimental[]

1. What jobs are stored in an index (or indices specified via a pattern)?
2. What target indices were rolled up, what fields were used in those rollups and what aggregations can be performed on each job?
[[rollup-get-rollup-index-caps-request]]
==== {api-request-title}

==== Request
`GET <index>/_rollup/data`

`GET {index}/_rollup/data`
[[rollup-get-rollup-index-caps-prereqs]]
==== {api-prereq-title}

//===== Description
* If the {es} {security-features} are enabled, you must have the `read` index
privilege on the index that stores the rollup results. For more information, see
<<security-privileges>>.

==== Path Parameters
[[rollup-get-rollup-index-caps-desc]]
==== {api-description-title}

`index`::
(string) Index or index-pattern of concrete rollup indices to check for capabilities.
A single rollup index may store the data for multiple {rollup-jobs}, and may
have a variety of capabilities depending on those jobs.

==== Request Body
This API will allow you to determine:

There is no request body for the Get Jobs API.
1. What jobs are stored in an index (or indices specified via a pattern)?
2. What target indices were rolled up, what fields were used in those rollups
and what aggregations can be performed on each job?

==== Authorization
[[rollup-get-rollup-index-caps-path-params]]
==== {api-path-parms-title}

You must have the `read` index privilege on the index that stores the rollup results.
For more information, see
<<security-privileges>>.
`<index>`::
(Required, string) Index or index-pattern of concrete rollup indices to check
for capabilities.

==== Examples
[[rollup-get-rollup-index-caps-example]]
==== {api-examples-title}

Imagine we have an index named `sensor-1` full of raw data. We know that the data will grow over time, so there
will be a `sensor-2`, `sensor-3`, etc. Let's create a Rollup job, which stores it's data in `sensor_rollup`:
Imagine we have an index named `sensor-1` full of raw data. We know that the
data will grow over time, so there will be a `sensor-2`, `sensor-3`, etc.
Let's create a {rollup-job} that stores its data in `sensor_rollup`:

[source,console]
--------------------------------------------------
Expand Down Expand Up @@ -74,17 +81,17 @@ PUT _rollup/job/sensor
--------------------------------------------------
// TEST[setup:sensor_index]

If at a later date, we'd like to determine what jobs and capabilities were stored in the `sensor_rollup` index, we can use the Get Rollup
Index API:
If at a later date, we'd like to determine what jobs and capabilities were
stored in the `sensor_rollup` index, we can use the get rollup index API:

[source,console]
--------------------------------------------------
GET /sensor_rollup/_rollup/data
--------------------------------------------------
// TEST[continued]

Note how we are requesting the concrete rollup index name (`sensor_rollup`) as the first part of the URL.
This will yield the following response:
Note how we are requesting the concrete rollup index name (`sensor_rollup`) as
the first part of the URL. This will yield the following response:

[source,console-result]
----
Expand Down Expand Up @@ -133,20 +140,24 @@ This will yield the following response:
----


The response that is returned contains information that is similar to the original Rollup configuration, but formatted
differently. First, there are some house-keeping details: the Rollup job's ID, the index that holds the rolled data,
The response that is returned contains information that is similar to the
original rollup configuration, but formatted differently. First, there are some
house-keeping details: the {rollup-job} ID, the index that holds the rolled data,
the index pattern that the job was targeting.

Next it shows a list of fields that contain data eligible for rollup searches. Here we see four fields: `node`, `temperature`,
`timestamp` and `voltage`. Each of these fields list the aggregations that are possible. For example, you can use a min, max
or sum aggregation on the `temperature` field, but only a `date_histogram` on `timestamp`.

Note that the `rollup_jobs` element is an array; there can be multiple, independent jobs configured for a single index
or index pattern. Each of these jobs may have different configurations, so the API returns a list of all the various
configurations available.
Next it shows a list of fields that contain data eligible for rollup searches.
Here we see four fields: `node`, `temperature`, `timestamp` and `voltage`. Each
of these fields list the aggregations that are possible. For example, you can
use a min, max, or sum aggregation on the `temperature` field, but only a
`date_histogram` on `timestamp`.

Note that the `rollup_jobs` element is an array; there can be multiple,
independent jobs configured for a single index or index pattern. Each of these
jobs may have different configurations, so the API returns a list of all the
various configurations available.

Like other APIs that interact with indices, you can specify index patterns instead of explicit indices:
Like other APIs that interact with indices, you can specify index patterns
instead of explicit indices:

[source,console]
--------------------------------------------------
Expand Down
Loading