Skip to content

Commit 939c9ac

Browse files
jrodewigjrodewig
authored
[DOCS] Reformat get pipeline API (#47131) (#47164)
1 parent 95a1931 commit 939c9ac

File tree

3 files changed

+88
-42
lines changed

3 files changed

+88
-42
lines changed

‎docs/reference/ingest/apis/get-pipeline.asciidoc‎

Lines changed: 34 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,18 @@
11
[[get-pipeline-api]]
2-
=== Get Pipeline API
2+
=== Get pipeline API
3+
++++
4+
<titleabbrev>Get pipeline</titleabbrev>
5+
++++
36

4-
The get pipeline API returns pipelines based on ID. This API always returns a local reference of the pipeline.
7+
Returns information about one or more ingest pipelines.
8+
This API returns a local reference of the pipeline.
59

6-
//////////////////////////
7-
8-
[source,js]
10+
[source,console]
911
--------------------------------------------------
1012
PUT _ingest/pipeline/my-pipeline-id
1113
{
1214
"description" : "describe pipeline",
15+
"version" : 123,
1316
"processors" : [
1417
{
1518
"set" : {
@@ -20,24 +23,28 @@ PUT _ingest/pipeline/my-pipeline-id
2023
]
2124
}
2225
--------------------------------------------------
23-
// CONSOLE
2426

25-
//////////////////////////
27+
[[get-pipeline-api-api-example]]
28+
==== {api-examples-title}
29+
30+
31+
[[get-pipeline-api-specific-ex]]
32+
===== Get information for a specific ingest pipeline
2633

27-
[source,js]
34+
[source,console]
2835
--------------------------------------------------
2936
GET _ingest/pipeline/my-pipeline-id
3037
--------------------------------------------------
31-
// CONSOLE
3238
// TEST[continued]
3339

34-
Example response:
40+
The API returns the following response:
3541

36-
[source,js]
42+
[source,console-result]
3743
--------------------------------------------------
3844
{
3945
"my-pipeline-id" : {
4046
"description" : "describe pipeline",
47+
"version" : 123,
4148
"processors" : [
4249
{
4350
"set" : {
@@ -49,23 +56,17 @@ Example response:
4956
}
5057
}
5158
--------------------------------------------------
52-
// TESTRESPONSE
5359

54-
For each returned pipeline, the source and the version are returned.
55-
The version is useful for knowing which version of the pipeline the node has.
56-
You can specify multiple IDs to return more than one pipeline. Wildcards are also supported.
5760

58-
[float]
59-
[[versioning-pipelines]]
60-
==== Pipeline Versioning
61+
[[get-pipeline-api-version-ex]]
62+
===== Get the version of an ingest pipeline
6163

62-
Pipelines can optionally add a `version` number, which can be any integer value,
63-
in order to simplify pipeline management by external systems. The `version`
64-
field is completely optional and it is meant solely for external management of
65-
pipelines. To unset a `version`, simply replace the pipeline without specifying
66-
one.
64+
When you create or update an ingest pipeline,
65+
you can specify an optional `version` parameter.
66+
The version is useful for managing changes to pipeline
67+
and viewing the current pipeline for an ingest node.
6768

68-
[source,js]
69+
[source,console]
6970
--------------------------------------------------
7071
PUT _ingest/pipeline/my-pipeline-id
7172
{
@@ -81,46 +82,42 @@ PUT _ingest/pipeline/my-pipeline-id
8182
]
8283
}
8384
--------------------------------------------------
84-
// CONSOLE
8585

86-
To check for the `version`, you can
87-
<<common-options-response-filtering, filter responses>>
88-
using `filter_path` to limit the response to just the `version`:
86+
To check the pipeline version,
87+
use the `filter_path` query parameter
88+
to <<common-options-response-filtering, filter the response>>
89+
to only the version.
8990

90-
[source,js]
91+
[source,console]
9192
--------------------------------------------------
9293
GET /_ingest/pipeline/my-pipeline-id?filter_path=*.version
9394
--------------------------------------------------
94-
// CONSOLE
9595
// TEST[continued]
9696

97-
This should give a small response that makes it both easy and inexpensive to parse:
97+
The API returns the following response:
9898

99-
[source,js]
99+
[source,console-result]
100100
--------------------------------------------------
101101
{
102102
"my-pipeline-id" : {
103103
"version" : 123
104104
}
105105
}
106106
--------------------------------------------------
107-
// TESTRESPONSE
108107

109108
//////////////////////////
110109
111-
[source,js]
110+
[source,console]
112111
--------------------------------------------------
113112
DELETE /_ingest/pipeline/my-pipeline-id
114113
--------------------------------------------------
115-
// CONSOLE
116114
// TEST[continued]
117115
118-
[source,js]
116+
[source,console-result]
119117
--------------------------------------------------
120118
{
121119
"acknowledged": true
122120
}
123121
--------------------------------------------------
124-
// TESTRESPONSE
125122
126123
//////////////////////////

‎docs/reference/ingest/apis/put-pipeline.asciidoc‎

Lines changed: 48 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
The put pipeline API adds pipelines and updates existing pipelines in the cluster.
55

6-
[source,js]
6+
[source,console]
77
--------------------------------------------------
88
PUT _ingest/pipeline/my-pipeline-id
99
{
@@ -18,18 +18,61 @@ PUT _ingest/pipeline/my-pipeline-id
1818
]
1919
}
2020
--------------------------------------------------
21-
// CONSOLE
21+
22+
[float]
23+
[[versioning-pipelines]]
24+
==== Pipeline versioning
25+
26+
Pipelines can optionally add a `version` number, which can be any integer value,
27+
in order to simplify pipeline management by external systems. The `version`
28+
field is completely optional and it is meant solely for external management of
29+
pipelines.
30+
31+
[source,console]
32+
--------------------------------------------------
33+
PUT /_ingest/pipeline/my-pipeline-id
34+
{
35+
"description" : "describe pipeline",
36+
"version" : 123,
37+
"processors" : [
38+
{
39+
"set" : {
40+
"field": "foo",
41+
"value": "bar"
42+
}
43+
}
44+
]
45+
}
46+
--------------------------------------------------
47+
48+
To unset a `version`, simply replace the pipeline without specifying
49+
one.
50+
51+
[source,console]
52+
--------------------------------------------------
53+
PUT /_ingest/pipeline/my-pipeline-id
54+
{
55+
"description" : "describe pipeline",
56+
"processors" : [
57+
{
58+
"set" : {
59+
"field": "foo",
60+
"value": "bar"
61+
}
62+
}
63+
]
64+
}
65+
--------------------------------------------------
2266

2367
//////////////////////////
2468
25-
[source,js]
69+
[source,console]
2670
--------------------------------------------------
2771
DELETE /_ingest/pipeline/my-pipeline-id
2872
--------------------------------------------------
29-
// CONSOLE
3073
// TEST[continued]
3174
32-
[source,js]
75+
[source,console-result]
3376
--------------------------------------------------
3477
{
3578
"acknowledged": true

‎docs/reference/rest-api/common-parms.asciidoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -401,6 +401,12 @@ tag::pipeline[]
401401
(Optional, string) ID of the pipeline to use to preprocess incoming documents.
402402
end::pipeline[]
403403

404+
tag::path-pipeline[]
405+
`<pipeline>`::
406+
(Optional, string) Comma-separated list or wildcard expression of pipeline IDs
407+
used to limit the request.
408+
end::path-pipeline[]
409+
404410
tag::preference[]
405411
`preference`::
406412
(Optional, string) Specifies the node or shard the operation should be

0 commit comments

Comments
 (0)