diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 88a67f8f50c..2551f92947f 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -8,7 +8,8 @@ - [Query parameters](#query-parameters) - [Path parameters](#path-parameters) - [Endpoints](#endpoints) - + - [Example_Code](#example_code) + ## Introduction The `.md` documents in this repository are rendered into HTML pages using [Jekyll](https://jekyllrb.com/). These HTML pages are hosted on [opensearch.org](https://docs.opensearch.org/latest/). @@ -88,6 +89,65 @@ All spec insert components accept the following arguments: - `component` (String; required): The name of the component to render, such as `query_parameters`, `path_parameters`, or `endpoints`. - `omit_header` (Boolean; Default is `false`): If set to `true`, the markdown header of the component will not be rendered. +### Example_Code + +- `api` should not be placed for the `component: example_code` tag. `rest` is mapped to the correct API by regex mapping. +- `rest` (String; required): The HTTP request line (`HTTP method` + `endpoint path`) that is regex mapped to the `opensearch-openapi.yaml`. + +The following tags are included to help with additional needs: + +- `body` (String; optional): The request body for the API call, using YAML `|` to preserve newlines and indentation. +- `include_client_setup:` (Boolean; Default is `false`): If set to `true`, the client setup for the language will be rendered. +- `skip` (Boolean; Default is `false`): If set to `true`, the language conversions will not render/re-render. Use for manual conversions. + +To insert multi-language support for the `cat.allocation` API, use the following snippet: + +```markdown + + +``` + +To insert multi-language support for the `index` API with a request body, use the following snippet. The `|` is needed for multiline support for the body: + +```markdown + + +``` + +To insert multi-language support for the `index` API and include the client setup for each language, use the following snippet: + +```markdown + + +``` + +To insert multi-language support for the `index` API but need to manually set the multi-language example for the `index` API, use the following snippet: + +```markdown + + +``` + ### Endpoints To insert endpoints for the `search` API, use the following snippet: @@ -153,6 +213,59 @@ pretty: true --> ``` +### Inserting new tags + +`_script/insert_tags_block.py` + +This script scans markdown documentation files in `/_api-reference` for `## Example Request(s)` headings and automatically inserts a blank `spec-insert` block for the `example_code` component. It will be placed immediately beneath the first matching +header. It supports scanning individual files, multiple files or the whole `_api-reference` tree. + +Update entire _api-reference/ tree: +``` +python3 _script/insert_tags_block.py +``` + +Update a specific folder (recursively): +``` +python3 _script/insert_tags_block.py _api-reference/cat +``` + +Update only the top-level files in a folder (no recursion): +``` +python3 _script/insert_tags_block.py _api-reference/cat --no-recursive +``` + +Update a specific file: +``` +python3 _script/insert_tags_block.py _api-reference/cat/cat-allocation.md +``` + +Update multiple files/folders at once: +``` +python3 _script/insert_tags_block.py _api-reference/cat _api-reference/indices/create-index.md +``` + +`--dry-runs` will show you what files will be modified: + +Dry-run on the entire _api-reference/ tree: +``` +python3 _script/insert_tags_block.py --dry-run +``` + +Dry-run on a specific folder (recursively): +``` +python3 _script/insert_tags_block.py _api-reference/cat --dry-run +``` + +Dry-run on a specific file: +``` +python3 _script/insert_tags_block.py _api-reference/cat/cat-allocation.md --dry-run +``` + +Dry-run on multiple files/folders: +``` +python3 _script/insert_tags_block.py _api-reference/cat _api-reference/indices/create-index.md --dry-run +``` ### Request and response bodies (Beta) diff --git a/_api-reference/analyze-apis.md b/_api-reference/analyze-apis.md index afca2c5ab87..c2e4709d48d 100644 --- a/_api-reference/analyze-apis.md +++ b/_api-reference/analyze-apis.md @@ -79,14 +79,45 @@ Field | Data type | Description When you pass an array of strings to the `text` field, it is analyzed as a multi-value field. -````json -GET /_analyze + +{% capture step1_rest %} +GET /_analyze +{ + "analyzer": "standard", + "text": [ + "first array element", + "second array element" + ] +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + body = { + "analyzer": "standard", + "text": [ + "first array element", + "second array element" + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: @@ -145,14 +176,39 @@ If you omit the `index` path parameter, you can apply any of the built-in analyz The following request analyzes text using the `standard` built-in analyzer: -````json -GET /_analyze + +{% capture step1_rest %} +GET /_analyze +{ + "analyzer": "standard", + "text": "OpenSearch text analysis" +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + body = { + "analyzer": "standard", + "text": "OpenSearch text analysis" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: @@ -192,14 +248,40 @@ In this scenario, a custom analyzer `lowercase_ascii_folding` has been created a The following request applies the custom analyzer to the provided text: -````json -GET /books2/_analyze + +{% capture step1_rest %} +GET /books2/_analyze +{ + "analyzer": "lowercase_ascii_folding", + "text": "Le garçon m'a SUIVI." +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + index = "books2", + body = { + "analyzer": "lowercase_ascii_folding", + "text": "Le garçon m'a SUIVI." + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: @@ -244,15 +326,46 @@ You can build a custom transient analyzer from tokenizers, token filters, or cha The following request uses the `uppercase` character filter to convert the text to uppercase: -````json -GET /_analyze + +{% capture step1_rest %} +GET /_analyze +{ + "tokenizer": "keyword", + "filter": [ + "uppercase" + ], + "text": "OpenSearch filter" +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + body = { + "tokenizer": "keyword", + "filter": [ + "uppercase" + ], + "text": "OpenSearch filter" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: @@ -273,16 +386,53 @@ The previous request returns the following fields: The following request uses the `html_strip` filter to remove HTML characters from the text: -````json -GET /_analyze + +{% capture step1_rest %} +GET /_analyze +{ + "tokenizer": "keyword", + "filter": [ + "lowercase" + ], + "char_filter": [ + "html_strip" + ], + "text": "Leave right now!" +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + body = { + "tokenizer": "keyword", + "filter": [ + "lowercase" + ], + "char_filter": [ + "html_strip" + ], + "text": "Leave right now!" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: @@ -306,15 +456,60 @@ You can combine filters using an array. The following request combines a `lowercase` translation with a `stop` filter that removes the words in the `stopwords` array: -````json -GET /_analyze + +{% capture step1_rest %} +GET /_analyze +{ + "tokenizer": "whitespace", + "filter": [ + "lowercase", + { + "type": "stop", + "stopwords": [ + "to", + "in" + ] + } + ], + "text": "how to train your dog in five steps" +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + body = { + "tokenizer": "whitespace", + "filter": [ + "lowercase", + { + "type": "stop", + "stopwords": [ + "to", + "in" + ] + } + ], + "text": "how to train your dog in five steps" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: @@ -373,13 +568,37 @@ You can analyze text using an index's default analyzer, or you can specify a dif The following request analyzes the provided text using the default analyzer associated with the `books` index: -````json -GET /books/_analyze + +{% capture step1_rest %} +GET /books/_analyze +{ + "text": "OpenSearch analyze test" +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + index = "books", + body = { + "text": "OpenSearch analyze test" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: @@ -415,14 +634,40 @@ The previous request returns the following fields: The following request analyzes the provided text using the `keyword` analyzer, which returns the entire text value as a single token: -````json -GET /books/_analyze + +{% capture step1_rest %} +GET /books/_analyze +{ + "analyzer": "keyword", + "text": "OpenSearch analyze test" +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + index = "books", + body = { + "analyzer": "keyword", + "text": "OpenSearch analyze test" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: @@ -448,14 +693,40 @@ If the mapping does not exist, the API uses the standard analyzer, which convert The following request causes the analysis to be based on the mapping for `name`: -````json -GET /books2/_analyze + +{% capture step1_rest %} +GET /books2/_analyze +{ + "field": "name", + "text": "OpenSearch analyze test" +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + index = "books2", + body = { + "field": "name", + "text": "OpenSearch analyze test" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: @@ -495,14 +766,40 @@ In this example, the `books2` index includes a normalizer called `to_lower_fold_ The following request applies `to_lower_fold_ascii` to the text: -````json -GET /books2/_analyze + +{% capture step1_rest %} +GET /books2/_analyze +{ + "normalizer": "to_lower_fold_ascii", + "text": "C'est le garçon qui m'a suivi." +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + index = "books2", + body = { + "normalizer": "to_lower_fold_ascii", + "text": "C'est le garçon qui m'a suivi." + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: @@ -526,14 +823,43 @@ You can create a custom transient normalizer with token and character filters. The following request uses the `uppercase` character filter to convert the given text to all uppercase: -````json -GET /_analyze + +{% capture step1_rest %} +GET /_analyze +{ + "filter": [ + "uppercase" + ], + "text": "That is the boy who followed me." +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + body = { + "filter": [ + "uppercase" + ], + "text": "That is the boy who followed me." + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: @@ -557,17 +883,56 @@ You can obtain additional details for all tokens by setting the `explain` attrib The following request provides detailed token information for the `reverse` filter used with the `standard` tokenizer: -````json -GET /_analyze + +{% capture step1_rest %} +GET /_analyze +{ + "tokenizer": "standard", + "filter": [ + "reverse" + ], + "text": "OpenSearch analyze test", + "explain": true, + "attributes": [ + "keyword" + ] +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.analyze( + body = { + "tokenizer": "standard", + "filter": [ + "reverse" + ], + "text": "OpenSearch analyze test", + "explain": true, + "attributes": [ + "keyword" + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The previous request returns the following fields: diff --git a/_api-reference/cat/cat-aliases.md b/_api-reference/cat/cat-aliases.md index 0e758f2d673..6d31244aa02 100644 --- a/_api-reference/cat/cat-aliases.md +++ b/_api-reference/cat/cat-aliases.md @@ -54,24 +54,78 @@ The following table lists the available query parameters. All query parameters a ## Example requests -```json -GET _cat/aliases?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/aliases?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.aliases( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To limit the information to a specific alias, add the alias name after your query: -```json -GET _cat/aliases/?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/aliases/?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.aliases( + name = "", + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to get information for more than one alias, separate the alias names with commas: -```json -GET _cat/aliases/alias1,alias2,alias3 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/aliases/alias1,alias2,alias3 + +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.aliases( + name = "alias1,alias2,alias3" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-allocation.md b/_api-reference/cat/cat-allocation.md index 4935c688a3d..4dd1830fec7 100644 --- a/_api-reference/cat/cat-allocation.md +++ b/_api-reference/cat/cat-allocation.md @@ -53,24 +53,75 @@ The following table lists the available query parameters. All query parameters a ## Example requests -```json -GET _cat/allocation?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/allocation?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.allocation( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To limit the information to a specific node, add the node name after your query: -```json -GET _cat/allocation/ -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/allocation/ +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.allocation( + node_id = "" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to get information for more than one node, separate the node names with commas: -```json -GET _cat/allocation/node_name_1,node_name_2,node_name_3 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/allocation/node_name_1,node_name_2,node_name_3 +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.allocation( + node_id = "node_name_1,node_name_2,node_name_3" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-cluster_manager.md b/_api-reference/cat/cat-cluster_manager.md index 0a27ba1ccd5..cbebaefe02f 100644 --- a/_api-reference/cat/cat-cluster_manager.md +++ b/_api-reference/cat/cat-cluster_manager.md @@ -51,10 +51,27 @@ The following table lists the available query parameters. All query parameters a ## Example request -``` -GET _cat/cluster_manager?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/cluster_manager?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.cluster_manager( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-count.md b/_api-reference/cat/cat-count.md index 7c4231a9587..0d2cd07b19d 100644 --- a/_api-reference/cat/cat-count.md +++ b/_api-reference/cat/cat-count.md @@ -50,24 +50,76 @@ The following table lists the available query parameters. All query parameters a ## Example requests -```json -GET _cat/count?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/count?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.count( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To see the number of documents in a specific index or alias, add the index or alias name after your query: -```json -GET _cat/count/?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/count/?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.count( + index = "", + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to get information for more than one index or alias, separate the index or alias names with commas: -```json -GET _cat/count/index_or_alias_1,index_or_alias_2,index_or_alias_3 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/count/index_or_alias_1,index_or_alias_2,index_or_alias_3 +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.count( + index = "index_or_alias_1,index_or_alias_2,index_or_alias_3" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-field-data.md b/_api-reference/cat/cat-field-data.md index 62cf9712196..1eb5c379dc6 100644 --- a/_api-reference/cat/cat-field-data.md +++ b/_api-reference/cat/cat-field-data.md @@ -50,24 +50,76 @@ The following table lists the available query parameters. All query parameters a ## Example requests -```json -GET _cat/fielddata?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/fielddata?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.fielddata( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To limit the information to a specific field, add the field name after your query: -```json -GET _cat/fielddata/?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/fielddata/?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.fielddata( + fields = "", + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to get information for more than one field, separate the field names with commas: -```json -GET _cat/fielddata/field_name_1,field_name_2,field_name_3 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/fielddata/field_name_1,field_name_2,field_name_3 +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.fielddata( + fields = "field_name_1,field_name_2,field_name_3" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-health.md b/_api-reference/cat/cat-health.md index e0c913ef28f..7dba043ba9d 100644 --- a/_api-reference/cat/cat-health.md +++ b/_api-reference/cat/cat-health.md @@ -52,10 +52,27 @@ The following table lists the available query parameters. All query parameters a The following example request give cluster health information for the past 5 days: -```json -GET _cat/health?v&time=5d -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/health?v&time=5d +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.health( + params = { "v": "true", "time": "5d" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-indices.md b/_api-reference/cat/cat-indices.md index 562d81f2f48..5497a8736b9 100644 --- a/_api-reference/cat/cat-indices.md +++ b/_api-reference/cat/cat-indices.md @@ -57,24 +57,76 @@ The following table lists the available query parameters. All query parameters a ## Example requests -```json -GET _cat/indices?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/indices?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.indices( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To limit the information to a specific index, add the index name after your query. -```json -GET _cat/indices/?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/indices/?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.indices( + index = "", + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to get information for more than one index, separate the indexes with commas: -```json -GET _cat/indices/index1,index2,index3 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/indices/index1,index2,index3 +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.indices( + index = "index1,index2,index3" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-nodeattrs.md b/_api-reference/cat/cat-nodeattrs.md index 2d09bb0324b..25e404717f4 100644 --- a/_api-reference/cat/cat-nodeattrs.md +++ b/_api-reference/cat/cat-nodeattrs.md @@ -52,10 +52,29 @@ The following table lists the available query parameters. All query parameters a The following example request returns attributes about custom nodes: -```json -GET _cat/nodeattrs?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/nodeattrs?v + +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.nodeattrs( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-nodes.md b/_api-reference/cat/cat-nodes.md index ec39ab8c521..c30bdcc1561 100644 --- a/_api-reference/cat/cat-nodes.md +++ b/_api-reference/cat/cat-nodes.md @@ -56,10 +56,27 @@ The following table lists the available query parameters. All query parameters a The following example request lists node level information: -```json -GET _cat/nodes?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/nodes?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.nodes( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-pending-tasks.md b/_api-reference/cat/cat-pending-tasks.md index 26028f61610..424828796cd 100644 --- a/_api-reference/cat/cat-pending-tasks.md +++ b/_api-reference/cat/cat-pending-tasks.md @@ -53,10 +53,27 @@ The following table lists the available query parameters. All query parameters a The following example request lists the progress of all pending node tasks: -```json -GET _cat/pending_tasks?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/pending_tasks?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.pending_tasks( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-pit-segments.md b/_api-reference/cat/cat-pit-segments.md index e105983c4e6..37c2ed82029 100644 --- a/_api-reference/cat/cat-pit-segments.md +++ b/_api-reference/cat/cat-pit-segments.md @@ -62,10 +62,23 @@ Field | Data type | Description ## Example request: PIT segments for all PITs -```json + +{% capture step1_rest %} GET /_cat/pit_segments/_all -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + +response = client.cat.all_pit_segments() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If there are no segments (there is no data stored), the API does not return any information. @@ -73,17 +86,45 @@ If there are no segments (there is no data stored), the API does not return any To list segments for one or several PITs, specify their PIT IDs in the request body: -```json -GET /_cat/pit_segments - + +{% capture step1_rest %} +GET /_cat/pit_segments +{ + "pit_id": [ + "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA", + "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA" + ] +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.pit_segments( + body = { + "pit_id": [ + "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA", + "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA" + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-plugins.md b/_api-reference/cat/cat-plugins.md index 65d68fe2e32..174c3b52867 100644 --- a/_api-reference/cat/cat-plugins.md +++ b/_api-reference/cat/cat-plugins.md @@ -51,10 +51,27 @@ The following table lists the available query parameters. All query parameters a The following example request lists all installed plugins: -```json -GET _cat/plugins?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/plugins?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.plugins( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-recovery.md b/_api-reference/cat/cat-recovery.md index 40e90566db6..7ee366b8943 100644 --- a/_api-reference/cat/cat-recovery.md +++ b/_api-reference/cat/cat-recovery.md @@ -54,24 +54,76 @@ The following table lists the available query parameters. All query parameters a ## Example requests -```json -GET _cat/recovery?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/recovery?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.recovery( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To see only the recoveries of a specific index, add the index name after your query. -```json -GET _cat/recovery/?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/recovery/?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.recovery( + index = "", + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to get information for more than one index, separate the indexes with commas: -```json -GET _cat/recovery/index1,index2,index3 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/recovery/index1,index2,index3 +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.recovery( + index = "index1,index2,index3" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-repositories.md b/_api-reference/cat/cat-repositories.md index fe9c0895171..d8f3b36f311 100644 --- a/_api-reference/cat/cat-repositories.md +++ b/_api-reference/cat/cat-repositories.md @@ -51,10 +51,27 @@ The following table lists the available query parameters. All query parameters a The following example request lists all snapshot repositories in the cluster: -```json -GET _cat/repositories?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/repositories?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.repositories( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-segment-replication.md b/_api-reference/cat/cat-segment-replication.md index 459e323370b..e09536a1fce 100644 --- a/_api-reference/cat/cat-segment-replication.md +++ b/_api-reference/cat/cat-segment-replication.md @@ -97,6 +97,27 @@ Parameter | Data type | Description `s` | String | Specifies to sort the results. For example, `s=shardId:desc` sorts by shardId in descending order. ## Example requests + +{% capture step1_rest %} +GET /_cat/segment_replication?v&s=s:desc +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.segment_replication( + params = { "v": "true", "s": "s:desc" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The following examples illustrate various segment replication responses. @@ -104,10 +125,27 @@ The following examples illustrate various segment replication responses. The following query requests segment replication metrics with column headings for all indexes: -```json + +{% capture step1_rest %} GET /_cat/segment_replication?v=true -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.segment_replication( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains the metrics for the preceding request: @@ -120,10 +158,28 @@ shardId target_node target_host checkpoints_behind bytes_behind current_lag last The following query requests segment replication metrics with column headings for shards with the ID `0` from indexes `index1` and `index2`: -```json + +{% capture step1_rest %} GET /_cat/segment_replication/index1,index2?v=true&shards=0 -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.segment_replication( + index = "index1,index2", + params = { "v": "true", "shards": "0" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains the metrics for the preceding request. The column headings correspond to the metric names: @@ -137,10 +193,27 @@ shardId target_node target_host checkpoints_behind bytes_behind current_lag last The following query requests detailed segment replication metrics with column headings for all indexes: -```json + +{% capture step1_rest %} GET /_cat/segment_replication?v=true&detailed=true -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.segment_replication( + params = { "v": "true", "detailed": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains additional metrics about the files and stages of a segment replication event: @@ -154,10 +227,27 @@ shardId target_node target_host checkpoints_behind bytes_behind current_lag last The following query requests segment replication metrics with column headings for all indexes, sorted by shard ID in descending order: -```json + +{% capture step1_rest %} GET /_cat/segment_replication?v&s=shardId:desc -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.segment_replication( + params = { "v": "true", "s": "shardId:desc" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains the sorted results: @@ -171,10 +261,27 @@ shardId target_node target_host checkpoints_behind bytes_behind current_lag In a request, you can either use a metric's full name or one of its aliases. The following query is the same as the preceding query, but it uses the alias `s` instead of `shardID` for sorting: -```json + +{% capture step1_rest %} GET /_cat/segment_replication?v&s=s:desc -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.segment_replication( + params = { "v": "true", "s": "s:desc" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response metrics diff --git a/_api-reference/cat/cat-segments.md b/_api-reference/cat/cat-segments.md index a1aad5954fe..ca1833d203b 100644 --- a/_api-reference/cat/cat-segments.md +++ b/_api-reference/cat/cat-segments.md @@ -51,24 +51,76 @@ The following table lists the available query parameters. All query parameters a ## Example requests -```json -GET _cat/segments?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/segments?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.segments( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To see only the information about segments of a specific index, add the index name after your query. -```json -GET _cat/segments/?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/segments/?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.segments( + index = "", + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to get information for more than one index, separate the indexes with commas: -```json -GET _cat/segments/index1,index2,index3 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/segments/index1,index2,index3 +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.segments( + index = "index1,index2,index3" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-shards.md b/_api-reference/cat/cat-shards.md index b90d82df3da..f1e3667b5f6 100644 --- a/_api-reference/cat/cat-shards.md +++ b/_api-reference/cat/cat-shards.md @@ -55,24 +55,76 @@ The following table lists the available query parameters. All query parameters a The following example requests returns information about shards: -``` -GET _cat/shards?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/shards?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.shards( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To see only the information about shards of a specific index, add the index name after your query. -``` -GET _cat/shards/?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/shards/?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.shards( + index = "", + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to get information for more than one index, separate the indexes with commas: -``` -GET _cat/shards/index1,index2,index3 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/shards/index1,index2,index3 +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.shards( + index = "index1,index2,index3" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-snapshots.md b/_api-reference/cat/cat-snapshots.md index 47e1ff22f2f..646116cf30e 100644 --- a/_api-reference/cat/cat-snapshots.md +++ b/_api-reference/cat/cat-snapshots.md @@ -55,10 +55,27 @@ The following table lists the available query parameters. The following example request lists all snapshots: -``` -GET _cat/snapshots?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/snapshots?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.snapshots( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-tasks.md b/_api-reference/cat/cat-tasks.md index da267b71198..d3e154a3e80 100644 --- a/_api-reference/cat/cat-tasks.md +++ b/_api-reference/cat/cat-tasks.md @@ -54,10 +54,27 @@ The following table lists the available query parameters. All query parameters a The following example request lists all tasks in progress: -``` -GET _cat/tasks?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/tasks?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.tasks( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-templates.md b/_api-reference/cat/cat-templates.md index 90d18384c82..f65024fa694 100644 --- a/_api-reference/cat/cat-templates.md +++ b/_api-reference/cat/cat-templates.md @@ -53,17 +53,51 @@ The following table lists the available query parameters. All query parameters a The following example request returns information about all templates: -```json -GET _cat/templates?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/templates?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.templates( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to get information for a specific template or pattern: -```json -GET _cat/templates/ -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/templates/ +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.templates( + name = "" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/cat-thread-pool.md b/_api-reference/cat/cat-thread-pool.md index dec78c4b15b..fb96ea54301 100644 --- a/_api-reference/cat/cat-thread-pool.md +++ b/_api-reference/cat/cat-thread-pool.md @@ -54,24 +54,76 @@ The following table lists the available query parameters. All query parameters a The following example request gives information about thread pools on all nodes: -```json -GET _cat/thread_pool?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/thread_pool?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.thread_pool( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to get information for more than one thread pool, separate the thread pool names with commas: -```json -GET _cat/thread_pool/thread_pool_name_1,thread_pool_name_2,thread_pool_name_3 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/thread_pool/thread_pool_name_1,thread_pool_name_2,thread_pool_name_3 +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.thread_pool( + thread_pool_patterns = "thread_pool_name_1,thread_pool_name_2,thread_pool_name_3" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to limit the information to a specific thread pool, add the thread pool name after your query: -```json -GET _cat/thread_pool/?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/thread_pool/?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.thread_pool( + thread_pool_patterns = "", + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cat/index.md b/_api-reference/cat/index.md index 15a64a74e7e..b246ebb9ed4 100644 --- a/_api-reference/cat/index.md +++ b/_api-reference/cat/index.md @@ -20,10 +20,23 @@ Using the CAT API, you can answer questions like which node is the elected clust To see the available operations in the CAT API, use the following command: -``` -GET _cat -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat +{% endcapture %} + +{% capture step1_python %} + +response = client.cat.help() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response is an ASCII cat (`=^.^=`) and a list of operations: @@ -82,10 +95,27 @@ You can specify a query parameter to any CAT operation to obtain more specific r To query aliases and get verbose output that includes all column headings in the response, use the `v` query parameter. -```json -GET _cat/aliases?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/aliases?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.aliases( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response provides more details, such as names of each column in the response. @@ -111,10 +141,27 @@ GET _cat/?help For example, to see the available headers for the CAT aliases operation, send the following request: -```json -GET _cat/aliases?help -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/aliases?help +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.aliases( + params = { "help": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains the available headers: @@ -137,10 +184,27 @@ GET _cat/?h=,&v For example, to limit aliases to only the alias name and index, send the following request: -```json -GET _cat/aliases?h=alias,index -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/aliases?h=alias,index +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.aliases( + params = { "h": "alias,index" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains the requested information: @@ -161,10 +225,27 @@ GET _cat/?s=, For example, to sort aliases by alias and then index, send the following request: -```json -GET _cat/aliases?s=i,a -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/aliases?s=i,a +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.aliases( + params = { "s": "i,a" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains the requested information: @@ -185,10 +266,27 @@ GET _cat/?format=json For example, to retrieve aliases in JSON format, send the following request: -```json -GET _cat/aliases?format=json -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cat/aliases?format=json +{% endcapture %} + +{% capture step1_python %} + + +response = client.cat.aliases( + params = { "format": "json" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains data in JSON format: diff --git a/_api-reference/cluster-api/cluster-allocation.md b/_api-reference/cluster-api/cluster-allocation.md index af819fd24c7..4c945232cd8 100644 --- a/_api-reference/cluster-api/cluster-allocation.md +++ b/_api-reference/cluster-api/cluster-allocation.md @@ -47,15 +47,43 @@ shard | Integer | The shard ID that you want an explanation for. ## Example request -```json -GET _cluster/allocation/explain?include_yes_decisions=true + +{% capture step1_rest %} +GET /_cluster/allocation/explain?include_yes_decisions=true +{ + "index": "movies", + "shard": 0, + "primary": true +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.allocation_explain( + params = { "include_yes_decisions": "true" }, + body = { + "index": "movies", + "shard": 0, + "primary": true + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cluster-api/cluster-awareness.md b/_api-reference/cluster-api/cluster-awareness.md index d3583d96dd3..613afad87dd 100644 --- a/_api-reference/cluster-api/cluster-awareness.md +++ b/_api-reference/cluster-api/cluster-awareness.md @@ -28,15 +28,53 @@ cluster.routing.allocation.awareness.attributes: zone,rack Alternatively, you can use the Cluster Settings API to configure the awareness attributes: -```json -PUT /_cluster/settings + +{% capture step1_rest %} +PUT /_cluster/routing/awareness/zone/weights +{ + "weights": { + "zone_1": "1", + "zone_2": "1", + "zone_3": "0" + }, + "_version": -1 +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.put_weighted_routing( + attribute = "zone", + body = { + "weights": { + "zone_1": "1", + "zone_2": "1", + "zone_3": "0" + }, + "_version": -1 + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + For more information about OpenSearch settings, see [Configuring OpenSearch]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/). @@ -79,19 +117,53 @@ The following table lists the available request body fields for the `PUT` and `D The following example request creates a round-robin shard allocation for search traffic between two zones while excluding a third zone from receiving any traffic: -```json -PUT /_cluster/routing/awareness/zone/weights -{ + +{% capture step1_rest %} +PUT /_cluster/routing/awareness/zone/weights +{ + "weights": { + "zone_1": "1", + "zone_2": "1", + "zone_3": "0" + }, + "_version": -1 +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.put_weighted_routing( + attribute = "zone", + body = { + "weights": { + "zone_1": "1", + "zone_2": "1", + "zone_3": "0" + }, + "_version": -1 + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + After this request, the `_version` increments to `0`. @@ -101,18 +173,50 @@ To create a shard allocation for multiple awareness attributes, send a separate The `PUT` request fully replaces the existing weight configuration for the specified awareness attribute. Any values omitted in the request are removed from the configuration. For example, the following request updates the weights for zones 1 and 3 and removes zone 2: -```json -PUT /_cluster/routing/awareness/zone/weights -{ + +{% capture step1_rest %} +PUT /_cluster/routing/awareness/zone/weights +{ + "weights": { + "zone_1": "2", + "zone_3": "1" + }, + "_version": 0 +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.put_weighted_routing( + attribute = "zone", + body = { + "weights": { + "zone_1": "2", + "zone_3": "1" + }, + "_version": 0 + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + After this request, the `_version` increments to `1`. @@ -120,10 +224,27 @@ After this request, the `_version` increments to `1`. To view the current weight configuration and its version, send the following request. Use the returned version number in subsequent update or delete requests: -```json + +{% capture step1_rest %} GET /_cluster/routing/awareness/zone/weights -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.get_weighted_routing( + attribute = "zone" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cluster-api/cluster-decommission.md b/_api-reference/cluster-api/cluster-decommission.md index 2db098ed92e..a7c35d10727 100644 --- a/_api-reference/cluster-api/cluster-decommission.md +++ b/_api-reference/cluster-api/cluster-decommission.md @@ -42,26 +42,74 @@ You can use the following example requests to decommission and recommission a zo The following example request decommissions `zone-a`: -```json + +{% capture step1_rest %} PUT /_cluster/decommission/awareness// -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.put_decommission_awareness( + awareness_attribute_name = "", + awareness_attribute_value = "" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to recommission a decommissioned zone, you can use the `DELETE` method: -```json + +{% capture step1_rest %} DELETE /_cluster/decommission/awareness -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + +response = client.cluster.delete_decommission_awareness() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Getting zone decommission status The following example requests returns the decommission status of all zones. -```json + +{% capture step1_rest %} GET /_cluster/decommission/awareness/zone/_status -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.get_decommission_awareness( + awareness_attribute_name = "zone" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + #### Example responses diff --git a/_api-reference/cluster-api/cluster-health.md b/_api-reference/cluster-api/cluster-health.md index c2337cdcf3d..9bcb0d52643 100644 --- a/_api-reference/cluster-api/cluster-health.md +++ b/_api-reference/cluster-api/cluster-health.md @@ -59,19 +59,49 @@ The following examples show how to use the cluster health API. This request waits 50 seconds for the cluster to reach the yellow status or better: -``` -GET _cluster/health?wait_for_status=yellow&timeout=50s -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cluster/health?wait_for_status=yellow&timeout=50s +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.health( + params = { "wait_for_status": "yellow", "timeout": "50s" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If the cluster health becomes yellow or green before 50 seconds elapse, it returns a response immediately. Otherwise it returns a response as soon as it exceeds the timeout. The following example request retrieves cluster health for all indexes in the cluster: -```json -GET _cluster/health -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cluster/health +{% endcapture %} + +{% capture step1_python %} + +response = client.cluster.health() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response @@ -125,10 +155,27 @@ The following table lists all response fields. To check cluster health by awareness attribute (for example, zone or rack), specify `awareness_attributes` in the `level` query parameter: -```json -GET _cluster/health?level=awareness_attributes -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cluster/health?level=awareness_attributes +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.health( + params = { "level": "awareness_attributes" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains cluster health metrics partitioned by awareness attribute: @@ -210,10 +257,27 @@ The response contains cluster health metrics partitioned by awareness attribute: If you're interested in a particular awareness attribute, you can include the name of the awareness attribute as a query parameter: -```json -GET _cluster/health?level=awareness_attributes&awareness_attribute=zone -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cluster/health?level=awareness_attributes&awareness_attribute=zone +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.health( + params = { "level": "awareness_attributes", "awareness_attribute": "zone" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + In response to the preceding request, OpenSearch returns cluster health information only for the `zone` awareness attribute. diff --git a/_api-reference/cluster-api/cluster-pending-tasks.md b/_api-reference/cluster-api/cluster-pending-tasks.md index 9d54348e74a..390e401ca49 100644 --- a/_api-reference/cluster-api/cluster-pending-tasks.md +++ b/_api-reference/cluster-api/cluster-pending-tasks.md @@ -31,11 +31,23 @@ The following table lists the available query parameters. All query parameters a The following request returns the list of currently pending cluster state update tasks: -```json + +{% capture step1_rest %} GET /_cluster/pending_tasks -``` +{% endcapture %} + +{% capture step1_python %} + +response = client.cluster.pending_tasks() +{% endcapture %} -{% include copy-curl.html %} +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example response diff --git a/_api-reference/cluster-api/cluster-reroute.md b/_api-reference/cluster-api/cluster-reroute.md index 8c49c945492..bcd15a8303e 100644 --- a/_api-reference/cluster-api/cluster-reroute.md +++ b/_api-reference/cluster-api/cluster-reroute.md @@ -133,7 +133,24 @@ PUT /test-cluster-index Run the following reroute command to move shard `0` of the index `test-cluster-index` from node `node1` to node `node2`: -```json + +{% capture step1_rest %} POST /_cluster/reroute { "commands": [ @@ -147,14 +164,55 @@ POST /_cluster/reroute } ] } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.reroute( + body = { + "commands": [ + { + "move": { + "index": "test-cluster-index", + "shard": 0, + "from_node": "node1", + "to_node": "node2" + } + } + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Simulating a reroute To simulate a reroute without executing it, set `dry_run=true`: -```json + +{% capture step1_rest %} POST /_cluster/reroute?dry_run=true { "commands": [ @@ -168,24 +226,83 @@ POST /_cluster/reroute?dry_run=true } ] } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.reroute( + params = { "dry_run": "true" }, + body = { + "commands": [ + { + "move": { + "index": "test-cluster-index", + "shard": 0, + "from_node": "node1", + "to_node": "node2" + } + } + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Retrying failed allocations If some shards failed to allocate because of previous issues, you can reattempt allocation: -```json + +{% capture step1_rest %} POST /_cluster/reroute?retry_failed=true -``` +{% endcapture %} -{% include copy-curl.html %} +{% capture step1_python %} + + +response = client.cluster.reroute( + params = { "retry_failed": "true" }, + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Explaining reroute decisions To understand why a reroute command is accepted or rejected, add `explain=true`: -```json + +{% capture step1_rest %} POST /_cluster/reroute?explain=true { "commands": [ @@ -194,13 +311,38 @@ POST /_cluster/reroute?explain=true "index": "test-cluster-index", "shard": 0, "from_node": "node1", - "to_node": "node3" + "to_node": "node2" } } ] } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.reroute( + params = { "explain": "true" }, + body = { + "commands": [ + { + "move": { + "index": "test-cluster-index", + "shard": 0, + "from_node": "node1", + "to_node": "node2" + } + } + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + This returns a `decisions` array explaining the outcome: diff --git a/_api-reference/cluster-api/cluster-settings.md b/_api-reference/cluster-api/cluster-settings.md index 14bfb3be048..37ede5baae6 100644 --- a/_api-reference/cluster-api/cluster-settings.md +++ b/_api-reference/cluster-api/cluster-settings.md @@ -50,25 +50,69 @@ The following example request show how to use the cluster settings API. The following example request checks for default cluster settings: -```json -GET _cluster/settings?include_defaults=true -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cluster/settings?include_defaults=true +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.get_settings( + params = { "include_defaults": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Update cluster setting The following example updates the `cluster.max_shards_per_node` setting. For a PUT operation, the request body must contain `transient` or `persistent`, along with the setting you want to update: -```json -PUT _cluster/settings + +{% capture step1_rest %} +PUT /_cluster/settings +{ + "persistent": { + "cluster.max_shards_per_node": 500 + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.put_settings( + body = { + "persistent": { + "cluster.max_shards_per_node": 500 + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + For more information about transient settings, persistent settings, and precedence, see [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/). diff --git a/_api-reference/cluster-api/cluster-state.md b/_api-reference/cluster-api/cluster-state.md index d2f2db46fe2..b72ce9ebda2 100644 --- a/_api-reference/cluster-api/cluster-state.md +++ b/_api-reference/cluster-api/cluster-state.md @@ -55,28 +55,76 @@ The following table lists the available query parameters. All query parameters a -## Example +## Example Requests Retrieve the full cluster state: -```json + +{% capture step1_rest %} GET /_cluster/state -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + +response = client.cluster.state() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Retrieve metadata and the routing table for a specific index: -```json + +{% capture step1_rest %} GET /_cluster/state/metadata,routing_table/my-index -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.state( + metric = "metadata,routing_table", + index = "my-index" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Retrieve only the currently elected cluster manager node: -```json + +{% capture step1_rest %} GET /_cluster/state/cluster_manager_node -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.state( + metric = "cluster_manager_node" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Response fields diff --git a/_api-reference/cluster-api/cluster-stats.md b/_api-reference/cluster-api/cluster-stats.md index 315d016bad1..ccc5f5d410a 100644 --- a/_api-reference/cluster-api/cluster-stats.md +++ b/_api-reference/cluster-api/cluster-stats.md @@ -79,19 +79,59 @@ The following index metrics are supported: For example, the following query requests statistics for `docs` and `search`: -```json -GET _cluster/stats/indices/docs,segments/nodes/_all -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cluster/stats/indices/docs,segments/nodes/_all + +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.stats( + index_metric = "docs,segments", + metric = "indices", + node_id = "_all" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example request The following example requests returns information about the cluster manager node: -```json -GET _cluster/stats/nodes/_cluster_manager -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cluster/stats/nodes/_cluster_manager + +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.stats( + node_id = "_cluster_manager" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/cluster-api/cluster-voting-configuration-exclusions.md b/_api-reference/cluster-api/cluster-voting-configuration-exclusions.md index 7a6079a3830..f502f3f846e 100644 --- a/_api-reference/cluster-api/cluster-voting-configuration-exclusions.md +++ b/_api-reference/cluster-api/cluster-voting-configuration-exclusions.md @@ -32,17 +32,55 @@ The following table lists the available query parameters. All query parameters a Exclude a node named `opensearch-node1` from the voting configuration: -```json + +{% capture step1_rest %} POST /_cluster/voting_config_exclusions?node_names=opensearch-node1 -``` -{% include copy-curl.html %} + +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.post_voting_config_exclusions( + params = { "node_names": "opensearch-node1" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Alternatively, you can specify the node IDs as a comma-separated list: -```json + +{% capture step1_rest %} POST /_cluster/voting_config_exclusions?node_ids=6ITS4DmNR7OJT1G5lyW8Lw,PEEW2S7-Su2XCA4zUE9_2Q -``` -{% include copy-curl.html %} + +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.post_voting_config_exclusions( + params = { "node_ids": "6ITS4DmNR7OJT1G5lyW8Lw,PEEW2S7-Su2XCA4zUE9_2Q" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Removing voting configuration exclusions @@ -66,8 +104,27 @@ The following table lists the available query parameters. All query parameters a Use the following request to remove all voting configuration exclusions without waiting for nodes to be removed: -```json + +{% capture step1_rest %} DELETE /_cluster/voting_config_exclusions?wait_for_removal=false -``` -{% include copy-curl.html %} + +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.delete_voting_config_exclusions( + params = { "wait_for_removal": "false" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + diff --git a/_api-reference/cluster-api/shard-stores.md b/_api-reference/cluster-api/shard-stores.md index 6cae8042258..0dc684d1e0c 100644 --- a/_api-reference/cluster-api/shard-stores.md +++ b/_api-reference/cluster-api/shard-stores.md @@ -33,7 +33,7 @@ The following table lists the available query parameters. All query parameters a | `ignore_unavailable` | Boolean | If `true`, missing or closed indexes are not included in the response. | `false` | | `status` | List or String | List of shard health statuses used to limit the request.
Valid values are:
- `all`: Return all shards, regardless of health status.
- `green`: The primary shard and all replica shards are assigned.
- `red`: The primary shard is unassigned.
- `yellow`: One or more replica shards are unassigned. | `yellow,red` | -## Example +## Example requests Create an index with multiple primary shards on a single-node cluster: @@ -56,21 +56,65 @@ PUT /logs-shardstore Index a document: -```json + +{% capture step1_rest %} POST /logs-shardstore/_doc { "timestamp": "2025-06-20T12:00:00Z", "message": "Log message 1" } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.index( + index = "logs-shardstore", + body = { + "timestamp": "2025-06-20T12:00:00Z", + "message": "Log message 1" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Get shard store status for the `logs-shardstore` index: -```json + +{% capture step1_rest %} GET /logs-shardstore/_shard_stores?status=all -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.shard_stores( + index = "logs-shardstore", + params = { "status": "all" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/document-apis/bulk.md b/_api-reference/document-apis/bulk.md index 243ff8c46c7..fa6301a2046 100644 --- a/_api-reference/document-apis/bulk.md +++ b/_api-reference/document-apis/bulk.md @@ -128,8 +128,10 @@ This operation creates a new document if one with ID `tt0816711` does not exist, ## Example request -```json -POST _bulk + +{% capture step1_rest %} +POST /_bulk +{ "delete": { "_index": "movies", "_id": "tt2229499" } } +{ "index": { "_index": "movies", "_id": "tt1979320" } } +{ "title": "Rush", "year": 2013 } +{ "create": { "_index": "movies", "_id": "tt1392214" } } +{ "title": "Prisoners", "year": 2013 } +{ "update": { "_index": "movies", "_id": "tt0816711" } } +{ "doc" : { "title": "World War Z" } } +{% endcapture %} -``` -{% include copy-curl.html %} +{% capture step1_python %} + + +response = client.bulk( + body = ''' +{ "delete": { "_index": "movies", "_id": "tt2229499" } } +{ "index": { "_index": "movies", "_id": "tt1979320" } } +{ "title": "Rush", "year": 2013 } +{ "create": { "_index": "movies", "_id": "tt1392214" } } +{ "title": "Prisoners", "year": 2013 } +{ "update": { "_index": "movies", "_id": "tt0816711" } } +{ "doc" : { "title": "World War Z" } } +''' +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/document-apis/delete-by-query.md b/_api-reference/document-apis/delete-by-query.md index 9d1a53f2ad9..f60cde0b85e 100644 --- a/_api-reference/document-apis/delete-by-query.md +++ b/_api-reference/document-apis/delete-by-query.md @@ -81,8 +81,10 @@ To search your index for specific documents, you must include a [query]({{site.u ## Example request -```json -POST sample-index1/_delete_by_query + +{% capture step1_rest %} +POST /sample-index1/_delete_by_query +{ + "query": { + "match": { + "movie-length": "124" + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.delete_by_query( + index = "sample-index1", + body = { + "query": { + "match": { + "movie-length": "124" + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/document-apis/delete-document.md b/_api-reference/document-apis/delete-document.md index 5b0a2a2dc67..2d0d0b32807 100644 --- a/_api-reference/document-apis/delete-document.md +++ b/_api-reference/document-apis/delete-document.md @@ -41,10 +41,28 @@ wait_for_active_shards | String | The number of active shards that must be avail ## Example request -```json + +{% capture step1_rest %} DELETE /sample-index1/_doc/1 -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.delete( + id = "1", + index = "sample-index1" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/document-apis/get-documents.md b/_api-reference/document-apis/get-documents.md index 2a53cbb7d98..6770f4a2f22 100644 --- a/_api-reference/document-apis/get-documents.md +++ b/_api-reference/document-apis/get-documents.md @@ -126,10 +126,28 @@ Internally, when a document is updated in OpenSearch, the original version is ma The following example request retrieves information about a document named `1`: -```json -GET sample-index1/_doc/1 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /sample-index1/_doc/1 +{% endcapture %} + +{% capture step1_python %} + + +response = client.get( + id = "1", + index = "sample-index1" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index 53c446c57a4..d516e7db3c3 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -66,35 +66,91 @@ version_type | Enum | Assigns a specific type to the document. Valid options are wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the request. Default is 1 (only the primary shard). Set to `all` or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the operation to succeed. | No require_alias | Boolean | Specifies whether the target index must be an index alias. Default is `false`. | No -## Example requests +## Example requests The following example requests create a sample index document for an index named `sample_index`: ### Example PUT request -```json + +{% capture step1_rest %} PUT /sample_index/_doc/1 { "name": "Example", "price": 29.99, "description": "To be or not to be, that is the question" } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.index( + index = "sample_index", + id = "1", + body = { + "name": "Example", + "price": 29.99, + "description": "To be or not to be, that is the question" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example POST request -```json + +{% capture step1_rest %} POST /sample_index/_doc { "name": "Another Example", "price": 19.99, "description": "We are such stuff as dreams are made on" } +{% endcapture %} -``` -{% include copy-curl.html %} +{% capture step1_python %} + + +response = client.index( + index = "sample_index", + body = { + "name": "Another Example", + "price": 19.99, + "description": "We are such stuff as dreams are made on" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/document-apis/mtermvectors.md b/_api-reference/document-apis/mtermvectors.md index 36cdfabe476..482d37ff060 100644 --- a/_api-reference/document-apis/mtermvectors.md +++ b/_api-reference/document-apis/mtermvectors.md @@ -94,7 +94,8 @@ The `filter` object in the request body allows you to filter the tokens to inclu | `min_word_length` | Integer | The minimum length of the term to be included. | | `max_word_length` | Integer | The maximum length of the term to be included. | -## Example +## Example requests + Create an index with term vectors enabled: @@ -115,30 +116,82 @@ PUT /my-index Index the first document: -```json + +{% capture step1_rest %} POST /my-index/_doc/1 { "text": "OpenSearch is a search engine." } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.index( + index = "my-index", + id = "1", + body = { + "text": "OpenSearch is a search engine." + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Index the second document: -```json + +{% capture step1_rest %} POST /my-index/_doc/2 { "text": "OpenSearch provides powerful features." } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.index( + index = "my-index", + id = "2", + body = { + "text": "OpenSearch provides powerful features." + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example request Get term vectors for multiple documents: -```json -POST /_mtermvectors + +{% capture step1_rest %} +POST /_mtermvectors +{ + "docs": [ + { + "_index": "my-index", + "_id": "1", + "fields": [ + "text" + ] + }, + { + "_index": "my-index", + "_id": "2", + "fields": [ + "text" + ] + } + ] +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.mtermvectors( + body = { + "docs": [ + { + "_index": "my-index", + "_id": "1", + "fields": [ + "text" + ] + }, + { + "_index": "my-index", + "_id": "2", + "fields": [ + "text" + ] + } + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Alternatively, you can specify both `ids` and `fields` as query parameters: -```json + +{% capture step1_rest %} GET /my-index/_mtermvectors?ids=1,2&fields=text -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.mtermvectors( + index = "my-index", + params = { "ids": "1,2", "fields": "text" }, + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + You can also provide document IDs in the `ids` array instead of specifying `docs`: -```json -GET /my-index/_mtermvectors?fields=text -{ + +{% capture step1_rest %} +GET /my-index/_mtermvectors?fields=text +{ + "ids": [ + "1", + "2" + ] +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.mtermvectors( + index = "my-index", + params = { "fields": "text" }, + body = { + "ids": [ + "1", + "2" + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/document-apis/multi-get.md b/_api-reference/document-apis/multi-get.md index 0497bd2c73a..13bb2877af0 100644 --- a/_api-reference/document-apis/multi-get.md +++ b/_api-reference/document-apis/multi-get.md @@ -65,8 +65,10 @@ ids | Array | IDs of the documents to retrieve. Only allowed when an index is sp The following example requests does specifies an index in the request body: -```json -GET _mget + +{% capture step1_rest %} +GET /_mget +{ + "docs": [ + { + "_index": "sample-index1", + "_id": "1" + }, + { + "_index": "sample-index2", + "_id": "1", + "_source": { + "include": [ + "Length" + ] + } + } + ] +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.mget( + body = { + "docs": [ + { + "_index": "sample-index1", + "_id": "1" + }, + { + "_index": "sample-index2", + "_id": "1", + "_source": { + "include": [ + "Length" + ] + } + } + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Specify an index the URL The following example specifies an index in the URL: -```json -GET sample-index1/_mget + +{% capture step1_rest %} +GET /sample-index1/_mget +{ + "docs": [ + { + "_id": "1", + "_source": false + }, + { + "_id": "2", + "_source": [ + "Director", + "Title" + ] + } + ] +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.mget( + index = "sample-index1", + body = { + "docs": [ + { + "_id": "1", + "_source": false + }, + { + "_id": "2", + "_source": [ + "Director", + "Title" + ] + } + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/document-apis/pull-based-ingestion-management.md b/_api-reference/document-apis/pull-based-ingestion-management.md index a590f35cfee..c2608eb0923 100644 --- a/_api-reference/document-apis/pull-based-ingestion-management.md +++ b/_api-reference/document-apis/pull-based-ingestion-management.md @@ -45,10 +45,27 @@ The following table lists the available query parameters. All query parameters a ### Example request -```json + +{% capture step1_rest %} POST /my-index/ingestion/_pause -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.ingestion.pause( + index = "my-index" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Resume ingestion @@ -94,14 +111,46 @@ The following table lists the available request body fields. To resume ingestion without specifying reset settings, send the following request: -```json + +{% capture step1_rest %} POST /my-index/ingestion/_resume -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.ingestion.resume( + index = "my-index", + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To provide reset settings when resuming ingestion, send the following request: -```json + +{% capture step1_rest %} POST /my-index/ingestion/_resume { "reset_settings": [ @@ -112,8 +161,30 @@ POST /my-index/ingestion/_resume } ] } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.ingestion.resume( + index = "my-index", + body = { + "reset_settings": [ + { + "shard": 0, + "mode": "offset", + "value": "1" + } + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Get ingestion state @@ -145,24 +216,77 @@ The following table lists the available query parameters. All query parameters a The following is a request with the default settings: -```json + +{% capture step1_rest %} GET /my-index/ingestion/_state -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.ingestion.get_state( + index = "my-index" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The following example shows a request with a page size of 20: -```json + +{% capture step1_rest %} GET /my-index/ingestion/_state?size=20 -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.ingestion.get_state( + index = "my-index", + params = { "size": "20" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The following example shows a request with a next page token: -```json + +{% capture step1_rest %} GET /my-index/ingestion/_state?size=20&next_token= -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.ingestion.get_state( + index = "my-index", + params = { "size": "20", "next_token": "" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example response diff --git a/_api-reference/document-apis/pull-based-ingestion.md b/_api-reference/document-apis/pull-based-ingestion.md index 3cf8d38a5c3..1bf60fe484d 100644 --- a/_api-reference/document-apis/pull-based-ingestion.md +++ b/_api-reference/document-apis/pull-based-ingestion.md @@ -109,13 +109,37 @@ You can use the [Update Settings API]({{site.url}}{{site.baseurl}}/api-reference The following example demonstrates how to update the error policy: -```json + +{% capture step1_rest %} PUT /my-index/_settings { "index.ingestion_source.error_strategy": "DROP" } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_settings( + index = "my-index", + body = { + "index.ingestion_source.error_strategy": "DROP" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Message format @@ -158,10 +182,29 @@ The following table lists the available `polling_ingest_stats` metrics. To retrieve shard-level pull-based ingestion metrics, use the [Nodes Stats API]({{site.url}}{{site.baseurl}}/api-reference/index-apis/update-settings/): -```json + +{% capture step1_rest %} GET /_nodes/stats/indices?level=shards&pretty -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.info( + metric = "indices", + node_id = "stats", + params = { "level": "shards", "pretty": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Limitations diff --git a/_api-reference/document-apis/reindex.md b/_api-reference/document-apis/reindex.md index ea0b783cac5..655b49a7976 100644 --- a/_api-reference/document-apis/reindex.md +++ b/_api-reference/document-apis/reindex.md @@ -69,8 +69,10 @@ lang | The scripting language. Valid options are `painless`, `expression`, `must ## Example request -```json -POST /_reindex + +{% capture step1_rest %} +POST /_reindex +{ + "source": { + "index": "my-source-index" + }, + "dest": { + "index": "my-destination-index" + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.reindex( + body = { + "source": { + "index": "my-source-index" + }, + "dest": { + "index": "my-destination-index" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response ```json diff --git a/_api-reference/document-apis/termvector.md b/_api-reference/document-apis/termvector.md index 73e12e57c81..031faaffb5f 100644 --- a/_api-reference/document-apis/termvector.md +++ b/_api-reference/document-apis/termvector.md @@ -87,7 +87,7 @@ The `filter` object in the request body allows you to filter the tokens to inclu | `min_word_length` | Integer | The minimum length of the term to be included. | | `max_word_length` | Integer | The maximum length of the term to be included. | -## Example +## Example Requests Create an index: @@ -108,33 +108,109 @@ PUT /my-index Index the document: -```json + +{% capture step1_rest %} POST /my-index/_doc/1 { "text": "OpenSearch is a search engine." } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.index( + index = "my-index", + id = "1", + body = { + "text": "OpenSearch is a search engine." + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example request Retrieve the term vectors: -```json -GET /my-index/_termvectors/1 + +{% capture step1_rest %} +GET /my-index/_termvectors/1 +{ + "fields": [ + "text" + ], + "term_statistics": true +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.termvectors( + index = "my-index", + id = "1", + body = { + "fields": [ + "text" + ], + "term_statistics": true + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Alternatively, you can provide `fields` and `term_statistics` as query parameters: -```json + +{% capture step1_rest %} GET /my-index/_termvectors/1?fields=text&term_statistics=true -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.termvectors( + index = "my-index", + id = "1", + params = { "fields": "text", "term_statistics": "true" }, + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example response diff --git a/_api-reference/document-apis/update-by-query.md b/_api-reference/document-apis/update-by-query.md index 1680def6fa7..26db2e58cad 100644 --- a/_api-reference/document-apis/update-by-query.md +++ b/_api-reference/document-apis/update-by-query.md @@ -92,8 +92,10 @@ To update your indexes and documents by query, you must include a [query]({{site ## Example requests -```json -POST test-index1/_update_by_query + +{% capture step1_rest %} +POST /test-index1/_update_by_query +{ + "query": { + "term": { + "oldValue": 10 + } + }, + "script": { + "source": "ctx._source.oldValue += params.newValue", + "lang": "painless", + "params": { + "newValue": 20 + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.update_by_query( + index = "test-index1", + body = { + "query": { + "term": { + "oldValue": 10 + } + }, + "script": { + "source": "ctx._source.oldValue += params.newValue", + "lang": "painless", + "params": { + "newValue": 20 + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response ```json diff --git a/_api-reference/document-apis/update-document.md b/_api-reference/document-apis/update-document.md index 00c5da2fbbb..4f1db98e9e5 100644 --- a/_api-reference/document-apis/update-document.md +++ b/_api-reference/document-apis/update-document.md @@ -80,31 +80,150 @@ You can also use a script to tell OpenSearch how to update your document: ``` ## Example requests + +{% capture step1_rest %} +POST /sample-index1/_update/2 +{ + "scripted_upsert": true, + "script": { + "source": "ctx._source.first_name = params.first_name; ctx._source.last_name = params.last_name; ctx._source.age = params.age;", + "params": { + "first_name": "Selina", + "last_name": "Kyle", + "age": 28 + } + }, + "upsert": {} +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.update( + id = "2", + index = "sample-index1", + body = { + "scripted_upsert": true, + "script": { + "source": "ctx._source.first_name = params.first_name; ctx._source.last_name = params.last_name; ctx._source.age = params.age;", + "params": { + "first_name": "Selina", + "last_name": "Kyle", + "age": 28 + } + }, + "upsert": {} + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Update a document -```json -POST /sample-index1/_update/1 + +{% capture step1_rest %} +POST /sample-index1/_update/1 +{ + "doc": { + "first_name": "Bruce", + "last_name": "Wayne" + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.update( + id = "1", + index = "sample-index1", + body = { + "doc": { + "first_name": "Bruce", + "last_name": "Wayne" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Update a document with a script -```json -POST /test-index1/_update/1 + +{% capture step1_rest %} +POST /test-index1/_update/1 +{ + "script": { + "source": "ctx._source.secret_identity = \"Batman\"" + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.update( + id = "1", + index = "test-index1", + body = { + "script": { + "source": "ctx._source.secret_identity = \"Batman\"" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Using the upsert operation @@ -113,7 +232,22 @@ Upsert is an operation that conditionally either updates an existing document or In the following example, the `upsert` operation updates the `first_name` and `last_name` fields if a document already exists. If a document does not exist, a new one is indexed using content in the `upsert` object. -```json + +{% capture step1_rest %} POST /sample-index1/_update/1 { "doc": { @@ -125,8 +259,32 @@ POST /sample-index1/_update/1 "age": "31" } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.update( + id = "1", + index = "sample-index1", + body = { + "doc": { + "first_name": "Martha", + "last_name": "Rivera" + }, + "upsert": { + "last_name": "Oliveira", + "age": "31" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Consider an index that contains the following document: @@ -175,7 +333,20 @@ If the document does not exist in the index, a new document is indexed with the You can also add `doc_as_upsert` to the request and set it to `true` to use the information in the `doc` field for performing the upsert operation: -```json + +{% capture step1_rest %} POST /sample-index1/_update/1 { "doc": { @@ -185,8 +356,30 @@ POST /sample-index1/_update/1 }, "doc_as_upsert": true } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.update( + id = "1", + index = "sample-index1", + body = { + "doc": { + "first_name": "Martha", + "last_name": "Oliveira", + "age": "31" + }, + "doc_as_upsert": true + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Consider an index that contains the following document: @@ -223,7 +416,24 @@ You can also use a script to control how the document is updated. By setting the In the following example, the script sets the document to contain specific fields regardless of whether it previously existed: -```json + +{% capture step1_rest %} POST /sample-index1/_update/2 { "scripted_upsert": true, @@ -237,8 +447,34 @@ POST /sample-index1/_update/2 }, "upsert": {} } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.update( + id = "2", + index = "sample-index1", + body = { + "scripted_upsert": true, + "script": { + "source": "ctx._source.first_name = params.first_name; ctx._source.last_name = params.last_name; ctx._source.age = params.age;", + "params": { + "first_name": "Selina", + "last_name": "Kyle", + "age": 28 + } + }, + "upsert": {} + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If the document with ID `2` does not already exist, this operation creates it using the script. If the document does exist, the script updates the specified fields. In both cases, the result is: diff --git a/_api-reference/index-apis/alias.md b/_api-reference/index-apis/alias.md index 268c1acbb7c..e7ce38cc6af 100644 --- a/_api-reference/index-apis/alias.md +++ b/_api-reference/index-apis/alias.md @@ -54,8 +54,10 @@ search_routing | String | Assigns a custom value to a shard only for search oper ## Example request -```json -POST _aliases + +{% capture step1_rest %} +POST /_aliases +{ + "actions": [ + { + "add": { + "index": "movies", + "alias": "movies-alias1" + } + }, + { + "remove": { + "index": "old-index", + "alias": "old-index-alias" + } + } + ] +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.update_aliases( + body = { + "actions": [ + { + "add": { + "index": "movies", + "alias": "movies-alias1" + } + }, + { + "remove": { + "index": "old-index", + "alias": "old-index-alias" + } + } + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/blocks.md b/_api-reference/index-apis/blocks.md index a830e71d8a6..9267e402fa9 100644 --- a/_api-reference/index-apis/blocks.md +++ b/_api-reference/index-apis/blocks.md @@ -38,13 +38,53 @@ The following table lists the available query parameters. All query parameters a `timeout` | Time | The amount of time to wait for the request to return. Default is `30s`. | ## Example request + +{% capture step1_rest %} +PUT /test-index/_block/write +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.add_block( + block = "write", + index = "test-index" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The following example request disables any `write` operations made to the test index: -```json + +{% capture step1_rest %} PUT /test-index/_block/write -``` -{% include copy.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.add_block( + block = "write", + index = "test-index" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/clear-index-cache.md b/_api-reference/index-apis/clear-index-cache.md index d511ff6bf36..07b5162a3c9 100644 --- a/_api-reference/index-apis/clear-index-cache.md +++ b/_api-reference/index-apis/clear-index-cache.md @@ -52,62 +52,183 @@ The following example requests show multiple clear cache API uses. The following request clears the fields cache only: -```json + +{% capture step1_rest %} POST /my-index/_cache/clear?fielddata=true -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.clear_cache( + index = "my-index", + params = { "fielddata": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} +
The following request clears the query cache only: -```json + +{% capture step1_rest %} POST /my-index/_cache/clear?query=true -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.clear_cache( + index = "my-index", + params = { "query": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} +
The following request clears the request cache only: -```json + +{% capture step1_rest %} POST /my-index/_cache/clear?request=true -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.clear_cache( + index = "my-index", + params = { "request": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Clear the cache for specific fields The following request clears the fields caches of `fielda` and `fieldb`: -```json + +{% capture step1_rest %} POST /my-index/_cache/clear?fields=fielda,fieldb -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.clear_cache( + index = "my-index", + params = { "fields": "fielda,fieldb" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Clear caches for specific data streams or indexes The following request clears the cache for two specific indexes: -```json + +{% capture step1_rest %} POST /my-index,my-index2/_cache/clear -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.clear_cache( + index = "my-index,my-index2" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + #### Clear caches for all data streams and indexes The following request clears the cache for all data streams and indexes: -```json + +{% capture step1_rest %} POST /_cache/clear -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + +response = client.indices.clear_cache() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + + ### Clear unused entries from the cache on search-capable nodes -```json -POST /*/_cache/clear?file=true -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +POST /*/_cache/clear?file=true +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.clear_cache( + index = "*", + params = { "file": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/clone.md b/_api-reference/index-apis/clone.md index 8dffbe1a4f5..a302c0a2629 100644 --- a/_api-reference/index-apis/clone.md +++ b/_api-reference/index-apis/clone.md @@ -55,7 +55,23 @@ The clone index API operation creates a new target index, so you can specify any ## Example request -```json + +{% capture step1_rest %} PUT /sample-index1/_clone/cloned-index1 { "settings": { @@ -68,8 +84,33 @@ PUT /sample-index1/_clone/cloned-index1 "sample-alias1": {} } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.clone( + index = "sample-index1", + target = "cloned-index1", + body = { + "settings": { + "index": { + "number_of_shards": 2, + "number_of_replicas": 1 + } + }, + "aliases": { + "sample-alias1": {} + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/close-index.md b/_api-reference/index-apis/close-index.md index 050cb0d62ff..a95c109fb41 100644 --- a/_api-reference/index-apis/close-index.md +++ b/_api-reference/index-apis/close-index.md @@ -41,10 +41,29 @@ timeout | Time | How long to wait for a response from the cluster. Default is `3 ## Example requests -```json + +{% capture step1_rest %} POST /sample-index/_close -``` -{% include copy-curl.html %} + +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.close( + index = "sample-index" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/component-template.md b/_api-reference/index-apis/component-template.md index 0e02834b5d2..5ec21ab39d4 100644 --- a/_api-reference/index-apis/component-template.md +++ b/_api-reference/index-apis/component-template.md @@ -89,8 +89,10 @@ The following example requests show how to use the Component Template API. The following example request creates a component template including index aliases: -```json -PUT _component_template/alias_template + +{% capture step1_rest %} +PUT /_component_template/alias_template +{ + "template": { + "settings": { + "number_of_shards": 1 + }, + "aliases": { + "alias1": {}, + "alias2": { + "filter": { + "term": { + "user.id": "hamlet" + } + }, + "routing": "shard-1" + }, + "{index}-alias": {} + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.put_component_template( + name = "alias_template", + body = { + "template": { + "settings": { + "number_of_shards": 1 + }, + "aliases": { + "alias1": {}, + "alias2": { + "filter": { + "term": { + "user.id": "hamlet" + } + }, + "routing": "shard-1" + }, + "{index}-alias": {} + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Adding component versioning The following example adds a `version` number to a component template which simplifies template management for external systems: -```json -PUT /_component_template/version_template + +{% capture step1_rest %} +PUT /_component_template/version_template +{ + "template": { + "settings": { + "number_of_shards": 1 + } + }, + "version": 3 +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.put_component_template( + name = "version_template", + body = { + "template": { + "settings": { + "number_of_shards": 1 + } + }, + "version": 3 + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Adding template metadata The following example request uses the `meta` parameter to add metadata to the index template. All metadata is stored in the cluster state. -```json -PUT /_component_template/meta_template + +{% capture step1_rest %} +PUT /_component_template/meta_template +{ + "template": { + "settings": { + "number_of_shards": 1 + } + }, + "_meta": { + "description": "Where art thou", + "serialization": { + "class": "MyIndexTemplate", + "id": 12 + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.put_component_template( + name = "meta_template", + body = { + "template": { + "settings": { + "number_of_shards": 1 + } + }, + "_meta": { + "description": "Where art thou", + "serialization": { + "class": "MyIndexTemplate", + "id": 12 + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + diff --git a/_api-reference/index-apis/create-index-template.md b/_api-reference/index-apis/create-index-template.md index 00d68de8ea7..61c97318d3c 100644 --- a/_api-reference/index-apis/create-index-template.md +++ b/_api-reference/index-apis/create-index-template.md @@ -82,8 +82,10 @@ The following examples show how to use the Create or Update Index Template API. The following example request includes index aliases in the template: -```json -PUT _index_template/alias-template + +{% capture step1_rest %} +PUT /_index_template/alias-template +{ + "index_patterns": [ + "sh*" + ], + "template": { + "settings": { + "number_of_shards": 1 + }, + "aliases": { + "alias1": {}, + "alias2": { + "filter": { + "term": { + "user.id": "hamlet" + } + }, + "routing": "shard-1" + }, + "{index}-alias": {} + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_index_template( + name = "alias-template", + body = { + "index_patterns": [ + "sh*" + ], + "template": { + "settings": { + "number_of_shards": 1 + }, + "aliases": { + "alias1": {}, + "alias2": { + "filter": { + "term": { + "user.id": "hamlet" + } + }, + "routing": "shard-1" + }, + "{index}-alias": {} + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Using multiple matching templates @@ -150,8 +212,10 @@ Overlapping index patterns given the same priority are not allowed. An error wil The following example request adds a `version` number to an index template, which simplifies template management for external systems: -```json -PUT /_index_template/template_one + +{% capture step1_rest %} +PUT /_index_template/template_one +{ + "index_patterns": [ + "mac", + "cheese" + ], + "priority": 0, + "template": { + "settings": { + "number_of_shards": 1 + } + }, + "version": 1 +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_index_template( + name = "template_one", + body = { + "index_patterns": [ + "mac", + "cheese" + ], + "priority": 0, + "template": { + "settings": { + "number_of_shards": 1 + } + }, + "version": 1 + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Adding template metadata The following example request uses the `meta` parameter to add metadata to the index template. All metadata is stored in the cluster state: -```json -PUT /_index_template/template_one + +{% capture step1_rest %} +PUT /_index_template/template_one +{ + "index_patterns": [ + "rom", + "juliet" + ], + "template": { + "settings": { + "number_of_shards": 2 + } + }, + "_meta": { + "description": "Where art thou", + "serialization": { + "class": "MyIndexTemplate", + "id": 12 + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_index_template( + name = "template_one", + body = { + "index_patterns": [ + "rom", + "juliet" + ], + "template": { + "settings": { + "number_of_shards": 2 + } + }, + "_meta": { + "description": "Where art thou", + "serialization": { + "class": "MyIndexTemplate", + "id": 12 + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Data stream definition Include a `data_stream` object to use an index template for data streams, as shown in the following example request: -```json -PUT /_index_template/template_1 + +{% capture step1_rest %} +PUT /_index_template/template_1 +{ + "index_patterns": [ + "logs-*" + ], + "data_stream": {} +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_index_template( + name = "template_1", + body = { + "index_patterns": [ + "logs-*" + ], + "data_stream": {} + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Using multiple component templates diff --git a/_api-reference/index-apis/create-index.md b/_api-reference/index-apis/create-index.md index 2e11c4b320f..81a01e46fe5 100644 --- a/_api-reference/index-apis/create-index.md +++ b/_api-reference/index-apis/create-index.md @@ -54,7 +54,30 @@ As part of your request, you can optionally specify [index settings]({{site.url} ## Example request -```json + +{% capture step1_rest %} PUT /sample-index1 { "settings": { @@ -74,5 +97,36 @@ PUT /sample-index1 "sample-alias1": {} } } -``` -{% include copy-curl.html %} \ No newline at end of file +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.create( + index = "sample-index1", + body = { + "settings": { + "index": { + "number_of_shards": 2, + "number_of_replicas": 1 + } + }, + "mappings": { + "properties": { + "age": { + "type": "integer" + } + } + }, + "aliases": { + "sample-alias1": {} + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + diff --git a/_api-reference/index-apis/dangling-index.md b/_api-reference/index-apis/dangling-index.md index fd7ad22aeff..a72eff71b3e 100644 --- a/_api-reference/index-apis/dangling-index.md +++ b/_api-reference/index-apis/dangling-index.md @@ -18,21 +18,18 @@ List dangling indexes: ```json GET /_dangling ``` -{% include copy-curl.html %} Import a dangling index: ```json POST /_dangling/ ``` -{% include copy-curl.html %} Delete a dangling index: ```json DELETE /_dangling/ ``` -{% include copy-curl.html %} ## Path parameters @@ -56,23 +53,74 @@ cluster_manager_timeout | Time units | The amount of time to wait for a connecti ### Sample list -````bash + +{% capture step1_rest %} GET /_dangling -```` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + +response = client.dangling_indices.list_dangling_indices() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Sample import -````bash + +{% capture step1_rest %} POST /_dangling/msdjernajxAT23RT-BupMB?accept_data_loss=true -```` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.dangling_indices.import_dangling_index( + index_uuid = "msdjernajxAT23RT-BupMB", + params = { "accept_data_loss": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + + ### Sample delete -````bash + +{% capture step1_rest %} DELETE /_dangling/msdjernajxAT23RT-BupMB?accept_data_loss=true -```` +{% endcapture %} + +{% capture step1_python %} + + +response = client.dangling_indices.delete_dangling_index( + index_uuid = "msdjernajxAT23RT-BupMB", + params = { "accept_data_loss": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/data-stream-stats.md b/_api-reference/index-apis/data-stream-stats.md index 0df0f0e1992..06ba7238563 100644 --- a/_api-reference/index-apis/data-stream-stats.md +++ b/_api-reference/index-apis/data-stream-stats.md @@ -35,44 +35,136 @@ The following table lists the available query parameters. All query parameters a | `pretty` | Boolean | Whether to pretty format the returned JSON response. | `false` | | `source` | String | The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests. | N/A | -## Example +## Example Requests Create an index template with a matching pattern and data stream enabled: -```json -PUT /_index_template/template-logs-app + +{% capture step1_rest %} +PUT /_index_template/template-logs-app +{ + "index_patterns": [ + "logs-app*" + ], + "data_stream": {} +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_index_template( + name = "template-logs-app", + body = { + "index_patterns": [ + "logs-app*" + ], + "data_stream": {} + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Create the data stream: -```json + +{% capture step1_rest %} PUT /_data_stream/logs-app -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.create_data_stream( + name = "logs-app", + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Index a document to generate backing indexes: -```json + +{% capture step1_rest %} POST /logs-app/_doc { "@timestamp": "2025-06-23T10:00:00Z", "message": "app started" } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.index( + index = "logs-app", + body = { + "@timestamp": "2025-06-23T10:00:00Z", + "message": "app started" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Retrieve data stream stats: -```json + +{% capture step1_rest %} GET /_data_stream/logs-app/_stats?human=true -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.data_streams_stats( + name = "logs-app", + params = { "human": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/delete-index.md b/_api-reference/index-apis/delete-index.md index db178e8c642..23796837c61 100644 --- a/_api-reference/index-apis/delete-index.md +++ b/_api-reference/index-apis/delete-index.md @@ -33,10 +33,27 @@ timeout | Time | How long to wait for the response to return. Default is `30s`. ## Example request -```json + +{% capture step1_rest %} DELETE /sample-index -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.delete( + index = "sample-index" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/delete-template-legacy.md b/_api-reference/index-apis/delete-template-legacy.md index 47fcff37b98..100722e581b 100644 --- a/_api-reference/index-apis/delete-template-legacy.md +++ b/_api-reference/index-apis/delete-template-legacy.md @@ -39,10 +39,27 @@ The following table lists the available query parameters. All parameters are opt ## Example request -```json + +{% capture step1_rest %} DELETE /_template/logging_template -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.delete_template( + name = "logging_template" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/exists.md b/_api-reference/index-apis/exists.md index 3f9fc01d089..1bd118c34cb 100644 --- a/_api-reference/index-apis/exists.md +++ b/_api-reference/index-apis/exists.md @@ -36,10 +36,27 @@ local | Boolean | Whether to return information from only the local node instead ## Example request -```json + +{% capture step1_rest %} HEAD /sample-index -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.exists( + index = "sample-index" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/flush.md b/_api-reference/index-apis/flush.md index e4c04fefa58..3f393c39a4b 100644 --- a/_api-reference/index-apis/flush.md +++ b/_api-reference/index-apis/flush.md @@ -51,20 +51,54 @@ All parameters are optional. The following example flushes an index named `shakespeare`: -```json + +{% capture step1_rest %} POST /shakespeare/_flush -``` -{% include copy-curl.html %} + +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.flush( + index = "shakespeare" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Flush all indexes The following example flushes all indexes in a cluster: -```json + +{% capture step1_rest %} POST /_flush -``` -{% include copy-curl.html %} + +{% endcapture %} + +{% capture step1_python %} + +response = client.indices.flush() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/force-merge.md b/_api-reference/index-apis/force-merge.md index 9953d0fe388..b84bbab19ec 100644 --- a/_api-reference/index-apis/force-merge.md +++ b/_api-reference/index-apis/force-merge.md @@ -76,6 +76,30 @@ The following table lists the available query parameters. All query parameters a | `primary_only` | Boolean | If set to `true`, then the merge operation is performed only on the primary shards of an index. This can be useful when you want to take a snapshot of the index after the merge is complete. Snapshots only copy segments from the primary shards. Merging the primary shards can reduce resource consumption. Default is `false`. | ## Example requests + +{% capture step1_rest %} +POST /.testindex-logs/_forcemerge?primary_only=true + +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.forcemerge( + index = ".testindex-logs", + params = { "primary_only": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The following examples show how to use the Force merge API. @@ -83,46 +107,133 @@ The following examples show how to use the Force merge API. The following example force merges a specific index: -```json + +{% capture step1_rest %} POST /testindex1/_forcemerge -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.forcemerge( + index = "testindex1" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Force merge multiple indexes The following example force merges multiple indexes: -```json + +{% capture step1_rest %} POST /testindex1,testindex2/_forcemerge -``` -{% include copy-curl.html %} + +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.forcemerge( + index = "testindex1,testindex2" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Force merge all indexes The following example force merges all indexes: -```json + +{% capture step1_rest %} POST /_forcemerge -``` -{% include copy-curl.html %} + +{% endcapture %} + +{% capture step1_python %} + +response = client.indices.forcemerge() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Force merge a data stream's backing indexes into one segment The following example force merges a data stream's backing indexes into one segment: -```json + +{% capture step1_rest %} POST /.testindex-logs/_forcemerge?max_num_segments=1 -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.forcemerge( + index = ".testindex-logs", + params = { "max_num_segments": "1" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Force merge primary shards The following example force merges an index's primary shards: -```json + +{% capture step1_rest %} POST /.testindex-logs/_forcemerge?primary_only=true -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.forcemerge( + index = ".testindex-logs", + params = { "primary_only": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/get-index-template.md b/_api-reference/index-apis/get-index-template.md index ab9b13d8639..d3a3daeeb1a 100644 --- a/_api-reference/index-apis/get-index-template.md +++ b/_api-reference/index-apis/get-index-template.md @@ -29,14 +29,44 @@ Parameter | Type | Description The following example request gets information about an index template by using a wildcard expression: -```json + +{% capture step1_rest %} GET /_index_template/h* -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.get_index_template( + name = "h*" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The following example request gets information about all index templates: -```json + +{% capture step1_rest %} GET /_index_template -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + +response = client.indices.get_index_template() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + diff --git a/_api-reference/index-apis/get-index.md b/_api-reference/index-apis/get-index.md index d35c2170503..d03650aeac0 100644 --- a/_api-reference/index-apis/get-index.md +++ b/_api-reference/index-apis/get-index.md @@ -44,10 +44,27 @@ cluster_manager_timeout | Time | How long to wait for a connection to the cluste ## Example request -```json + +{% capture step1_rest %} GET /sample-index -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.get( + index = "sample-index" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response ```json diff --git a/_api-reference/index-apis/get-settings.md b/_api-reference/index-apis/get-settings.md index c7529941841..33b22d0eef7 100644 --- a/_api-reference/index-apis/get-settings.md +++ b/_api-reference/index-apis/get-settings.md @@ -46,10 +46,27 @@ cluster_manager_timeout | Time | How long to wait for a connection to the cluste ## Example request -```json + +{% capture step1_rest %} GET /sample-index1/_settings -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.get_settings( + index = "sample-index1" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/get-template-legacy.md b/_api-reference/index-apis/get-template-legacy.md index 61760e6060a..dbe92d28064 100644 --- a/_api-reference/index-apis/get-template-legacy.md +++ b/_api-reference/index-apis/get-template-legacy.md @@ -39,10 +39,27 @@ The following table lists the available query parameters. All parameters are opt ## Example request -```json + +{% capture step1_rest %} GET /_template/sample-template -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.get_template( + name = "sample-template" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/index-template-exists.md b/_api-reference/index-apis/index-template-exists.md index 43632e01a0f..06d6c6027d9 100644 --- a/_api-reference/index-apis/index-template-exists.md +++ b/_api-reference/index-apis/index-template-exists.md @@ -34,10 +34,27 @@ All parameters are optional. ## Example request -```json + +{% capture step1_rest %} HEAD /_index_template/my-template -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.exists_index_template( + name = "my-template" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example responses diff --git a/_api-reference/index-apis/open-index.md b/_api-reference/index-apis/open-index.md index 7cc747c8cab..e190647f100 100644 --- a/_api-reference/index-apis/open-index.md +++ b/_api-reference/index-apis/open-index.md @@ -43,10 +43,27 @@ task_execution_timeout | Time | The explicit task execution timeout. Only useful ## Example request -```json + +{% capture step1_rest %} POST /sample-index/_open -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.open( + index = "sample-index" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/post-template-legacy.md b/_api-reference/index-apis/post-template-legacy.md index 788070c0cc0..0f96904360b 100644 --- a/_api-reference/index-apis/post-template-legacy.md +++ b/_api-reference/index-apis/post-template-legacy.md @@ -50,8 +50,10 @@ The request body must define one or more of the following components. ## Example request -```json -POST /_template/logs_template + +{% capture step1_rest %} +POST /_template/logs_template +{ + "index_patterns": [ + "logs-*" + ], + "settings": { + "number_of_shards": 1 + }, + "mappings": { + "properties": { + "@timestamp": { + "type": "date" + }, + "message": { + "type": "text" + } + } + }, + "aliases": { + "logs": {} + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_template( + name = "logs_template", + body = { + "index_patterns": [ + "logs-*" + ], + "settings": { + "number_of_shards": 1 + }, + "mappings": { + "properties": { + "@timestamp": { + "type": "date" + }, + "message": { + "type": "text" + } + } + }, + "aliases": { + "logs": {} + } + } +) + +{% endcapture %} -{% include copy-curl.html %} +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/put-mapping.md b/_api-reference/index-apis/put-mapping.md index 3ea23a67fe8..0fa26cdc0e8 100644 --- a/_api-reference/index-apis/put-mapping.md +++ b/_api-reference/index-apis/put-mapping.md @@ -92,9 +92,10 @@ You can make the document structure match the structure of the index mapping by The following request creates a new mapping for the `sample-index` index: -```json -PUT /sample-index/_mapping - + +{% capture step1_rest %} +PUT /sample-index/_mapping +{ + "properties": { + "age": { + "type": "integer" + }, + "occupation": { + "type": "text" + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_mapping( + index = "sample-index", + body = { + "properties": { + "age": { + "type": "integer" + }, + "occupation": { + "type": "text" + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/put-template-legacy.md b/_api-reference/index-apis/put-template-legacy.md index e0f9b378ea1..3445a497fa1 100644 --- a/_api-reference/index-apis/put-template-legacy.md +++ b/_api-reference/index-apis/put-template-legacy.md @@ -50,8 +50,10 @@ The request body must define one or more of the following components. ## Example request -```json -PUT /_template/logs_template + +{% capture step1_rest %} +PUT /_template/logs_template +{ + "index_patterns": [ + "logs-*" + ], + "settings": { + "number_of_shards": 1 + }, + "mappings": { + "properties": { + "@timestamp": { + "type": "date" + }, + "message": { + "type": "text" + } + } + }, + "aliases": { + "logs": {} + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_template( + name = "logs_template", + body = { + "index_patterns": [ + "logs-*" + ], + "settings": { + "number_of_shards": 1 + }, + "mappings": { + "properties": { + "@timestamp": { + "type": "date" + }, + "message": { + "type": "text" + } + } + }, + "aliases": { + "logs": {} + } + } +) + +{% endcapture %} -{% include copy-curl.html %} +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/recover.md b/_api-reference/index-apis/recover.md index ccba3975f57..b5902d66ca5 100644 --- a/_api-reference/index-apis/recover.md +++ b/_api-reference/index-apis/recover.md @@ -57,26 +57,78 @@ The following examples demonstrate how to recover information using the Recovery The following example request returns recovery information about several indexes in a [human-readable format]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#human-readable-output): -```json -GET index1,index2/_recovery?human -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /index1,index2/_recovery?human +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.recovery( + index = "index1,index2", + params = { "human": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The following example request returns recovery information about all indexes in a human-readable format: -```json + +{% capture step1_rest %} GET /_recovery?human -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.recovery( + params = { "human": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Recover detailed information The following example request returns detailed recovery information: -```json -GET _recovery?human&detailed=true -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_recovery?human&detailed=true +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.recovery( + params = { "human": "true", "detailed": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/refresh.md b/_api-reference/index-apis/refresh.md index 5e1c4f8ac43..3ed26d93eb0 100644 --- a/_api-reference/index-apis/refresh.md +++ b/_api-reference/index-apis/refresh.md @@ -60,10 +60,27 @@ The following table lists the available query parameters. All query parameters a The following example request refreshes two indexes named `my-index-A` and `my-index-B`: -```json + +{% capture step1_rest %} POST /my-index-A,my-index-B/_refresh -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.refresh( + index = "my-index-A,my-index-B" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Refresh all data streams and indexes in a cluster diff --git a/_api-reference/index-apis/resolve-index.md b/_api-reference/index-apis/resolve-index.md index 7850fc12aaf..4feb5705e5a 100644 --- a/_api-reference/index-apis/resolve-index.md +++ b/_api-reference/index-apis/resolve-index.md @@ -39,36 +39,105 @@ The following sections provide example Resolve API requests. ### Resolve a concrete index -```json -GET _resolve/index/my-index-001 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_resolve/index/my-index-001 +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.resolve_index( + name = "my-index-001" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Resolve indexes using a wildcard -```json -GET _resolve/index/my-index-* -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_resolve/index/my-index-* +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.resolve_index( + name = "my-index-*" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Resolve a data stream or alias If an alias or data stream named `logs-app` exists, use the following request to resolve it: -```json -GET _resolve/index/logs-app -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_resolve/index/logs-app +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.resolve_index( + name = "logs-app" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Resolve hidden indexes using a wildcard in a remote cluster The following example shows an API request using a wildcard, a remote cluster, and `expand_wildcards` configured to `hidden`: -```json -GET _resolve/index/my-index-*,remote-cluster:my-index-*?expand_wildcards=hidden -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_resolve/index/my-index-*,remote-cluster:my-index-*?expand_wildcards=hidden +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.resolve_index( + name = "my-index-*,remote-cluster:my-index-*", + params = { "expand_wildcards": "hidden" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/rollover.md b/_api-reference/index-apis/rollover.md index bbb594106dd..6198393739c 100644 --- a/_api-reference/index-apis/rollover.md +++ b/_api-reference/index-apis/rollover.md @@ -111,8 +111,10 @@ The following examples illustrate using the Rollover Index API. A rollover occur The following request rolls over the data stream if the current write index meets any of the specified conditions: -```json -POST my-data-stream/_rollover + +{% capture step1_rest %} +POST /my-alias/_rollover +{ + "conditions": { + "max_age": "5d", + "max_docs": 500, + "max_size": "100gb" + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.rollover( + alias = "my-alias", + body = { + "conditions": { + "max_age": "5d", + "max_docs": 500, + "max_size": "100gb" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Rolling over an index alias with a write index @@ -142,8 +174,10 @@ PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E The next request performs a rollover using the alias: -```json -POST my-alias/_rollover + +{% capture step1_rest %} +POST /my-data-stream/_rollover +{ + "conditions": { + "max_age": "5d", + "max_docs": 500, + "max_size": "100gb" + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.rollover( + alias = "my-data-stream", + body = { + "conditions": { + "max_age": "5d", + "max_docs": 500, + "max_size": "100gb" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Specifying settings during a rollover In most cases, you can use an index template to automatically configure the indexes created during a rollover operation. However, when rolling over an index alias, you can use the Rollover Index API to introduce additional index settings or override the settings defined in the template by sending the following request: -```json -POST my-alias/_rollover + +{% capture step1_rest %} +POST /my-alias/_rollover +{ + "settings": { + "index.number_of_shards": 4 + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.rollover( + alias = "my-alias", + body = { + "settings": { + "index.number_of_shards": 4 + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/segment.md b/_api-reference/index-apis/segment.md index 3cf593d0b17..775fc92426e 100644 --- a/_api-reference/index-apis/segment.md +++ b/_api-reference/index-apis/segment.md @@ -45,24 +45,71 @@ The following example requests show you how to use the Segment API. ### Specific data stream or index -```json + +{% capture step1_rest %} GET /index1/_segments -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.segments( + index = "index1" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Several data streams and indexes -```json + +{% capture step1_rest %} GET /index1,index2/_segments -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.segments( + index = "index1,index2" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### All data streams and indexes in a cluster -```json + +{% capture step1_rest %} GET /_segments -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + +response = client.indices.segments() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/shrink-index.md b/_api-reference/index-apis/shrink-index.md index 712fa56414e..0df6902f2d4 100644 --- a/_api-reference/index-apis/shrink-index.md +++ b/_api-reference/index-apis/shrink-index.md @@ -81,8 +81,10 @@ For index codec considerations, see [Index codecs]({{site.url}}{{site.baseurl}}/ ## Example request -```json -POST /my-old-index/_shrink/my-new-index + +{% capture step1_rest %} +POST /my-old-index/_shrink/my-new-index +{ + "settings": { + "index.number_of_replicas": 4, + "index.number_of_shards": 3 + }, + "aliases": { + "new-index-alias": {} + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.shrink( + index = "my-old-index", + target = "my-new-index", + body = { + "settings": { + "index.number_of_replicas": 4, + "index.number_of_shards": 3 + }, + "aliases": { + "new-index-alias": {} + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + diff --git a/_api-reference/index-apis/simulate-index-template.md b/_api-reference/index-apis/simulate-index-template.md index 3aa11a6f295..c4252abd7b9 100644 --- a/_api-reference/index-apis/simulate-index-template.md +++ b/_api-reference/index-apis/simulate-index-template.md @@ -45,37 +45,95 @@ The following table lists the available request body fields. Use the following request to simulate a template without creating it: -```json -POST /_index_template/_simulate + +{% capture step1_rest %} +POST /_index_template/_simulate_index/logs-sim-1 +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.simulate_index_template( + name = "logs-sim-1", + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + + +### Example request: Simulate a named template + +{% capture step1_rest %} +POST /_index_template/_simulate/template_for_simulation +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.simulate_template( + name = "template_for_simulation", + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + +You can simulate a specific template by specifying the name of the template. + +First, create a template named `template_for_simulation` using the following request: + + +{% capture step1_rest %} PUT /_index_template/template_for_simulation { - "index_patterns": ["logs-sim-*"], + "index_patterns": [ + "logs-sim-*" + ], "template": { "settings": { "number_of_shards": 1, @@ -102,25 +160,104 @@ PUT /_index_template/template_for_simulation "owner": "Docs Team" } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_index_template( + name = "template_for_simulation", + body = { + "index_patterns": [ + "logs-sim-*" + ], + "template": { + "settings": { + "number_of_shards": 1, + "number_of_replicas": 1 + }, + "mappings": { + "properties": { + "timestamp": { + "type": "date" + }, + "message": { + "type": "text" + }, + "level": { + "type": "keyword" + } + } + } + }, + "priority": 10, + "version": 1, + "_meta": { + "description": "Template used for simulation example", + "owner": "Docs Team" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + You can now simulate the template named `template_for_simulation`: -```json + +{% capture step1_rest %} POST /_index_template/_simulate/template_for_simulation -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.simulate_template( + name = "template_for_simulation", + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example request: Simulate a template on a specific index Simulating a template on a specific index name is particularly useful for resolving conflicts or debugging priority issues among templates. The following request demonstrates how all applicable templates, with overlapping index patterns, will be applied to an index named `logs-sim-1`: -```json + +{% capture step1_rest %} POST /_index_template/_simulate_index/logs-sim-1 -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.simulate_index_template( + name = "logs-sim-1", + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/split.md b/_api-reference/index-apis/split.md index 221f2967cac..2a322c98b23 100644 --- a/_api-reference/index-apis/split.md +++ b/_api-reference/index-apis/split.md @@ -16,9 +16,25 @@ The split index API operation splits an existing read-only index into a new inde To make the index read-only, set the [dynamic index-level index setting]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index-settings/#dynamic-index-level-index-settings) `index.blocks.write` to `true`. {: .note} -## Example +## Example Request -```json + +{% capture step1_rest %} PUT /sample-index1/_split/split-index1 { "settings": { @@ -31,8 +47,33 @@ PUT /sample-index1/_split/split-index1 "sample-alias1": {} } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.split( + index = "sample-index1", + target = "split-index1", + body = { + "settings": { + "index": { + "number_of_shards": 4, + "number_of_replicas": 2 + } + }, + "aliases": { + "sample-alias1": {} + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Endpoints diff --git a/_api-reference/index-apis/stats.md b/_api-reference/index-apis/stats.md index a5e6403edc8..bf5c88e39e3 100644 --- a/_api-reference/index-apis/stats.md +++ b/_api-reference/index-apis/stats.md @@ -79,55 +79,160 @@ The following example requests show how to use the Index Stats API. The following example returns index stats for a single index: -```json + +{% capture step1_rest %} GET /testindex/_stats -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.stats( + index = "testindex" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Comma-separated list of indexes The following example returns stats for multiple indexes: -```json + +{% capture step1_rest %} GET /testindex1,testindex2/_stats -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.stats( + index = "testindex1,testindex2" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Wildcard expression The following example returns starts about any index that starts with `testindex`: -```json + +{% capture step1_rest %} GET /testindex*/_stats -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.stats( + index = "testindex*" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Specific stats The following example returns index stats related to the index and flush operations: -```json + +{% capture step1_rest %} GET /testindex/_stats/refresh,flush -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.stats( + metric = "refresh,flush", + index = "testindex" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Expand wildcards The following example expands all wildcards related to index stats: -```json + +{% capture step1_rest %} GET /testindex*/_stats?expand_wildcards=open,hidden -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.stats( + index = "testindex*", + params = { "expand_wildcards": "open,hidden" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Shard-level statistics The following example returns shard level stats about a test index: -```json + +{% capture step1_rest %} GET /testindex/_stats?level=shards -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.stats( + index = "testindex", + params = { "level": "shards" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/template-exists-legacy.md b/_api-reference/index-apis/template-exists-legacy.md index d8b3d20ba75..72f0a51a3f2 100644 --- a/_api-reference/index-apis/template-exists-legacy.md +++ b/_api-reference/index-apis/template-exists-legacy.md @@ -38,10 +38,27 @@ The following table lists the available query parameters. All parameters are opt ## Example request -```json + +{% capture step1_rest %} HEAD /_template/logging_template -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.exists_template( + name = "logging_template" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/update-alias.md b/_api-reference/index-apis/update-alias.md index 86652c8bf21..73040831720 100644 --- a/_api-reference/index-apis/update-alias.md +++ b/_api-reference/index-apis/update-alias.md @@ -65,13 +65,38 @@ Field | Type | Description The following example request adds a sample alias with a custom routing value: -```json -POST sample-index/_alias/sample-alias + +{% capture step1_rest %} +POST /sample-index/_alias/sample-alias +{ + "routing": "test" +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_alias( + name = "sample-alias", + index = "sample-index", + body = { + "routing": "test" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/index-apis/update-settings.md b/_api-reference/index-apis/update-settings.md index 3bc969c2ce0..0f687209639 100644 --- a/_api-reference/index-apis/update-settings.md +++ b/_api-reference/index-apis/update-settings.md @@ -55,7 +55,18 @@ The request body must all of the index settings that you want to update. ## Example request -```json + +{% capture step1_rest %} PUT /sample-index1/_settings { "index.plugins.index_state_management.rollover_skip": true, @@ -63,8 +74,27 @@ PUT /sample-index1/_settings "number_of_replicas": 4 } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_settings( + index = "sample-index1", + body = { + "index.plugins.index_state_management.rollover_skip": true, + "index": { + "number_of_replicas": 4 + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/list/index.md b/_api-reference/list/index.md index 91a1cb5f834..6168eaf0552 100644 --- a/_api-reference/list/index.md +++ b/_api-reference/list/index.md @@ -39,10 +39,27 @@ To query indexes and their statistics with a verbose output that includes all co #### Request -```json -GET _list/indices?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_list/indices?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.list.indices( + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + #### Response @@ -67,10 +84,27 @@ GET _list/?help The following example list indices operation returns all the available headers: -```json -GET _list/indices?help -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_list/indices?help +{% endcapture %} + +{% capture step1_python %} + + +response = client.list.indices( + params = { "help": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + #### Response @@ -101,10 +135,27 @@ For any operation, you can determine which headers are available by using the `h The following example limits the indexes in the response to only the index name and health status headers: -```json -GET _list/indices?h=health,index -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_list/indices?h=health,index +{% endcapture %} + +{% capture step1_python %} + + +response = client.list.indices( + params = { "h": "health,index" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Response @@ -128,10 +179,27 @@ GET _list/?s=, The following example request sorts indexes by index name: -```json -GET _list/indices?s=h,i -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_list/indices?s=h,i +{% endcapture %} + +{% capture step1_python %} + + +response = client.list.indices( + params = { "s": "h,i" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + #### Response @@ -154,16 +222,33 @@ If you use the Security plugin, ensure you have the appropriate permissions. #### Request ```json -GET _list/?format=json +GET _list/?help ``` {% include copy-curl.html %} #### Request -```json -GET _list/indices?format=json -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_list/indices?format=json +{% endcapture %} + +{% capture step1_python %} + + +response = client.list.indices( + params = { "format": "json" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Response diff --git a/_api-reference/list/list-indices.md b/_api-reference/list/list-indices.md index 5b9ee27845a..6cc96811011 100644 --- a/_api-reference/list/list-indices.md +++ b/_api-reference/list/list-indices.md @@ -53,17 +53,53 @@ GET _list/indices/?v&next_token=token To limit the information to a specific index, add the index name after your query, as shown in the following example: -```json -GET _list/indices/?v -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_list/indices/?v +{% endcapture %} + +{% capture step1_python %} + + +response = client.list.indices( + index = "", + params = { "v": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To get information about more than one index, separate the indexes with commas, as shown in the following example: -```json -GET _list/indices/index1,index2,index3?v&next_token=token -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_list/indices/index1,index2,index3?v&next_token=token +{% endcapture %} + +{% capture step1_python %} + + +response = client.list.indices( + index = "index1,index2,index3", + params = { "v": "true", "next_token": "token" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/list/list-shards.md b/_api-reference/list/list-shards.md index 6706acfc969..281b7640699 100644 --- a/_api-reference/list/list-shards.md +++ b/_api-reference/list/list-shards.md @@ -46,17 +46,53 @@ GET _list/shards/?v&next_token=token To limit the information to a specific index, add the index name after your query, as shown in the following example and keep specifying the `next_token` as received from response until its `null`: -```json -GET _list/shards/?v&next_token=token -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_list/shards/?v&next_token=token +{% endcapture %} + +{% capture step1_python %} + + +response = client.list.shards( + index = "", + params = { "v": "true", "next_token": "token" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to get information for more than one index, separate the indexes with commas, as shown in the following example: -```json -GET _list/shards/index1,index2,index3?v&next_token=token -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_list/shards/index1,index2,index3?v&next_token=token +{% endcapture %} + +{% capture step1_python %} + + +response = client.list.shards( + index = "index1,index2,index3", + params = { "v": "true", "next_token": "token" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/nodes-apis/index.md b/_api-reference/nodes-apis/index.md index 79a4b630806..c9729468fa8 100644 --- a/_api-reference/nodes-apis/index.md +++ b/_api-reference/nodes-apis/index.md @@ -49,17 +49,53 @@ Resolution mechanisms are applied sequentially in the order specified by the cli To get statistics from the elected cluster manager node only, use the following query : -```json + +{% capture step1_rest %} GET /_nodes/_cluster_manager/stats -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.info( + metric = "stats", + node_id = "_cluster_manager" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To get statistics from nodes that are data-only nodes, use the following query: -```json + +{% capture step1_rest %} GET /_nodes/data:true/stats -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.info( + metric = "stats", + node_id = "data:true" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Order of resolution mechanisms @@ -67,14 +103,50 @@ The order of resolution mechanisms is applied sequentially, and each can add or To get statistics from all the nodes except the cluster manager node, use the following query: -```json + +{% capture step1_rest %} GET /_nodes/_all,cluster_manager:false/stats -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.info( + metric = "stats", + node_id = "_all,cluster_manager:false" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + However, if you switch the resolution mechanisms, the result will include all the cluster nodes, including the cluster manager node: -```json + +{% capture step1_rest %} GET /_nodes/cluster_manager:false,_all/stats -``` -{% include copy-curl.html %} \ No newline at end of file +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.info( + metric = "stats", + node_id = "cluster_manager:false,_all" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + diff --git a/_api-reference/nodes-apis/nodes-hot-threads.md b/_api-reference/nodes-apis/nodes-hot-threads.md index 33291386904..e3c2f55cc36 100644 --- a/_api-reference/nodes-apis/nodes-hot-threads.md +++ b/_api-reference/nodes-apis/nodes-hot-threads.md @@ -42,10 +42,27 @@ timeout | Time | Sets the time limit for node response. Default value is `30s`. ## Example request -```json + +{% capture step1_rest %} GET /_nodes/hot_threads -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.info( + node_id_or_metric = "hot_threads" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/nodes-apis/nodes-info.md b/_api-reference/nodes-apis/nodes-info.md index 0763a876d1c..f06c7a19168 100644 --- a/_api-reference/nodes-apis/nodes-info.md +++ b/_api-reference/nodes-apis/nodes-info.md @@ -68,17 +68,53 @@ timeout | Time | Sets the time limit for node response. Default value is `30s`. The following query requests the `process` and `transport` metrics from the cluster manager node: -```json + +{% capture step1_rest %} GET /_nodes/cluster_manager:true/process,transport -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.info( + metric = "process,transport", + node_id = "cluster_manager:true" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To get thread pool information about the cluster manager node only, use the following query: -```json + +{% capture step1_rest %} GET /_nodes/master:true/thread_pool -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.info( + metric = "thread_pool", + node_id = "master:true" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/nodes-apis/nodes-reload-secure.md b/_api-reference/nodes-apis/nodes-reload-secure.md index b4ba409b1d2..d4509e339e3 100644 --- a/_api-reference/nodes-apis/nodes-reload-secure.md +++ b/_api-reference/nodes-apis/nodes-reload-secure.md @@ -40,10 +40,27 @@ The request may include an optional object containing the password for the OpenS The following is an example API request: -``` -POST _nodes/reload_secure_settings -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +POST /_nodes/reload_secure_settings +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.reload_secure_settings( + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/nodes-apis/nodes-stats.md b/_api-reference/nodes-apis/nodes-stats.md index f610e45ff62..13c819fdef8 100644 --- a/_api-reference/nodes-apis/nodes-stats.md +++ b/_api-reference/nodes-apis/nodes-stats.md @@ -87,10 +87,28 @@ The following index metrics are supported: For example, the following query requests statistics for `docs` and `search`: -```json -GET _nodes/stats/indices/docs,search -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_nodes/stats/indices/docs,search +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.stats( + metric = "indices", + index_metric = "docs,search" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + You can also use specific `index_metric` values in the `caches` metric to specify which caches will return statistics. The following index metrics are supported: @@ -99,10 +117,28 @@ The following index metrics are supported: For example, the following query requests statistics for the `request_cache`: -```json -GET _nodes/stats/caches/request_cache -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_nodes/stats/caches/request_cache +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.stats( + metric = "caches", + index_metric = "request_cache" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Query parameters @@ -120,10 +156,27 @@ include_segment_file_sizes | Boolean | If segment statistics are requested, this ## Example request -```json -GET _nodes/stats/ -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_nodes/stats +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.info( + node_id_or_metric = "stats" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/nodes-apis/nodes-usage.md b/_api-reference/nodes-apis/nodes-usage.md index fed45f2b005..2f32dd7c7c6 100644 --- a/_api-reference/nodes-apis/nodes-usage.md +++ b/_api-reference/nodes-apis/nodes-usage.md @@ -42,10 +42,27 @@ cluster_manager_timeout | Time | Sets the time limit for a response from the clu The following request returns usage details for all nodes: -``` -GET _nodes/usage -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_nodes/usage +{% endcapture %} + +{% capture step1_python %} + + +response = client.nodes.info( + node_id_or_metric = "usage" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/script-apis/create-stored-script.md b/_api-reference/script-apis/create-stored-script.md index f6b4f913411..2a3ebc6fb4a 100644 --- a/_api-reference/script-apis/create-stored-script.md +++ b/_api-reference/script-apis/create-stored-script.md @@ -51,23 +51,56 @@ All parameters are optional. The following example requests uses an index called `books` with the following documents: -```json -POST _bulk + +{% capture step1_rest %} +POST /_bulk +{"index":{"_index":"books","_id":1}} +{"name":"book1","author":"Faustine","ratings":[4,3,5]} +{"index":{"_index":"books","_id":2}} +{"name":"book2","author":"Amit","ratings":[5,5,5]} +{"index":{"_index":"books","_id":3}} +{"name":"book3","author":"Gilroy","ratings":[2,1,5]} +{% endcapture %} + +{% capture step1_python %} + + +response = client.bulk( + body = ''' +{"index":{"_index":"books","_id":1}} +{"name":"book1","author":"Faustine","ratings":[4,3,5]} +{"index":{"_index":"books","_id":2}} +{"name":"book2","author":"Amit","ratings":[5,5,5]} +{"index":{"_index":"books","_id":3}} +{"name":"book3","author":"Gilroy","ratings":[2,1,5]} +''' +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Creating a Painless script The following request creates the Painless script `my-first-script`. It sums the ratings for each book and displays the sum in the output. -````json -PUT _scripts/my-first-script + +{% capture step1_rest %} +PUT /_scripts/my-first-script +{ + "script": { + "lang": "painless", + "source": """ + int total = 0; + for (int i = 0; i < doc['ratings'].length; ++i) { + total += doc['ratings'][i]; + } + return total; + """ + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.put_script( + id = "my-first-script", + body = ''' +{ + "script": { + "lang": "painless", + "source": """ + int total = 0; + for (int i = 0; i < doc['ratings'].length; ++i) { + total += doc['ratings'][i]; + } + return total; + """ + } +} +''' +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The preceding example uses the syntax of the Dev Tools console in OpenSearch Dashboards. You can also use a curl request. {: .note } @@ -108,8 +183,10 @@ The Painless script supports `params` to pass variables to the script. The following request creates the Painless script `multiplier-script`. The request sums the ratings for each book, multiplies the summed value by the `multiplier` parameter, and displays the result in the output: -````json -PUT _scripts/multiplier-script + +{% capture step1_rest %} +PUT /_scripts/multiplier-script +{ + "script": { + "lang": "painless", + "source": """ + int total = 0; + for (int i = 0; i < doc['ratings'].length; ++i) { + total += doc['ratings'][i]; + } + return total * params['multiplier']; + """ + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.put_script( + id = "multiplier-script", + body = ''' +{ + "script": { + "lang": "painless", + "source": """ + int total = 0; + for (int i = 0; i < doc['ratings'].length; ++i) { + total += doc['ratings'][i]; + } + return total * params['multiplier']; + """ + } +} +''' +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/script-apis/delete-script.md b/_api-reference/script-apis/delete-script.md index 9946fa6b0f8..efbf7595ef2 100644 --- a/_api-reference/script-apis/delete-script.md +++ b/_api-reference/script-apis/delete-script.md @@ -36,10 +36,27 @@ Path parameters are optional. The following request deletes the `my-first-script` script: -````json -DELETE _scripts/my-script -```` -{% include copy-curl.html %} + +{% capture step1_rest %} +DELETE /_scripts/my-script +{% endcapture %} + +{% capture step1_python %} + + +response = client.delete_script( + id = "my-script" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/script-apis/exec-script.md b/_api-reference/script-apis/exec-script.md index 0c234f22434..0de3ed0b239 100644 --- a/_api-reference/script-apis/exec-script.md +++ b/_api-reference/script-apis/exec-script.md @@ -27,10 +27,92 @@ POST /_scripts/painless/_execute | context_setup | Specifies additional parameters for the context. Optional.| ## Example request + +{% capture step1_rest %} +POST /_scripts/painless/_execute +{ + "script": { + "source": "doc['gpa_4_0'].value * params.max_gpa / 4.0", + "params": { + "max_gpa": 5.0 + } + }, + "context": "score", + "context_setup": { + "index": "testindex1", + "document": { + "gpa_4_0": 3.5 + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.put_script( + id = "painless", + context = "_execute", + body = { + "script": { + "source": "doc['gpa_4_0'].value * params.max_gpa / 4.0", + "params": { + "max_gpa": 5.0 + } + }, + "context": "score", + "context_setup": { + "index": "testindex1", + "document": { + "gpa_4_0": 3.5 + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The following request uses the default `painless_context` for the script: -```json + +{% capture step1_rest %} GET /_scripts/painless/_execute { "script": { @@ -41,8 +123,29 @@ GET /_scripts/painless/_execute } } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.scripts_painless_execute( + body = { + "script": { + "source": "(params.x + params.y)/ 2", + "params": { + "x": 80, + "y": 100 + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response @@ -101,7 +204,28 @@ PUT /testindex1 Run a script to determine if a student is eligible to graduate with honors: -```json + +{% capture step1_rest %} POST /_scripts/painless/_execute { "script": { @@ -119,8 +243,38 @@ POST /_scripts/painless/_execute } } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.put_script( + id = "painless", + context = "_execute", + body = { + "script": { + "source": "doc['grad'].value == true && doc['gpa'].value >= params.min_honors_gpa", + "params": { + "min_honors_gpa": 3.5 + } + }, + "context": "filter", + "context_setup": { + "index": "testindex1", + "document": { + "grad": true, + "gpa": 3.79 + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains the result: @@ -160,7 +314,27 @@ PUT /testindex1 Run a script that converts a GPA on a 4.0 scale into a different scale that is provided as a parameter: -```json + +{% capture step1_rest %} POST /_scripts/painless/_execute { "script": { @@ -177,8 +351,37 @@ POST /_scripts/painless/_execute } } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.put_script( + id = "painless", + context = "_execute", + body = { + "script": { + "source": "doc['gpa_4_0'].value * params.max_gpa / 4.0", + "params": { + "max_gpa": 5.0 + } + }, + "context": "score", + "context_setup": { + "index": "testindex1", + "document": { + "gpa_4_0": 3.5 + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains the result: diff --git a/_api-reference/script-apis/exec-stored-script.md b/_api-reference/script-apis/exec-stored-script.md index 9d3fa1ad8b9..a3ae74295fa 100644 --- a/_api-reference/script-apis/exec-stored-script.md +++ b/_api-reference/script-apis/exec-stored-script.md @@ -37,6 +37,73 @@ GET books/_search | script | Object | ID of the script that produces a value for a field. | ## Example request + +{% capture step1_rest %} +GET /books/_search +{ + "query": { + "match_all": {} + }, + "script_fields": { + "total_ratings": { + "script": { + "id": "multiplier-script", + "params": { + "multiplier": 2 + } + } + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "books", + body = { + "query": { + "match_all": {} + }, + "script_fields": { + "total_ratings": { + "script": { + "id": "multiplier-script", + "params": { + "multiplier": 2 + } + } + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The following request runs the stored script that was created in [Create or update stored script]({{site.url}}{{site.baseurl}}/api-reference/script-apis/create-stored-script/). The script sums the ratings for each book and displays the sum in the `total_ratings` field in the output. @@ -46,8 +113,10 @@ The following request runs the stored script that was created in [Create or upda * The `total_ratings` field value is the result of the `my-first-script` execution. See [Create or update stored script]({{site.url}}{{site.baseurl}}/api-reference/script-apis/create-stored-script/). -````json -GET books/_search + +{% capture step1_rest %} +GET /books/_search +{ + "query": { + "match_all": {} + }, + "script_fields": { + "total_ratings": { + "script": { + "id": "my-first-script" + } + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "books", + body = { + "query": { + "match_all": {} + }, + "script_fields": { + "total_ratings": { + "script": { + "id": "my-first-script" + } + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + #### Example response @@ -161,8 +270,10 @@ The following request runs the stored script that was created in [Create or upda * `"multiplier": 2` in the `params` field is a variable passed to the stored script `multiplier-script`: -```json -GET books/_search + +{% capture step1_rest %} +GET /books/_search +{ + "query": { + "match_all": {} + }, + "script_fields": { + "total_ratings": { + "script": { + "id": "multiplier-script", + "params": { + "multiplier": 2 + } + } + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "books", + body = { + "query": { + "match_all": {} + }, + "script_fields": { + "total_ratings": { + "script": { + "id": "multiplier-script", + "params": { + "multiplier": 2 + } + } + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + #### Example response diff --git a/_api-reference/script-apis/get-script-contexts.md b/_api-reference/script-apis/get-script-contexts.md index 2eb583ab67f..8e7afca3f31 100644 --- a/_api-reference/script-apis/get-script-contexts.md +++ b/_api-reference/script-apis/get-script-contexts.md @@ -13,10 +13,23 @@ Retrieves all contexts for stored scripts. ## Example request -```json -GET _script_context -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_script_context +{% endcapture %} + +{% capture step1_python %} + +response = client.get_script_context() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/script-apis/get-script-language.md b/_api-reference/script-apis/get-script-language.md index 7c594935f8b..250d3f2e92b 100644 --- a/_api-reference/script-apis/get-script-language.md +++ b/_api-reference/script-apis/get-script-language.md @@ -13,10 +13,23 @@ The get script language API operation retrieves all supported script languages a ## Example request -```json -GET _script_language -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_script_language +{% endcapture %} + +{% capture step1_python %} + +response = client.get_script_languages() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/script-apis/get-stored-script.md b/_api-reference/script-apis/get-stored-script.md index 75ccf1e836b..47c8a6d6b29 100644 --- a/_api-reference/script-apis/get-stored-script.md +++ b/_api-reference/script-apis/get-stored-script.md @@ -33,10 +33,27 @@ GET _scripts/my-first-script The following retrieves the `my-first-script` stored script. -````json -GET _scripts/my-first-script -```` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_scripts/my-first-script +{% endcapture %} + +{% capture step1_python %} + + +response = client.get_script( + id = "my-first-script" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/search-apis/count.md b/_api-reference/search-apis/count.md index 961eb543d30..4bbf3d88221 100644 --- a/_api-reference/search-apis/count.md +++ b/_api-reference/search-apis/count.md @@ -43,11 +43,12 @@ Parameter | Type | Description `terminate_after` | Integer | The maximum number of matching documents (hits) OpenSearch should process before terminating the request. ## Example requests - To see the number of documents that match a query: -```json -GET opensearch_dashboards_sample_data_logs/_count + +{% capture step1_rest %} +GET /opensearch_dashboards_sample_data_logs/_count +{ + "query": { + "term": { + "response": "200" + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.count( + index = "opensearch_dashboards_sample_data_logs", + body = { + "query": { + "term": { + "response": "200" + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The following call to the search API produces equivalent results: -```json -GET opensearch_dashboards_sample_data_logs/_search + +{% capture step1_rest %} +GET /opensearch_dashboards_sample_data_logs/_search +{ + "query": { + "term": { + "response": "200" + } + }, + "size": 0, + "track_total_hits": true +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "opensearch_dashboards_sample_data_logs", + body = { + "query": { + "term": { + "response": "200" + } + }, + "size": 0, + "track_total_hits": true + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To see the number of documents in an index: -```json -GET opensearch_dashboards_sample_data_logs/_count -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /opensearch_dashboards_sample_data_logs/_count +{% endcapture %} + +{% capture step1_python %} + + +response = client.count( + index = "opensearch_dashboards_sample_data_logs", + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To check for the number of documents in a [data stream]({{site.url}}{{site.baseurl}}/opensearch/data-streams/), replace the index name with the data stream name. To see the number of documents in your cluster: -```json -GET _count -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_count +{% endcapture %} + +{% capture step1_python %} + + +response = client.count( + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Alternatively, you could use the [cat indexes]({{site.url}}{{site.baseurl}}/api-reference/cat/cat-indices/) and [cat count]({{site.url}}{{site.baseurl}}/api-reference/cat/cat-count/) APIs to see the number of documents per index or data stream. {: .note } diff --git a/_api-reference/search-apis/explain.md b/_api-reference/search-apis/explain.md index 0a52a844043..83478913e48 100644 --- a/_api-reference/search-apis/explain.md +++ b/_api-reference/search-apis/explain.md @@ -57,8 +57,10 @@ Parameter | Type | Description | Required To see the explain output for all results, set the `explain` flag to `true` either in the URL or in the body of the request: -```json -POST opensearch_dashboards_sample_data_ecommerce/_search?explain=true + +{% capture step1_rest %} +POST /opensearch_dashboards_sample_data_ecommerce/_search?explain=true +{ + "query": { + "match": { + "customer_first_name": "Mary" + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "opensearch_dashboards_sample_data_ecommerce", + params = { "explain": "true" }, + body = { + "query": { + "match": { + "customer_first_name": "Mary" + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + More often, you want the output for a single document. In that case, specify the document ID in the URL: -```json -POST opensearch_dashboards_sample_data_ecommerce/_explain/EVz1Q3sBgg5eWQP6RSte + +{% capture step1_rest %} +POST /opensearch_dashboards_sample_data_ecommerce/_explain/EVz1Q3sBgg5eWQP6RSte +{ + "query": { + "match": { + "customer_first_name": "Mary" + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.explain( + id = "EVz1Q3sBgg5eWQP6RSte", + index = "opensearch_dashboards_sample_data_ecommerce", + body = { + "query": { + "match": { + "customer_first_name": "Mary" + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/search-apis/field-caps.md b/_api-reference/search-apis/field-caps.md index 3d0c3c4934c..9532849ffc0 100644 --- a/_api-reference/search-apis/field-caps.md +++ b/_api-reference/search-apis/field-caps.md @@ -48,7 +48,7 @@ The following table lists the available request body fields. | :------------- | :-------- | :---------------------------------------------------------------------- | | `index_filter` | Object | A query DSL object used to filter indexes included in the request. See [Example: Using an index filter](#example-using-an-index-filter). _Optional_.| -## Example +## Example Requests Create two indexes with different mappings for the same field: @@ -80,10 +80,29 @@ PUT /store-east Query field capabilities across both indexes: -```json + +{% capture step1_rest %} GET /store-west,store-east/_field_caps?fields=product,price -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.field_caps( + index = "store-west,store-east", + params = { "fields": "product,price" }, + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example response @@ -129,7 +148,19 @@ The response provides the capabilities of the available fields: You can restrict the indexes considered using an `index_filter`. The `index_filter` filters out indexes based on field-level metadata, not actual document content. The following request limits the index selection to those that contain mappings containing a `product` field, even if there are no documents indexed: -```json + +{% capture step1_rest %} POST /_field_caps?fields=product,price { "index_filter": { @@ -138,8 +169,28 @@ POST /_field_caps?fields=product,price } } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.field_caps( + params = { "fields": "product,price" }, + body = { + "index_filter": { + "term": { + "product": "notebook" + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example response diff --git a/_api-reference/search-apis/multi-search.md b/_api-reference/search-apis/multi-search.md index ffa5c2c74df..a6ae8e9f0f9 100644 --- a/_api-reference/search-apis/multi-search.md +++ b/_api-reference/search-apis/multi-search.md @@ -84,15 +84,41 @@ Just like the [bulk]({{site.url}}{{site.baseurl}}/api-reference/document-apis/bu The following example `msearch` API request runs queries against multiple indexes: -```json -GET _msearch + +{% capture step1_rest %} +GET /_msearch { "index": "opensearch_dashboards_sample_data_logs"} { "query": { "match_all": {} }, "from": 0, "size": 10} { "index": "opensearch_dashboards_sample_data_ecommerce", "search_type": "dfs_query_then_fetch"} { "query": { "match_all": {} } } +{% endcapture %} -``` -{% include copy-curl.html %} +{% capture step1_python %} + + +response = client.msearch( + body = ''' +{ "index": "opensearch_dashboards_sample_data_logs"} +{ "query": { "match_all": {} }, "from": 0, "size": 10} +{ "index": "opensearch_dashboards_sample_data_ecommerce", "search_type": "dfs_query_then_fetch"} +{ "query": { "match_all": {} } } +''' +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/search-apis/point-in-time-api.md b/_api-reference/search-apis/point-in-time-api.md index e2862985da1..1fc0c6bc4b5 100644 --- a/_api-reference/search-apis/point-in-time-api.md +++ b/_api-reference/search-apis/point-in-time-api.md @@ -53,9 +53,28 @@ Parameter | Data type | Description #### Example request -```json + +{% capture step1_rest %} POST /my-index-1/_search/point_in_time?keep_alive=100m -``` +{% endcapture %} + +{% capture step1_python %} + + +response = client.create_pit( + index = "my-index-1", + params = { "keep_alive": "100m" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + #### Example response @@ -120,9 +139,23 @@ The List All PITs API returns only local PITs or mixed PITs (PITs created in bot #### Example request -```json + +{% capture step1_rest %} GET /_search/point_in_time/_all -``` +{% endcapture %} + +{% capture step1_python %} + +response = client.get_all_pits() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + #### Example response @@ -171,9 +204,23 @@ The Delete All PITs API deletes only local PITs or mixed PITs (PITs created in b #### Example request: Delete all PITs -```json + +{% capture step1_rest %} DELETE /_search/point_in_time/_all -``` +{% endcapture %} + +{% capture step1_python %} + +response = client.delete_all_pits() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + If you want to delete one or several PITs, specify their PIT IDs in the request body. @@ -185,16 +232,45 @@ Field | Data type | Description #### Example request: Delete PITs by ID -```json -DELETE /_search/point_in_time - + +{% capture step1_rest %} +DELETE /_search/point_in_time +{ + "pit_id": [ + "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA", + "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA" + ] +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.delete_pit( + body = { + "pit_id": [ + "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA", + "o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAIWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA" + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + #### Example response diff --git a/_api-reference/search-apis/profile.md b/_api-reference/search-apis/profile.md index be6507aeb7b..b93ff4b7b5d 100644 --- a/_api-reference/search-apis/profile.md +++ b/_api-reference/search-apis/profile.md @@ -47,29 +47,98 @@ In general, the max/min/avg slice time captures statistics across all slices for To use the Profile API, include the `profile` parameter set to `true` in the search request sent to the `_search` endpoint: -```json -GET /testindex/_search + +{% capture step1_rest %} +GET /testindex/_search +{ + "profile": true, + "query": { + "match": { + "title": "wind" + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "testindex", + body = { + "profile": true, + "query": { + "match": { + "title": "wind" + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To turn on human-readable format, include the `?human=true` query parameter in the request: -```json -GET /testindex/_search?human=true + +{% capture step1_rest %} +GET /testindex/_search?human=true +{ + "profile": true, + "query": { + "match": { + "title": "wind" + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "testindex", + params = { "human": "true" }, + body = { + "profile": true, + "query": { + "match": { + "title": "wind" + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The response contains an additional `time` field with human-readable units, for example: @@ -93,8 +162,10 @@ To profile aggregations, send an aggregation request and provide the `profile` p #### Global aggregation -```json -GET /opensearch_dashboards_sample_data_ecommerce/_search + +{% capture step1_rest %} +GET /opensearch_dashboards_sample_data_ecommerce/_search +{ + "profile": "true", + "size": 0, + "query": { + "match": { + "manufacturer": "Elitelligence" + } + }, + "aggs": { + "all_products": { + "global": {}, + "aggs": { + "avg_price": { + "avg": { + "field": "taxful_total_price" + } + } + } + }, + "elitelligence_products": { + "avg": { + "field": "taxful_total_price" + } + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "opensearch_dashboards_sample_data_ecommerce", + body = { + "profile": "true", + "size": 0, + "query": { + "match": { + "manufacturer": "Elitelligence" + } + }, + "aggs": { + "all_products": { + "global": {}, + "aggs": { + "avg_price": { + "avg": { + "field": "taxful_total_price" + } + } + } + }, + "elitelligence_products": { + "avg": { + "field": "taxful_total_price" + } + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + #### Non-global aggregation -```json + +{% capture step1_rest %} GET /opensearch_dashboards_sample_data_ecommerce/_search { "size": 0, @@ -128,8 +282,31 @@ GET /opensearch_dashboards_sample_data_ecommerce/_search } } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "opensearch_dashboards_sample_data_ecommerce", + body = { + "size": 0, + "aggs": { + "avg_taxful_total_price": { + "avg": { + "field": "taxful_total_price" + } + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/search-apis/rank-eval.md b/_api-reference/search-apis/rank-eval.md index 9936f5572a2..e5b84130bd5 100644 --- a/_api-reference/search-apis/rank-eval.md +++ b/_api-reference/search-apis/rank-eval.md @@ -50,16 +50,18 @@ params | Parameters used in the template. ## Example request -````json -GET shakespeare/_rank_eval + +{% capture step1_rest %} +GET /shakespeare/_rank_eval +{ + "requests": [ + { + "id": "books_query", + "request": { + "query": { + "match": { + "text": "thou" + } + } + }, + "ratings": [ + { + "_index": "shakespeare", + "_id": "80", + "rating": 0 + }, + { + "_index": "shakespeare", + "_id": "115", + "rating": 1 + }, + { + "_index": "shakespeare", + "_id": "117", + "rating": 2 + } + ] + }, + { + "id": "words_query", + "request": { + "query": { + "match": { + "text": "art" + } + } + }, + "ratings": [ + { + "_index": "shakespeare", + "_id": "115", + "rating": 2 + } + ] + } + ] +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.rank_eval( + index = "shakespeare", + body = { + "requests": [ + { + "id": "books_query", + "request": { + "query": { + "match": { + "text": "thou" + } + } + }, + "ratings": [ + { + "_index": "shakespeare", + "_id": "80", + "rating": 0 + }, + { + "_index": "shakespeare", + "_id": "115", + "rating": 1 + }, + { + "_index": "shakespeare", + "_id": "117", + "rating": 2 + } + ] + }, + { + "id": "words_query", + "request": { + "query": { + "match": { + "text": "art" + } + } + }, + "ratings": [ + { + "_index": "shakespeare", + "_id": "115", + "rating": 2 + } + ] + } + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/search-apis/scroll.md b/_api-reference/search-apis/scroll.md index 5fa81a8f07b..ca708bcba60 100644 --- a/_api-reference/search-apis/scroll.md +++ b/_api-reference/search-apis/scroll.md @@ -48,13 +48,38 @@ rest_total_hits_as_int | Boolean | Whether the `hits.total` property is returned To set the number of results that you want returned for each batch, use the `size` parameter: -```json -GET shakespeare/_search?scroll=10m + +{% capture step1_rest %} +GET /shakespeare/_search?scroll=10m +{ + "size": 10000 +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "shakespeare", + params = { "scroll": "10m" }, + body = { + "size": 10000 + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + OpenSearch caches the results and returns a scroll ID to access them in batches: @@ -64,22 +89,49 @@ OpenSearch caches the results and returns a scroll ID to access them in batches: Pass this scroll ID to the `scroll` operation to get back the next batch of results: -```json -GET _search/scroll + +{% capture step1_rest %} +GET /_search/scroll +{ + "scroll": "10m", + "scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAUWdmpUZDhnRFBUcWFtV21nMmFwUGJEQQ==" +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.scroll( + body = { + "scroll": "10m", + "scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAUWdmpUZDhnRFBUcWFtV21nMmFwUGJEQQ==" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Using this scroll ID, you get results in batches of 10,000 as long as the search context is still open. Typically, the scroll ID does not change between requests, but it *can* change, so make sure to always use the latest scroll ID. If you don't send the next scroll request within the set search context, the `scroll` operation does not return any results. If you expect billions of results, use a sliced scroll. Slicing allows you to perform multiple scroll operations for the same request, but in parallel. Set the ID and the maximum number of slices for the scroll: -```json -GET shakespeare/_search?scroll=10m + +{% capture step1_rest %} +GET /shakespeare/_search?scroll=10m +{ + "slice": { + "id": 0, + "max": 10 + }, + "query": { + "match_all": {} + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "shakespeare", + params = { "scroll": "10m" }, + body = { + "slice": { + "id": 0, + "max": 10 + }, + "query": { + "match_all": {} + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + With a single scroll ID, you get back 10 results. You can have up to 10 IDs. Close the search context when you’re done scrolling, because the `scroll` operation continues to consume computing resources until the timeout: -```json -DELETE _search/scroll/DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAcWdmpUZDhnRFBUcWFtV21nMmFwUGJEQQ== -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +DELETE /_search/scroll/DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAcWdmpUZDhnRFBUcWFtV21nMmFwUGJEQQ== +{% endcapture %} + +{% capture step1_python %} + + +response = client.clear_scroll( + scroll_id = "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAcWdmpUZDhnRFBUcWFtV21nMmFwUGJEQQ==", + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To close all open scroll contexts: -```json -DELETE _search/scroll/_all -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +DELETE /_search/scroll/_all +{% endcapture %} + +{% capture step1_python %} + + +response = client.clear_scroll( + scroll_id = "_all", + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The `scroll` operation corresponds to a specific timestamp. It doesn't consider documents added after that timestamp as potential results. diff --git a/_api-reference/search-apis/search-shards.md b/_api-reference/search-apis/search-shards.md index af1dde298d1..566f5de2644 100644 --- a/_api-reference/search-apis/search-shards.md +++ b/_api-reference/search-apis/search-shards.md @@ -77,33 +77,103 @@ PUT /logs-demo Index the first document with `routing=user1`: -```json + +{% capture step1_rest %} POST /logs-demo/_doc?routing=user1 { "@timestamp": "2025-05-23T10:00:00Z", "user": "user1", "message": "User login successful" } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.index( + index = "logs-demo", + params = { "routing": "user1" }, + body = { + "@timestamp": "2025-05-23T10:00:00Z", + "user": "user1", + "message": "User login successful" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Index the second document with `routing=user2`: -```json + +{% capture step1_rest %} POST /logs-demo/_doc?routing=user2 { "@timestamp": "2025-05-23T10:01:00Z", "user": "user2", "message": "User login failed" } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.index( + index = "logs-demo", + params = { "routing": "user2" }, + body = { + "@timestamp": "2025-05-23T10:01:00Z", + "user": "user2", + "message": "User login failed" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example request Simulate routing with `_search_shards`: -```json + +{% capture step1_rest %} POST /logs-demo/_search_shards?routing=user1 { "query": { @@ -112,8 +182,29 @@ POST /logs-demo/_search_shards?routing=user1 } } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search_shards( + index = "logs-demo", + params = { "routing": "user1" }, + body = { + "query": { + "term": { + "user": "user1" + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example response diff --git a/_api-reference/search-apis/search-template/index.md b/_api-reference/search-apis/search-template/index.md index 5e03ffd138d..87dfcc2fcfe 100644 --- a/_api-reference/search-apis/search-template/index.md +++ b/_api-reference/search-apis/search-template/index.md @@ -30,8 +30,10 @@ You can code your application to ask your user what they want to search for and This command defines a search template to find a play by its name. The `{% raw %}{{play_name}}{% endraw %}` in the query is replaced by the value `Henry IV`: -```json -GET _search/template + +{% capture step1_rest %} +GET /_search/template +{ + "source": { + "query": { + "match": { + "play_name": "{% raw %}{{play_name}}{% endraw %}" + } + } + }, + "params": { + "play_name": "Henry IV" + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search_template( + body = { + "source": { + "query": { + "match": { + "play_name": "{% raw %}{{play_name}}{% endraw %}" + } + } + }, + "params": { + "play_name": "Henry IV" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + This template runs the search on your entire cluster. To run this search on a specific index, add the index name to the request: -```json -GET shakespeare/_search/template -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /shakespeare/_search/template +{% endcapture %} + +{% capture step1_python %} + + +response = client.search_template( + index = "shakespeare", + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Specify the `from` and `size` parameters: -```json -GET _search/template + +{% capture step1_rest %} +GET /_search/template +{ + "source": { + "from": "{% raw %}{{from}}{% endraw %}", + "size": "{% raw %}{{size}}{% endraw %}", + "query": { + "match": { + "play_name": "{% raw %}{{play_name}}{% endraw %}" + } + } + }, + "params": { + "play_name": "Henry IV", + "from": 10, + "size": 10 + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search_template( + body = { + "source": { + "from": "{% raw %}{{from}}{% endraw %}", + "size": "{% raw %}{{size}}{% endraw %}", + "query": { + "match": { + "play_name": "{% raw %}{{play_name}}{% endraw %}" + } + } + }, + "params": { + "play_name": "Henry IV", + "from": 10, + "size": 10 + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To improve the search experience, you can define defaults so the user doesn’t have to specify every possible parameter. If the parameter is not defined in the `params` section, OpenSearch uses the default value. @@ -88,8 +196,10 @@ The syntax for defining the default value for a variable `var` is as follows: This command sets the defaults for `from` as 10 and `size` as 10: -```json -GET _search/template + +{% capture step1_rest %} +GET /_search/template +{ + "source": { + "from": "{% raw %}{{from}}{{^from}}10{{/from}}{% endraw %}", + "size": "{% raw %}{{size}}{{^size}}10{{/size}}{% endraw %}", + "query": { + "match": { + "play_name": "{% raw %}{{play_name}}{% endraw %}" + } + } + }, + "params": { + "play_name": "Henry IV" + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search_template( + body = { + "source": { + "from": "{% raw %}{{from}}{{^from}}10{{/from}}{% endraw %}", + "size": "{% raw %}{{size}}{{^size}}10{{/size}}{% endraw %}", + "query": { + "match": { + "play_name": "{% raw %}{{play_name}}{% endraw %}" + } + } + }, + "params": { + "play_name": "Henry IV" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Save and execute search templates @@ -137,8 +290,10 @@ POST _scripts/play_search_template Now you can reuse the template by referring to its `id` parameter. You can reuse this source template for different input values: -```json -GET _search/template + +{% capture step1_rest %} +GET /_search/template +{ + "id": "play_search_template", + "params": { + "play_name": "Henry IV", + "from": 0, + "size": 1 + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search_template( + body = { + "id": "play_search_template", + "params": { + "play_name": "Henry IV", + "from": 0, + "size": 1 + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response @@ -191,16 +377,45 @@ GET _search/template If you have a stored template and want to validate it, use the `render` operation: -```json -POST _render/template + +{% capture step1_rest %} +POST /_render/template +{ + "id": "play_search_template", + "params": { + "play_name": "Henry IV" + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.render_search_template( + body = { + "id": "play_search_template", + "params": { + "play_name": "Henry IV" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + For more information, see [Render Template API]({{site.url}}{{site.baseurl}}/api-reference/search-apis/search-template/render-template/). @@ -225,8 +440,10 @@ Using section tags would make your JSON invalid, so you must write your query in This command includes the `size` parameter in the query only when the `limit` parameter is set to `true`. In the following example, the `limit` parameter is `true`, so the `size` parameter is activated. As a result, you would get back only two documents. -```json -GET _search/template + +{% capture step1_rest %} +POST /_render/template +{ + "source": "{% raw %}{ {{#limit}} \"size\": \"{{size}}\", {{/limit}} \"query\":{\"match\":{\"play_name\": \"{{play_name}}\"}}}{% endraw %}", + "params": { + "play_name": "Henry IV", + "limit": true, + "size": 2 + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.render_search_template( + body = { + "source": "{% raw %}{ {{#limit}} \"size\": \"{{size}}\", {{/limit}} \"query\":{\"match\":{\"play_name\": \"{{play_name}}\"}}}{% endraw %}", + "params": { + "play_name": "Henry IV", + "limit": true, + "size": 2 + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + You can also design an `if-else` condition. This command sets `size` to `2` if `limit` is `true`. Otherwise, it sets `size` to `10`: -```json -GET _search/template + +{% capture step1_rest %} +GET /_search/template +{ + "source": "{% raw %}{ {{#limit}} \"size\": \"2\", {{/limit}} {{^limit}} \"size\": \"10\", {{/limit}} \"query\":{\"match\":{\"play_name\": \"{{play_name}}\"}}}{% endraw %}", + "params": { + "play_name": "Henry IV", + "limit": true + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search_template( + body = { + "source": "{% raw %}{ {{#limit}} \"size\": \"2\", {{/limit}} {{^limit}} \"size\": \"10\", {{/limit}} \"query\":{\"match\":{\"play_name\": \"{{play_name}}\"}}}{% endraw %}", + "params": { + "play_name": "Henry IV", + "limit": true + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Loops @@ -263,8 +542,10 @@ You can also use the section tag to implement a for-each loop: When `var` is an array, the search template iterates through it and creates a `terms` query. -```json -GET _search/template + +{% capture step1_rest %} +GET /_search/template +{ + "source": "{% raw %}{\"query\":{\"terms\":{\"play_name\":[\"{{#play_name}}\",\"{{.}}\",\"{{/play_name}}\"]}}}{% endraw %}", + "params": { + "play_name": [ + "Henry IV", + "Othello" + ] + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search_template( + body = { + "source": "{% raw %}{\"query\":{\"terms\":{\"play_name\":[\"{{#play_name}}\",\"{{.}}\",\"{{/play_name}}\"]}}}{% endraw %}", + "params": { + "play_name": [ + "Henry IV", + "Othello" + ] + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + This template is rendered as: @@ -299,8 +613,10 @@ GET _search/template You can use the `join` tag to concatenate values of an array (separated by commas): -```json -GET _search/template + +{% capture step1_rest %} +GET /_search/template +{ + "source": { + "query": { + "match": { + "text_entry": "{% raw %}{{#join}}{{text_entry}}{{/join}}{% endraw %}" + } + } + }, + "params": { + "text_entry": [ + "To be", + "or not to be" + ] + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search_template( + body = { + "source": { + "query": { + "match": { + "text_entry": "{% raw %}{{#join}}{{text_entry}}{{/join}}{% endraw %}" + } + } + }, + "params": { + "text_entry": [ + "To be", + "or not to be" + ] + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Renders as: @@ -338,8 +699,10 @@ GET _search/template You can use the `toJson` tag to convert parameters to their JSON representation: -```json -GET _search/template + +{% capture step1_rest %} +GET /_search/template +{ + "source": "{\"query\":{\"bool\":{\"must\":[{\"terms\": {\"text_entries\": {% raw %}{{#toJson}}text_entries{{/toJson}}{% endraw %} }}] }}}", + "params": { + "text_entries": [ + { + "term": { + "text_entry": "love" + } + }, + { + "term": { + "text_entry": "soldier" + } + } + ] + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search_template( + body = { + "source": "{\"query\":{\"bool\":{\"must\":[{\"terms\": {\"text_entries\": {% raw %}{{#toJson}}text_entries{{/toJson}}{% endraw %} }}] }}}", + "params": { + "text_entries": [ + { + "term": { + "text_entry": "love" + } + }, + { + "term": { + "text_entry": "soldier" + } + } + ] + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + Renders as: @@ -403,21 +815,73 @@ For more information, see [Multi-search Template API]({{site.url}}{{site.baseurl To list all scripts, run the following command: -```json -GET _cluster/state/metadata?pretty&filter_path=**.stored_scripts -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_cluster/state/metadata?pretty&filter_path=**.stored_scripts +{% endcapture %} + +{% capture step1_python %} + + +response = client.cluster.state( + metric = "metadata", + params = { "pretty": "true", "filter_path": "**.stored_scripts" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To retrieve a specific search template, run the following command: -```json -GET _scripts/ -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_scripts/ +{% endcapture %} + +{% capture step1_python %} + + +response = client.get_script( + id = "" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To delete a search template, run the following command: -```json -DELETE _scripts/ -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +DELETE /_scripts/ +{% endcapture %} + +{% capture step1_python %} + + +response = client.delete_script( + id = "" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + diff --git a/_api-reference/search-apis/search-template/msearch-template.md b/_api-reference/search-apis/search-template/msearch-template.md index 080c61a55fd..69a1feae09b 100644 --- a/_api-reference/search-apis/search-template/msearch-template.md +++ b/_api-reference/search-apis/search-template/msearch-template.md @@ -78,14 +78,41 @@ Like the [bulk]({{site.url}}{{site.baseurl}}/api-reference/document-apis/bulk/) The following example `msearch/template` API request runs queries against a single index using multiple templates named `line_search_template` and `play_search_template`: -```json -GET _msearch/template + +{% capture step1_rest %} +GET /_msearch/template +{"index":"shakespeare"} +{"id":"line_search_template","params":{"text_entry":"All the world's a stage","limit":false,"size":2}} +{"index":"shakespeare"} +{"id":"play_search_template","params":{"play_name":"Henry IV"}} +{% endcapture %} + +{% capture step1_python %} + + +response = client.msearch_template( + body = ''' +{"index":"shakespeare"} +{"id":"line_search_template","params":{"text_entry":"All the world's a stage","limit":false,"size":2}} +{"index":"shakespeare"} +{"id":"play_search_template","params":{"play_name":"Henry IV"}} +''' +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/search-apis/search-template/render-template.md b/_api-reference/search-apis/search-template/render-template.md index 51c1a145d6a..8d70117c917 100644 --- a/_api-reference/search-apis/search-template/render-template.md +++ b/_api-reference/search-apis/search-template/render-template.md @@ -64,16 +64,45 @@ Both of the following request examples use the search template with the template The following example request validates a search template with the ID `play_search_template`: -```json -POST _render/template + +{% capture step1_rest %} +POST /_render/template +{ + "id": "play_search_template", + "params": { + "play_name": "Henry IV" + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.render_search_template( + body = { + "id": "play_search_template", + "params": { + "play_name": "Henry IV" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Render template using `_source` diff --git a/_api-reference/search-apis/search.md b/_api-reference/search-apis/search.md index cfb69fa5f75..79db0f7991c 100644 --- a/_api-reference/search-apis/search.md +++ b/_api-reference/search-apis/search.md @@ -114,7 +114,19 @@ version | Boolean | Whether to include the document version in the response. ## Example request -```json + +{% capture step1_rest %} GET /movies/_search { "query": { @@ -123,8 +135,28 @@ GET /movies/_search } } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "movies", + body = { + "query": { + "match": { + "text_entry": "I am the night" + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Response body fields diff --git a/_api-reference/search-apis/validate.md b/_api-reference/search-apis/validate.md index 007b251312b..1d0f08098e1 100644 --- a/_api-reference/search-apis/validate.md +++ b/_api-reference/search-apis/validate.md @@ -52,26 +52,76 @@ allow_partial_search_results | Boolean | Whether to return partial results if th The following example request uses an index named `Hamlet` created using a `bulk` request: -```json -PUT hamlet/_bulk?refresh + +{% capture step1_rest %} +PUT /hamlet/_bulk?refresh +{"index":{"_id":1}} +{"user" : { "id": "hamlet" }, "@timestamp" : "2099-11-15T14:12:12", "message" : "To Search or Not To Search"} +{"index":{"_id":2}} +{"user" : { "id": "hamlet" }, "@timestamp" : "2099-11-15T14:12:13", "message" : "My dad says that I'm such a ham."} +{% endcapture %} + +{% capture step1_python %} + + +response = client.bulk( + index = "hamlet", + params = { "refresh": "true" }, + body = ''' +{"index":{"_id":1}} +{"user" : { "id": "hamlet" }, "@timestamp" : "2099-11-15T14:12:12", "message" : "To Search or Not To Search"} +{"index":{"_id":2}} +{"user" : { "id": "hamlet" }, "@timestamp" : "2099-11-15T14:12:13", "message" : "My dad says that I'm such a ham."} +''' +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + You can then use the Validate Query API to validate an index query, as shown in the following example: -```json -GET hamlet/_validate/query?q=user.id:hamlet -``` -{% include copy.html %} + +{% capture step1_rest %} +GET /hamlet/_validate/query?q=user.id:hamlet +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.validate_query( + index = "hamlet", + params = { "q": "user.id:hamlet" }, + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The query can also be sent as a request body, as shown in the following example: -```json -GET hamlet/_validate/query + +{% capture step1_rest %} +GET /hamlet/_validate/query +{ + "query": { + "bool": { + "must": { + "query_string": { + "query": "*:*" + } + }, + "filter": { + "term": { + "user.id": "hamlet" + } + } + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.validate_query( + index = "hamlet", + body = { + "query": { + "bool": { + "must": { + "query_string": { + "query": "*:*" + } + }, + "filter": { + "term": { + "user.id": "hamlet" + } + } + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example responses @@ -107,8 +205,10 @@ If the query passes validation, then the response indicates that the query is `t If the query does not pass validation, then OpenSearch responds that the query is `false`. The following example request query includes a dynamic mapping not configured in the `hamlet` index: -```json -GET hamlet/_validate/query + +{% capture step1_rest %} +GET /hamlet/_validate/query +{ + "query": { + "query_string": { + "query": "@timestamp:foo", + "lenient": false + } + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.validate_query( + index = "hamlet", + body = { + "query": { + "query_string": { + "query": "@timestamp:foo", + "lenient": false + } + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + OpenSearch responds with the following, where the `valid` parameter is `false`: diff --git a/_api-reference/security/authentication/auth-info.md b/_api-reference/security/authentication/auth-info.md index bd1b05fac4c..2250d095e8c 100644 --- a/_api-reference/security/authentication/auth-info.md +++ b/_api-reference/security/authentication/auth-info.md @@ -29,7 +29,7 @@ component: query_parameters --> ## Query parameters -The following table lists the available query parameters. All query parameters are optional. +The following table lists the available query parameters. | Parameter | Data type | Description | | :--- | :--- | :--- | @@ -42,17 +42,47 @@ The following table lists the available query parameters. All query parameters a The following example request retrieves authentication information for the currently authenticated user: -```bash + +{% capture step1_rest %} GET /_plugins/_security/authinfo -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + +response = client.security.authinfo() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To get verbose information: -```bash + +{% capture step1_rest %} GET /_plugins/_security/authinfo?verbose=true -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.security.authinfo( + params = { "verbose": "true" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/security/authentication/change-password.md b/_api-reference/security/authentication/change-password.md index eabb594a8fe..9e421a715da 100644 --- a/_api-reference/security/authentication/change-password.md +++ b/_api-reference/security/authentication/change-password.md @@ -40,14 +40,39 @@ The request body is __required__. It is a JSON object with the following fields. ## Example request -```json + +{% capture step1_rest %} PUT /_plugins/_security/api/account { "current_password": "old-secure-password", "password": "new-secure-password" } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.security.change_password( + body = { + "current_password": "old-secure-password", + "password": "new-secure-password" + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/security/configuration/get-configuration.md b/_api-reference/security/configuration/get-configuration.md index 6fd3236a012..a75f35e0c99 100644 --- a/_api-reference/security/configuration/get-configuration.md +++ b/_api-reference/security/configuration/get-configuration.md @@ -24,10 +24,23 @@ GET /_plugins/_security/api/securityconfig ## Example request -```bash + +{% capture step1_rest %} GET /_plugins/_security/api/securityconfig -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + +response = client.security.get_configuration() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response @@ -96,20 +109,3 @@ The response body is a JSON object with the following fields. ## Usage notes - -The Get Configuration API provides a way to inspect the current security configuration. When using the API, remember the following usage notes: - -- **Read-only operation**: This API only retrieves the configuration and does not modify it. - -- **Access control**: Access to this API should be restricted to administrators because the configuration contains sensitive information about your security setup. - -## Security considerations - -The security configuration contains sensitive information about your authentication mechanisms, LDAP settings, and security policies. Consider the following security best practices: - -- Be cautious about storing or logging the output from this API, as it may contain sensitive configuration details. -- Use HTTPS/TLS when interacting with this API to prevent information disclosure. - -## Permissions - -Any users with roles defined in `plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access"]` have access to this API. \ No newline at end of file diff --git a/_api-reference/security/configuration/patch-configuration.md b/_api-reference/security/configuration/patch-configuration.md index 0f0e6b48205..ba7739223eb 100644 --- a/_api-reference/security/configuration/patch-configuration.md +++ b/_api-reference/security/configuration/patch-configuration.md @@ -39,7 +39,48 @@ The request body is **required**. It is an **array of JSON objects** (NDJSON). E The following example adds a new authentication domain and modifies an existing setting: -```json + +{% capture step1_rest %} PATCH /_plugins/_security/api/securityconfig [ { @@ -77,8 +118,56 @@ PATCH /_plugins/_security/api/securityconfig "path": "/config/dynamic/authc/legacy_auth_domain" } ] -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.security.patch_configuration( + body = [ + { + "op": "add", + "path": "/config/dynamic/authc/saml_auth_domain", + "value": { + "http_enabled": true, + "transport_enabled": false, + "order": 1, + "http_authenticator": { + "type": "saml", + "challenge": false, + "config": { + "idp": { + "metadata_url": "https://idp.example.com/saml/metadata" + }, + "sp": { + "entity_id": "opensearch" + } + } + }, + "authentication_backend": { + "type": "noop", + "config": {} + } + } + }, + { + "op": "replace", + "path": "/config/dynamic/multi_rolespan_enabled", + "value": true + }, + { + "op": "remove", + "path": "/config/dynamic/authc/legacy_auth_domain" + } + ] +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response @@ -97,48 +186,3 @@ The response body is a JSON object with the following fields. | :--- | :--- | :--- | | `status` | String | The status of the request. A successful request returns "OK". | | `message` | String | A message describing the result of the operation. | - -## JSON patch operations - -The API supports the following JSON patch operations: - -- **add**: Adds a value to an object or inserts it into an array. For existing properties, the value is replaced. -- **remove**: Removes a value from an object or array. -- **replace**: Replaces a value. -- **move**: Moves a value from one location to another. -- **copy**: Copies a value from one location to another. -- **test**: Tests that a value at the target location is equal to the specified value. - -## Usage notes - -The Patch Configuration API provides more granular control over configuration updates than the Update Configuration API but still comes with potential risks: - -- **Path format**: Paths start with `/config` followed by the JSON pointer path to the specific configuration element you want to modify. - -- **Validation**: Limited validation is performed on the patched configuration, which may lead to security vulnerabilities if misconfigured. - -- **Backup configuration**: Always back up your current security configuration before making changes. - -- **Testing**: Test configuration changes in a development environment before deploying them to production. - -## Enabling this API - -By default, this API is disabled for security reasons. To enable it, perform the following steps: - -1. Update the `opensearch.yml` file with the following: - - ``` - plugins.security.unsupported.restapi.allow_securityconfig_modification: true - ``` - {% include copy.html %} - -2. Update the Security plugin's `config.yml` file with the following: - - ``` - plugins.security.restapi.endpoints_disabled.securityconfig: "false" - ``` - {% include copy.html %} - -3. Restart your OpenSearch cluster. - -Due to the potential security implications, enabling this API is generally not recommended for production environments. \ No newline at end of file diff --git a/_api-reference/security/configuration/update-configuration.md b/_api-reference/security/configuration/update-configuration.md index 523ad1a0a88..3f4d34521a3 100644 --- a/_api-reference/security/configuration/update-configuration.md +++ b/_api-reference/security/configuration/update-configuration.md @@ -63,7 +63,50 @@ The request body is **required**. It is a JSON object with the following fields. The following example updates the security configuration to configure basic authentication and an internal user database: -```json + +{% capture step1_rest %} PUT /_plugins/_security/api/securityconfig/config { "dynamic": { @@ -103,8 +146,58 @@ PUT /_plugins/_security/api/securityconfig/config "do_not_fail_on_forbidden_empty": false } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.security.update_configuration( + body = { + "dynamic": { + "filtered_alias_mode": "warn", + "disable_rest_auth": false, + "disable_intertransport_auth": false, + "respect_request_indices_options": false, + "opensearch-dashboards": { + "multitenancy_enabled": true, + "server_username": "kibanaserver", + "index": ".opensearch-dashboards" + }, + "http": { + "anonymous_auth_enabled": false + }, + "authc": { + "basic_internal_auth_domain": { + "http_enabled": true, + "transport_enabled": true, + "order": 0, + "http_authenticator": { + "challenge": true, + "type": "basic", + "config": {} + }, + "authentication_backend": { + "type": "intern", + "config": {} + }, + "description": "Authenticate via HTTP Basic against internal users database" + } + }, + "auth_failure_listeners": {}, + "do_not_fail_on_forbidden": false, + "multi_rolespan_enabled": true, + "hosts_resolver_mode": "ip-only", + "do_not_fail_on_forbidden_empty": false + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response @@ -143,9 +236,3 @@ The Update Configuration API allows you to directly modify the Security plugin's ## Enabling this API By default, this API is disabled for security reasons. To enable it, you need to: - -1. Update the Security plugin's `config.yml` file. -2. Add the setting `plugins.security.restapi.endpoints_disabled.securityconfig: "false"`. -3. Restart your OpenSearch cluster. - -Due to the potential security implications, enabling this API is generally not recommended for production environments. \ No newline at end of file diff --git a/_api-reference/security/configuration/upgrade-check.md b/_api-reference/security/configuration/upgrade-check.md index 9ad11733023..3d3e5c647c6 100644 --- a/_api-reference/security/configuration/upgrade-check.md +++ b/_api-reference/security/configuration/upgrade-check.md @@ -25,10 +25,23 @@ GET /_plugins/_security/api/_upgrade_check ## Example request -```bash + +{% capture step1_rest %} GET /_plugins/_security/api/_upgrade_check -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + +response = client.security.config_upgrade_check() +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/security/configuration/upgrade-perform.md b/_api-reference/security/configuration/upgrade-perform.md index 7d14135de46..a4c662e70a6 100644 --- a/_api-reference/security/configuration/upgrade-perform.md +++ b/_api-reference/security/configuration/upgrade-perform.md @@ -34,13 +34,42 @@ The request body is optional. It is a JSON object with the following fields. The following example request performs upgrades on only the `roles` and `config` components: -```json -POST /_plugins/_security/api/_upgrade_perform + +{% capture step1_rest %} +POST /_plugins/_security/api/_upgrade_perform +{ + "config": [ + "roles", + "config" + ] +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.security.config_upgrade_perform( + body = { + "config": [ + "roles", + "config" + ] + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + To upgrade all components requiring it, you can omit the request body. @@ -74,21 +103,3 @@ If no components require upgrades, you'll receive a response similar to the foll ``` ## Response body fields - -The response body is a JSON object with the following fields. - -| Property | Data type | Description | -| :--- | :--- | :--- | -| `status` | String | The status of the upgrade operation. A successful operation returns "OK". | -| `upgrades` | Object | A detailed breakdown of the upgrades performed. Each key represents a configuration component that was upgraded, with an array of string descriptions detailing the specific changes made. | - -## Usage notes - -Consider the following important points when using this API: - -- Before performing upgrades, we recommend first running the Upgrade Check API to identify which components need to be upgraded. -- Always back up your security configuration before performing upgrades. -- You must have administrator privileges to use this API. -- This API makes actual changes to your configuration, unlike the Upgrade Check API, which only identifies required changes. -- For clusters in production environments, consider first testing the upgrade process in a staging environment. -- After performing upgrades, verify that your security settings still work as expected. \ No newline at end of file diff --git a/_api-reference/snapshots/cleanup-snapshot-repository.md b/_api-reference/snapshots/cleanup-snapshot-repository.md index 0521299ad97..2583972b9ad 100644 --- a/_api-reference/snapshots/cleanup-snapshot-repository.md +++ b/_api-reference/snapshots/cleanup-snapshot-repository.md @@ -37,10 +37,27 @@ The following table lists the available query parameters. All query parameters a The following request removes all stale data from the repository `my_backup`: -```json + +{% capture step1_rest %} POST /_snapshot/my_backup/_cleanup -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.cleanup_repository( + repository = "my_backup" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/snapshots/clone-snapshot.md b/_api-reference/snapshots/clone-snapshot.md index da026bcf95c..76b206becaf 100644 --- a/_api-reference/snapshots/clone-snapshot.md +++ b/_api-reference/snapshots/clone-snapshot.md @@ -46,11 +46,11 @@ include_deprecated: false --> ## Query parameters -The following table lists the available query parameters. All query parameters are optional. +The following table lists the available query parameters. | Parameter | Data type | Description | | :--- | :--- | :--- | -| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters](https://opensearch.org/docs/latest/api-reference/common-parameters/#time-units). | @@ -59,13 +59,41 @@ The following table lists the available query parameters. All query parameters a The following request clones indexes `index_a` and `index_b` from `my_snapshot`, a snapshot located in the snapshot repository `my-opensearch-repo`, into a new snapshot in the same repository called `my_new_snapshot`: -```json + +{% capture step1_rest %} PUT /_snapshot/my-opensearch-repo/my_snapshot/_clone/my_new_snapshot { “indices” : “index_a,index_b” } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.clone( + repository = "my-opensearch-repo", + snapshot = "my_snapshot", + target_snapshot = "my_new_snapshot", + body = ''' +{ + “indices” : “index_a,index_b” +} +''' +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/snapshots/create-repository.md b/_api-reference/snapshots/create-repository.md index 4eb0a541dae..83e4c068b72 100644 --- a/_api-reference/snapshots/create-repository.md +++ b/_api-reference/snapshots/create-repository.md @@ -103,7 +103,18 @@ The `server_side_encryption` setting is removed as of OpenSearch 3.1.0. S3 appli The following example registers an `fs` repository using the local directory `/mnt/snapshots` as `location`: -```json + +{% capture step1_rest %} PUT /_snapshot/my-fs-repository { "type": "fs", @@ -111,15 +122,46 @@ PUT /_snapshot/my-fs-repository "location": "/mnt/snapshots" } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.create_repository( + repository = "my-fs-repository", + body = { + "type": "fs", + "settings": { + "location": "/mnt/snapshots" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### `s3` The following request registers a new S3 repository called `my-opensearch-repo` in an existing bucket called `my-open-search-bucket`. By default, all snapshots are stored in the `my/snapshot/directory`: -```json + +{% capture step1_rest %} PUT /_snapshot/my-opensearch-repo { "type": "s3", @@ -128,13 +170,49 @@ PUT /_snapshot/my-opensearch-repo "base_path": "my/snapshot/directory" } } -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.create_repository( + repository = "my-opensearch-repo", + body = { + "type": "s3", + "settings": { + "bucket": "my-open-search-bucket", + "base_path": "my/snapshot/directory" + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + The following request registers a new S3 repository called `my-opensearch-repo` in an existing bucket called `my-open-search-bucket`. By default, all snapshots are stored in the `my/snapshot/directory`. Additionally, this repository is configured to use [SSE-KMS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#encryption-context), and the expected bucket owner AWS account ID is `123456789000`. -```json + +{% capture step1_rest %} PUT /_snapshot/my-opensearch-repo { "type": "s3", @@ -147,9 +225,34 @@ PUT /_snapshot/my-opensearch-repo "expected_bucket_owner": "123456789000", } } -' -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.create_repository( + repository = "my-opensearch-repo", + body = ''' +{ + "type": "s3", + "settings": { + "bucket": "my-open-search-bucket", + "base_path": "my/snapshot/directory", + "server_side_encryption_type": "aws:kms", + "server_side_encryption_kms_key_id": "arn:aws:kms:us-east-1:123456789000:key/kms-key-id", + "server_side_encryption_encryption_context": "{\"additional-enc-ctx\": \"sample-context\"}", + "expected_bucket_owner": "123456789000", + } +} +''' +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/snapshots/create-snapshot.md b/_api-reference/snapshots/create-snapshot.md index eb00e1c1117..68fe7f995d0 100644 --- a/_api-reference/snapshots/create-snapshot.md +++ b/_api-reference/snapshots/create-snapshot.md @@ -52,25 +52,75 @@ Field | Data type | Description The following request creates a snapshot called `my-first-snapshot` in an S3 repository called `my-s3-repository`. A request body is not included because it is optional. -```json -POST _snapshot/my-s3-repository/my-first-snapshot -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +POST /_snapshot/my-s3-repository/my-first-snapshot +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.create( + repository = "my-s3-repository", + snapshot = "my-first-snapshot", + body = { "Insert body here" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Request with a body You can also add a request body to include or exclude certain indices or specify other settings: -```json -PUT _snapshot/my-s3-repository/2 + +{% capture step1_rest %} +PUT /_snapshot/my-s3-repository/2 +{ + "indices": "opensearch-dashboards*,my-index*,-my-index-2016", + "ignore_unavailable": true, + "include_global_state": false, + "partial": false +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.create( + repository = "my-s3-repository", + snapshot = "2", + body = { + "indices": "opensearch-dashboards*,my-index*,-my-index-2016", + "ignore_unavailable": true, + "include_global_state": false, + "partial": false + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example responses diff --git a/_api-reference/snapshots/delete-snapshot-repository.md b/_api-reference/snapshots/delete-snapshot-repository.md index f0c0632a483..ae39881e115 100644 --- a/_api-reference/snapshots/delete-snapshot-repository.md +++ b/_api-reference/snapshots/delete-snapshot-repository.md @@ -31,10 +31,27 @@ repository | String | Repository to delete. | The following request deletes the `my-opensearch-repo` repository: -````json -DELETE _snapshot/my-opensearch-repo -```` -{% include copy-curl.html %} + +{% capture step1_rest %} +DELETE /_snapshot/my-opensearch-repo +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.delete_repository( + repository = "my-opensearch-repo" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/snapshots/delete-snapshot.md b/_api-reference/snapshots/delete-snapshot.md index d8cba2dd67e..1253d83637e 100644 --- a/_api-reference/snapshots/delete-snapshot.md +++ b/_api-reference/snapshots/delete-snapshot.md @@ -36,10 +36,28 @@ snapshot | String | Snapshot to delete. | The following request deletes a snapshot called `my-first-snapshot` from the `my-opensearch-repo` repository: -```json -DELETE _snapshot/my-opensearch-repo/my-first-snapshot -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +DELETE /_snapshot/my-opensearch-repo/my-first-snapshot +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.delete( + repository = "my-opensearch-repo", + snapshot = "my-first-snapshot" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/snapshots/get-snapshot-repository.md b/_api-reference/snapshots/get-snapshot-repository.md index baf6e2a874e..a1acdc01a22 100644 --- a/_api-reference/snapshots/get-snapshot-repository.md +++ b/_api-reference/snapshots/get-snapshot-repository.md @@ -39,10 +39,27 @@ GET /_snapshot/ The following request retrieves information for the `my-opensearch-repo` repository: -````json + +{% capture step1_rest %} GET /_snapshot/my-opensearch-repo -```` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.get_repository( + repository = "my-opensearch-repo" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/snapshots/get-snapshot-status.md b/_api-reference/snapshots/get-snapshot-status.md index 34a5bd54cf2..718b2aca067 100644 --- a/_api-reference/snapshots/get-snapshot-status.md +++ b/_api-reference/snapshots/get-snapshot-status.md @@ -60,13 +60,36 @@ Using the API to return the state of snapshots that are not currently running ca The following request returns the status of `my-first-snapshot` in the `my-opensearch-repo` repository. Unavailable snapshots are ignored. -````json -GET _snapshot/my-opensearch-repo/my-first-snapshot/_status + +{% capture step1_rest %} +GET /_snapshot/my-opensearch-repo/my-first-snapshot/_status +{ + "ignore_unavailable": true +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.status( + repository = "my-opensearch-repo", + snapshot = "my-first-snapshot" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + + ## Example response diff --git a/_api-reference/snapshots/get-snapshot.md b/_api-reference/snapshots/get-snapshot.md index 0fe04c61589..459afe0277e 100644 --- a/_api-reference/snapshots/get-snapshot.md +++ b/_api-reference/snapshots/get-snapshot.md @@ -35,10 +35,28 @@ GET _snapshot/// The following request retrieves information for the `my-first-snapshot` located in the `my-opensearch-repo` repository: -````json -GET _snapshot/my-opensearch-repo/my-first-snapshot -```` -{% include copy-curl.html %} + +{% capture step1_rest %} +GET /_snapshot/my-opensearch-repo/my-first-snapshot +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.get( + repository = "my-opensearch-repo", + snapshot = "my-first-snapshot" +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/snapshots/restore-snapshot.md b/_api-reference/snapshots/restore-snapshot.md index 71d2090e001..301829e02fe 100644 --- a/_api-reference/snapshots/restore-snapshot.md +++ b/_api-reference/snapshots/restore-snapshot.md @@ -70,17 +70,53 @@ storage_type | `local` indicates that all snapshot metadata and index data will The following request restores the `opendistro-reports-definitions` index from `my-first-snapshot`. The `rename_pattern` and `rename_replacement` combination causes the index to be renamed to `opendistro-reports-definitions_restored` because duplicate open index names in a cluster are not allowed. -````json + +{% capture step1_rest %} POST /_snapshot/my-opensearch-repo/my-first-snapshot/_restore { "indices": "opendistro-reports-definitions", "ignore_unavailable": true, - "include_global_state": false, + "include_global_state": false, "rename_pattern": "(.+)", "rename_replacement": "$1_restored", "include_aliases": false } -```` +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.restore( + repository = "my-opensearch-repo", + snapshot = "my-first-snapshot", + body = { + "indices": "opendistro-reports-definitions", + "ignore_unavailable": true, + "include_global_state": false, + "rename_pattern": "(.+)", + "rename_replacement": "$1_restored", + "include_aliases": false + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/snapshots/verify-snapshot-repository.md b/_api-reference/snapshots/verify-snapshot-repository.md index 56a29f4bc62..6ef2dbcceb2 100644 --- a/_api-reference/snapshots/verify-snapshot-repository.md +++ b/_api-reference/snapshots/verify-snapshot-repository.md @@ -41,9 +41,28 @@ Path parameters are optional. The following request verifies that the my-opensearch-repo is functional: -````json + +{% capture step1_rest %} POST /_snapshot/my-opensearch-repo/_verify?timeout=0s&cluster_manager_timeout=50s -```` +{% endcapture %} + +{% capture step1_python %} + + +response = client.snapshot.verify_repository( + repository = "my-opensearch-repo", + params = { "timeout": "0s", "cluster_manager_timeout": "50s" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/tasks/cancel-tasks.md b/_api-reference/tasks/cancel-tasks.md index ebffd3dcde0..74071db68ca 100644 --- a/_api-reference/tasks/cancel-tasks.md +++ b/_api-reference/tasks/cancel-tasks.md @@ -29,7 +29,7 @@ component: path_parameters --> ## Path parameters -The following table lists the available path parameters. All path parameters are optional. +The following table lists the available path parameters. | Parameter | Data type | Description | | :--- | :--- | :--- | @@ -43,7 +43,7 @@ component: query_parameters --> ## Query parameters -The following table lists the available query parameters. All query parameters are optional. +The following table lists the available query parameters. | Parameter | Data type | Description | | :--- | :--- | :--- | @@ -58,10 +58,27 @@ The following table lists the available query parameters. All query parameters a The following request cancels any tasks currently running on `opensearch-node1` and `opensearch-node2`: -``` -POST _tasks/_cancel?nodes=opensearch-node1,opensearch-node2 -``` -{% include copy-curl.html %} + +{% capture step1_rest %} +POST /_tasks/_cancel?nodes=opensearch-node1,opensearch-node2 +{% endcapture %} + +{% capture step1_python %} + + +response = client.tasks.cancel( + params = { "nodes": "opensearch-node1,opensearch-node2" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/tasks/get-tasks.md b/_api-reference/tasks/get-tasks.md index 416614b37ae..9e227adc03f 100644 --- a/_api-reference/tasks/get-tasks.md +++ b/_api-reference/tasks/get-tasks.md @@ -41,7 +41,7 @@ component: query_parameters --> ## Query parameters -The following table lists the available query parameters. All query parameters are optional. +The following table lists the available query parameters. | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | diff --git a/_api-reference/tasks/list-tasks.md b/_api-reference/tasks/list-tasks.md index 396b3e60ce6..755fe3739a0 100644 --- a/_api-reference/tasks/list-tasks.md +++ b/_api-reference/tasks/list-tasks.md @@ -27,7 +27,7 @@ component: query_parameters --> ## Query parameters -The following table lists the available query parameters. All query parameters are optional. +The following table lists the available query parameters. | Parameter | Data type | Description | Default | | :--- | :--- | :--- | :--- | @@ -45,10 +45,27 @@ The following table lists the available query parameters. All query parameters a The following request returns tasks currently running on a node named `opensearch-node1`: -```json + +{% capture step1_rest %} GET /_tasks?nodes=opensearch-node1 -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.tasks.list( + params = { "nodes": "opensearch-node1" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_api-reference/tasks/rethrottle.md b/_api-reference/tasks/rethrottle.md index 519ca486f8a..6a6593905ce 100644 --- a/_api-reference/tasks/rethrottle.md +++ b/_api-reference/tasks/rethrottle.md @@ -31,25 +31,79 @@ Parameter | Data type | Description ### Example request: Rethrottle a running delete by query task -```json + +{% capture step1_rest %} POST /_delete_by_query//_rethrottle?requests_per_second=10 -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.delete_by_query_rethrottle( + task_id = "", + params = { "requests_per_second": "10" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example request: Rethrottle a running reindex task -```json + +{% capture step1_rest %} POST /_reindex//_rethrottle?requests_per_second=20 -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.reindex_rethrottle( + task_id = "", + params = { "requests_per_second": "20" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ### Example request: Rethrottle a running update by query task -```json + +{% capture step1_rest %} POST /_update_by_query//_rethrottle?requests_per_second=5 -``` -{% include copy-curl.html %} +{% endcapture %} + +{% capture step1_python %} + + +response = client.update_by_query_rethrottle( + task_id = "", + params = { "requests_per_second": "5" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + ## Example response diff --git a/_script/insert_tags_block.py b/_script/insert_tags_block.py new file mode 100644 index 00000000000..d1dcc7d3c9e --- /dev/null +++ b/_script/insert_tags_block.py @@ -0,0 +1,113 @@ +#!/usr/bin/env python3 +import argparse +import pathlib +import re +from typing import Optional, Iterable + +# Match ##/###/#### heading + "Example request(s)" (case-insensitive) +HEADING_RE = re.compile( + r"^(?P\s{0,3})(?P#{2,4})\s+Example requests?\b\s*$", + re.IGNORECASE, +) + +# Detect start of an existing spec-insert block +START_TAG_RE = re.compile(r"^\s* + +""" + +def find_insert_position(lines: list[str]) -> Optional[int]: + """Return the index *after* the heading line where we should insert, or None.""" + in_fence = False + for i, line in enumerate(lines): + if FENCE_RE.match(line): + in_fence = not in_fence + continue + if in_fence: + continue + if HEADING_RE.match(line): + return i + 1 + return None + +def has_block_immediately_after(lines: list[str], pos: int) -> bool: + """True if the next non-blank line at/after pos starts a spec-insert block.""" + j = pos + while j < len(lines) and lines[j].strip() == "": + j += 1 + return j < len(lines) and START_TAG_RE.match(lines[j]) is not None + +def process_file(p: pathlib.Path, write: bool) -> bool: + if not p.is_file() or p.suffix.lower() != ".md": + return False + text = p.read_text(encoding="utf-8") + lines = text.splitlines(keepends=True) + + insert_at = find_insert_position(lines) + if insert_at is None: + return False + + if has_block_immediately_after(lines, insert_at): + return False + + needs_blank = not (insert_at < len(lines) and lines[insert_at].strip() == "") + block = (("\n" if needs_blank else "") + SPEC_BLOCK) + + if write: + lines.insert(insert_at, block) + p.write_text("".join(lines), encoding="utf-8") + return True + +def iter_targets(paths: Iterable[pathlib.Path], recursive: bool) -> Iterable[pathlib.Path]: + for path in paths: + if path.is_file(): + yield path + elif path.is_dir(): + if recursive: + yield from path.rglob("*.md") + else: + yield from (p for p in path.glob("*.md") if p.is_file()) + +def main(): + ap = argparse.ArgumentParser( + description="Insert a blank spec-insert block under Example request headings." + ) + ap.add_argument( + "paths", nargs="*", default=["_api-reference"], + help="Files and/or directories to process (default: _api-reference)" + ) + ap.add_argument( + "--no-recursive", action="store_true", + help="When a directory is given, only scan its top level (no recursion)." + ) + ap.add_argument("--dry-run", action="store_true", help="Preview changes only.") + args = ap.parse_args() + + base_paths = [pathlib.Path(p).resolve() for p in args.paths] + recursive = not args.no_recursive + write = not args.dry_run + + changed = [] + for target in iter_targets(base_paths, recursive=recursive): + try: + if process_file(target, write=write): + changed.append(str(target)) + except UnicodeDecodeError: + # Skip non-UTF8 files + continue + + verb = "Would modify" if args.dry_run else "Modified" + print(f"{verb} {len(changed)} file(s).") + if changed: + print("\n".join(changed)) + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/spec-insert/lib/api/action.rb b/spec-insert/lib/api/action.rb index f0a8fdcf1df..b6a5b5f9661 100644 --- a/spec-insert/lib/api/action.rb +++ b/spec-insert/lib/api/action.rb @@ -103,6 +103,26 @@ def deprecated; @spec.deprecated; end # @return [String] Deprecation message def deprecation_message; @spec['x-deprecation-message']; end + def self.find_by_rest(rest_line) + method, raw_path = rest_line.strip.split(' ', 2) + return nil unless method && raw_path + + # Remove query parameters + path = raw_path.split('?').first + + all.find do |action| + action.operations.any? do |op| + op.http_verb.casecmp?(method) && + path_template_matches?(op.url, path) + end + end + end + + def self.path_template_matches?(template, actual) + # "/{index}/_doc/{id}" => "^/[^/]+/_doc/[^/]+$" + regex = Regexp.new("^" + template.gsub(/\{[^\/]+\}/, '[^/]+') + "$") + regex.match?(actual) + end # @return [String] API reference def api_reference; @operation.external_docs.url; end end diff --git a/spec-insert/lib/doc_processor.rb b/spec-insert/lib/doc_processor.rb index 8140b85102b..0edab19525a 100644 --- a/spec-insert/lib/doc_processor.rb +++ b/spec-insert/lib/doc_processor.rb @@ -53,8 +53,9 @@ def find_insertions(lines) start_indices.zip(end_indices).map do |start, finish| args = InsertArguments.from_marker(lines[start..finish]) + next nil if args.skip? [start, finish, SpecInsert.new(args)] - end + end.compact end # @param [Array] start_indices diff --git a/spec-insert/lib/insert_arguments.rb b/spec-insert/lib/insert_arguments.rb index aa05cc01df1..737a136df34 100644 --- a/spec-insert/lib/insert_arguments.rb +++ b/spec-insert/lib/insert_arguments.rb @@ -2,11 +2,13 @@ require_relative 'utils' require_relative 'spec_insert_error' - +require 'json' # Doc Insert Arguments class InsertArguments attr_reader :raw + Rest = Struct.new(:verb, :path, :query, :body, :raw_lines, keyword_init:true) + # @param [Hash] args raw arguments read from the doc insert marker def initialize(args) @raw = args.to_h.with_indifferent_access @@ -15,17 +17,52 @@ def initialize(args) # @param [Array] lines the lines between "" # @return [InsertArguments] def self.from_marker(lines) + # Extract lines between start and end marker end_index = lines.each_with_index.find { |line, _index| line.match?(/^\s*-->/) }&.last&.- 1 - args = lines[1..end_index].filter { |line| line.include?(':') }.to_h do |line| - key, value = line.split(':') - [key.strip, value.strip] + args = {} + i = 1 + + while i <= end_index + line = lines[i] + next unless line.include?(':') + + key, value = line.split(':', 2) + key = key.strip + value = value.strip + + if value == '|' + # Multi-line block value + multiline_value = [] + i += 1 + while i <= end_index + line = lines[i] + break if line.match?(/^\s*\w+:/) # Stop at new top-level key + multiline_value << line.rstrip + i += 1 + end + args[key] = multiline_value.join("\n") + next + else + args[key] = value + end + i += 1 end + new(args) end # @return [String] def api - @raw['api'] + return @raw['api'] if @raw['api'].present? + + if rest_line = rest&.raw_lines&.first + inferred_action = Api::Action.find_by_rest(rest_line) + raise SpecInsertError, "Could not infer API from rest line: #{rest_line}" unless inferred_action + + return inferred_action.full_name + end + + nil end # @return [String] @@ -41,11 +78,19 @@ def columns parse_array(@raw['columns']) || [] end + def skip? + parse_boolean(@raw['skip'], default: false) + end + # @return [Boolean] def pretty parse_boolean(@raw['pretty'], default: false) end + def include_client_setup + parse_boolean(@raw['include_client_setup'], default: false) + end + # @return [Boolean] def include_global parse_boolean(@raw['include_global'], default: false) @@ -61,6 +106,34 @@ def omit_header parse_boolean(@raw['omit_header'], default: false) end + # @return [Rest, nil] + def rest + lines = @raw['rest']&.split("\n")&.map(&:strip) || [] + return nil if lines.empty? + + verb, full_path = lines.first.to_s.split + path, query_string = full_path.to_s.split('?', 2) + + query = (query_string || "").split('&').to_h do |pair| + k, v = pair.split('=', 2) + [k, v || "true"] + end + + body = begin + JSON.parse(@raw['body']) if @raw['body'] + rescue JSON::ParserError + @raw['body'] + end + + Rest.new( + verb: verb, + path: path, + query: query, + body: body, + raw_lines: lines + ) + end + private # @param [String] value comma-separated array diff --git a/spec-insert/lib/jekyll-spec-insert.rb b/spec-insert/lib/jekyll-spec-insert.rb index f474fdd1235..1ac8d4ea884 100644 --- a/spec-insert/lib/jekyll-spec-insert.rb +++ b/spec-insert/lib/jekyll-spec-insert.rb @@ -30,6 +30,7 @@ def self.process_file(file, fail_on_error: false) raise e if fail_on_error relative_path = Pathname(file).relative_path_from(Pathname.new(Dir.pwd)) Jekyll.logger.error "Error processing #{relative_path}: #{e.message}" + Jekyll.logger.error "Error backtrace: #{e.backtrace.join("\n")}" end def self.watch(fail_on_error: false) @@ -43,4 +44,4 @@ def self.watch(fail_on_error: false) trap('TERM') { exit } sleep end -end +end \ No newline at end of file diff --git a/spec-insert/lib/renderers/example_code.rb b/spec-insert/lib/renderers/example_code.rb new file mode 100644 index 00000000000..301e2b76203 --- /dev/null +++ b/spec-insert/lib/renderers/example_code.rb @@ -0,0 +1,30 @@ +# frozen_string_literal: true + +require 'json' +require_relative 'example_code_python' + +class ExampleCode < BaseMustacheRenderer + self.template_file = "#{__dir__}/templates/example_code.mustache" + + def initialize(action, args) + super(action, args) + end + + def rest_lines + @args.rest.raw_lines + end + + def rest_code + base = rest_lines.join("\n") + body = @args.rest.body + if body + body.is_a?(String) ? base + "\n" + body : base + "\n" + JSON.pretty_generate(body) + else + base + end + end + + def python_code + ExampleCodePython.new(@action, @args).render + end +end diff --git a/spec-insert/lib/renderers/example_code_python.rb b/spec-insert/lib/renderers/example_code_python.rb new file mode 100644 index 00000000000..0e3028c7487 --- /dev/null +++ b/spec-insert/lib/renderers/example_code_python.rb @@ -0,0 +1,157 @@ +require 'json' + +class ExampleCodePython < BaseMustacheRenderer + self.template_file = "#{__dir__}/templates/example_code.python.mustache" + + def initialize(action, args) + super(action, args) + end + + def call_code + return "# Invalid action" unless @action&.full_name + client_setup = <<~PYTHON + from opensearchpy import OpenSearch + + host = 'localhost' + port = 9200 + auth = ('admin', 'admin') # For testing only. Don't store credentials in code. + ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA. + + # Create the client with SSL/TLS enabled, but hostname verification disabled. + client = OpenSearch( + hosts = [{'host': host, 'port': port}], + http_compress = True, # enables gzip compression for request bodies + http_auth = auth, + use_ssl = True, + verify_certs = True, + ssl_assert_hostname = False, + ssl_show_warn = False, + ca_certs = ca_certs_path + ) + + PYTHON + + parts = @action.full_name.split('.') + client_call = "client" + + if parts.length == 2 + namespace, method = parts + client_call += ".#{namespace}.#{method}" + else + namespace = parts[0] + client_call += ".#{namespace}" + end + + args = [] + + rest = @args.rest + http_verb = rest.verb + full_path = [rest.path, rest.query&.map { |k,v| "#{k}=#{v}" }.join('&')].compact.join('?') + path_part, query_string = full_path.to_s.split('?', 2) + path_values = path_part.split('/').reject(&:empty?) + + spec_path = match_spec_path(full_path) + spec_parts = spec_path.split('/').reject(&:empty?) + + param_mapping = {} + spec_parts.each_with_index do |part, i| + if part =~ /\{(.+?)\}/ && path_values[i] + param_mapping[$1] = path_values[i] + end + end + + @action.path_parameters.each do |param| + if param_mapping.key?(param.name) + args << "#{param.name} = \"#{param_mapping[param.name]}\"" + end + end + + if query_string + query_pairs = query_string.split('&').map { |s| s.split('=', 2) } + query_hash = query_pairs.map do |k, v| + "\"#{k}\": \"#{v}\"" + end.join(', ') + args << "params = { #{query_hash} }" unless query_hash.empty? + end + + body = rest.body + if expects_body?(http_verb) + if body + raw_body = @args.raw['body'] + begin + parsed = JSON.parse(raw_body) + pretty = JSON.pretty_generate(parsed).gsub(/^/, ' ') + args << "body = #{pretty}" + rescue JSON::ParserError + if raw_body.include?("\n") + args << "body = '''\n#{raw_body.rstrip}\n'''" + else + args << "body = #{JSON.dump(raw_body)}" + end + end + else + args << 'body = { "Insert body here" }' + end + end + + python_setup = if args.empty? + "response = #{client_call}()" + else + final_args = args.map { |line| " #{line}" }.join(",\n") + <<~PYTHON + + response = #{client_call}( + #{final_args} + ) + PYTHON + end + if @args.include_client_setup + client_setup + python_setup + else + python_setup + end + end + + private + + def expects_body?(verb) + verb = verb.downcase + @action.operations.any? do |op| + op.http_verb.to_s.downcase == verb && + op.spec&.requestBody && + op.spec.requestBody.respond_to?(:content) + end + end + + def match_spec_path(full_path) + request_path = full_path.split('?').first + request_segments = request_path.split('/').reject(&:empty?) + + best = '' + best_score = -1 + + @action.urls.each do |spec_path| + spec_segments = spec_path.split('/').reject(&:empty?) + next unless spec_segments.size == request_segments.size + + score = 0 + spec_segments.each_with_index do |seg, i| + if seg.start_with?('{') + score += 1 + elsif seg == request_segments[i] + score += 2 + else + score = -1 + break + end + end + + if score > best_score + best = spec_path + best_score = score + end + end + + best + end +end diff --git a/spec-insert/lib/renderers/spec_insert.rb b/spec-insert/lib/renderers/spec_insert.rb index 87289a9baf8..662da7fc1c9 100644 --- a/spec-insert/lib/renderers/spec_insert.rb +++ b/spec-insert/lib/renderers/spec_insert.rb @@ -7,6 +7,7 @@ require_relative 'path_parameters' require_relative 'query_parameters' require_relative 'body_parameters' +require_relative 'example_code' # Class to render spec insertions class SpecInsert < BaseMustacheRenderer @@ -16,18 +17,25 @@ class SpecInsert < BaseMustacheRenderer def initialize(args) action = Api::Action.by_full_name[args.api] super(action, args) - raise SpecInsertError, '`api` argument not specified.' unless @args.api + raise SpecInsertError, '`api` argument could not be resolved.' unless @action raise SpecInsertError, "API Action '#{@args.api}' does not exist in the spec." unless @action end def arguments - @args.raw.map { |key, value| { key:, value: } } + @args.raw.map do |key, value| + if value.is_a?(String) && value.include?("\n") + { key: key, value: "|\n" + value } + else + { key: key, value: value } + end + end end def api; @args.api end def component; @args.component end def content + return "" if @args.skip? raise SpecInsertError, '`component` argument not specified.' unless @args.component case @args.component.to_sym when :query_parameters @@ -40,8 +48,10 @@ def content BodyParameters.new(@action, @args, is_request: true).render when :response_body_parameters BodyParameters.new(@action, @args, is_request: false).render + when :example_code + ExampleCode.new(@action, @args).render else - raise SpecInsertError, "Invalid component: #{@args.component}" + raise SpecInsertError, "Invalid component: #{@args.component}, from spec_insert.rb " end end end diff --git a/spec-insert/lib/renderers/templates/example_code.mustache b/spec-insert/lib/renderers/templates/example_code.mustache new file mode 100644 index 00000000000..5076450346d --- /dev/null +++ b/spec-insert/lib/renderers/templates/example_code.mustache @@ -0,0 +1,11 @@ +{% capture step1_rest %} +{{{rest_code}}} +{% endcapture %} + +{% capture step1_python %} +{{{python_code}}} +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} \ No newline at end of file diff --git a/spec-insert/lib/renderers/templates/example_code.python.mustache b/spec-insert/lib/renderers/templates/example_code.python.mustache new file mode 100644 index 00000000000..afc70070b77 --- /dev/null +++ b/spec-insert/lib/renderers/templates/example_code.python.mustache @@ -0,0 +1,3 @@ +{{! example_code.python.mustache }} + +{{{call_code}}} \ No newline at end of file diff --git a/spec-insert/lib/utils.rb b/spec-insert/lib/utils.rb index 22bd273db2b..8f53d71931f 100644 --- a/spec-insert/lib/utils.rb +++ b/spec-insert/lib/utils.rb @@ -13,7 +13,8 @@ module Utils 'query_parameters' => 'Query Parameters', 'path_parameters' => 'Path Parameters', 'request_body_parameters' => 'Request Body Parameters', - 'response_body_parameters' => 'Response Body Parameters' + 'response_body_parameters' => 'Response Body Parameters', + 'example_code' => 'Example Code' }.freeze # @return [Array] list of markdown files to insert the spec components into diff --git a/spec-insert/spec/_fixtures/expected_output/example_code.md b/spec-insert/spec/_fixtures/expected_output/example_code.md new file mode 100644 index 00000000000..cce9be74519 --- /dev/null +++ b/spec-insert/spec/_fixtures/expected_output/example_code.md @@ -0,0 +1,229 @@ + +{% capture step1_rest %} +GET /_cat/health?pretty=true&human=false +{% endcapture %} + +{% capture step1_python %} + +from opensearchpy import OpenSearch + +host = 'localhost' +port = 9200 +auth = ('admin', 'admin') # For testing only. Don't store credentials in code. +ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA. + +# Create the client with SSL/TLS enabled, but hostname verification disabled. +client = OpenSearch( + hosts = [{'host': host, 'port': port}], + http_compress = True, # enables gzip compression for request bodies + http_auth = auth, + use_ssl = True, + verify_certs = True, + ssl_assert_hostname = False, + ssl_show_warn = False, + ca_certs = ca_certs_path +) + + +response = client.cat.health( + params = { "pretty": "true", "human": "false" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + + + +{% capture step1_rest %} +GET /{index}/_search?analyzer=standard&expand_wildcards=all +{% endcapture %} + +{% capture step1_python %} + + +response = client.search( + index = "{index}", + params = { "analyzer": "standard", "expand_wildcards": "all" } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + + + + + + +{% capture step1_rest %} +PUT /_settings?expand_wildcards=all&analyze_wildcard +{ + "index": { + "number_of_replicas": 2 + } +} +{% endcapture %} + +{% capture step1_python %} + + +response = client.indices.put_settings( + params = { "expand_wildcards": "all", "analyze_wildcard": "true" }, + body = { + "index": { + "number_of_replicas": 2 + } + } +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + + + +{% capture step1_rest %} +POST /_bulk?expand_wildcards=all +{"index":{"_index":"test","_id":"1"}} +{"field1":"value1"} +{"delete":{"_index":"test","_id":"2"}} +{% endcapture %} + +{% capture step1_python %} + +from opensearchpy import OpenSearch + +host = 'localhost' +port = 9200 +auth = ('admin', 'admin') # For testing only. Don't store credentials in code. +ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA. + +# Create the client with SSL/TLS enabled, but hostname verification disabled. +client = OpenSearch( + hosts = [{'host': host, 'port': port}], + http_compress = True, # enables gzip compression for request bodies + http_auth = auth, + use_ssl = True, + verify_certs = True, + ssl_assert_hostname = False, + ssl_show_warn = False, + ca_certs = ca_certs_path +) + + +response = client.bulk( + params = { "expand_wildcards": "all" }, + body = ''' +{"index":{"_index":"test","_id":"1"}} +{"field1":"value1"} +{"delete":{"_index":"test","_id":"2"}} +''' +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + + + +{% capture step1_rest %} +POST /_bulk?expand_wildcards=all +{ "delete": { "_index": "movies", "_id": "tt2229499" } } +{ "index": { "_index": "movies", "_id": "tt1979320" } } +{ "title": "Rush", "year": 2013 } +{ "create": { "_index": "movies", "_id": "tt1392214" } } +{ "title": "Prisoners", "year": 2013 } +{ "update": { "_index": "movies", "_id": "tt0816711" } } +{ "doc" : { "title": "World War Z" } } +{% endcapture %} + +{% capture step1_python %} + +from opensearchpy import OpenSearch + +host = 'localhost' +port = 9200 +auth = ('admin', 'admin') # For testing only. Don't store credentials in code. +ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA. + +# Create the client with SSL/TLS enabled, but hostname verification disabled. +client = OpenSearch( + hosts = [{'host': host, 'port': port}], + http_compress = True, # enables gzip compression for request bodies + http_auth = auth, + use_ssl = True, + verify_certs = True, + ssl_assert_hostname = False, + ssl_show_warn = False, + ca_certs = ca_certs_path +) + + +response = client.bulk( + params = { "expand_wildcards": "all" }, + body = ''' +{ "delete": { "_index": "movies", "_id": "tt2229499" } } +{ "index": { "_index": "movies", "_id": "tt1979320" } } +{ "title": "Rush", "year": 2013 } +{ "create": { "_index": "movies", "_id": "tt1392214" } } +{ "title": "Prisoners", "year": 2013 } +{ "update": { "_index": "movies", "_id": "tt0816711" } } +{ "doc" : { "title": "World War Z" } } +''' +) + +{% endcapture %} + +{% include code-block.html + rest=step1_rest + python=step1_python %} + diff --git a/spec-insert/spec/_fixtures/input/example_code.md b/spec-insert/spec/_fixtures/input/example_code.md new file mode 100644 index 00000000000..ad91834cd78 --- /dev/null +++ b/spec-insert/spec/_fixtures/input/example_code.md @@ -0,0 +1,57 @@ + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/spec-insert/spec/_fixtures/opensearch_spec.yaml b/spec-insert/spec/_fixtures/opensearch_spec.yaml index b95265eb749..6acfa03404c 100644 --- a/spec-insert/spec/_fixtures/opensearch_spec.yaml +++ b/spec-insert/spec/_fixtures/opensearch_spec.yaml @@ -69,6 +69,8 @@ paths: url: https://docs.opensearch.org/latest/api-reference/index-apis/update-settings/ requestBody: $ref: '#/components/requestBodies/indices.put_settings' + parameters: + - $ref: '#/components/parameters/cat.health___query.expand_wildcard' responses: '200': $ref: '#/components/responses/indices.put_settings___200' @@ -81,6 +83,8 @@ paths: description: Allows to perform multiple index/update/delete operations in a single request. externalDocs: url: https://docs.opensearch.org/latest/api-reference/document-apis/bulk/ + parameters: + - $ref: '#/components/parameters/cat.health___query.expand_wildcard' requestBody: $ref: '#/components/requestBodies/bulk' components: diff --git a/spec-insert/spec/doc_processor_spec.rb b/spec-insert/spec/doc_processor_spec.rb index 4f2c46b9e7d..c5f2a99d2fc 100644 --- a/spec-insert/spec/doc_processor_spec.rb +++ b/spec-insert/spec/doc_processor_spec.rb @@ -25,4 +25,8 @@ def test_file(file_name) it 'inserts the body param tables correctly' do test_file('body_params_tables') end + + it 'inserts translations correctly' do + test_file('example_code') + end end