Skip to content

Commit

Permalink
[DOCS] Reformat rollup APIs to use new API format (elastic#44131)
Browse files Browse the repository at this point in the history
  • Loading branch information
@lcawl
lcawl authored Jul 10, 2019
1 parent 61de092 commit ae97d4c
Show file tree
Hide file tree
Showing 6 changed files with 184 additions and 246 deletions.
12 changes: 6 additions & 6 deletions docs/reference/rollup/api-quickref.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,12 @@ Most rollup endpoints have the following base:
[[rollup-api-jobs]]
=== /job/

* {ref}/rollup-put-job.html[PUT /_rollup/job/<job_id+++>+++]: Create a job
* {ref}/rollup-get-job.html[GET /_rollup/job]: List jobs
* {ref}/rollup-get-job.html[GET /_rollup/job/<job_id+++>+++]: Get job details
* {ref}/rollup-start-job.html[POST /_rollup/job/<job_id>/_start]: Start a job
* {ref}/rollup-stop-job.html[POST /_rollup/job/<job_id>/_stop]: Stop a job
* {ref}/rollup-delete-job.html[DELETE /_rollup/job/<job_id+++>+++]: Delete a job
* {ref}/rollup-put-job.html[PUT /_rollup/job/<job_id+++>+++]: Create a {rollup-job}
* {ref}/rollup-get-job.html[GET /_rollup/job]: List {rollup-jobs}
* {ref}/rollup-get-job.html[GET /_rollup/job/<job_id+++>+++]: Get {rollup-job} details
* {ref}/rollup-start-job.html[POST /_rollup/job/<job_id>/_start]: Start a {rollup-job}
* {ref}/rollup-stop-job.html[POST /_rollup/job/<job_id>/_stop]: Stop a {rollup-job}
* {ref}/rollup-delete-job.html[DELETE /_rollup/job/<job_id+++>+++]: Delete a {rollup-job}

[float]
[[rollup-api-data]]
Expand Down
111 changes: 46 additions & 65 deletions docs/reference/rollup/apis/delete-job.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,48 @@
[role="xpack"]
[testenv="basic"]
[[rollup-delete-job]]
=== Delete job API
=== Delete {rollup-jobs} API
[subs="attributes"]
++++
<titleabbrev>Delete job</titleabbrev>
<titleabbrev>Delete {rollup-jobs}</titleabbrev>
++++

Deletes an existing {rollup-job}.

experimental[]

This API deletes an existing rollup job. A job must be *stopped* first before it can be deleted. Attempting to delete
a started job will result in an error. Similarly, attempting to delete a nonexistent job will throw an exception.
[[rollup-delete-job-request]]
==== {api-request-title}

`DELETE _rollup/job/<job_id>`

[[rollup-delete-job-prereqs]]
==== {api-prereq-title}

.Deleting the job does not delete rolled up data
**********************************
When a job is deleted, that only removes the process that is actively monitoring and rolling up data.
It does not delete any previously rolled up data. This is by design; a user may wish to roll up a static dataset. Because
the dataset is static, once it has been fully rolled up there is no need to keep the indexing Rollup job around (as there
will be no new data). So the job may be deleted, leaving behind the rolled up data for analysis.
* If the {es} {security-features} are enabled, you must have `manage` or
`manage_rollup` cluster privileges to use this API. For more information, see
{stack-ov}/security-privileges.html[Security privileges].

If you wish to also remove the rollup data, and the rollup index only contains the data for a single job, you can simply
delete the whole rollup index. If the rollup index stores data from several jobs, you must issue a Delete-By-Query that
targets the Rollup job's ID in the rollup index:
[[rollup-delete-job-desc]]
==== {api-description-title}

A job must be *stopped* first before it can be deleted. If you attempt to delete
a started job, an error occurs. Similarly, if you attempt to delete a
nonexistent job, an exception occurs.

[IMPORTANT]
===============================
When a job is deleted, that only removes the process that is actively monitoring
and rolling up data. It does not delete any previously rolled up data. This is
by design; a user may wish to roll up a static dataset. Because the dataset is
static, once it has been fully rolled up there is no need to keep the indexing
rollup job around (as there will be no new data). So the job can be deleted,
leaving behind the rolled up data for analysis.
If you wish to also remove the rollup data, and the rollup index only contains
the data for a single job, you can simply delete the whole rollup index. If the
rollup index stores data from several jobs, you must issue a delete-by-query
that targets the rollup job's ID in the rollup index.
[source,js]
--------------------------------------------------
Expand All @@ -35,32 +56,23 @@ POST my_rollup_index/_delete_by_query
}
--------------------------------------------------
// NOTCONSOLE
===============================

**********************************
==== Request

`DELETE _rollup/job/<job_id>`

//===== Description

==== Path Parameters

`job_id` (required)::
(string) Identifier for the job


==== Request Body

There is no request body for the Delete Job API.
[[rollup-delete-job-path-params]]
==== {api-path-parms-title}

==== Authorization
`<job_id>`::
(string) Required. Identifier for the job.

You must have `manage` or `manage_rollup` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
[[rollup-delete-job-response-codes]]
==== {api-response-codes-title}

`404` (Missing resources)::
This code indicates that there are no resources that match the request. It
occurs if you try to delete a job that doesn't exist.

==== Examples
[[rollup-delete-job-example]]
==== {api-example-title}

If we have a rollup job named `sensor`, it can be deleted with:

Expand All @@ -80,34 +92,3 @@ Which will return the response:
}
----
// TESTRESPONSE

If however we try to delete a job which doesn't exist:

[source,js]
--------------------------------------------------
DELETE _rollup/job/does_not_exist
--------------------------------------------------
// CONSOLE
// TEST[catch:missing]

A 404 `resource_not_found` exception will be thrown:

[source,js]
----
{
"error" : {
"root_cause" : [
{
"type" : "resource_not_found_exception",
"reason" : "the task with id [does_not_exist] doesn't exist",
"stack_trace": ...
}
],
"type" : "resource_not_found_exception",
"reason" : "the task with id [does_not_exist] doesn't exist",
"stack_trace": ...
},
"status": 404
}
----
// TESTRESPONSE[s/"stack_trace": .../"stack_trace": $body.$_path/]
75 changes: 44 additions & 31 deletions docs/reference/rollup/apis/put-job.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,61 +1,74 @@
[role="xpack"]
[testenv="basic"]
[[rollup-put-job]]
=== Create job API
=== Create {rollup-jobs} API
[subs="attributes"]
++++
<titleabbrev>Create job</titleabbrev>
<titleabbrev>Create {rollup-jobs}</titleabbrev>
++++

experimental[]
Creates a {rollup-job}.

This API enables you to create a rollup job. The job will be created in a `STOPPED` state, and must be
started with the <<rollup-start-job,Start Job API>>.
experimental[]

==== Request
[[sample-api-request]]
==== {api-request-title}

`PUT _rollup/job/<job_id>`

//===== Description
[[sample-api-prereqs]]
==== {api-prereq-title}

==== Path Parameters
* If the {es} {security-features} are enabled, you must have `manage` or
`manage_rollup` cluster privileges to use this API. For more information, see
{stack-ov}/security-privileges.html[Security privileges].

`job_id` (required)::
(string) Identifier for the job
[[sample-api-desc]]
==== {api-description-title}

Jobs are created in a `STOPPED` state. You can start them with the
<<rollup-start-job,start {rollup-jobs} API>>.

==== Request Body
[[sample-api-path-params]]
==== {api-path-parms-title}

`index_pattern` (required)::
(string) The index, or index pattern, that you wish to rollup. Supports wildcard-style patterns (`logstash-*`).
`job_id`::
(string) Required. Identifier for the {rollup-job}.

`rollup_index` (required)::
(string) The index that you wish to store rollup results into. Can be shared with other rollup jobs.
[[sample-api-request-body]]
==== {api-request-body-title}

`cron` (required)::
(string) A cron string which defines when the rollup job should be executed.
`cron`::
(string) Required. A cron string which defines when the {rollup-job} should be executed.

`page_size` (required)::
(int) The number of bucket results that should be processed on each iteration of the rollup indexer. A larger value
will tend to execute faster, but will require more memory during processing.
`groups`::
(object) Required. Defines the grouping fields that are defined for this
{rollup-job}. See <<rollup-job-config,{rollup-job} config>>.

`groups` (required)::
(object) Defines the grouping fields that are defined for this rollup job. See <<rollup-job-config,rollup job config>>.
`index_pattern`::
(string) Required. The index or index pattern to roll up. Supports
wildcard-style patterns (`logstash-*`).

`metrics`::
(object) Defines the metrics that should be collected for each grouping tuple. See <<rollup-job-config,rollup job config>>.
(object) Optional. Defines the metrics to collect for each grouping tuple. See
<<rollup-job-config,{rollup-job} config>>.

For more details about the job configuration, see <<rollup-job-config>>.
`page_size`::
(integer) Required. The number of bucket results that are processed on each
iteration of the rollup indexer. A larger value tends to execute faster, but
requires more memory during processing.

==== Authorization

You must have `manage` or `manage_rollup` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
`rollup_index`::
(string) Required. The index that contains the rollup results. The index can
be shared with other {rollup-jobs}.

For more details about the job configuration, see <<rollup-job-config>>.

==== Examples
[[sample-api-example]]
==== {api-example-title}

The following example creates a rollup job named "sensor", targeting the "sensor-*" index pattern:
The following example creates a {rollup-job} named "sensor", targeting the
"sensor-*" index pattern:

[source,js]
--------------------------------------------------
Expand Down
81 changes: 30 additions & 51 deletions docs/reference/rollup/apis/start-job.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,41 +1,51 @@
[role="xpack"]
[testenv="basic"]
[[rollup-start-job]]
=== Start rollup job API
=== Start {rollup-jobs} API
[subs="attributes"]
++++
<titleabbrev>Start job</titleabbrev>
<titleabbrev>Start {rollup-jobs}</titleabbrev>
++++

experimental[]
Starts an existing, stopped {rollup-job}.

This API starts an existing, stopped rollup job. If the job does not exist an exception will be thrown.
Starting an already started job has no action.
experimental[]

==== Request
[[rollup-start-job-request]]
==== {api-request-title}

`POST _rollup/job/<job_id>/_start`

//===== Description

==== Path Parameters
[[rollup-start-job-prereqs]]
==== {api-prereq-title}

`job_id` (required)::
(string) Identifier for the job
* You must have `manage` or `manage_rollup` cluster privileges to use this API.
For more information, see
{stack-ov}/security-privileges.html[Security privileges].

[[rollup-start-job-desc]]
==== {api-description-title}

==== Request Body
If you try to start a job that does not exist, an exception occurs. If you try
to start a job that is already started, nothing happens.

There is no request body for the Start Job API.
[[rollup-start-job-path-params]]
==== {api-path-parms-title}

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

[[rollup-start-job-response-codes]]
==== {api-response-codes-title}

You must have `manage` or `manage_rollup` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].
`404` (Missing resources)::
This code indicates that there are no resources that match the request. It
occurs if you try to start a job that doesn't exist.

==== Examples
[[rollup-start-job-examples]]
==== {api-examples-title}

If we have already created a rollup job named `sensor`, it can be started with:
If we have already created a {rollup-job} named `sensor`, it can be started with:

[source,js]
--------------------------------------------------
Expand All @@ -52,35 +62,4 @@ Which will return the response:
"started": true
}
----
// TESTRESPONSE

If however we try to start a job which doesn't exist:

[source,js]
--------------------------------------------------
POST _rollup/job/does_not_exist/_start
--------------------------------------------------
// CONSOLE
// TEST[catch:missing]

A 404 `resource_not_found` exception will be thrown:

[source,js]
----
{
"error" : {
"root_cause" : [
{
"type" : "resource_not_found_exception",
"reason" : "Task for Rollup Job [does_not_exist] not found",
"stack_trace": ...
}
],
"type" : "resource_not_found_exception",
"reason" : "Task for Rollup Job [does_not_exist] not found",
"stack_trace": ...
},
"status": 404
}
----
// TESTRESPONSE[s/"stack_trace": \.\.\./"stack_trace": $body.$_path/]
// TESTRESPONSE
Loading

0 comments on commit ae97d4c

Please sign in to comment.