diff --git a/API_STYLE_GUIDE.md b/API_STYLE_GUIDE.md index a6e0551f17..a058bbe7c2 100644 --- a/API_STYLE_GUIDE.md +++ b/API_STYLE_GUIDE.md @@ -103,7 +103,7 @@ For GET and DELETE APIs: Introduce what you can do with the optional parameters. Parameter | Data type | Description :--- | :--- | :--- -### Request fields +### Request body fields For PUT and POST APIs: Introduce what the request fields are allowed to provide in the body of the request. @@ -189,7 +189,7 @@ The `POST _reindex` request returns the following response fields: } ``` -### Response fields +### Response body fields For PUT and POST APIs: Define all allowable response fields that can be returned in the body of the response. diff --git a/_api-reference/analyze-apis.md b/_api-reference/analyze-apis.md index ac8e9e249f..0443752096 100644 --- a/_api-reference/analyze-apis.md +++ b/_api-reference/analyze-apis.md @@ -81,7 +81,7 @@ text | String or Array of Strings | Text to analyze. If you provide an array of [Set a token limit](#set-a-token-limit) -#### Analyze array of text strings +### Analyze array of text strings When you pass an array of strings to the `text` field, it is analyzed as a multi-value field. @@ -145,7 +145,7 @@ The previous request returns the following fields: } ```` -#### Apply a built-in analyzer +### Apply a built-in analyzer If you omit the `index` path parameter, you can apply any of the built-in analyzers to the text string. @@ -190,7 +190,7 @@ The previous request returns the following fields: } ```` -#### Apply a custom analyzer +### Apply a custom analyzer You can create your own analyzer and specify it in an analyze request. @@ -244,7 +244,7 @@ The previous request returns the following fields: } ```` -#### Apply a custom transient analyzer +### Apply a custom transient analyzer You can build a custom transient analyzer from tokenizers, token filters, or character filters. Use the `filter` parameter to specify token filters. @@ -373,7 +373,7 @@ The previous request returns the following fields: } ```` -#### Specify an index +### Specify an index You can analyze text using an index's default analyzer, or you can specify a different analyzer. @@ -446,7 +446,7 @@ The previous request returns the following fields: } ```` -#### Derive the analyzer from an index field +### Derive the analyzer from an index field You can pass text and a field in the index. The API looks up the field's analyzer and uses it to analyze the text. @@ -493,7 +493,7 @@ The previous request returns the following fields: } ```` -#### Specify a normalizer +### Specify a normalizer Instead of using a keyword field, you can use the normalizer associated with the index. A normalizer causes the analysis change to produce a single token. @@ -557,7 +557,7 @@ The previous request returns the following fields: } ```` -#### Get token details +### Get token details You can obtain additional details for all tokens by setting the `explain` attribute to `true`. @@ -640,7 +640,7 @@ The previous request returns the following fields: } ```` -#### Set a token limit +### Set a token limit You can set a limit to the number of tokens generated. Setting a lower value reduces a node's memory usage. The default value is 10000. @@ -659,7 +659,7 @@ PUT /books2 The preceding request is an index API rather than an analyze API. See [Dynamic index-level index settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index-settings/#dynamic-index-level-index-settings) for additional details. {: .note} -### Response fields +## Response body fields The text analysis endpoints return the following response fields. diff --git a/_api-reference/cat/cat-aliases.md b/_api-reference/cat/cat-aliases.md index 2d5c5c300a..965e53dc8e 100644 --- a/_api-reference/cat/cat-aliases.md +++ b/_api-reference/cat/cat-aliases.md @@ -24,7 +24,7 @@ GET _cat/aliases ``` -## URL parameters +## Query parameters All CAT aliases URL parameters are optional. diff --git a/_api-reference/cat/cat-allocation.md b/_api-reference/cat/cat-allocation.md index 085a755dc1..59c936eec2 100644 --- a/_api-reference/cat/cat-allocation.md +++ b/_api-reference/cat/cat-allocation.md @@ -22,7 +22,7 @@ GET _cat/allocation?v GET _cat/allocation/ ``` -## URL parameters +## Query parameters All CAT allocation URL parameters are optional. diff --git a/_api-reference/cat/cat-cluster_manager.md b/_api-reference/cat/cat-cluster_manager.md index d81e334009..836f9434ae 100644 --- a/_api-reference/cat/cat-cluster_manager.md +++ b/_api-reference/cat/cat-cluster_manager.md @@ -17,11 +17,12 @@ The CAT cluster manager operation lists information that helps identify the elec ## Path and HTTP methods -``` +```json GET _cat/cluster_manager ``` +{% include copy-curl.html %} -## URL parameters +## Query parameters All CAT cluster manager URL parameters are optional. diff --git a/_api-reference/cat/cat-count.md b/_api-reference/cat/cat-count.md index 8d0b4fbad2..2da426f8c5 100644 --- a/_api-reference/cat/cat-count.md +++ b/_api-reference/cat/cat-count.md @@ -18,12 +18,13 @@ The CAT count operation lists the number of documents in your cluster. ## Path and HTTP methods -``` +```json GET _cat/count?v GET _cat/count/?v ``` +{% include copy-curl.html %} -## URL parameters +## Query parameters All CAT count URL parameters are optional. You can specify any of the [common URL parameters]({{site.url}}{{site.baseurl}}/api-reference/cat/index). diff --git a/_api-reference/cat/cat-field-data.md b/_api-reference/cat/cat-field-data.md index 05c720b952..13c24d2544 100644 --- a/_api-reference/cat/cat-field-data.md +++ b/_api-reference/cat/cat-field-data.md @@ -17,12 +17,13 @@ The CAT Field Data operation lists the memory size used by each field per node. ## Path and HTTP methods -``` +```json GET _cat/fielddata?v GET _cat/fielddata/?v ``` +{% include copy-curl.html %} -## URL parameters +## Query parameters All CAT fielddata URL parameters are optional. diff --git a/_api-reference/cat/cat-health.md b/_api-reference/cat/cat-health.md index 1c400916ad..3cf2b98c27 100644 --- a/_api-reference/cat/cat-health.md +++ b/_api-reference/cat/cat-health.md @@ -18,12 +18,12 @@ The CAT health operation lists the status of the cluster, how long the cluster h ## Path and HTTP methods -``` +```json GET _cat/health?v ``` {% include copy-curl.html %} -## URL parameters +## Query parameters All CAT health URL parameters are optional. @@ -39,6 +39,7 @@ The following example request give cluster health information for the past 5 day ```json GET _cat/health?v&time=5d ``` +{% include copy-curl.html %} ## Example response diff --git a/_api-reference/cat/cat-indices.md b/_api-reference/cat/cat-indices.md index 16c57e5791..ee8fdfc5f9 100644 --- a/_api-reference/cat/cat-indices.md +++ b/_api-reference/cat/cat-indices.md @@ -22,7 +22,7 @@ GET _cat/indices/ GET _cat/indices ``` -## URL parameters +## Query parameters All URL parameters are optional. @@ -40,14 +40,14 @@ expand_wildcards | Enum | Expands wildcard expressions to concrete indexes. Comb ## Example requests -``` +```json GET _cat/indices?v ``` {% include copy-curl.html %} To limit the information to a specific index, add the index name after your query. -``` +```json GET _cat/indices/?v ``` {% include copy-curl.html %} diff --git a/_api-reference/cat/cat-nodeattrs.md b/_api-reference/cat/cat-nodeattrs.md index b09e164698..b830020683 100644 --- a/_api-reference/cat/cat-nodeattrs.md +++ b/_api-reference/cat/cat-nodeattrs.md @@ -21,7 +21,7 @@ The CAT nodeattrs operation lists the attributes of custom nodes. GET _cat/nodeattrs ``` -## URL parameters +## Query parameters All CAT nodeattrs URL parameters are optional. @@ -36,7 +36,7 @@ cluster_manager_timeout | Time | The amount of time to wait for a connection to The following example request returns attributes about custom nodes: -``` +```json GET _cat/nodeattrs?v ``` {% include copy-curl.html %} diff --git a/_api-reference/cat/cat-nodes.md b/_api-reference/cat/cat-nodes.md index 5e7238a0d0..268d6ff18c 100644 --- a/_api-reference/cat/cat-nodes.md +++ b/_api-reference/cat/cat-nodes.md @@ -23,7 +23,7 @@ A few important node metrics are `pid`, `name`, `cluster_manager`, `ip`, `port`, GET _cat/nodes ``` -## URL parameters +## Query parameters All CAT nodes URL parameters are optional. @@ -41,7 +41,7 @@ include_unloaded_segments | Boolean | Whether to include information from segmen The following example request lists node level information: -``` +```json GET _cat/nodes?v ``` {% include copy-curl.html %} diff --git a/_api-reference/cat/cat-pending-tasks.md b/_api-reference/cat/cat-pending-tasks.md index ea224670ac..33a9e255b8 100644 --- a/_api-reference/cat/cat-pending-tasks.md +++ b/_api-reference/cat/cat-pending-tasks.md @@ -22,7 +22,7 @@ The CAT pending tasks operation lists the progress of all pending tasks, includi GET _cat/pending_tasks ``` -## URL parameters +## Query parameters All CAT nodes URL parameters are optional. @@ -38,7 +38,7 @@ time | Time | Specify the units for time. For example, `5d` or `7h`. For more in The following example request lists the progress of all pending node tasks: -``` +```json GET _cat/pending_tasks?v ``` {% include copy-curl.html %} diff --git a/_api-reference/cat/cat-plugins.md b/_api-reference/cat/cat-plugins.md index 358eb70fbf..f2426738d1 100644 --- a/_api-reference/cat/cat-plugins.md +++ b/_api-reference/cat/cat-plugins.md @@ -18,11 +18,11 @@ The CAT plugins operation lists the names, components, and versions of the insta ## Path and HTTP methods -``` +```json GET _cat/plugins ``` -## URL parameters +## Query parameters All CAT plugins URL parameters are optional. @@ -37,7 +37,7 @@ cluster_manager_timeout | Time | The amount of time to wait for a connection to The following example request lists all installed plugins: -``` +```json GET _cat/plugins?v ``` {% include copy-curl.html %} diff --git a/_api-reference/cat/cat-recovery.md b/_api-reference/cat/cat-recovery.md index 8f251a94e0..c9f1c2c52e 100644 --- a/_api-reference/cat/cat-recovery.md +++ b/_api-reference/cat/cat-recovery.md @@ -22,7 +22,7 @@ The CAT recovery operation lists all completed and ongoing index and shard recov GET _cat/recovery ``` -## URL parameters +## Query parameters All CAT recovery URL parameters are optional. @@ -37,14 +37,14 @@ time | Time | Specify the units for time. For example, `5d` or `7h`. For more in ## Example requests -``` +```json GET _cat/recovery?v ``` {% include copy-curl.html %} 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 %} diff --git a/_api-reference/cat/cat-repositories.md b/_api-reference/cat/cat-repositories.md index f0fc4bb622..1c8940d70a 100644 --- a/_api-reference/cat/cat-repositories.md +++ b/_api-reference/cat/cat-repositories.md @@ -17,11 +17,11 @@ The CAT repositories operation lists all snapshot repositories for a cluster. ## Path and HTTP methods -``` +```json GET _cat/repositories ``` -## URL parameters +## Query parameters All CAT repositories URL parameters are optional. @@ -36,7 +36,7 @@ cluster_manager_timeout | Time | The amount of time to wait for a connection to The following example request lists all snapshot repositories in the cluster: -``` +```json GET _cat/repositories?v ``` {% include copy-curl.html %} diff --git a/_api-reference/cat/cat-segments.md b/_api-reference/cat/cat-segments.md index cd9eda38be..e9eed42d62 100644 --- a/_api-reference/cat/cat-segments.md +++ b/_api-reference/cat/cat-segments.md @@ -18,11 +18,11 @@ The cat segments operation lists Lucene segment-level information for each index ## Path and HTTP methods -``` +```json GET _cat/segments ``` -## URL parameters +## Query parameters All CAT segments URL parameters are optional. @@ -35,21 +35,21 @@ cluster_manager_timeout | Time | The amount of time to wait for a connection to ## Example requests -``` +```json GET _cat/segments?v ``` {% include copy-curl.html %} 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 %} 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 %} diff --git a/_api-reference/cat/cat-shards.md b/_api-reference/cat/cat-shards.md index 56817936a6..3afda5f516 100644 --- a/_api-reference/cat/cat-shards.md +++ b/_api-reference/cat/cat-shards.md @@ -18,11 +18,12 @@ The CAT shards operation lists the state of all primary and replica shards and h ## Path and HTTP methods -``` +```json GET _cat/shards ``` +{% include copy-curl.html %} -## URL parameters +## Query parameters All cat shards URL parameters are optional. diff --git a/_api-reference/cat/cat-snapshots.md b/_api-reference/cat/cat-snapshots.md index 2e1bd514bf..9c38c3f755 100644 --- a/_api-reference/cat/cat-snapshots.md +++ b/_api-reference/cat/cat-snapshots.md @@ -18,11 +18,12 @@ The CAT snapshots operation lists all snapshots for a repository. ## Path and HTTP methods -``` +```json GET _cat/snapshots ``` +{% include copy-curl.html %} -## URL parameters +## Query parameters All CAT snapshots URL parameters are optional. diff --git a/_api-reference/cat/cat-tasks.md b/_api-reference/cat/cat-tasks.md index 7a71b592e7..31c09132b1 100644 --- a/_api-reference/cat/cat-tasks.md +++ b/_api-reference/cat/cat-tasks.md @@ -17,11 +17,12 @@ The CAT tasks operation lists the progress of all tasks currently running on you ## Path and HTTP methods -``` +```json GET _cat/tasks ``` +{% include copy-curl.html %} -## URL parameters +## Query parameters All CAT tasks URL parameters are optional. diff --git a/_api-reference/cat/cat-templates.md b/_api-reference/cat/cat-templates.md index ba47ae711d..403547f308 100644 --- a/_api-reference/cat/cat-templates.md +++ b/_api-reference/cat/cat-templates.md @@ -18,12 +18,12 @@ The CAT templates operation lists the names, patterns, order numbers, and versio ## Path and HTTP methods -``` +```json GET _cat/templates ``` {% include copy-curl.html %} -## URL parameters +## Query parameters All CAT templates URL parameters are optional. @@ -38,14 +38,14 @@ cluster_manager_timeout | Time | The amount of time to wait for a connection to The following example request returns information about all templates: -``` +```json GET _cat/templates?v ``` {% include copy-curl.html %} If you want to get information for a specific template or pattern: -``` +```json GET _cat/templates/ ``` {% include copy-curl.html %} diff --git a/_api-reference/cat/cat-thread-pool.md b/_api-reference/cat/cat-thread-pool.md index de24052175..7d602b8cc2 100644 --- a/_api-reference/cat/cat-thread-pool.md +++ b/_api-reference/cat/cat-thread-pool.md @@ -17,11 +17,11 @@ The CAT thread pool operation lists the active, queued, and rejected threads of ## Path and HTTP methods -``` +```json GET _cat/thread_pool ``` -## URL parameters +## Query parameters All CAT thread pool URL parameters are optional. @@ -36,21 +36,21 @@ cluster_manager_timeout | Time | The amount of time to wait for a connection to The following example request gives information about thread pools on all nodes: -``` +```json GET _cat/thread_pool?v ``` {% include copy-curl.html %} 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 %} 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 %} diff --git a/_api-reference/cluster-api/cluster-allocation.md b/_api-reference/cluster-api/cluster-allocation.md index 4ec6e27f2b..9ea9622a34 100644 --- a/_api-reference/cluster-api/cluster-allocation.md +++ b/_api-reference/cluster-api/cluster-allocation.md @@ -20,13 +20,13 @@ If you add some options, you can instead get information on a specific shard, in ## Path and HTTP methods -``` +```json GET _cluster/allocation/explain POST _cluster/allocation/explain ``` +{% include copy-curl.html %} - -## URL parameters +## Query parameters All cluster allocation explain parameters are optional. @@ -36,7 +36,7 @@ include_yes_decisions | Boolean | OpenSearch makes a series of yes or no decisio include_disk_info | Boolean | Whether to include information about disk usage in the response. Default is `false`. -## Request body +## Request body fields All cluster allocation explain fields are optional. diff --git a/_api-reference/cluster-api/cluster-awareness.md b/_api-reference/cluster-api/cluster-awareness.md index 18259b9a98..8c162f214c 100644 --- a/_api-reference/cluster-api/cluster-awareness.md +++ b/_api-reference/cluster-api/cluster-awareness.md @@ -17,7 +17,7 @@ To control the distribution of search or HTTP traffic, you can use the weights p ## Path and HTTP methods -``` +```json PUT /_cluster/routing/awareness//weights GET /_cluster/routing/awareness//weights?local GET /_cluster/routing/awareness//weights @@ -29,7 +29,7 @@ Parameter | Type | Description :--- | :--- | :--- attribute | String | The name of the awareness attribute, usually `zone`. The attribute name must match the values listed in the request body when assigning weights to zones. -## Request body parameters +## Request body fields Parameter | Type | Description :--- | :--- | :--- @@ -51,11 +51,12 @@ In the following example request body, `zone_1` and `zone_2` receive 50 requests } ``` -## Example: Weighted round robin search +## Example requests + +### Weighted round robin search The following example request creates a round robin shard allocation for search traffic by using an undefined ratio: -#### Request ```json PUT /_cluster/routing/awareness/zone/weights @@ -71,27 +72,37 @@ PUT /_cluster/routing/awareness/zone/weights ``` {% include copy-curl.html %} -#### Response -``` -{ - "acknowledged": true -} -``` +### Getting weights for all zones + +The following example request gets weights for all zones. +```json +GET /_cluster/routing/awareness/zone/weights +``` +{% include copy-curl.html %} -## Example: Getting weights for all zones -The following example request gets weights for all zones. +### Deleting weights -#### Request +You can remove your weight ratio for each zone using the `DELETE` method: ```json -GET /_cluster/routing/awareness/zone/weights +DELETE /_cluster/routing/awareness/zone/weights ``` {% include copy-curl.html %} -#### Response +## Example responses + +OpenSearch typically responds with the following when successfully allocating shards: + +```json +{ + "acknowledged": true +} +``` + +### Getting weights for all zone OpenSearch responds with the weight of each zone: @@ -106,26 +117,7 @@ OpenSearch responds with the weight of each zone: }, "_version":1 } -``` - -## Example: Deleting weights - -You can remove your weight ratio for each zone using the `DELETE` method. -#### Request - -```json -DELETE /_cluster/routing/awareness/zone/weights -``` -{% include copy-curl.html %} - -#### Response - -```json -{ - "_version":1 -} -``` ## Next steps diff --git a/_api-reference/cluster-api/cluster-decommission.md b/_api-reference/cluster-api/cluster-decommission.md index c707e5390a..4c602fce6f 100644 --- a/_api-reference/cluster-api/cluster-decommission.md +++ b/_api-reference/cluster-api/cluster-decommission.md @@ -20,25 +20,25 @@ For more information about allocation awareness, see [Shard allocation awareness ## HTTP and Path methods -``` +```json PUT /_cluster/decommission/awareness/{awareness_attribute_name}/{awareness_attribute_value} GET /_cluster/decommission/awareness/{awareness_attribute_name}/_status DELETE /_cluster/decommission/awareness ``` -## URL parameters +## Query parameters Parameter | Type | Description :--- | :--- | :--- awareness_attribute_name | String | The name of awareness attribute, usually `zone`. awareness_attribute_value | String | The value of the awareness attribute. For example, if you have shards allocated in two different zones, you can give each zone a value of `zone-a` or `zoneb`. The cluster decommission operation decommissions the zone listed in the method. +## Example requests -## Example: Decommissioning and recommissioning a zone +### Decommissioning and recommissioning a zone You can use the following example requests to decommission and recommission a zone: -#### Request The following example request decommissions `zone-a`: @@ -54,27 +54,29 @@ DELETE /_cluster/decommission/awareness ``` {% include copy-curl.html %} -#### Example response +### Getting zone decommission status +The following example requests returns the decommission status of all zones. ```json -{ - "acknowledged": true -} +GET /_cluster/decommission/awareness/zone/_status ``` +{% include copy-curl.html %} -## Example: Getting zone decommission status +#### Example responses -The following example requests returns the decommission status of all zones. - -#### Request +The following example response shows a successful zone decommission: ```json -GET /_cluster/decommission/awareness/zone/_status +{ + "acknowledged": true +} ``` -{% include copy-curl.html %} -#### Example response +### Getting zone decommission status + +The following example response returns the decommission status of all zones: + ```json { diff --git a/_api-reference/cluster-api/cluster-health.md b/_api-reference/cluster-api/cluster-health.md index 0fd5662d91..8e5bda02bc 100644 --- a/_api-reference/cluster-api/cluster-health.md +++ b/_api-reference/cluster-api/cluster-health.md @@ -98,7 +98,7 @@ The response contains cluster health information: } ``` -## Response fields +## Response body fields The following table lists all response fields. diff --git a/_api-reference/cluster-api/cluster-settings.md b/_api-reference/cluster-api/cluster-settings.md index ec682ecdbd..5be06261f2 100644 --- a/_api-reference/cluster-api/cluster-settings.md +++ b/_api-reference/cluster-api/cluster-settings.md @@ -32,9 +32,9 @@ include_defaults (GET only) | Boolean | Whether to include default settings as p cluster_manager_timeout | Time unit | The amount of time to wait for a response from the cluster manager node. Default is `30 seconds`. timeout (PUT only) | Time unit | The amount of time to wait for a response from the cluster. Default is `30 seconds`. -## Request fields +## Request body fields -The GET operation has no request body options. All cluster setting field parameters are optional. +The GET operation has no request body fields. All cluster setting field parameters are optional. Not all cluster settings can be updated using the cluster settings API. You will receive the error message `"setting [cluster.some.setting], not dynamically updateable"` when trying to configure these settings through the API. {: .note } diff --git a/_api-reference/cluster-api/cluster-stats.md b/_api-reference/cluster-api/cluster-stats.md index fb0ade2c6b..f712caa51a 100644 --- a/_api-reference/cluster-api/cluster-stats.md +++ b/_api-reference/cluster-api/cluster-stats.md @@ -23,7 +23,7 @@ GET _cluster/stats GET _cluster/stats/nodes/ ``` -## URL parameters +## Query parameters All cluster stats parameters are optional. diff --git a/_api-reference/count.md b/_api-reference/count.md index 2ac336eeb0..601dff01ec 100644 --- a/_api-reference/count.md +++ b/_api-reference/count.md @@ -13,7 +13,35 @@ redirect_from: The count API gives you quick access to the number of documents that match a query. You can also use it to check the document count of an index, data stream, or cluster. -## Example + +## Path and HTTP methods + +``` +GET /_count/ +POST /_count/ +``` + + +## Query parameters + +All count parameters are optional. + +Parameter | Type | Description +:--- | :--- | :--- +`allow_no_indices` | Boolean | If false, the request returns an error if any wildcard expression or index alias targets any closed or missing indexes. Default is `false`. +`analyzer` | String | The analyzer to use in the query string. +`analyze_wildcard` | Boolean | Specifies whether to analyze wildcard and prefix queries. Default is `false`. +`default_operator` | String | Indicates whether the default operator for a string query should be `AND` or `OR`. Default is `OR`. +`df` | String | The default field in case a field prefix is not provided in the query string. +`expand_wildcards` | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indexes), `closed` (match closed, non-hidden indexes), `hidden` (match hidden indexes), and `none` (deny wildcard expressions). Default is `open`. +`ignore_unavailable` | Boolean | Specifies whether to include missing or closed indexes in the response. Default is `false`. +`lenient` | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is `false`. +`min_score` | Float | Include only documents with a minimum `_score` value in the result. +`routing` | String | Value used to route the operation to a specific shard. +`preference` | String | Specifies which shard or node OpenSearch should perform the count operation on. +`terminate_after` | Integer | The maximum number of documents OpenSearch should process before terminating the request. + +## Example requests To see the number of documents that match a query: @@ -64,35 +92,7 @@ GET _count 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 } - -## Path and HTTP methods - -``` -GET /_count/ -POST /_count/ -``` - - -## URL parameters - -All count parameters are optional. - -Parameter | Type | Description -:--- | :--- | :--- -`allow_no_indices` | Boolean | If false, the request returns an error if any wildcard expression or index alias targets any closed or missing indexes. Default is `false`. -`analyzer` | String | The analyzer to use in the query string. -`analyze_wildcard` | Boolean | Specifies whether to analyze wildcard and prefix queries. Default is `false`. -`default_operator` | String | Indicates whether the default operator for a string query should be `AND` or `OR`. Default is `OR`. -`df` | String | The default field in case a field prefix is not provided in the query string. -`expand_wildcards` | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indexes), `closed` (match closed, non-hidden indexes), `hidden` (match hidden indexes), and `none` (deny wildcard expressions). Default is `open`. -`ignore_unavailable` | Boolean | Specifies whether to include missing or closed indexes in the response. Default is `false`. -`lenient` | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is `false`. -`min_score` | Float | Include only documents with a minimum `_score` value in the result. -`routing` | String | Value used to route the operation to a specific shard. -`preference` | String | Specifies which shard or node OpenSearch should perform the count operation on. -`terminate_after` | Integer | The maximum number of documents OpenSearch should process before terminating the request. - -## Response +## Example response ```json { diff --git a/_api-reference/document-apis/bulk-streaming.md b/_api-reference/document-apis/bulk-streaming.md index 7d05e93c8a..89eb3765bf 100644 --- a/_api-reference/document-apis/bulk-streaming.md +++ b/_api-reference/document-apis/bulk-streaming.md @@ -25,6 +25,7 @@ The default HTTP transport method does not support streaming. You must install t POST _bulk/stream POST /_bulk/stream ``` +{% include copy.html %} If you specify the index in the path, then you don't need to include it in the [request body chunks]({{site.url}}{{site.baseurl}}/api-reference/document-apis/bulk/#request-body). @@ -51,7 +52,7 @@ Parameter | Data type | Description `_source_excludes` | List | asdf `_source_includes` | List | asdf{% endcomment %} -## Request body +## Request body fields The Streaming Bulk API request body is fully compatible with the [Bulk API request body]({{site.url}}{{site.baseurl}}/api-reference/document-apis/bulk/#request-body), where each bulk operation (create/index/update/delete) is sent as a separate chunk. diff --git a/_api-reference/document-apis/bulk.md b/_api-reference/document-apis/bulk.md index 4add60ee37..2e3ec747a5 100644 --- a/_api-reference/document-apis/bulk.md +++ b/_api-reference/document-apis/bulk.md @@ -17,20 +17,6 @@ The bulk operation lets you add, update, or delete multiple documents in a singl Beginning in OpenSearch 2.9, when indexing documents using the bulk operation, the document `_id` must be 512 bytes or less in size. {: .note} -## Example - -```json -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" } } - -``` -{% include copy-curl.html %} ## Path and HTTP methods @@ -46,7 +32,7 @@ OpenSearch also accepts PUT requests to the `_bulk` path, but we highly recommen {: .note } -## URL parameters +## Query parameters All bulk URL parameters are optional. @@ -81,7 +67,7 @@ The optional JSON document doesn't need to be minified---spaces are fine---but i All actions support the same metadata: `_index`, `_id`, and `_require_alias`. If you don't provide an ID, OpenSearch generates one automatically, which can make it challenging to update the document at a later time. -- Create +### Create Creates a document if it doesn't already exist and returns an error otherwise. The next line must include a JSON document: @@ -90,49 +76,64 @@ All actions support the same metadata: `_index`, `_id`, and `_require_alias`. If { "title": "Prisoners", "year": 2013 } ``` -- Delete +### Delete - This action deletes a document if it exists. If the document doesn't exist, OpenSearch doesn't return an error but instead returns `not_found` under `result`. Delete actions don't require documents on the next line: +This action deletes a document if it exists. If the document doesn't exist, OpenSearch doesn't return an error but instead returns `not_found` under `result`. Delete actions don't require documents on the next line: - ```json - { "delete": { "_index": "movies", "_id": "tt2229499" } } - ``` +```json +{ "delete": { "_index": "movies", "_id": "tt2229499" } } +``` -- Index +### Index - Index actions create a document if it doesn't yet exist and replace the document if it already exists. The next line must include a JSON document: +Index actions create a document if it doesn't yet exist and replace the document if it already exists. The next line must include a JSON document: - ```json - { "index": { "_index": "movies", "_id": "tt1979320" } } - { "title": "Rush", "year": 2013} - ``` +```json +{ "index": { "_index": "movies", "_id": "tt1979320" } } +{ "title": "Rush", "year": 2013} +``` -- Update +### Update - By default, this action updates existing documents and returns an error if the document doesn't exist. The next line must include a full or partial JSON document, depending on how much of the document you want to update: +By default, this action updates existing documents and returns an error if the document doesn't exist. The next line must include a full or partial JSON document, depending on how much of the document you want to update: - ```json - { "update": { "_index": "movies", "_id": "tt0816711" } } - { "doc" : { "title": "World War Z" } } - ``` +```json +{ "update": { "_index": "movies", "_id": "tt0816711" } } +{ "doc" : { "title": "World War Z" } } +``` - To upsert a document, specify `doc_as_upsert` as `true`. If a document exists, it is updated; if it does not exist, a new document is indexed with the parameters specified in the `doc` field: +### Upsert - - Upsert - ```json - { "update": { "_index": "movies", "_id": "tt0816711" } } - { "doc" : { "title": "World War Z" }, "doc_as_upsert": true } - ``` +To upsert a document, specify `doc_as_upsert` as `true`. If a document exists, it is updated; if it does not exist, a new document is indexed with the parameters specified in the `doc` field: - You can specify a script for more complex document updates by defining the script with the `source` or `id` from a document: +```json +{ "update": { "_index": "movies", "_id": "tt0816711" } } +{ "doc" : { "title": "World War Z" }, "doc_as_upsert": true } +``` +### Script +You can specify a script for more complex document updates by defining the script with the `source` or `id` from a document: - - Script - ```json - { "update": { "_index": "movies", "_id": "tt0816711" } } - { "script" : { "source": "ctx._source.title = \"World War Z\"" } } - ``` +```json +{ "update": { "_index": "movies", "_id": "tt0816711" } } +{ "script" : { "source": "ctx._source.title = \"World War Z\"" } } +``` + +## Example request + +```json +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" } } + +``` +{% include copy-curl.html %} ## Example response diff --git a/_api-reference/document-apis/delete-by-query.md b/_api-reference/document-apis/delete-by-query.md index 64da909aad..ff2ddf207a 100644 --- a/_api-reference/document-apis/delete-by-query.md +++ b/_api-reference/document-apis/delete-by-query.md @@ -33,7 +33,7 @@ POST sample-index1/_delete_by_query POST /_delete_by_query ``` -## URL parameters +## Query parameters All URL parameters are optional. @@ -74,7 +74,7 @@ wait_for_active_shards | String | The number of shards that must be active befor wait_for_completion | Boolean | Setting this parameter to false indicates to OpenSearch it should not wait for completion and perform this request asynchronously. Asynchronous requests run in the background, and you can use the [Tasks]({{site.url}}{{site.baseurl}}/api-reference/tasks) API to monitor progress. -## Request body +## Request body fields To search your index for specific documents, you must include a [query]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/index) in the request body that OpenSearch uses to match documents. If you don't use a query, OpenSearch treats your delete request as a simple [delete document operation]({{site.url}}{{site.baseurl}}/api-reference/document-apis/delete-document). @@ -88,6 +88,21 @@ To search your index for specific documents, you must include a [query]({{site.u } ``` +## Example request + +```json +POST sample-index1/_delete_by_query +{ + "query": { + "match": { + "movie-length": "124" + } + } +} +``` +{% include copy-curl.html %} + + ## Example response ```json { diff --git a/_api-reference/document-apis/delete-document.md b/_api-reference/document-apis/delete-document.md index ece99a28ca..91065ffbd8 100644 --- a/_api-reference/document-apis/delete-document.md +++ b/_api-reference/document-apis/delete-document.md @@ -15,18 +15,18 @@ If you no longer need a document in your index, you can use the delete document ## Example -``` +```json DELETE /sample-index1/_doc/1 ``` {% include copy-curl.html %} ## Path and HTTP methods -``` +```json DELETE //_doc/<_id> ``` -## URL parameters +## Query parameters Parameter | Type | Description | Required :--- | :--- | :--- | :--- @@ -41,6 +41,13 @@ version | Integer | The version of the document to delete, which must match the version_type | Enum | Retrieves a specifically typed document. Available options are `external` (retrieve the document if the specified version number is greater than the document's current version) and `external_gte` (retrieve the document if the specified version number is greater than or equal to the document's current version). For example, to delete version 3 of a document, use `/_doc/1?version=3&version_type=external`. | No wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the delete 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 +## Example request + +```json +DELETE /sample-index1/_doc/1 +``` +{% include copy-curl.html %} + ## Example response ```json diff --git a/_api-reference/document-apis/index-document.md b/_api-reference/document-apis/index-document.md index a506e2d9d8..6b6f5e44e2 100644 --- a/_api-reference/document-apis/index-document.md +++ b/_api-reference/document-apis/index-document.md @@ -13,15 +13,6 @@ redirect_from: You can use the `Index document` operation to add a single document to your index. -## Example - -```json -PUT sample-index/_doc/1 -{ - "Description": "To be or not to be, that is the question." -} -``` -{% include copy-curl.html %} ## Path and HTTP methods @@ -80,7 +71,7 @@ POST /sample_index/_doc ``` {% include copy-curl.html %} -## URL parameters +## Query parameters In your request, you must specify the index you want to add your document to. If the index doesn't already exist, OpenSearch automatically creates the index and adds in your document. All other URL parameters are optional. @@ -100,17 +91,38 @@ 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 -## Request body +## Example requests + +The following example requests create a sample index document for an index named `sample_index`: + + +### Example PUT request + +```json +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 %} -Your request body must contain the information you want to index. +### Example POST request ```json +POST /sample_index/_doc { - "Description": "This is just a sample document" + "name": "Another Example", + "price": 19.99, + "description": "We are such stuff as dreams are made on" } + ``` +{% include copy-curl.html %} ## Example response + ```json { "_index": "sample-index", diff --git a/_api-reference/document-apis/multi-get.md b/_api-reference/document-apis/multi-get.md index b267b8f3ac..8cd16e1ac6 100644 --- a/_api-reference/document-apis/multi-get.md +++ b/_api-reference/document-apis/multi-get.md @@ -22,7 +22,7 @@ POST _mget POST /_mget ``` -## URL parameters +## Query parameters All multi-get URL parameters are optional. diff --git a/_api-reference/document-apis/reindex.md b/_api-reference/document-apis/reindex.md index 8ac1c48be4..696c2ec28d 100644 --- a/_api-reference/document-apis/reindex.md +++ b/_api-reference/document-apis/reindex.md @@ -35,7 +35,7 @@ POST /_reindex POST /_reindex ``` -## URL parameters +## Query parameters All URL parameters are optional. diff --git a/_api-reference/document-apis/update-by-query.md b/_api-reference/document-apis/update-by-query.md index 09b3bd599f..f44e1e3c05 100644 --- a/_api-reference/document-apis/update-by-query.md +++ b/_api-reference/document-apis/update-by-query.md @@ -13,26 +13,6 @@ redirect_from: You can include a query and a script as part of your update request so OpenSearch can run the script to update all of the documents that match the query. -## Example - -```json -POST test-index1/_update_by_query -{ - "query": { - "term": { - "oldValue": 10 - } - }, - "script" : { - "source": "ctx._source.oldValue += params.newValue", - "lang": "painless", - "params" : { - "newValue" : 20 - } - } -} -``` -{% include copy-curl.html %} ## Path and HTTP methods @@ -40,7 +20,7 @@ POST test-index1/_update_by_query POST , /_update_by_query ``` -## URL parameters +## Query parameters All URL parameters are optional. @@ -81,7 +61,7 @@ version | Boolean | Whether to include the document version as a match. wait_for_active_shards | String | The number of shards that must be active before OpenSearch executes the operation. Valid values are `all` or any integer up to the total number of shards in the index. Default is 1, which is the primary shard. wait_for_completion | boolean | When set to `false`, the response body includes a task ID and OpenSearch executes the operation asynchronously. The task ID can be used to check the status of the task or to cancel the task. Default is set to `true`. -## Request body +## Request body options To update your indexes and documents by query, you must include a [query]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/index) and a script in the request body that OpenSearch can run to update your documents. If you don't specify a query, then every document in the index gets updated. @@ -102,6 +82,27 @@ To update your indexes and documents by query, you must include a [query]({{site } ``` +## Example requests + +```json +POST test-index1/_update_by_query +{ + "query": { + "term": { + "oldValue": 10 + } + }, + "script" : { + "source": "ctx._source.oldValue += params.newValue", + "lang": "painless", + "params" : { + "newValue" : 20 + } + } +} +``` +{% include copy-curl.html %} + ## Example response ```json { diff --git a/_api-reference/document-apis/update-document.md b/_api-reference/document-apis/update-document.md index 3f951b5adf..f9c4812cd6 100644 --- a/_api-reference/document-apis/update-document.md +++ b/_api-reference/document-apis/update-document.md @@ -11,32 +11,8 @@ redirect_from: **Introduced 1.0** {: .label .label-purple } -If you need to update a document's fields in your index, you can use the update document API operation. You can do so by specifying the new data you want to be in your index or by including a script in your request body, which OpenSearch runs to update the document. By default, the update operation only updates a document that exists in the index. If a document does not exist, the API returns an error. To _upsert_ a document (update the document that exists or index a new one), use the [upsert](#upsert) operation. +If you need to update a document's fields in your index, you can use the update document API operation. You can do so by specifying the new data you want to be in your index or by including a script in your request body, which OpenSearch runs to update the document. By default, the update operation only updates a document that exists in the index. If a document does not exist, the API returns an error. To _upsert_ a document (update the document that exists or index a new one), use the [upsert](#using-the-upsert-operation) operation. -## Example - -```json -POST /sample-index1/_update/1 -{ - "doc": { - "first_name" : "Bruce", - "last_name" : "Wayne" - } -} -``` -{% include copy-curl.html %} - -## Script example - -```json -POST /test-index1/_update/1 -{ - "script" : { - "source": "ctx._source.secret_identity = \"Batman\"" - } -} -``` -{% include copy-curl.html %} ## Path and HTTP methods @@ -44,7 +20,7 @@ POST /test-index1/_update/1 POST //_update/<_id> ``` -## URL parameters +## Query parameters Parameter | Type | Description | Required :--- | :--- | :--- | :--- @@ -63,7 +39,7 @@ _source_includes | List | A comma-separated list of source fields to include in timeout | Time | How long to wait for a response from the cluster. | No wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the update 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 -## Request body +## Request body fields Your request body must contain the information with which you want to update your document. If you only want to replace certain fields in your document, your request body must include a `doc` object containing the fields that you want to update: @@ -90,7 +66,34 @@ You can also use a script to tell OpenSearch how to update your document: } ``` -## Upsert +## Example requests + +### Update a document + +```json +POST /sample-index1/_update/1 +{ + "doc": { + "first_name" : "Bruce", + "last_name" : "Wayne" + } +} +``` +{% include copy-curl.html %} + +### Update a document with a script + +```json +POST /test-index1/_update/1 +{ + "script" : { + "source": "ctx._source.secret_identity = \"Batman\"" + } +} +``` +{% include copy-curl.html %} + +### Using the upsert operation Upsert is an operation that conditionally either updates an existing document or inserts a new one based on information in the object. @@ -109,6 +112,7 @@ POST /sample-index1/_update/1 } } ``` +{% include copy-curl.html %} Consider an index that contains the following document: @@ -123,6 +127,7 @@ Consider an index that contains the following document: } } ``` +{% include copy-curl.html %} After the upsert operation, the document's `first_name` and `last_name` fields are updated: @@ -137,6 +142,7 @@ After the upsert operation, the document's `first_name` and `last_name` fields a } } ``` +{% include copy-curl.html %} If the document does not exist in the index, a new document is indexed with the fields specified in the `upsert` object: @@ -151,6 +157,7 @@ If the document does not exist in the index, a new document is indexed with the } } ``` +{% include copy-curl.html %} 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: @@ -165,6 +172,7 @@ POST /sample-index1/_update/1 "doc_as_upsert": true } ``` +{% include copy-curl.html %} Consider an index that contains the following document: @@ -179,6 +187,7 @@ Consider an index that contains the following document: } } ``` +{% include copy-curl.html %} After the upsert operation, the document's `first_name` and `last_name` fields are updated and an `age` field is added. If the document does not exist in the index, a new document is indexed with the fields specified in the `upsert` object. In both cases, the document is as follows: @@ -194,8 +203,10 @@ After the upsert operation, the document's `first_name` and `last_name` fields a } } ``` +{% include copy-curl.html %} ## Example response + ```json { "_index": "sample-index1", diff --git a/_api-reference/explain.md b/_api-reference/explain.md index 8c2b757945..2fb7280e5f 100644 --- a/_api-reference/explain.md +++ b/_api-reference/explain.md @@ -18,44 +18,14 @@ The explain API is an expensive operation in terms of both resources and time. O {: .warning } -## Example - -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 -{ - "query": { - "match": { - "customer_first_name": "Mary" - } - } -} -``` -{% include copy-curl.html %} - -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 -{ - "query": { - "match": { - "customer_first_name": "Mary" - } - } -} -``` -{% include copy-curl.html %} - ## Path and HTTP methods -``` +```json GET /_explain/ POST /_explain/ ``` -## URL parameters +## Query parameters You must specify the index and document ID. All other URL parameters are optional. diff --git a/_api-reference/index-apis/alias.md b/_api-reference/index-apis/alias.md index ebd7bdedfd..22277bbec8 100644 --- a/_api-reference/index-apis/alias.md +++ b/_api-reference/index-apis/alias.md @@ -15,36 +15,13 @@ redirect_from: An alias is a virtual pointer that you can use to reference one or more indexes. Creating and updating aliases are atomic operations, so you can reindex your data and point an alias at it without any downtime. -## Example - -```json -POST _aliases -{ - "actions": [ - { - "add": { - "index": "movies", - "alias": "movies-alias1" - } - }, - { - "remove": { - "index": "old-index", - "alias": "old-index-alias" - } - } - ] -} -``` -{% include copy-curl.html %} - ## Path and HTTP methods ``` POST _aliases ``` -## URL parameters +## Query parameters All alias parameters are optional. @@ -53,7 +30,7 @@ Parameter | Data Type | Description cluster_manager_timeout | Time | The amount of time to wait for a response from the cluster manager node. Default is `30s`. timeout | Time | The amount of time to wait for a response from the cluster. Default is `30s`. -## Request body +## Request body fields In your request body, you need to specify what action to take, the alias name, and the index you want to associate with the alias. Other fields are optional. @@ -75,6 +52,29 @@ routing | String | Used to assign a custom value to a shard for specific operati index_routing | String | Assigns a custom value to a shard only for index operations. | No search_routing | String | Assigns a custom value to a shard only for search operations. | No +## Example request + +```json +POST _aliases +{ + "actions": [ + { + "add": { + "index": "movies", + "alias": "movies-alias1" + } + }, + { + "remove": { + "index": "old-index", + "alias": "old-index-alias" + } + } + ] +} +``` +{% include copy-curl.html %} + ## Example response ```json diff --git a/_api-reference/index-apis/clear-index-cache.md b/_api-reference/index-apis/clear-index-cache.md index 9bf873301d..4fad71d8d2 100644 --- a/_api-reference/index-apis/clear-index-cache.md +++ b/_api-reference/index-apis/clear-index-cache.md @@ -117,7 +117,7 @@ The `POST /books,hockey/_cache/clear` request returns the following fields: } ``` -## Response fields +## Response body fields The `POST /books,hockey/_cache/clear` request returns the following response fields: diff --git a/_api-reference/index-apis/clone.md b/_api-reference/index-apis/clone.md index c1496cbaf8..d06011a4f2 100644 --- a/_api-reference/index-apis/clone.md +++ b/_api-reference/index-apis/clone.md @@ -13,24 +13,6 @@ redirect_from: The clone index API operation clones all data in an existing read-only index into a new index. The new index cannot already exist. -## Example - -```json -PUT /sample-index1/_clone/cloned-index1 -{ - "settings": { - "index": { - "number_of_shards": 2, - "number_of_replicas": 1 - } - }, - "aliases": { - "sample-alias1": {} - } -} -``` -{% include copy-curl.html %} - ## Path and HTTP methods ``` @@ -48,7 +30,7 @@ OpenSearch indexes have the following naming restrictions: `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, or `<` -## URL parameters +## Query parameters Your request must include the source and target indexes. All other clone index parameters are optional. diff --git a/_api-reference/index-apis/close-index.md b/_api-reference/index-apis/close-index.md index 865d17d90a..286b070671 100644 --- a/_api-reference/index-apis/close-index.md +++ b/_api-reference/index-apis/close-index.md @@ -13,12 +13,6 @@ redirect_from: The close index API operation closes an index. Once an index is closed, you cannot add data to it or search for any data within the index. -#### Example - -```json -POST /sample-index/_close -``` -{% include copy-curl.html %} ## Path and HTTP methods @@ -26,7 +20,7 @@ POST /sample-index/_close POST //_close ``` -## URL parameters +## Query parameters All parameters are optional. @@ -40,6 +34,13 @@ wait_for_active_shards | String | Specifies the number of active shards that mus cluster_manager_timeout | Time | How long to wait for a connection to the cluster manager node. Default is `30s`. timeout | Time | How long to wait for a response from the cluster. Default is `30s`. +## Example requests + +```json +POST /sample-index/_close +``` +{% include copy-curl.html %} + ## Example response ```json diff --git a/_api-reference/index-apis/component-template.md b/_api-reference/index-apis/component-template.md index bafdfa95c7..fa73e64c94 100644 --- a/_api-reference/index-apis/component-template.md +++ b/_api-reference/index-apis/component-template.md @@ -40,7 +40,7 @@ Parameter | Data type | Description `cluster_manager_timeout` | Time | The amount of time to wait for a connection to the cluster manager node. Default is `30s`. `timeout` | Time | The amount of time for the operation to wait for a response. Default is `30s`. -## Request fields +## Request body fields The following options can be used in the request body to customize the index template. diff --git a/_api-reference/index-apis/create-index-template.md b/_api-reference/index-apis/create-index-template.md index ea71126210..c2f4228c8e 100644 --- a/_api-reference/index-apis/create-index-template.md +++ b/_api-reference/index-apis/create-index-template.md @@ -31,7 +31,7 @@ Parameter | Data type | Description `create` | Boolean | When true, the API cannot replace or update any existing index templates. Default is `false`. `cluster_manager_timeout` | Time | The amount of time to wait for a connection to the cluster manager node. Default is `30s`. -## Request body options +## Request body fields The following options can be used in the request body to customize the index template. diff --git a/_api-reference/index-apis/dangling-index.md b/_api-reference/index-apis/dangling-index.md index 9d40687f9f..f44a9dc4d4 100644 --- a/_api-reference/index-apis/dangling-index.md +++ b/_api-reference/index-apis/dangling-index.md @@ -15,21 +15,24 @@ After a node joins a cluster, dangling indexes occur if any shards exist in the 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 @@ -49,31 +52,29 @@ accept_data_loss | Boolean | Must be set to `true` for an `import` or `delete` b timeout | Time units | The amount of time to wait for a response. If no response is received in the defined time period, an error is returned. Default is `30` seconds. cluster_manager_timeout | Time units | The amount of time to wait for a connection to the cluster manager. If no response is received in the defined time period, an error is returned. Default is `30` seconds. -## Examples - -The following are example requests and a example response. +## Example requests -#### Sample list +### Sample list ````bash GET /_dangling ```` {% include copy-curl.html %} -#### Sample import +### Sample import ````bash POST /_dangling/msdjernajxAT23RT-BupMB?accept_data_loss=true ```` {% include copy-curl.html %} -#### Sample delete +### Sample delete ````bash DELETE /_dangling/msdjernajxAT23RT-BupMB?accept_data_loss=true ```` -#### Example response body +## Example response ````json { diff --git a/_api-reference/index-apis/delete-index.md b/_api-reference/index-apis/delete-index.md index ad00eb7eca..d324106258 100644 --- a/_api-reference/index-apis/delete-index.md +++ b/_api-reference/index-apis/delete-index.md @@ -13,19 +13,14 @@ redirect_from: If you no longer need an index, you can use the delete index API operation to delete it. -## Example +## Path and HTTP methods ```json -DELETE /sample-index -``` -{% include copy-curl.html %} - -## Path and HTTP methods -``` DELETE / ``` +{% include copy-curl.html %} -## URL parameters +## Query parameters All parameters are optional. @@ -37,6 +32,13 @@ ignore_unavailable | Boolean | If true, OpenSearch does not include missing or c cluster_manager_timeout | Time | How long to wait for a connection to the cluster manager node. Default is `30s`. timeout | Time | How long to wait for the response to return. Default is `30s`. +## Example request + +```json +DELETE /sample-index +``` +{% include copy-curl.html %} + ## Example response ```json diff --git a/_api-reference/index-apis/exists.md b/_api-reference/index-apis/exists.md index 351e2f2088..5da3888001 100644 --- a/_api-reference/index-apis/exists.md +++ b/_api-reference/index-apis/exists.md @@ -13,20 +13,15 @@ redirect_from: The index exists API operation returns whether or not an index already exists. -## Example - -```json -HEAD /sample-index -``` -{% include copy-curl.html %} ## Path and HTTP methods -``` +```json HEAD / ``` +{% include copy-curl.html %} -## URL parameters +## Query parameters All parameters are optional. @@ -40,6 +35,13 @@ ignore_unavailable | Boolean | If true, OpenSearch does not search for missing o local | Boolean | Whether to return information from only the local node instead of from the cluster manager node. Default is `false`. +## Example request + +```json +HEAD /sample-index +``` +{% include copy-curl.html %} + ## Example response The index exists API operation returns only one of two possible response codes: `200` -- the index exists, and `404` -- the index does not exist. diff --git a/_api-reference/index-apis/flush.md b/_api-reference/index-apis/flush.md index fb97e43900..2f9715a6e8 100644 --- a/_api-reference/index-apis/flush.md +++ b/_api-reference/index-apis/flush.md @@ -18,12 +18,13 @@ OpenSearch automatically performs flushes in the background based on conditions The Flush API supports the following paths: -``` +```json GET /_flush POST /_flush GET /{index}/_flush POST /{index}/_flush ``` +{% include copy-curl.html %} ## Path parameters @@ -45,21 +46,26 @@ The Flush API supports the following query parameters. | `ignore_unavailable` | Boolean | When `true`, OpenSearch ignores missing or closed indexes. If `false`, OpenSearch returns an error if the force merge operation encounters missing or closed indexes. Default is `false`. | | `wait_if_ongoing` | Boolean | When `true`, the Flush API does not run while another flush request is active. When `false`, OpenSearch returns an error if another flush request is active. Default is `true`. | -## Example request: Flush a specific index +## Example requests + +### Flush a specific index The following example flushes an index named `shakespeare`: -``` +```json POST /shakespeare/_flush ``` +{% include copy-curl.html %} -## Example request: Flush all indexes + +### Flush all indexes The following example flushes all indexes in a cluster: -``` +```json POST /_flush ``` +{% include copy-curl.html %} ## Example response diff --git a/_api-reference/index-apis/force-merge.md b/_api-reference/index-apis/force-merge.md index ce7501ebe3..a03421fdbf 100644 --- a/_api-reference/index-apis/force-merge.md +++ b/_api-reference/index-apis/force-merge.md @@ -135,7 +135,7 @@ POST /.testindex-logs/_forcemerge?primary_only=true } ``` -## Response fields +## Response body fields The following table lists all response fields. diff --git a/_api-reference/index-apis/get-index.md b/_api-reference/index-apis/get-index.md index e2d2d85c65..f1ca69e62a 100644 --- a/_api-reference/index-apis/get-index.md +++ b/_api-reference/index-apis/get-index.md @@ -13,20 +13,15 @@ redirect_from: You can use the get index API operation to return information about an index. -## Example - -```json -GET /sample-index -``` -{% include copy-curl.html %} ## Path and HTTP methods -``` +```json GET / ``` +{% include copy-curl.html %} -## URL parameters +## Query parameters All parameters are optional. @@ -40,6 +35,12 @@ ignore_unavailable | Boolean | If true, OpenSearch does not include missing or c local | Boolean | Whether to return information from only the local node instead of from the cluster manager node. Default is `false`. cluster_manager_timeout | Time | How long to wait for a connection to the cluster manager node. Default is `30s`. +## Example request + +```json +GET /sample-index +``` +{% include copy-curl.html %} ## Example response ```json diff --git a/_api-reference/index-apis/get-settings.md b/_api-reference/index-apis/get-settings.md index 94cb4a7c6c..cf1745c356 100644 --- a/_api-reference/index-apis/get-settings.md +++ b/_api-reference/index-apis/get-settings.md @@ -14,22 +14,17 @@ redirect_from: The get settings API operation returns all the settings in your index. -## Example - -```json -GET /sample-index1/_settings -``` -{% include copy-curl.html %} ## Path and HTTP methods -``` +```json GET /_settings GET //_settings GET //_settings/ ``` +{% include copy-curl.html %} -## URL parameters +## Query parameters All get settings parameters are optional. @@ -45,6 +40,13 @@ ignore_unavailable | Boolean | If true, OpenSearch does not include missing or c local | Boolean | Whether to return information from the local node only instead of the cluster manager node. Default is `false`. cluster_manager_timeout | Time | How long to wait for a connection to the cluster manager node. Default is `30s`. +## Example request + +```json +GET /sample-index1/_settings +``` +{% include copy-curl.html %} + ## Example response ```json diff --git a/_api-reference/index-apis/open-index.md b/_api-reference/index-apis/open-index.md index 0d8ef62282..c653c04ce6 100644 --- a/_api-reference/index-apis/open-index.md +++ b/_api-reference/index-apis/open-index.md @@ -13,20 +13,15 @@ redirect_from: The open index API operation opens a closed index, letting you add or search for data within the index. -## Example - -```json -POST /sample-index/_open -``` -{% include copy-curl.html %} ## Path and HTTP methods -``` +```json POST //_open ``` +{% include copy-curl.html %} -## URL parameters +## Query parameters All parameters are optional. @@ -42,6 +37,13 @@ timeout | Time | How long to wait for a response from the cluster. Default is `3 wait_for_completion | Boolean | When set to `false`, the request returns immediately instead of after the operation is finished. To monitor the operation status, use the [Tasks API]({{site.url}}{{site.baseurl}}/api-reference/tasks/) with the task ID returned by the request. Default is `true`. task_execution_timeout | Time | The explicit task execution timeout. Only useful when wait_for_completion is set to `false`. Default is `1h`. +## Example request + +```json +POST /sample-index/_open +``` +{% include copy-curl.html %} + ## Example response ```json diff --git a/_api-reference/index-apis/put-mapping.md b/_api-reference/index-apis/put-mapping.md index f7d9321d33..26bfbae0d9 100644 --- a/_api-reference/index-apis/put-mapping.md +++ b/_api-reference/index-apis/put-mapping.md @@ -17,17 +17,45 @@ If you want to create or add mappings and fields to an index, you can use the pu You can't use this operation to update mappings that already map to existing data in the index. You must first create a new index with your desired mappings, and then use the [reindex API operation]({{site.url}}{{site.baseurl}}/opensearch/reindex-data) to map all the documents from your old index to the new index. If you don't want any downtime while you re-index your indexes, you can use [aliases]({{site.url}}{{site.baseurl}}/opensearch/index-alias). +## Path and HTTP methods -## Required path parameter +```json +PUT //_mapping +PUT /,/_mapping +``` + + +## Path parameters The only required path parameter is the index with which to associate the mapping. If you don't specify an index, you will get an error. You can specify a single index, or multiple indexes separated by a comma as follows: -``` +```json PUT //_mapping PUT /,/_mapping ``` -## Required request body field +## Query parameters + +Optionally, you can add query parameters to make a more specific request. For example, to skip any missing or closed indexes in the response, you can add the `ignore_unavailable` query parameter to your request as follows: + +```json +PUT /sample-index/_mapping?ignore_unavailable +``` + +The following table defines the put mapping query parameters: + +Parameter | Data type | Description +:--- | :--- | :--- +allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indexes. Default is `true`. +expand_wildcards | String | Expands wildcard expressions to different indexes. Combine multiple values with commas. Available values are `all` (match all indexes), `open` (match open indexes), `closed` (match closed indexes), `hidden` (match hidden indexes), and `none` (do not accept wildcard expressions), which must be used with `open`, `closed`, or both. Default is `open`. +ignore_unavailable | Boolean | If true, OpenSearch does not include missing or closed indexes in the response. +cluster_manager_timeout | Time | How long to wait for a connection to the cluster manager node. Default is `30s`. +timeout | Time | How long to wait for the response to return. Default is `30s`. +write_index_only | Boolean | Whether OpenSearch should apply mapping updates only to the write index. + +## Request body fields + +### properties The request body must contain `properties`, which has all of the mappings that you want to create or update. @@ -44,8 +72,6 @@ The request body must contain `properties`, which has all of the mappings that y } ``` -## Optional request body fields - ### dynamic You can make the document structure match the structure of the index mapping by setting the `dynamic` request body field to `strict`, as seen in the following example: @@ -61,26 +87,8 @@ You can make the document structure match the structure of the index mapping by } ``` -## Optional query parameters - -Optionally, you can add query parameters to make a more specific request. For example, to skip any missing or closed indexes in the response, you can add the `ignore_unavailable` query parameter to your request as follows: - -```json -PUT /sample-index/_mapping?ignore_unavailable -``` - -The following table defines the put mapping query parameters: - -Parameter | Data type | Description -:--- | :--- | :--- -allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indexes. Default is `true`. -expand_wildcards | String | Expands wildcard expressions to different indexes. Combine multiple values with commas. Available values are `all` (match all indexes), `open` (match open indexes), `closed` (match closed indexes), `hidden` (match hidden indexes), and `none` (do not accept wildcard expressions), which must be used with `open`, `closed`, or both. Default is `open`. -ignore_unavailable | Boolean | If true, OpenSearch does not include missing or closed indexes in the response. -cluster_manager_timeout | Time | How long to wait for a connection to the cluster manager node. Default is `30s`. -timeout | Time | How long to wait for the response to return. Default is `30s`. -write_index_only | Boolean | Whether OpenSearch should apply mapping updates only to the write index. -#### Sample Request +## Example request The following request creates a new mapping for the `sample-index` index: @@ -100,7 +108,7 @@ PUT /sample-index/_mapping ``` {% include copy-curl.html %} -#### Sample Response +## Example response Upon success, the response returns `"acknowledged": true`. diff --git a/_api-reference/index-apis/recover.md b/_api-reference/index-apis/recover.md index dc2df1e5a2..c89371b62a 100644 --- a/_api-reference/index-apis/recover.md +++ b/_api-reference/index-apis/recover.md @@ -48,24 +48,6 @@ Parameter | Data type | Description `detailed` | Boolean | When `true`, provides detailed information about shard recoveries. Default is `false`. `index` | String | A comma-separated list or wildcard expression of index names used to limit the request. -## Response fields - -The API responds with the following information about the recovery shard. - -Parameter | Data type | Description -:--- | :--- | :--- -`id` | Integer | The ID of the shard. -`type` | String | The recovery source for the shard. Returned values include:
- `EMPTY_STORE`: An empty store. Indicates a new primary shard or the forced allocation of an empty primary shard using the Cluster Reroute API.
- `EXISTING_STORE`: The store of an existing primary shard. Indicates that the recovery is related to node startup or the allocation of an existing primary shard.
- `LOCAL_SHARDS`: Shards belonging to another index on the same node. Indicates that the recovery is related to a clone, shrink, or split operation.
- `PEER`: A primary shard on another node. Indicates that the recovery is related to shard replication.
- `SNAPSHOT`: A snapshot. Indicates that the recovery is related to a snapshot restore operation. -`STAGE` | String | The recovery stage. Returned values can include:
- `INIT`: Recovery has not started.
- `INDEX`: Reading index metadata and copying bytes from the source to the destination.
- `VERIFY_INDEX`: Verifying the integrity of the index.
- `TRANSLOG`: Replaying the transaction log.
- `FINALIZE`: Cleanup.
- `DONE`: Complete. -`primary` | Boolean | When `true`, the shard is a primary shard. -`start_time` | String | The timestamp indicating when the recovery started. -`stop_time` | String | The timestamp indicating when the recovery completed. -`total_time_in_millis` | String | The total amount of time taken to recover a shard, in milliseconds. -`source` | Object | The recovery source. This can include a description of the repository (if the recovery is from a snapshot) or a description of the source node. -`target` | Object | The destination node. -`index` | Object | Statistics about the physical index recovery. -`translog` | Object | Statistics about the translog recovery. - `start` | Object | Statistics about the amount of time taken to open and start the index. ## Example requests @@ -289,3 +271,22 @@ The following response returns detailed recovery information about an index name } } ``` + +## Response body fields + +The API responds with the following information about the recovery shard. + +Parameter | Data type | Description +:--- | :--- | :--- +`id` | Integer | The ID of the shard. +`type` | String | The recovery source for the shard. Returned values include:
- `EMPTY_STORE`: An empty store. Indicates a new primary shard or the forced allocation of an empty primary shard using the Cluster Reroute API.
- `EXISTING_STORE`: The store of an existing primary shard. Indicates that the recovery is related to node startup or the allocation of an existing primary shard.
- `LOCAL_SHARDS`: Shards belonging to another index on the same node. Indicates that the recovery is related to a clone, shrink, or split operation.
- `PEER`: A primary shard on another node. Indicates that the recovery is related to shard replication.
- `SNAPSHOT`: A snapshot. Indicates that the recovery is related to a snapshot restore operation. +`STAGE` | String | The recovery stage. Returned values can include:
- `INIT`: Recovery has not started.
- `INDEX`: Reading index metadata and copying bytes from the source to the destination.
- `VERIFY_INDEX`: Verifying the integrity of the index.
- `TRANSLOG`: Replaying the transaction log.
- `FINALIZE`: Cleanup.
- `DONE`: Complete. +`primary` | Boolean | When `true`, the shard is a primary shard. +`start_time` | String | The timestamp indicating when the recovery started. +`stop_time` | String | The timestamp indicating when the recovery completed. +`total_time_in_millis` | String | The total amount of time taken to recover a shard, in milliseconds. +`source` | Object | The recovery source. This can include a description of the repository (if the recovery is from a snapshot) or a description of the source node. +`target` | Object | The destination node. +`index` | Object | Statistics about the physical index recovery. +`translog` | Object | Statistics about the translog recovery. + `start` | Object | Statistics about the amount of time taken to open and start the index. diff --git a/_api-reference/index-apis/refresh.md b/_api-reference/index-apis/refresh.md index 4d75060087..917ca5d9a9 100644 --- a/_api-reference/index-apis/refresh.md +++ b/_api-reference/index-apis/refresh.md @@ -48,22 +48,24 @@ The following table lists the available query parameters. All query parameters a | `expand_wildcards` | String | The type of index that the wildcard patterns can match. If the request targets data streams, this argument determines whether the wildcard expressions match any hidden data streams. Supports comma-separated values, such as `open,hidden`. Valid values are `all`, `open`, `closed`, `hidden`, and `none`. +## Example requests -#### Example: Refresh several data streams or indexes +### Refresh several data streams or indexes The following example request refreshes two indexes named `my-index-A` and `my-index-B`: -``` +```json POST /my-index-A,my-index-B/_refresh ``` {% include copy-curl.html %} -#### Example: Refresh all data streams and indexes in a cluster +### Refresh all data streams and indexes in a cluster The following request refreshes all data streams and indexes in a cluster: -``` +```json POST /_refresh ``` +{% include copy-curl.html %} diff --git a/_api-reference/index-apis/rollover.md b/_api-reference/index-apis/rollover.md index 722dfe196c..db30a5d7bf 100644 --- a/_api-reference/index-apis/rollover.md +++ b/_api-reference/index-apis/rollover.md @@ -61,9 +61,9 @@ Parameter | Type | Description `timeout` | Time | The amount of time to wait for a response. Default is `30s`. `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). You can also set to `all` or a positive integer. Values greater than `1` require replicas. For example, if you specify a value of `3`, then the index must have two replicas distributed across two additional nodes in order for the operation to succeed. -## Request body +## Request body fields -The following request body parameters are supported. +The following request body fields are supported. ### `alias` diff --git a/_api-reference/index-apis/segment.md b/_api-reference/index-apis/segment.md index 0ecee63e77..3f8f12c99b 100644 --- a/_api-reference/index-apis/segment.md +++ b/_api-reference/index-apis/segment.md @@ -38,21 +38,6 @@ Parameter | Data type | Description `ignore_unavailable` | Boolean | When `true`, OpenSearch ignores missing or closed indexes. If `false`, OpenSearch returns an error if the force merge operation encounters missing or closed indexes. Default is `false`. `verbose` | Boolean | When `true`, provides information about Lucene's memory usage. Default is `false`. -## Response body fields - -Parameter | Data type | Description - :--- | :--- | :--- -`` | String | The name of the segment used to create internal file names in the shard directory. -`generation` | Integer | The generation number, such as `0`, incremented for each written segment and used to name the segment. -`num_docs` | Integer | The number of documents, obtained from Lucene. Nested documents are counted separately from their parents. Deleted documents, as well as recently indexed documents that are not yet assigned to a segment, are excluded. -`deleted_docs` | Integer | The number of deleted documents, obtained from Lucene, which may not match the actual number of delete operations performed. Recently deleted documents that are not yet assigned to a segment are excluded. Deleted documents are automatically merged when appropriate. OpenSearch will occasionally delete extra documents in order to track recent shard operations. -`size_in_bytes` | Integer | The amount of disk space used by the segment, for example, `50kb`. -`memory_in_bytes` | Integer | The amount of segment data, measured in bytes, that is kept in memory to facilitate efficient search operations, such as `1264`. A value of `-1` indicates that OpenSearch was unable to compute this number. -`committed` | Boolean | When `true`, the segments are synced to disk. Segments synced to disk can survive a hard reboot. If `false`, then uncommitted segment data is stored in the transaction log as well so that changes can be replayed at the next startup. -`search` | Boolean | When `true`, segment search is enabled. When `false`, the segment may have already been written to disk and require a refresh in order to be searchable. -`version` | String | The Lucene version used to write the segment. -`compound` | Boolean | When `true`, indicates that Lucene merged all segment files into one file in order to save any file descriptions. -`attributes` | Object | Shows if high compression was enabled. ## Example requests @@ -119,3 +104,19 @@ GET /_segments } ``` +## Response body fields + +Parameter | Data type | Description + :--- | :--- | :--- +`` | String | The name of the segment used to create internal file names in the shard directory. +`generation` | Integer | The generation number, such as `0`, incremented for each written segment and used to name the segment. +`num_docs` | Integer | The number of documents, obtained from Lucene. Nested documents are counted separately from their parents. Deleted documents, as well as recently indexed documents that are not yet assigned to a segment, are excluded. +`deleted_docs` | Integer | The number of deleted documents, obtained from Lucene, which may not match the actual number of delete operations performed. Recently deleted documents that are not yet assigned to a segment are excluded. Deleted documents are automatically merged when appropriate. OpenSearch will occasionally delete extra documents in order to track recent shard operations. +`size_in_bytes` | Integer | The amount of disk space used by the segment, for example, `50kb`. +`memory_in_bytes` | Integer | The amount of segment data, measured in bytes, that is kept in memory to facilitate efficient search operations, such as `1264`. A value of `-1` indicates that OpenSearch was unable to compute this number. +`committed` | Boolean | When `true`, the segments are synced to disk. Segments synced to disk can survive a hard reboot. If `false`, then uncommitted segment data is stored in the transaction log as well so that changes can be replayed at the next startup. +`search` | Boolean | When `true`, segment search is enabled. When `false`, the segment may have already been written to disk and require a refresh in order to be searchable. +`version` | String | The Lucene version used to write the segment. +`compound` | Boolean | When `true`, indicates that Lucene merged all segment files into one file in order to save any file descriptions. +`attributes` | Object | Shows if high compression was enabled. + diff --git a/_api-reference/index-apis/shrink-index.md b/_api-reference/index-apis/shrink-index.md index 17b7c4dff6..9e2f5166a7 100644 --- a/_api-reference/index-apis/shrink-index.md +++ b/_api-reference/index-apis/shrink-index.md @@ -13,21 +13,6 @@ redirect_from: The shrink index API operation moves all of your data in an existing index into a new index with fewer primary shards. -## Example - -```json -POST /my-old-index/_shrink/my-new-index -{ - "settings": { - "index.number_of_replicas": 4, - "index.number_of_shards": 3 - }, - "aliases":{ - "new-index-alias": {} - } -} -``` -{% include copy-curl.html %} ## Path and HTTP methods @@ -44,7 +29,7 @@ When creating new indexes with this operation, remember that OpenSearch indexes `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, or `<` -## URL parameters +## Query parameters The shrink index API operation requires you to specify both the source index and the target index. All other parameters are optional. @@ -58,13 +43,13 @@ timeout | Time | How long to wait for the request to return a response. Default wait_for_completion | Boolean | When set to `false`, the request returns immediately instead of after the operation is finished. To monitor the operation status, use the [Tasks API]({{site.url}}{{site.baseurl}}/api-reference/tasks/) with the task ID returned by the request. Default is `true`. task_execution_timeout | Time | The explicit task execution timeout. Only useful when wait_for_completion is set to `false`. Default is `1h`. -## Request body +## Request body fields You can use the request body to configure some index settings for the target index. All fields are optional. Field | Type | Description :--- | :--- | :--- -alias | Object | Sets an alias for the target index. Can have the fields `filter`, `index_routing`, `is_hidden`, `is_write_index`, `routing`, or `search_routing`. See [Index Aliases]({{site.url}}{{site.baseurl}}/api-reference/alias/#request-body). +alias | Object | Sets an alias for the target index. Can have the fields `filter`, `index_routing`, `is_hidden`, `is_write_index`, `routing`, or `search_routing`. See [Index Aliases]({{site.url}}{{site.baseurl}}/api-reference/alias/#request-body-fields). settings | Object | Index settings you can apply to your target index. See [Index Settings]({{site.url}}{{site.baseurl}}/im-plugin/index-settings/). [max_shard_size](#the-max_shard_size-parameter) | Bytes | Specifies the maximum size of a primary shard in the target index. Because `max_shard_size` conflicts with the `index.number_of_shards` setting, you cannot set both of them at the same time. @@ -84,4 +69,20 @@ The minimum number of primary shards for the target index is 1. ## Index codec considerations -For index codec considerations, see [Index codecs]({{site.url}}{{site.baseurl}}/im-plugin/index-codecs/#splits-and-shrinks). \ No newline at end of file +For index codec considerations, see [Index codecs]({{site.url}}{{site.baseurl}}/im-plugin/index-codecs/#splits-and-shrinks). + +## Example request + +```json +POST /my-old-index/_shrink/my-new-index +{ + "settings": { + "index.number_of_replicas": 4, + "index.number_of_shards": 3 + }, + "aliases":{ + "new-index-alias": {} + } +} +``` +{% include copy-curl.html %} \ No newline at end of file diff --git a/_api-reference/index-apis/split.md b/_api-reference/index-apis/split.md index ad13bffbba..8a45b0e059 100644 --- a/_api-reference/index-apis/split.md +++ b/_api-reference/index-apis/split.md @@ -48,7 +48,7 @@ OpenSearch indexes have the following naming restrictions: `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, or `<` -## URL parameters +## Query parameters Your request must include the source and target indexes. All split index parameters are optional. diff --git a/_api-reference/index-apis/stats.md b/_api-reference/index-apis/stats.md index 7310298594..728fe7751f 100644 --- a/_api-reference/index-apis/stats.md +++ b/_api-reference/index-apis/stats.md @@ -825,6 +825,6 @@ By default, the returned statistics are aggregated in the `primaries` and `total ``` -## Response fields +## Response body fields For information about response fields, see [Nodes Stats API response fields]({{site.url}}{{site.baseurl}}/api-reference/nodes-apis/nodes-stats/#indices). diff --git a/_api-reference/index-apis/update-settings.md b/_api-reference/index-apis/update-settings.md index 9fc9f01f85..7e774bce5a 100644 --- a/_api-reference/index-apis/update-settings.md +++ b/_api-reference/index-apis/update-settings.md @@ -15,18 +15,6 @@ You can use the update settings API operation to update index-level settings. Yo Aside from the static and dynamic index settings, you can also update individual plugins' settings. To get the full list of updatable settings, run `GET /_settings?include_defaults=true`. -## Example - -```json -PUT /sample-index1/_settings -{ - "index.plugins.index_state_management.rollover_skip": true, - "index": { - "number_of_replicas": 4 - } -} -``` -{% include copy-curl.html %} ## Path and HTTP methods @@ -59,7 +47,20 @@ The request body must all of the index settings that you want to update. } ``` -## Response +## Example request + +```json +PUT /sample-index1/_settings +{ + "index.plugins.index_state_management.rollover_skip": true, + "index": { + "number_of_replicas": 4 + } +} +``` +{% include copy-curl.html %} + +## Example response ```json { diff --git a/_api-reference/msearch-template.md b/_api-reference/msearch-template.md index 316cc134ff..a6b6f673de 100644 --- a/_api-reference/msearch-template.md +++ b/_api-reference/msearch-template.md @@ -15,31 +15,15 @@ The Multi-search Template API runs multiple search template requests in a single The Multi-search Template API uses the following paths: -``` +```json GET /_msearch/template POST /_msearch/template GET /{index}/_msearch/template POST /{index}/_msearch/template ``` -## Request body - -The multi-search template request body follows this pattern, similar to the [Multi-search API]({{site.url}}{{site.baseurl}}/api-reference/multi-search/) pattern: - -``` -Metadata\n -Query\n -Metadata\n -Query\n - -``` - -- Metadata lines include options, such as which indexes to search and the type of search. -- Query lines use [query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/). - -Like the [bulk]({{site.url}}{{site.baseurl}}/api-reference/document-apis/bulk/) operation, the JSON doesn't need to be minified---spaces are fine---but it does need to be on a single line. OpenSearch uses newline characters to parse multi-search requests and requires that the request body end with a newline character. -## URL parameters and metadata options +## Query parameters and metadata options All multi-search template URL parameters are optional. Some can also be applied per search as part of each metadata line. @@ -57,7 +41,7 @@ rest_total_hits_as_int | String | Specifies whether the `hits.total` property is search_type | String | Affects the relevance score. Valid options are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using term and document frequencies for a single shard (faster, less accurate), whereas `dfs_query_then_fetch` uses term and document frequencies across all shards (slower, more accurate). Default is `query_then_fetch`. | Yes typed_keys | Boolean | Specifies whether to prefix aggregation names with their internal types in the response. Default is `false`. | No -## Metadata-only options +### Metadata-only options Some options can't be applied as URL parameters to the entire request. Instead, you can apply them per search as part of each metadata line. All are optional. @@ -68,11 +52,26 @@ preference | String | Specifies the nodes or shards on which you want to perform request_cache | Boolean | Specifies whether to cache results, which can improve latency for repeated searches. Default is to use the `index.requests.cache.enable` setting for the index (which defaults to `true` for new indexes). routing | String | Comma-separated custom routing values, for example, `"routing": "value1,value2,value3"`. -## Example +## Request body -The following example `msearch/template` API request runs queries against a single index using multiple templates named `line_search_template` and `play_search_template`: +The multi-search template request body follows this pattern, similar to the [Multi-search API]({{site.url}}{{site.baseurl}}/api-reference/multi-search/) pattern: + +``` +Metadata\n +Query\n +Metadata\n +Query\n -### Request +``` + +- Metadata lines include options, such as which indexes to search and the type of search. +- Query lines use [query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/). + +Like the [bulk]({{site.url}}{{site.baseurl}}/api-reference/document-apis/bulk/) operation, the JSON doesn't need to be minified---spaces are fine---but it does need to be on a single line. OpenSearch uses newline characters to parse multi-search requests and requires that the request body end with a newline character. + +## Example request + +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 @@ -83,7 +82,7 @@ GET _msearch/template ``` {% include copy-curl.html %} -### Response +## Example response OpenSearch returns an array with the results of each search in the same order as in the multi-search template request: diff --git a/_api-reference/multi-search.md b/_api-reference/multi-search.md index ff04b2d075..7ba7a89da4 100644 --- a/_api-reference/multi-search.md +++ b/_api-reference/multi-search.md @@ -55,7 +55,7 @@ Query\n Just like the [bulk]({{site.url}}{{site.baseurl}}/api-reference/document-apis/bulk/) operation, the JSON doesn't need to be minified---spaces are fine---but it does need to be on a single line. OpenSearch uses newline characters to parse multi-search requests and requires that the request body end with a newline character. -## URL parameters and metadata options +## Query parameters and metadata options All multi-search URL parameters are optional. Some can also be applied per-search as part of each metadata line. @@ -90,11 +90,10 @@ request_cache | Boolean | Whether to cache results, which can improve latency fo routing | String | Comma-separated custom routing values, for example, `"routing": "value1,value2,value3"`. -## Example +## Example request The following example `msearch` API request runs queries against multiple indexes: -### Request ```json GET _msearch @@ -107,7 +106,7 @@ GET _msearch {% include copy-curl.html %} -### Response +## Example response OpenSearch returns an array with the results of each search in the same order as the multi-search request. diff --git a/_api-reference/nodes-apis/nodes-hot-threads.md b/_api-reference/nodes-apis/nodes-hot-threads.md index f5e014dd6d..5339903d1e 100644 --- a/_api-reference/nodes-apis/nodes-hot-threads.md +++ b/_api-reference/nodes-apis/nodes-hot-threads.md @@ -11,12 +11,6 @@ nav_order: 30 The nodes hot threads endpoint provides information about busy JVM threads for selected cluster nodes. It provides a unique view of the of activity each node. -#### Example - -```json -GET /_nodes/hot_threads -``` -{% include copy-curl.html %} ## Path and HTTP methods diff --git a/_api-reference/nodes-apis/nodes-info.md b/_api-reference/nodes-apis/nodes-info.md index a8953505ff..be4c71fa95 100644 --- a/_api-reference/nodes-apis/nodes-info.md +++ b/_api-reference/nodes-apis/nodes-info.md @@ -18,21 +18,6 @@ The nodes info API represents mostly static information about your cluster's nod - Thread pools settings - Installed plugins -## Example - -To get information about all nodes in a cluster, use the following query: - -```json -GET /_nodes -``` -{% include copy-curl.html %} - -To get thread pool information about the cluster manager node only, use the following query: - -```json -GET /_nodes/master:true/thread_pool -``` -{% include copy-curl.html %} ## Path and HTTP methods @@ -88,6 +73,13 @@ GET /_nodes/cluster_manager:true/process,transport ``` {% include copy-curl.html %} +To get thread pool information about the cluster manager node only, use the following query: + +```json +GET /_nodes/master:true/thread_pool +``` +{% include copy-curl.html %} + ## Example response The response contains the metric groups specified in the `` request parameter (in this case, `process` and `transport`): @@ -136,7 +128,7 @@ The response contains the metric groups specified in the `` request par } ``` -## Response fields +## Response body fields The response contains the basic node identification and build info for every node matching the `` request parameter. The following table lists the response fields. diff --git a/_api-reference/nodes-apis/nodes-reload-secure.md b/_api-reference/nodes-apis/nodes-reload-secure.md index b4be66ddd4..861d3af5a3 100644 --- a/_api-reference/nodes-apis/nodes-reload-secure.md +++ b/_api-reference/nodes-apis/nodes-reload-secure.md @@ -26,7 +26,7 @@ Parameter | Type | Description :--- | :--- | :--- nodeId | String | A comma-separated list of nodeIds used to filter results. Supports [node filters]({{site.url}}{{site.baseurl}}/api-reference/nodes-apis/index/#node-filters). Defaults to `_all`. -## Request fields +## Request body fields The request may include an optional object containing the password for the OpenSearch keystore. diff --git a/_api-reference/nodes-apis/nodes-stats.md b/_api-reference/nodes-apis/nodes-stats.md index 479cd8e732..604b89969b 100644 --- a/_api-reference/nodes-apis/nodes-stats.md +++ b/_api-reference/nodes-apis/nodes-stats.md @@ -788,7 +788,7 @@ Select the arrow to view the example response. ``` -## Response fields +## Response body fields The following table lists all response fields. diff --git a/_api-reference/profile.md b/_api-reference/profile.md index 4f8c69db9c..e54ffabe15 100644 --- a/_api-reference/profile.md +++ b/_api-reference/profile.md @@ -18,6 +18,18 @@ The Profile API provides timing information about the execution of individual co The Profile API is a resource-consuming operation that adds overhead to search operations. {: .warning} +## Path and HTTP methods + +```json +GET /testindex/_search +{ + "profile": true, + "query" : { + "match" : { "title" : "wind" } + } +} +``` + ## Concurrent segment search Starting in OpenSearch 2.12, [concurrent segment search]({{site.url}}{{site.baseurl}}/search-plugins/concurrent-segment-search/) allows each shard-level request to search segments in parallel during the query phase. The Profile API response contains several additional fields with statistics about _slices_. @@ -26,7 +38,9 @@ A slice is the unit of work that can be executed by a thread. Each query can be In general, the max/min/avg slice time captures statistics across all slices for a timing type. For example, when profiling aggregations, the `max_slice_time_in_nanos` field in the `aggregations` section shows the maximum time consumed by the aggregation operation and its children across all slices. -## Example request: Non-concurrent search +## Example requests + +### Non-concurrent search To use the Profile API, include the `profile` parameter set to `true` in the search request sent to the `_search` endpoint: @@ -70,7 +84,54 @@ The response contains an additional `time` field with human-readable units, for The Profile API response is verbose, so if you're running the request through the `curl` command, include the `?pretty` query parameter to make the response easier to understand. {: .tip} -#### Example response +### Aggregations + +To profile aggregations, send an aggregation request and provide the `profile` parameter set to `true`. + +#### Global aggregation + +```json +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" } } + } +} +``` +{% include copy-curl.html %} + +#### Non-global aggregation + +```json +GET /opensearch_dashboards_sample_data_ecommerce/_search +{ + "size": 0, + "aggs": { + "avg_taxful_total_price": { + "avg": { + "field": "taxful_total_price" + } + } + } +} +``` +{% include copy-curl.html %} + + +## Example response + +### Non-concurrent search The response contains profiling information: @@ -221,7 +282,7 @@ The response contains profiling information: ``` -#### Example response: Concurrent segment search +### Concurrent segment search The following is an example response for a concurrent segment search with three segment slices: @@ -435,7 +496,7 @@ The following is an example response for a concurrent segment search with three ``` -## Response fields +## Response body fields The response includes the following fields. @@ -522,34 +583,9 @@ Reason | Description `aggregation` | A collector for aggregations that is run against the specified query scope. OpenSearch uses a single `aggregation` collector to collect documents for all aggregations. `global_aggregation` | A collector that is run against the global query scope. Global scope is different from a specified query scope, so in order to collect the entire dataset, a `match_all` query must be run. -## Aggregations - -To profile aggregations, send an aggregation request and provide the `profile` parameter set to `true`. - -#### Example request: Global aggregation - -```json -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" } } - } -} -``` -{% include copy-curl.html %} +### Aggregation responses -#### Example response: Global aggregation +#### Response: Global aggregation The response contains profiling information: @@ -804,24 +840,7 @@ The response contains profiling information: ``` -#### Example request: Non-global aggregation - -```json -GET /opensearch_dashboards_sample_data_ecommerce/_search -{ - "size": 0, - "aggs": { - "avg_taxful_total_price": { - "avg": { - "field": "taxful_total_price" - } - } - } -} -``` -{% include copy-curl.html %} - -#### Example response: Non-global aggregation +#### Response: Non-global aggregation The response contains profiling information: @@ -966,13 +985,13 @@ The response contains profiling information: ``` -### Response fields +#### Response body fields The `aggregations` array contains aggregation objects with the following fields. Field | Data type | Description :--- | :--- | :--- -`type` | String | The aggregator type. In the [non-global aggregation example response](#example-response-non-global-aggregation), the aggregator type is `AvgAggregator`. [Global aggregation example response](#example-request-global-aggregation) contains a `GlobalAggregator` with an `AvgAggregator` child. +`type` | String | The aggregator type. In the [non-global aggregation example response](#response-non-global-aggregation), the aggregator type is `AvgAggregator`. [Global aggregation example response](#response-global-aggregation) contains a `GlobalAggregator` with an `AvgAggregator` child. `description` | String | Contains a Lucene explanation of the aggregation. Helps differentiate aggregations with the same type. `time_in_nanos` | Long | The total elapsed time for this aggregation, in nanoseconds. For concurrent segment search, `time_in_nanos` is the total amount of time across all slices (the difference between the last completed slice execution end time and the first slice execution start time). [`breakdown`](#the-breakdown-object-1) | Object | Contains timing statistics about low-level Lucene execution. @@ -982,7 +1001,7 @@ Field | Data type | Description `min_slice_time_in_nanos` |Long |The minimum amount of time taken by any slice to run an aggregation, in nanoseconds. This field is included only if you enable concurrent segment search. `avg_slice_time_in_nanos` |Long |The average amount of time taken by any slice to run an aggregation, in nanoseconds. This field is included only if you enable concurrent segment search. -### The `breakdown` object +#### The `breakdown` object The `breakdown` object represents the timing statistics about low-level Lucene execution, broken down by method. Each field in the `breakdown` object represents an internal Lucene method executed within the aggregation. Timings are listed in wall-clock nanoseconds and are not normalized. The `breakdown` timings are inclusive of all child times. The `breakdown` object is comprised of the following fields. All fields contain integer values. diff --git a/_api-reference/rank-eval.md b/_api-reference/rank-eval.md index 881ff3a22b..05d2e9a672 100644 --- a/_api-reference/rank-eval.md +++ b/_api-reference/rank-eval.md @@ -28,7 +28,7 @@ allow_no_indices | Boolean | Defaults to `true`. When set to `false` the respons expand_wildcards | String | Expand wildcard expressions for indexes that are `open`, `closed`, `hidden`, `none`, or `all`. search_type | String | Set search type to either `query_then_fetch` or `dfs_query_then_fetch`. -## Request fields +## Request body fields The request body must contain at least one parameter. diff --git a/_api-reference/remote-info.md b/_api-reference/remote-info.md index ac2971f294..7f703fee1d 100644 --- a/_api-reference/remote-info.md +++ b/_api-reference/remote-info.md @@ -17,12 +17,12 @@ The response is more comprehensive and useful than a call to `_cluster/settings` ## Path and HTTP methods -``` +```json GET _remote/info ``` {% include copy-curl.html %} -## Response +## Example Response ```json { diff --git a/_api-reference/render-template.md b/_api-reference/render-template.md index 409fde5e4a..132cb2e088 100644 --- a/_api-reference/render-template.md +++ b/_api-reference/render-template.md @@ -25,7 +25,7 @@ The Render Template API supports the following optional path parameter. | :--- | :--- | :--- | | `id` | String | The ID of the search template to render. | -## Request options +## Request body fields The following options are supported in the request body of the Render Template API. diff --git a/_api-reference/script-apis/create-stored-script.md b/_api-reference/script-apis/create-stored-script.md index 0a915cd836..d28c504a51 100644 --- a/_api-reference/script-apis/create-stored-script.md +++ b/_api-reference/script-apis/create-stored-script.md @@ -34,7 +34,7 @@ All parameters are optional. | cluster_manager_timeout | Time | Amount of time to wait for a connection to the cluster manager. Defaults to 30 seconds. | | timeout | Time | The period of time to wait for a response. If a response is not received before the timeout value, the request fails and returns an error. Defaults to 30 seconds.| -## Request fields +## Request body fields | Field | Data type | Description | :--- | :--- | :--- @@ -49,7 +49,7 @@ All parameters are optional. ## Example request -The sample uses an index called `books` with the following documents: +The following example requests uses an index called `books` with the following documents: ````json {"index":{"_id":1}} @@ -60,6 +60,8 @@ The sample uses an index called `books` with the following documents: {"name":"book3","author":"Gilroy","ratings":[2,1,5]} ```` +### 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 @@ -96,10 +98,16 @@ curl -XPUT "http://opensearch:9200/_scripts/my-first-script" -H 'Content-Type: a {% include copy.html %} -The following request creates the Painless script `my-first-script`, which sums the ratings for each book and displays the sum in the output: +See [Execute Painless stored script]({{site.url}}{{site.baseurl}}/api-reference/script-apis/exec-stored-script/) for information about running the script. + +### Creating or updating a stored script with parameters + +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/my-first-script +PUT _scripts/multiplier-script { "script": { "lang": "painless", @@ -108,15 +116,13 @@ PUT _scripts/my-first-script for (int i = 0; i < doc['ratings'].length; ++i) { total += doc['ratings'][i]; } - return total; + return total * params['multiplier']; """ } } ```` {% include copy-curl.html %} -See [Execute Painless stored script]({{site.url}}{{site.baseurl}}/api-reference/script-apis/exec-stored-script/) for information about running the script. - ## Example response The `PUT _scripts/my-first-script` request returns the following field: @@ -130,43 +136,5 @@ The `PUT _scripts/my-first-script` request returns the following field: To determine whether the script was successfully created, use the [Get stored script]({{site.url}}{{site.baseurl}}/api-reference/script-apis/get-stored-script/) API, passing the script name as the `script` path parameter. {: .note} -### Response fields - -| Field | Data type | Description | -:--- | :--- | :--- -| acknowledged | Boolean | Whether the request was received. | - -## Creating or updating a stored script with parameters - -The Painless script supports `params` to pass variables to the script. - -#### Example - -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 -{ - "script": { - "lang": "painless", - "source": """ - int total = 0; - for (int i = 0; i < doc['ratings'].length; ++i) { - total += doc['ratings'][i]; - } - return total * params['multiplier']; - """ - } -} -```` -{% include copy-curl.html %} - -### Example response -The `PUT _scripts/multiplier-script` request returns the following field: -````json -{ - "acknowledged" : true -} -```` \ No newline at end of file diff --git a/_api-reference/script-apis/delete-script.md b/_api-reference/script-apis/delete-script.md index fe9c272acc..fc40eb896d 100644 --- a/_api-reference/script-apis/delete-script.md +++ b/_api-reference/script-apis/delete-script.md @@ -9,7 +9,14 @@ nav_order: 4 **Introduced 1.0** {: .label .label-purple } -Deletes a stored script +Deletes a stored script. + +## Path and HTTP methods + +````json +DELETE _scripts/my-script +```` + ## Path parameters @@ -47,7 +54,7 @@ The `DELETE _scripts/my-first-script` request returns the following field: To determine whether the stored script was successfully deleted, use the [Get stored script]({{site.url}}{{site.baseurl}}/api-reference/script-apis/get-stored-script/) API, passing the script name as the `script` path parameter. -## Response fields +## Response body fields The request returns the following response fields: diff --git a/_api-reference/script-apis/exec-script.md b/_api-reference/script-apis/exec-script.md index b6476be980..cd31ad92f4 100644 --- a/_api-reference/script-apis/exec-script.md +++ b/_api-reference/script-apis/exec-script.md @@ -18,7 +18,7 @@ GET /_scripts/painless/_execute POST /_scripts/painless/_execute ``` -## Request fields +## Request body fields | Field | Description | :--- | :--- @@ -54,7 +54,7 @@ The response contains the average of two script parameters: } ``` -## Response fields +## Response body fields | Field | Description | :--- | :--- diff --git a/_api-reference/script-apis/exec-stored-script.md b/_api-reference/script-apis/exec-stored-script.md index a7de3b5274..31102c23dd 100644 --- a/_api-reference/script-apis/exec-stored-script.md +++ b/_api-reference/script-apis/exec-stored-script.md @@ -13,7 +13,22 @@ Runs a stored script written in the Painless language. OpenSearch provides several ways to run a script; the following sections show how to run a script by passing script information in the request body of a `GET /_search` request. -## Request fields +## Path and HTTP methods + +```json +GET books/_search +{ + "script_fields": { + "total_ratings": { + "script": { + "id": "my-first-script" + } + } + } +} +``` + +## Request field options | Field | Data type | Description | :--- | :--- | :--- @@ -104,7 +119,7 @@ The `GET books/_search` request returns the following fields: } ```` -## Response fields +## Response body fields | Field | Data type | Description | :--- | :--- | :--- diff --git a/_api-reference/script-apis/get-script-contexts.md b/_api-reference/script-apis/get-script-contexts.md index 85421128a1..68c4dd086c 100644 --- a/_api-reference/script-apis/get-script-contexts.md +++ b/_api-reference/script-apis/get-script-contexts.md @@ -547,7 +547,7 @@ The `GET _script_context` request returns the following fields: } ```` -## Response fields +## Response body fields The `GET _script_context` request returns the following response fields: diff --git a/_api-reference/script-apis/get-script-language.md b/_api-reference/script-apis/get-script-language.md index 76414d52ea..a7bb7e7b51 100644 --- a/_api-reference/script-apis/get-script-language.md +++ b/_api-reference/script-apis/get-script-language.md @@ -89,7 +89,7 @@ The `GET _script_language` request returns the available contexts for each langu } ``` -## Response fields +## Response body fields The request contains the following response fields. diff --git a/_api-reference/script-apis/get-stored-script.md b/_api-reference/script-apis/get-stored-script.md index d7987974d3..341bfc046e 100644 --- a/_api-reference/script-apis/get-stored-script.md +++ b/_api-reference/script-apis/get-stored-script.md @@ -11,6 +11,12 @@ nav_order: 3 Retrieves a stored script. +## Path and HTTP methods + +```json +GET _scripts/my-first-script +``` + ## Path parameters | Parameter | Data type | Description | @@ -53,7 +59,7 @@ The `GET _scripts/my-first-script` request returns the following fields: } ```` -## Response fields +## Response body fields The `GET _scripts/my-first-script` request returns the following response fields: diff --git a/_api-reference/scroll.md b/_api-reference/scroll.md index b940c90d86..d667167bef 100644 --- a/_api-reference/scroll.md +++ b/_api-reference/scroll.md @@ -17,7 +17,28 @@ To use the `scroll` operation, add a `scroll` parameter to the request header wi Because search contexts consume a lot of memory, we suggest you don't use the `scroll` operation for frequent user queries. Instead, use the `sort` parameter with the `search_after` parameter to scroll responses for user queries. {: .note } -## Example +## Path and HTTP methods + +``` +GET _search/scroll +POST _search/scroll +``` +``` +GET _search/scroll/ +POST _search/scroll/ +``` + +## Query parameters + +All scroll parameters are optional. + +Parameter | Type | Description +:--- | :--- | :--- +scroll | Time | Specifies the amount of time the search context is maintained. +scroll_id | String | The scroll ID for the search. +rest_total_hits_as_int | Boolean | Whether the `hits.total` property is returned as an integer (`true`) or an object (`false`). Default is `false`. + +## Example requests To set the number of results that you want returned for each batch, use the `size` parameter: @@ -84,28 +105,6 @@ DELETE _search/scroll/_all The `scroll` operation corresponds to a specific timestamp. It doesn't consider documents added after that timestamp as potential results. - -## Path and HTTP methods - -``` -GET _search/scroll -POST _search/scroll -``` -``` -GET _search/scroll/ -POST _search/scroll/ -``` - -## URL parameters - -All scroll parameters are optional. - -Parameter | Type | Description -:--- | :--- | :--- -scroll | Time | Specifies the amount of time the search context is maintained. -scroll_id | String | The scroll ID for the search. -rest_total_hits_as_int | Boolean | Whether the `hits.total` property is returned as an integer (`true`) or an object (`false`). Default is `false`. - ## Example response ```json diff --git a/_api-reference/search.md b/_api-reference/search.md index 777f48354e..18040768b7 100644 --- a/_api-reference/search.md +++ b/_api-reference/search.md @@ -12,20 +12,6 @@ redirect_from: The Search API operation lets you execute a search request to search your cluster for data. -## Example - -```json -GET /movies/_search -{ - "query": { - "match": { - "text_entry": "I am the night" - } - } -} -``` -{% include copy-curl.html %} - ## Path and HTTP Methods ``` @@ -36,7 +22,7 @@ POST //_search POST /_search ``` -## URL Parameters +## Query parameters All URL parameters are optional. @@ -124,7 +110,22 @@ terminate_after | Integer | The maximum number of documents OpenSearch should pr timeout | Time | How long to wait for a response. Default is no timeout. version | Boolean | Whether to include the document version in the response. -## Response body +## Example request + +```json +GET /movies/_search +{ + "query": { + "match": { + "text_entry": "I am the night" + } + } +} +``` +{% include copy-curl.html %} + + +## Response body fields ```json { diff --git a/_api-reference/snapshots/create-snapshot.md b/_api-reference/snapshots/create-snapshot.md index b35d1a1d0c..45e5a28b55 100644 --- a/_api-reference/snapshots/create-snapshot.md +++ b/_api-reference/snapshots/create-snapshot.md @@ -26,7 +26,7 @@ POST /_snapshot// Parameter | Data type | Description :--- | :--- | :--- -repository | String | Repostory name to contain the snapshot. | +repository | String | Repository name to store the snapshot. | snapshot | String | Name of Snapshot to create. | ## Query parameters @@ -35,7 +35,7 @@ Parameter | Data type | Description :--- | :--- | :--- wait_for_completion | Boolean | Whether to wait for snapshot creation to complete before continuing. If you include this parameter, the snapshot definition is returned after completion. | -## Request fields +## Request body fields The request body is optional. @@ -48,7 +48,7 @@ Field | Data type | Description ## Example requests -##### Request without a body +### Request without a body 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. @@ -57,7 +57,7 @@ POST _snapshot/my-s3-repository/my-first-snapshot ``` {% include copy-curl.html %} -##### Request with a body +### Request with a body You can also add a request body to include or exclude certain indices or specify other settings: @@ -87,7 +87,7 @@ Upon success, the response content depends on whether you include the `wait_for_ To verify that the snapshot was created, use the [Get snapshot]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot) API, passing the snapshot name as the `snapshot` path parameter. {: .note} -##### `wait_for_completion` included +### `wait_for_completion` included The snapshot definition is returned. @@ -125,7 +125,7 @@ The snapshot definition is returned. } ``` -#### Response fields +## Response body fields | Field | Data type | Description | | :--- | :--- | :--- | diff --git a/_api-reference/snapshots/get-snapshot-repository.md b/_api-reference/snapshots/get-snapshot-repository.md index 6617106059..f348213f08 100644 --- a/_api-reference/snapshots/get-snapshot-repository.md +++ b/_api-reference/snapshots/get-snapshot-repository.md @@ -54,7 +54,7 @@ Upon success, the response returns repositry information. This sample is for an } ```` -## Response fields +## Response body fields | Field | Data type | Description | | :--- | :--- | :--- | diff --git a/_api-reference/snapshots/get-snapshot-status.md b/_api-reference/snapshots/get-snapshot-status.md index 9636b40d64..ff80e735e6 100644 --- a/_api-reference/snapshots/get-snapshot-status.md +++ b/_api-reference/snapshots/get-snapshot-status.md @@ -44,7 +44,7 @@ Snapshot API calls only work if the total number of shards across the requested Using the API to return the state of snapshots that are not currently running can be very costly in terms of both machine resources and processing time when querying data in the cloud. For each snapshot, each request causes a file read of all of the snapshot's shards. {: .warning} -## Request fields +## Request body fields | Field | Data type | Description | :--- | :--- | :--- @@ -377,7 +377,7 @@ The `GET _snapshot/my-opensearch-repo/my-first-snapshot/_status` request returns } ```` -## Response fields +## Response body fields | Field | Data type | Description | :--- | :--- | :--- @@ -390,7 +390,7 @@ The `GET _snapshot/my-opensearch-repo/my-first-snapshot/_status` request returns | stats | Object | Information about files included in the snapshot. `file_count`: number of files. `size_in_bytes`: total size of all files. See [Snapshot file stats](#snapshot-file-stats). | | index | list of Objects | List of objects that contain information about the indices in the snapshot. See [Index objects](#index-objects).| -##### Snapshot states +### Snapshot states | State | Description | :--- | :--- | @@ -399,9 +399,9 @@ The `GET _snapshot/my-opensearch-repo/my-first-snapshot/_status` request returns | PARTIAL | The global cluster state was stored, but data from at least one shard was not stored. The `failures` property of the [Create snapshot]({{site.url}}{{site.baseurl}}/api-reference/snapshots/create-snapshot) response contains additional details. | | SUCCESS | The snapshot finished and all shards were stored successfully. | -##### Shard stats +### Shard stats -All property values are Integers. +All property values are integers. | Property | Description | :--- | :--- | @@ -412,7 +412,7 @@ All property values are Integers. | failed | Number of shards that failed to be included in the snapshot. | | total | Total number of shards included in the snapshot. | -##### Snapshot file stats +### Snapshot file stats | Property | Type | Description | :--- | :--- | :--- | @@ -422,7 +422,7 @@ All property values are Integers. | start_time_in_millis | Long | Time (in milliseconds) when snapshot creation began. | | time_in_millis | Long | Total time (in milliseconds) that the snapshot took to complete. | -##### Index objects +### Index objects | Property | Type | Description | :--- | :--- | :--- | diff --git a/_api-reference/snapshots/get-snapshot.md b/_api-reference/snapshots/get-snapshot.md index ac55c0370f..dff0feefaf 100644 --- a/_api-reference/snapshots/get-snapshot.md +++ b/_api-reference/snapshots/get-snapshot.md @@ -73,7 +73,7 @@ Upon success, the response returns snapshot information: ] } ```` -## Response fields +## Response body fields | Field | Data type | Description | | :--- | :--- | :--- | diff --git a/_api-reference/snapshots/restore-snapshot.md b/_api-reference/snapshots/restore-snapshot.md index cdb9948c28..228ee7292f 100644 --- a/_api-reference/snapshots/restore-snapshot.md +++ b/_api-reference/snapshots/restore-snapshot.md @@ -32,7 +32,7 @@ Parameter | Data type | Description :--- | :--- | :--- wait_for_completion | Boolean | Whether to wait for snapshot restoration to complete before continuing. | -### Request fields +## Request body fields All request body parameters are optional. @@ -92,7 +92,7 @@ Upon success, the response returns the following JSON object: ```` Except for the snapshot name, all properties are empty or `0`. This is because any changes made to the volume after the snapshot was generated are lost. However, if you invoke the [Get snapshot]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot) API to examine the snapshot, a fully populated snapshot object is returned. -## Response fields +## Response body fields | Field | Data type | Description | | :--- | :--- | :--- | diff --git a/_api-reference/snapshots/verify-snapshot-repository.md b/_api-reference/snapshots/verify-snapshot-repository.md index e5e6337196..9af7cca08f 100644 --- a/_api-reference/snapshots/verify-snapshot-repository.md +++ b/_api-reference/snapshots/verify-snapshot-repository.md @@ -70,7 +70,7 @@ In the preceding sample, one node is connected to the snapshot repository. If mo } ```` -## Response fields +## Response body fields | Field | Data type | Description | :--- | :--- | :--- diff --git a/_api-reference/tasks.md b/_api-reference/tasks.md index e4ca0b6049..477e720d22 100644 --- a/_api-reference/tasks.md +++ b/_api-reference/tasks.md @@ -12,9 +12,9 @@ redirect_from: A task is any operation you run in a cluster. For example, searching your data collection of books for a title or author name is a task. When you run OpenSearch, a task is automatically created to monitor your cluster's health and performance. For more information about all of the tasks currently executing in your cluster, you can use the `tasks` API operation. -The following request returns information about all of your tasks: +## Path and HTTP methods -``` +```json GET _tasks ``` {% include copy-curl.html %} @@ -28,6 +28,7 @@ GET _tasks/ Note that if a task finishes running, it won't be returned as part of your request. For an example of a task that takes a little longer to finish, you can run the [`_reindex`]({{site.url}}{{site.baseurl}}/opensearch/reindex-data) API operation on a larger document, and then run `tasks`. +## Query parameters You can also use the following parameters with your query. @@ -42,7 +43,6 @@ Parameter | Data type | Description | `timeout` | Time | An explicit operation timeout. (Default: 30 seconds) `cluster_manager_timeout` | Time | The time to wait for a connection to the primary node. (Default: 30 seconds) -For example, this request returns tasks currently running on a node named `opensearch-node1`: ## Example requests diff --git a/_automating-configurations/api/create-workflow.md b/_automating-configurations/api/create-workflow.md index 770c1a1a13..610bfe8fab 100644 --- a/_automating-configurations/api/create-workflow.md +++ b/_automating-configurations/api/create-workflow.md @@ -105,7 +105,7 @@ The following table lists the available query parameters. All query parameters a | `use_case` | String | The name of the [workflow template]({{site.url}}{{site.baseurl}}/automating-configurations/workflow-templates/#supported-workflow-templates) to use when creating the workflow. | | User-provided substitution expressions | String | Parameters matching substitution expressions in the template. Only allowed if `provision` is set to `true`. Optional. If `provision` is set to `false`, you can pass these parameters in the [Provision Workflow API query parameters]({{site.url}}{{site.baseurl}}/automating-configurations/api/provision-workflow/#query-parameters). | -## Request fields +## Request body fields The following table lists the available request fields. diff --git a/_dashboards/visualize/maps-stats-api.md b/_dashboards/visualize/maps-stats-api.md index f81c7e6ac4..7c974a33d9 100644 --- a/_dashboards/visualize/maps-stats-api.md +++ b/_dashboards/visualize/maps-stats-api.md @@ -93,7 +93,7 @@ The following is the response for the preceding request: } ``` -## Response fields +## Response body fields The response contains statistics for the following layer types: diff --git a/_getting-started/search-data.md b/_getting-started/search-data.md index c6970e7e7b..8e4169fbae 100644 --- a/_getting-started/search-data.md +++ b/_getting-started/search-data.md @@ -104,7 +104,7 @@ OpenSearch returns the matching documents: } ``` -## Response fields +## Response body fields The preceding response contains the following fields. diff --git a/_im-plugin/ism/policies.md b/_im-plugin/ism/policies.md index e6262e883b..27c37e67ea 100644 --- a/_im-plugin/ism/policies.md +++ b/_im-plugin/ism/policies.md @@ -539,7 +539,7 @@ GET _plugins/_rollup/jobs//_explain } ```` -#### Request fields +#### Request body fields Request fields are required when creating an ISM policy. You can reference the [Index rollups API]({{site.url}}{{site.baseurl}}/im-plugin/index-rollups/rollup-api/#create-or-update-an-index-rollup-job) page for request field options. diff --git a/_ml-commons-plugin/api/agent-apis/execute-agent.md b/_ml-commons-plugin/api/agent-apis/execute-agent.md index 27d50bced0..2af4fc2c8e 100644 --- a/_ml-commons-plugin/api/agent-apis/execute-agent.md +++ b/_ml-commons-plugin/api/agent-apis/execute-agent.md @@ -18,7 +18,7 @@ When an agent is executed, it runs the tools with which it is configured. POST /_plugins/_ml/agents//_execute ``` -## Request fields +## Request body fields The following table lists the available request fields. diff --git a/_ml-commons-plugin/api/agent-apis/get-agent.md b/_ml-commons-plugin/api/agent-apis/get-agent.md index 6190406649..7a03e85221 100644 --- a/_ml-commons-plugin/api/agent-apis/get-agent.md +++ b/_ml-commons-plugin/api/agent-apis/get-agent.md @@ -77,6 +77,6 @@ Assistant:""" } ``` -## Response fields +## Response body fields -For response field descriptions, see [Register Agent API request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agent-apis/register-agent#request-fields). \ No newline at end of file +For response field descriptions, see [Register Agent API request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agent-apis/register-agent#request-body-fields). \ No newline at end of file diff --git a/_ml-commons-plugin/api/agent-apis/register-agent.md b/_ml-commons-plugin/api/agent-apis/register-agent.md index eeea2af715..0057b44427 100644 --- a/_ml-commons-plugin/api/agent-apis/register-agent.md +++ b/_ml-commons-plugin/api/agent-apis/register-agent.md @@ -27,7 +27,7 @@ POST /_plugins/_ml/agents/_register ``` {% include copy-curl.html %} -## Request fields +## Request body fields The following table lists the available request fields. diff --git a/_ml-commons-plugin/api/agent-apis/search-agent.md b/_ml-commons-plugin/api/agent-apis/search-agent.md index 3d950cde8f..63b1d07eed 100644 --- a/_ml-commons-plugin/api/agent-apis/search-agent.md +++ b/_ml-commons-plugin/api/agent-apis/search-agent.md @@ -134,6 +134,6 @@ Assistant:""" } ``` -## Response fields +## Response body fields -For response field descriptions, see [Register Agent API request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agent-apis/register-agent#request-fields). +For response field descriptions, see [Register Agent API request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agent-apis/register-agent#request-body-fields). diff --git a/_ml-commons-plugin/api/async-batch-ingest.md b/_ml-commons-plugin/api/async-batch-ingest.md index ace95ba4d4..493f192d0f 100644 --- a/_ml-commons-plugin/api/async-batch-ingest.md +++ b/_ml-commons-plugin/api/async-batch-ingest.md @@ -19,7 +19,7 @@ Use the Asynchronous Batch Ingestion API to ingest data into your OpenSearch clu POST /_plugins/_ml/_batch_ingestion ``` -#### Request fields +#### Request body fields The following table lists the available request fields. diff --git a/_ml-commons-plugin/api/connector-apis/create-connector.md b/_ml-commons-plugin/api/connector-apis/create-connector.md index 4225a24053..b99306bb8a 100644 --- a/_ml-commons-plugin/api/connector-apis/create-connector.md +++ b/_ml-commons-plugin/api/connector-apis/create-connector.md @@ -16,7 +16,7 @@ Creates a standalone connector. For more information, see [Connectors]({{site.ur POST /_plugins/_ml/connectors/_create ``` -## Request fields +## Request body fields For a list of request fields, see [Blueprint configuration parameters]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints#configuration-parameters). diff --git a/_ml-commons-plugin/api/connector-apis/update-connector.md b/_ml-commons-plugin/api/connector-apis/update-connector.md index 625d58bb62..4b62652da8 100644 --- a/_ml-commons-plugin/api/connector-apis/update-connector.md +++ b/_ml-commons-plugin/api/connector-apis/update-connector.md @@ -15,7 +15,7 @@ Use this API to update a standalone connector based on the `model_ID`. To update Before updating a standalone connector, you must undeploy all models that use the connector. For information about undeploying a model, see [Undeploy Model API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/undeploy-model/). {: .note} -Using this API, you can update the connector fields listed in the [Request fields](#request-fields) section and add optional fields to your connector. You cannot delete fields from a connector using this API. +Using this API, you can update the connector fields listed in the [Request fields](#request-body-fields) section and add optional fields to your connector. You cannot delete fields from a connector using this API. For information about user access for this API, see [Model access control considerations]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/index/#model-access-control-considerations). @@ -25,7 +25,7 @@ For information about user access for this API, see [Model access control consid PUT /_plugins/_ml/connectors/ ``` -## Request fields +## Request body fields The following table lists the updatable fields. For more information about all connector fields, see [Blueprint configuration parameters]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints#configuration-parameters). diff --git a/_ml-commons-plugin/api/controller-apis/create-controller.md b/_ml-commons-plugin/api/controller-apis/create-controller.md index 91a6be4387..9fe9306575 100644 --- a/_ml-commons-plugin/api/controller-apis/create-controller.md +++ b/_ml-commons-plugin/api/controller-apis/create-controller.md @@ -35,7 +35,7 @@ Parameter | Data type | Description :--- | :--- | :--- `model_id` | String | The model ID of the model for which you want to set rate limits. Required. -## Request fields +## Request body fields The following table lists the available request fields. diff --git a/_ml-commons-plugin/api/controller-apis/get-controller.md b/_ml-commons-plugin/api/controller-apis/get-controller.md index b30fe15679..48e6f16549 100644 --- a/_ml-commons-plugin/api/controller-apis/get-controller.md +++ b/_ml-commons-plugin/api/controller-apis/get-controller.md @@ -69,9 +69,9 @@ If there is no controller defined for the model, OpenSearch returns an error: } ``` -## Response fields +## Response body fields -For response field descriptions, see [Create Controller API request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/controller-apis/create-controller#request-fields). +For response field descriptions, see [Create Controller API request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/controller-apis/create-controller#request-body-fields). ## Required permissions diff --git a/_ml-commons-plugin/api/memory-apis/create-memory.md b/_ml-commons-plugin/api/memory-apis/create-memory.md index c7dac1783d..58ba34b2a4 100644 --- a/_ml-commons-plugin/api/memory-apis/create-memory.md +++ b/_ml-commons-plugin/api/memory-apis/create-memory.md @@ -34,7 +34,7 @@ Parameter | Data type | Description :--- | :--- | :--- `memory_id` | String | The ID of the memory to be updated. Required for the PUT method. -## Request fields +## Request body fields The following table lists the available request fields. diff --git a/_ml-commons-plugin/api/memory-apis/create-message.md b/_ml-commons-plugin/api/memory-apis/create-message.md index 345f411ccd..78ec0ade34 100644 --- a/_ml-commons-plugin/api/memory-apis/create-message.md +++ b/_ml-commons-plugin/api/memory-apis/create-message.md @@ -38,7 +38,7 @@ Parameter | Data type | Description `memory_id` | String | The ID of the memory to which to add the message. Required for the POST method. `message_id` | String | The ID of the message to be updated. Required for the PUT method. -## Request fields +## Request body fields The following table lists the available request fields. diff --git a/_ml-commons-plugin/api/memory-apis/get-memory.md b/_ml-commons-plugin/api/memory-apis/get-memory.md index 63ab548c00..7f62445072 100644 --- a/_ml-commons-plugin/api/memory-apis/get-memory.md +++ b/_ml-commons-plugin/api/memory-apis/get-memory.md @@ -120,7 +120,7 @@ GET /_plugins/_ml/memory?max_results=2&next_token=1 } ``` -## Response fields +## Response body fields The following table lists the available response fields. diff --git a/_ml-commons-plugin/api/memory-apis/get-message-traces.md b/_ml-commons-plugin/api/memory-apis/get-message-traces.md index 300adfc11d..1b0e9b1902 100644 --- a/_ml-commons-plugin/api/memory-apis/get-message-traces.md +++ b/_ml-commons-plugin/api/memory-apis/get-message-traces.md @@ -137,6 +137,6 @@ green open .opendistro-job-scheduler-lock XjgmXAVKQ4e8Y-ac54VBzg 1 } ``` -## Response fields +## Response body fields -For information about response fields, see [Create Message request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/create-message#request-fields). \ No newline at end of file +For information about response fields, see [Create Message request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/create-message#request-body-fields). \ No newline at end of file diff --git a/_ml-commons-plugin/api/memory-apis/get-message.md b/_ml-commons-plugin/api/memory-apis/get-message.md index 2f4cfc949f..36baa84bf4 100644 --- a/_ml-commons-plugin/api/memory-apis/get-message.md +++ b/_ml-commons-plugin/api/memory-apis/get-message.md @@ -62,7 +62,7 @@ GET /_plugins/_ml/memory/message/0m8ya40BfUsSoeNTj-pU } ``` -For information about response fields, see [Create Message request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/create-message#request-fields). +For information about response fields, see [Create Message request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/create-message#request-body-fields). ## Get all messages within a memory @@ -133,7 +133,7 @@ POST /_plugins/_ml/message/_search } ``` -## Response fields +## Response body fields -For information about response fields, see [Create Message request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/create-message#request-fields). +For information about response fields, see [Create Message request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/create-message#request-body-fields). diff --git a/_ml-commons-plugin/api/memory-apis/search-memory.md b/_ml-commons-plugin/api/memory-apis/search-memory.md index fc8dd3e1d9..4fa022bfaf 100644 --- a/_ml-commons-plugin/api/memory-apis/search-memory.md +++ b/_ml-commons-plugin/api/memory-apis/search-memory.md @@ -120,7 +120,7 @@ POST /_plugins/_ml/memory/_search } ``` -## Response fields +## Response body fields The following table lists all response fields. diff --git a/_ml-commons-plugin/api/memory-apis/search-message.md b/_ml-commons-plugin/api/memory-apis/search-message.md index a88ccfbb41..22602c21f2 100644 --- a/_ml-commons-plugin/api/memory-apis/search-message.md +++ b/_ml-commons-plugin/api/memory-apis/search-message.md @@ -89,6 +89,6 @@ GET /_plugins/_ml/memory/gW8Aa40BfUsSoeNTvOKI/_search } ``` -## Response fields +## Response body fields -For information about response fields, see [Create Message request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/create-message#request-fields). \ No newline at end of file +For information about response fields, see [Create Message request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/memory-apis/create-message#request-body-fields). \ No newline at end of file diff --git a/_ml-commons-plugin/api/model-apis/register-model.md b/_ml-commons-plugin/api/model-apis/register-model.md index 7d8f6d8cc6..63537d0443 100644 --- a/_ml-commons-plugin/api/model-apis/register-model.md +++ b/_ml-commons-plugin/api/model-apis/register-model.md @@ -46,7 +46,7 @@ OpenSearch provides several pretrained models. For more information, see [OpenSe To register a pretrained text embedding model, the only required parameters are `name`, `version`, and `model_format`. -#### Request fields +#### Request body fields The following table lists the available request fields. @@ -75,7 +75,7 @@ POST /_plugins/_ml/models/_register To register a pretrained sparse encoding model, you must set the function name to `SPARSE_ENCODING` or `SPARSE_TOKENIZE`. -#### Request fields +#### Request body fields The following table lists the available request fields. @@ -107,7 +107,7 @@ POST /_plugins/_ml/models/_register To use a custom model locally within the OpenSearch cluster, you need to provide a URL and a config object for that model. For more information, see [Custom local models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/custom-local-models/). -### Request fields +### Request body fields The following table lists the available request fields. @@ -170,7 +170,7 @@ POST /_plugins/_ml/models/_register To register a model hosted on a third-party platform, you can either first create a standalone connector and provide the ID of that connector or specify an internal connector for the model. For more information, see [Creating connectors for third-party ML platforms]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/connectors/). -### Request fields +### Request body fields The following table lists the available request fields. diff --git a/_ml-commons-plugin/api/model-apis/update-model.md b/_ml-commons-plugin/api/model-apis/update-model.md index 048b5b76e5..083f2cb448 100644 --- a/_ml-commons-plugin/api/model-apis/update-model.md +++ b/_ml-commons-plugin/api/model-apis/update-model.md @@ -20,13 +20,13 @@ For information about user access for this API, see [Model access control consid PUT /_plugins/_ml/models/ ``` -## Request fields +## Request body fields The following table lists the updatable fields. Not all request fields are applicable to all models. To determine whether the field is applicable to your model type, see [Register Model API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/register-model/). Field | Data type | Description :--- | :--- | :--- -`connector` | Object | Contains specifications for a connector for a model hosted on a third-party platform. For more information, see [Creating a connector for a specific model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/connectors/#creating-a-connector-for-a-specific-model). For information about the updatable fields within a connector, see [Update Connector API request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/connector-apis/update-connector/#request-fields). +`connector` | Object | Contains specifications for a connector for a model hosted on a third-party platform. For more information, see [Creating a connector for a specific model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/connectors/#creating-a-connector-for-a-specific-model). For information about the updatable fields within a connector, see [Update Connector API request fields]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/connector-apis/update-connector/#request-body-fields). `connector_id` | Optional | The connector ID of a standalone connector for a model hosted on a third-party platform. For more information, see [Standalone connector]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/connectors/#creating-a-standalone-connector). To update a standalone connector, you must undeploy the model, update the connector, and then redeploy the model. `description` | String | The model description. `is_enabled`| Boolean | Specifies whether the model is enabled. Disabling the model makes it unavailable for Predict API requests, regardless of the model's deployment status. Default is `true`. diff --git a/_ml-commons-plugin/api/model-group-apis/register-model-group.md b/_ml-commons-plugin/api/model-group-apis/register-model-group.md index 312513ff3f..d224a3356b 100644 --- a/_ml-commons-plugin/api/model-group-apis/register-model-group.md +++ b/_ml-commons-plugin/api/model-group-apis/register-model-group.md @@ -21,7 +21,7 @@ For more information, see [Model access control]({{site.url}}{{site.baseurl}}/ml POST /_plugins/_ml/model_groups/_register ``` -## Request fields +## Request body fields The following table lists the available request fields. @@ -54,7 +54,7 @@ POST /_plugins/_ml/model_groups/_register } ``` -## Response fields +## Response body fields The following table lists the available response fields. diff --git a/_ml-commons-plugin/api/model-group-apis/update-model-group.md b/_ml-commons-plugin/api/model-group-apis/update-model-group.md index 5aa5239794..d299094771 100644 --- a/_ml-commons-plugin/api/model-group-apis/update-model-group.md +++ b/_ml-commons-plugin/api/model-group-apis/update-model-group.md @@ -24,9 +24,9 @@ For more information, see [Model access control]({{site.url}}{{site.baseurl}}/ml PUT /_plugins/_ml/model_groups/ ``` -## Request fields +## Request body fields -Refer to [Request fields](#request-fields) for request field descriptions. +Refer to [Request fields](#request-body-fields) for request field descriptions. #### Example request diff --git a/_ml-commons-plugin/api/profile.md b/_ml-commons-plugin/api/profile.md index e8f65bb16c..8337f23e6e 100644 --- a/_ml-commons-plugin/api/profile.md +++ b/_ml-commons-plugin/api/profile.md @@ -41,7 +41,7 @@ Parameter | Data type | Description `model_id` | String | Returns runtime data for a specific model. You can provide multiple model IDs as comma-separated values to retrieve multiple model profiles. `task_id`| String | Returns runtime data for a specific task. You can provide multiple task IDs as comma-separated values to retrieve multiple task profiles. -### Request fields +### Request body fields All profile body request fields are optional. diff --git a/_monitoring-your-cluster/pa/rca/shard-hotspot.md b/_monitoring-your-cluster/pa/rca/shard-hotspot.md index 18a6804410..889658716a 100644 --- a/_monitoring-your-cluster/pa/rca/shard-hotspot.md +++ b/_monitoring-your-cluster/pa/rca/shard-hotspot.md @@ -78,7 +78,7 @@ The response contains a list of unhealthy shards: }] ``` -## Response fields +## Response body fields The following table lists the response fields. diff --git a/_observing-your-data/alerting/composite-monitors.md b/_observing-your-data/alerting/composite-monitors.md index eb26dcc15e..7ba182a865 100644 --- a/_observing-your-data/alerting/composite-monitors.md +++ b/_observing-your-data/alerting/composite-monitors.md @@ -74,7 +74,7 @@ POST _plugins/_alerting/workflows ``` {% include copy-curl.html %} -#### Request fields +#### Request body fields | Field | Type | Description | | :--- | :--- | :--- | @@ -526,7 +526,7 @@ GET /_plugins/_alerting/workflows/alerts?workflowIds=&getAssociate } ``` -#### Request fields +#### Request body fields | Field | Type | Description | | :--- | :--- | :--- | @@ -546,7 +546,7 @@ POST _plugins/_alerting/workflows//_acknowledge/alerts ``` {% include copy-curl.html %} -#### Request fields +#### Request body fields | Field | Type | Description | | :--- | :--- | :--- | diff --git a/_observing-your-data/query-insights/grouping-top-n-queries.md b/_observing-your-data/query-insights/grouping-top-n-queries.md index 28cbcbb8e5..495766c0f3 100644 --- a/_observing-your-data/query-insights/grouping-top-n-queries.md +++ b/_observing-your-data/query-insights/grouping-top-n-queries.md @@ -307,7 +307,7 @@ The response contains the top N query groups: -## Response fields +## Response body fields The response includes the following fields. @@ -323,7 +323,7 @@ Field | Data type | Description `top_queries.task_resource_usages` | Array of objects | The resource usage breakdown for the various tasks belonging to the first query in the query group. `top_queries.indices` | Array | The indexes searched by the first query in the query group. `top_queries.labels` | Object | Used to label the top query. -`top_queries.search_type` | String | The search request execution type (`query_then_fetch` or `dfs_query_then_fetch`). For more information, see the `search_type` parameter in the [Search API documentation]({{site.url}}{{site.baseurl}}/api-reference/search/#url-parameters). +`top_queries.search_type` | String | The search request execution type (`query_then_fetch` or `dfs_query_then_fetch`). For more information, see the `search_type` parameter in the [Search API documentation]({{site.url}}{{site.baseurl}}/api-reference/search/#query-parameters). `top_queries.measurements` | Object | The aggregate measurements for the query group. `top_queries.measurements.latency` | Object | The aggregate latency measurements for the query group. `top_queries.measurements.latency.number` | Integer | The total latency for the query group. diff --git a/_query-dsl/specialized/neural-sparse.md b/_query-dsl/specialized/neural-sparse.md index 8de3eaf693..904d340b13 100644 --- a/_query-dsl/specialized/neural-sparse.md +++ b/_query-dsl/specialized/neural-sparse.md @@ -11,7 +11,7 @@ Introduced 2.11 Use the `neural_sparse` query for vector field search in [neural sparse search]({{site.url}}{{site.baseurl}}/search-plugins/neural-sparse-search/). The query can use either raw text or sparse vector tokens. -## Request fields +## Request body fields Include the following request fields in the `neural_sparse` query: ### Example: Query by raw text diff --git a/_query-dsl/specialized/neural.md b/_query-dsl/specialized/neural.md index 6cd534b87f..ae9e1f2ea4 100644 --- a/_query-dsl/specialized/neural.md +++ b/_query-dsl/specialized/neural.md @@ -9,7 +9,7 @@ nav_order: 50 Use the `neural` query for vector field search in [neural search]({{site.url}}{{site.baseurl}}/search-plugins/neural-search/). -## Request fields +## Request body fields Include the following request fields in the `neural` query: diff --git a/_search-plugins/concurrent-segment-search.md b/_search-plugins/concurrent-segment-search.md index 80614e2fff..6675faf1f9 100644 --- a/_search-plugins/concurrent-segment-search.md +++ b/_search-plugins/concurrent-segment-search.md @@ -175,7 +175,7 @@ The following sections provide additional considerations for concurrent segment ### The `terminate_after` search parameter -The [`terminate_after` search parameter]({{site.url}}{{site.baseurl}}/api-reference/search/#url-parameters) is used to terminate a search request once a specified number of documents has been collected. If you include the `terminate_after` parameter in a request, concurrent segment search is disabled and the request is run in a non-concurrent manner. +The [`terminate_after` search parameter]({{site.url}}{{site.baseurl}}/api-reference/search/#query-parameters) is used to terminate a search request once a specified number of documents has been collected. If you include the `terminate_after` parameter in a request, concurrent segment search is disabled and the request is run in a non-concurrent manner. Typically, queries are used with smaller `terminate_after` values and thus complete quickly because the search is performed on a reduced dataset. Therefore, concurrent search may not further improve performance in this case. Moreover, when `terminate_after` is used with other search request parameters, such as `track_total_hits` or `size`, it adds complexity and changes the expected query behavior. Falling back to a non-concurrent path for search requests that include `terminate_after` ensures consistent results between concurrent and non-concurrent requests. diff --git a/_search-plugins/cross-cluster-search.md b/_search-plugins/cross-cluster-search.md index 7d3ff72efb..6a22c4c430 100644 --- a/_search-plugins/cross-cluster-search.md +++ b/_search-plugins/cross-cluster-search.md @@ -38,7 +38,7 @@ To query indexes on remote clusters, users must have `READ` or `SEARCH` permissi indices:admin/shards/search_shards ``` -For more information about the `ccs_minimize_roundtrips` parameter, see the list of [URL Parameters]({{site.url}}{{site.baseurl}}/api-reference/search/#url-parameters) for the Search API. +For more information about the `ccs_minimize_roundtrips` parameter, see the list of [URL Parameters]({{site.url}}{{site.baseurl}}/api-reference/search/#query-parameters) for the Search API. #### Example roles.yml configuration diff --git a/_search-plugins/search-pipelines/collapse-processor.md b/_search-plugins/search-pipelines/collapse-processor.md index 8a2723efa7..a802b48aca 100644 --- a/_search-plugins/search-pipelines/collapse-processor.md +++ b/_search-plugins/search-pipelines/collapse-processor.md @@ -20,7 +20,7 @@ Using the `collapse` response processor will likely result in fewer than `size` from a set whose size is already less than or equal to `size`. To increase the likelihood of returning `size` hits, use the `oversample` request processor and `truncate_hits` response processor, as shown in [this example]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/truncate-hits-processor/#oversample-collapse-and-truncate-hits). -## Request fields +## Request body fields The following table lists all request fields. diff --git a/_search-plugins/search-pipelines/filter-query-processor.md b/_search-plugins/search-pipelines/filter-query-processor.md index 799d393e42..a55180f53c 100644 --- a/_search-plugins/search-pipelines/filter-query-processor.md +++ b/_search-plugins/search-pipelines/filter-query-processor.md @@ -13,7 +13,7 @@ Introduced 2.8 The `filter_query` search request processor intercepts a search request and applies an additional query to the request, filtering the results. This is useful when you don't want to rewrite existing queries in your application but need additional filtering of the results. -## Request fields +## Request body fields The following table lists all available request fields. diff --git a/_search-plugins/search-pipelines/ml-inference-search-response.md b/_search-plugins/search-pipelines/ml-inference-search-response.md index e2ed7889c7..efd24e13c8 100644 --- a/_search-plugins/search-pipelines/ml-inference-search-response.md +++ b/_search-plugins/search-pipelines/ml-inference-search-response.md @@ -48,7 +48,7 @@ The following is the syntax for the `ml-inference` search response processor: ``` {% include copy-curl.html %} -## Request fields +## Request body fields The following table lists the required and optional parameters for the `ml-inference` search response processor. @@ -294,7 +294,7 @@ The model generates embeddings in the `$.inference_results.*.output.*.data` fiel ] ``` -To configure an `ml_inference` search response processor with a local model, specify the `function_name` explicitly. In this example, the `function_name` is `text_embedding`. For information about valid `function_name` values, see [Request fields](#request-fields). +To configure an `ml_inference` search response processor with a local model, specify the `function_name` explicitly. In this example, the `function_name` is `text_embedding`. For information about valid `function_name` values, see [Request fields](#request-body-fields). The following is the final configuration of the `ml_inference` search response processor with the local model: diff --git a/_search-plugins/search-pipelines/neural-query-enricher.md b/_search-plugins/search-pipelines/neural-query-enricher.md index 683eaa7b85..a237f8841d 100644 --- a/_search-plugins/search-pipelines/neural-query-enricher.md +++ b/_search-plugins/search-pipelines/neural-query-enricher.md @@ -13,7 +13,7 @@ Introduced 2.11 The `neural_query_enricher` search request processor is designed to set a default machine learning (ML) model ID at the index or field level for [neural search]({{site.url}}{{site.baseurl}}/search-plugins/neural-search/) queries. To learn more about ML models, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/using-ml-models/) and [Connecting to remote models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/index/). -## Request fields +## Request body fields The following table lists all available request fields. diff --git a/_search-plugins/search-pipelines/neural-sparse-query-two-phase-processor.md b/_search-plugins/search-pipelines/neural-sparse-query-two-phase-processor.md index 3ba1e21405..41119e643a 100644 --- a/_search-plugins/search-pipelines/neural-sparse-query-two-phase-processor.md +++ b/_search-plugins/search-pipelines/neural-sparse-query-two-phase-processor.md @@ -15,7 +15,7 @@ The `neural_sparse_two_phase_processor` search processor is designed to provide 1. High-weight tokens score the documents and filter out the top documents. 2. Low-weight tokens rescore the top documents. -## Request fields +## Request body fields The following table lists all available request fields. diff --git a/_search-plugins/search-pipelines/normalization-processor.md b/_search-plugins/search-pipelines/normalization-processor.md index ac29b079f1..e70f815bdd 100644 --- a/_search-plugins/search-pipelines/normalization-processor.md +++ b/_search-plugins/search-pipelines/normalization-processor.md @@ -25,7 +25,7 @@ OpenSearch supports two search types: `query_then_fetch` and `dfs_query_then_fet When you send a search request to a node, the node becomes a _coordinating node_. During the first phase of search, the _query phase_, the coordinating node routes the search request to all shards in the index, including primary and replica shards. Each shard then runs the search query locally and returns metadata about the matching documents, which includes their document IDs and relevance scores. The `normalization-processor` then normalizes and combines scores from different query clauses. The coordinating node merges and sorts the local lists of results, compiling a global list of top documents that match the query. After that, search execution enters a _fetch phase_, in which the coordinating node requests the documents in the global list from the shards where they reside. Each shard returns the documents' `_source` to the coordinating node. Finally, the coordinating node sends a search response containing the results back to you. -## Request fields +## Request body fields The following table lists all available request fields. diff --git a/_search-plugins/search-pipelines/oversample-processor.md b/_search-plugins/search-pipelines/oversample-processor.md index 81f4252f3d..e881d5f32c 100644 --- a/_search-plugins/search-pipelines/oversample-processor.md +++ b/_search-plugins/search-pipelines/oversample-processor.md @@ -13,7 +13,7 @@ Introduced 2.12 The `oversample` request processor multiplies the `size` parameter of the search request by a specified `sample_factor` (>= 1.0), saving the original value in the `original_size` pipeline variable. The `oversample` processor is designed to work with the [`truncate_hits` response processor]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/truncate-hits-processor/) but may be used on its own. -## Request fields +## Request body fields The following table lists all request fields. diff --git a/_search-plugins/search-pipelines/personalize-search-ranking.md b/_search-plugins/search-pipelines/personalize-search-ranking.md index b63ba4b966..32ff251cae 100644 --- a/_search-plugins/search-pipelines/personalize-search-ranking.md +++ b/_search-plugins/search-pipelines/personalize-search-ranking.md @@ -16,7 +16,7 @@ The `personalize_search_ranking` search response processor intercepts a search r To use the `personalize_search_ranking` processor, you must first install the Amazon Personalize Search Ranking (`opensearch-search-processor`) plugin. For detailed instructions, see [Installing and configuring the Amazon Personalize Search Ranking plugin](https://docs.aws.amazon.com/personalize/latest/dg/opensearch-install.html). {: .important} -## Request fields +## Request body fields The following table lists all available request fields. diff --git a/_search-plugins/search-pipelines/rag-processor.md b/_search-plugins/search-pipelines/rag-processor.md index 60257ebd05..e9fca2e2c5 100644 --- a/_search-plugins/search-pipelines/rag-processor.md +++ b/_search-plugins/search-pipelines/rag-processor.md @@ -16,7 +16,7 @@ The `retrieval_augmented_generation` processor is a search results processor tha As of OpenSearch 2.12, the `retrieval_augmented_generation` processor supports only OpenAI and Amazon Bedrock models. {: .note} -## Request fields +## Request body fields The following table lists all available request fields. diff --git a/_search-plugins/search-pipelines/rename-field-processor.md b/_search-plugins/search-pipelines/rename-field-processor.md index 9c734af656..4715a6308a 100644 --- a/_search-plugins/search-pipelines/rename-field-processor.md +++ b/_search-plugins/search-pipelines/rename-field-processor.md @@ -13,7 +13,7 @@ Introduced 2.8 The `rename_field` search response processor intercepts a search response and renames the specified field. This is useful when your index and your application use different names for the same field. For example, if you rename a field in your index, the `rename_field` processor can change the new name to the old one before sending the response to your application. -## Request fields +## Request body fields The following table lists all available request fields. diff --git a/_search-plugins/search-pipelines/rerank-processor.md b/_search-plugins/search-pipelines/rerank-processor.md index 313ae5f74d..e543c8a28a 100644 --- a/_search-plugins/search-pipelines/rerank-processor.md +++ b/_search-plugins/search-pipelines/rerank-processor.md @@ -13,7 +13,7 @@ Introduced 2.12 The `rerank` search request processor intercepts search results and passes them to a cross-encoder model to be reranked. The model reranks the results, taking into account the scoring context. Then the processor orders documents in the search results based on their new scores. -## Request fields +## Request body fields The following table lists all available request fields. diff --git a/_search-plugins/search-pipelines/script-processor.md b/_search-plugins/search-pipelines/script-processor.md index 1fd1d08e57..d927348d33 100644 --- a/_search-plugins/search-pipelines/script-processor.md +++ b/_search-plugins/search-pipelines/script-processor.md @@ -26,7 +26,7 @@ The `script` search request processor intercepts a search request and adds an in For request field definitions, see [search request fields]({{site.url}}{{site.baseurl}}/api-reference/search#request-body). -## Request fields +## Request body fields The following table lists all available request fields. diff --git a/_search-plugins/search-pipelines/sort-processor.md b/_search-plugins/search-pipelines/sort-processor.md index 6df2352c1e..1b4a28d2a9 100644 --- a/_search-plugins/search-pipelines/sort-processor.md +++ b/_search-plugins/search-pipelines/sort-processor.md @@ -13,7 +13,7 @@ Introduced 2.16 The `sort` processor sorts an array of items in either ascending or descending order. Numeric arrays are sorted numerically, while string or mixed arrays (strings and numbers) are sorted lexicographically. The processor throws an error if the input is not an array. -## Request fields +## Request body fields The following table lists all available request fields. diff --git a/_search-plugins/search-pipelines/split-processor.md b/_search-plugins/search-pipelines/split-processor.md index c524386262..0ffcc6fea9 100644 --- a/_search-plugins/search-pipelines/split-processor.md +++ b/_search-plugins/search-pipelines/split-processor.md @@ -13,7 +13,7 @@ Introduced 2.17 The `split` processor splits a string field into an array of substrings based on a specified delimiter. -## Request fields +## Request body fields The following table lists all available request fields. diff --git a/_search-plugins/search-pipelines/truncate-hits-processor.md b/_search-plugins/search-pipelines/truncate-hits-processor.md index 7bba627734..12426f3890 100644 --- a/_search-plugins/search-pipelines/truncate-hits-processor.md +++ b/_search-plugins/search-pipelines/truncate-hits-processor.md @@ -22,7 +22,7 @@ The following is a common usage pattern: 1. In the response pipeline, apply a reranking processor (which may promote results from beyond the originally requested top N) or the `collapse` processor (which may discard results after deduplication). 1. Apply the `truncate` processor to return (at most) the originally requested number of hits. -## Request fields +## Request body fields The following table lists all request fields. diff --git a/_search-plugins/search-relevance/reranking-search-results.md b/_search-plugins/search-relevance/reranking-search-results.md index 4b4deaeb92..b1e480a84a 100644 --- a/_search-plugins/search-relevance/reranking-search-results.md +++ b/_search-plugins/search-relevance/reranking-search-results.md @@ -53,7 +53,7 @@ PUT /_search/pipeline/my_pipeline ``` {% include copy-curl.html %} -For more information about the request fields, see [Request fields]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/rerank-processor/#request-fields). +For more information about the request fields, see [Request fields]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/rerank-processor/#request-body-fields). ## Step 2: Create an index for ingestion diff --git a/_search-plugins/search-relevance/stats-api.md b/_search-plugins/search-relevance/stats-api.md index 3be40c70f6..d5bd286187 100644 --- a/_search-plugins/search-relevance/stats-api.md +++ b/_search-plugins/search-relevance/stats-api.md @@ -83,7 +83,7 @@ The following is the response for the preceding request: } ``` -## Response fields +## Response body fields The following table lists all response fields. diff --git a/_search-plugins/searching-data/point-in-time-api.md b/_search-plugins/searching-data/point-in-time-api.md index d386d138cc..6a3d867052 100644 --- a/_search-plugins/searching-data/point-in-time-api.md +++ b/_search-plugins/searching-data/point-in-time-api.md @@ -71,7 +71,7 @@ POST /my-index-1/_search/point_in_time?keep_alive=100m } ``` -### Response fields +### Response body fields Field | Data type | Description :--- | :--- | :--- @@ -142,7 +142,7 @@ GET /_search/point_in_time/_all } ``` -### Response fields +### Response body fields Field | Data type | Description :--- | :--- | :--- @@ -176,7 +176,7 @@ DELETE /_search/point_in_time/_all If you want to delete one or several PITs, specify their PIT IDs in the request body. -### Request fields +### Request body fields Field | Data type | Description :--- | :--- | :--- @@ -214,7 +214,7 @@ For each PIT, the response contains a JSON object with a PIT ID and a `successfu } ``` -### Response fields +### Response body fields Field | Data type | Description :--- | :--- | :--- @@ -235,7 +235,7 @@ GET /_cat/pit_segments/_all If you want to list segments for one or several PITs, specify their PIT IDs in the request body. -### Request fields +### Request body fields Field | Data type | Description :--- | :--- | :--- diff --git a/_search-plugins/sql/sql-ppl-api.md b/_search-plugins/sql/sql-ppl-api.md index fefd612ceb..26f5f2cc81 100644 --- a/_search-plugins/sql/sql-ppl-api.md +++ b/_search-plugins/sql/sql-ppl-api.md @@ -20,7 +20,7 @@ Parameter | Data Type | Description [format]({{site.url}}{{site.baseurl}}/search-plugins/sql/response-formats/) | String | The format for the response. The `_sql` endpoint supports `jdbc`, `csv`, `raw`, and `json` formats. The `_ppl` endpoint supports `jdbc`, `csv`, and `raw` formats. Default is `jdbc`. sanitize | Boolean | Specifies whether to escape special characters in the results. See [Response formats]({{site.url}}{{site.baseurl}}/search-plugins/sql/response-formats/) for more information. Default is `true`. -### Request fields +### Request body fields Field | Data Type | Description :--- | :--- | :--- @@ -149,7 +149,7 @@ The response contains the schema and the results: } ``` -### Response fields +### Response body fields Field | Data Type | Description :--- | :--- | :--- diff --git a/_security-analytics/api-tools/alert-finding-api.md b/_security-analytics/api-tools/alert-finding-api.md index ed977361c5..582e892fc7 100644 --- a/_security-analytics/api-tools/alert-finding-api.md +++ b/_security-analytics/api-tools/alert-finding-api.md @@ -71,7 +71,7 @@ GET /_plugins/_security_analytics/alerts?detectorType=windows } ``` -#### Response fields +#### Response body fields Alerts persist until you resolve the root cause and have the following states: diff --git a/_security-analytics/api-tools/correlation-eng.md b/_security-analytics/api-tools/correlation-eng.md index c2a6ca56b1..449563d876 100644 --- a/_security-analytics/api-tools/correlation-eng.md +++ b/_security-analytics/api-tools/correlation-eng.md @@ -20,7 +20,7 @@ POST /_plugins/_security_analytics/correlation/rules ``` {% include copy-curl.html %} -### Request fields +### Request body fields | Field | Type | Description | | :--- | :--- |:--- | @@ -94,7 +94,7 @@ POST /_plugins/_security_analytics/correlation/rules ``` {% include copy-curl.html %} -### Response fields +### Response body fields | Field | Type | Description | | :--- | :--- |:--- | @@ -144,7 +144,7 @@ GET /_plugins/_security_analytics/correlations?start_timestamp=1689289210000&end ``` {% include copy-curl.html %} -### Response fields +### Response body fields | Field | Type | Description | | :--- | :--- |:--- | @@ -221,7 +221,7 @@ GET /_plugins/_security_analytics/findings/correlate?finding=425dce0b-f5ee-4889- ``` {% include copy-curl.html %} -### Response fields +### Response body fields | Field | Type | Description | | :--- | :--- |:--- | diff --git a/_security-analytics/api-tools/detector-api.md b/_security-analytics/api-tools/detector-api.md index e9de8698a4..5b0f9a9eb0 100644 --- a/_security-analytics/api-tools/detector-api.md +++ b/_security-analytics/api-tools/detector-api.md @@ -18,7 +18,7 @@ Creates a new detector. POST _plugins/_security_analytics/detectors ``` -### Request fields +### Request body fields You can specify the following fields when creating a detector. @@ -224,7 +224,7 @@ The Update Detector API can be used to update a detector definition. It requires PUT /_plugins/_security_analytics/detectors/ ``` -### Request fields +### Request body fields You can specify the following fields when updating a detector. @@ -332,7 +332,7 @@ PUT /_plugins/_security_analytics/detectors/J1RX1IMByX0LvTiGTddR } ``` -#### Response fields +#### Response body fields Field | Type | Description :--- | :--- |:--- | @@ -428,7 +428,7 @@ GET /_plugins/_security_analytics/detectors/ The Search Detector API searches for detector matches by detector ID, detector name, or detector type. -### Request fields +### Request body fields Field | Type | Description :--- | :--- |:--- | diff --git a/_security-analytics/api-tools/mappings-api.md b/_security-analytics/api-tools/mappings-api.md index b1e8ab2c51..64e83c7a0a 100644 --- a/_security-analytics/api-tools/mappings-api.md +++ b/_security-analytics/api-tools/mappings-api.md @@ -14,7 +14,7 @@ The following APIs can be used for a number of tasks related to mappings, from c This API returns a view of the fields contained in an index used as a log source. -### Request fields +### Request body fields The following fields are used to get field mappings. diff --git a/_security-analytics/threat-intelligence/api/findings.md b/_security-analytics/threat-intelligence/api/findings.md index 3d1b3e8951..5c648ab2ae 100644 --- a/_security-analytics/threat-intelligence/api/findings.md +++ b/_security-analytics/threat-intelligence/api/findings.md @@ -77,7 +77,7 @@ GET /_plugins/_security_analytics/threat_intel/alerts } ``` -### Response fields +### Response body fields A threat intelligence alert can have one of the following states. diff --git a/_security-analytics/threat-intelligence/api/monitor.md b/_security-analytics/threat-intelligence/api/monitor.md index 965fd79af3..e22b31f156 100644 --- a/_security-analytics/threat-intelligence/api/monitor.md +++ b/_security-analytics/threat-intelligence/api/monitor.md @@ -25,7 +25,7 @@ POST _plugins/_security_analytics/threat_intel/monitors PUT _plugins/_security_analytics/threat_intel/monitors/ ``` -### Request fields +### Request body fields You can specify the following fields in the request body. diff --git a/_security-analytics/threat-intelligence/api/source.md b/_security-analytics/threat-intelligence/api/source.md index 7cfadfd813..e9bd540477 100644 --- a/_security-analytics/threat-intelligence/api/source.md +++ b/_security-analytics/threat-intelligence/api/source.md @@ -21,7 +21,7 @@ POST _plugins/_security_analytics/threat_intel/sources PUT _plugins/_security_analytics/threat_intel/sources/ ``` -### Request fields +### Request body fields | Field | Type | Description | | :--- | :--- | :---- | @@ -60,7 +60,7 @@ The following fields modify the `ioc_types` option. | `spec_version` | String | The specification version used for the IOC. | | `version` | Integer | A version number for the IOC. | -### Response fields +### Response body fields | Field | Data type | Description | | :---- | :--- |:----- | diff --git a/_security/access-control/api.md b/_security/access-control/api.md index 63717d621a..0a6aedbb95 100644 --- a/_security/access-control/api.md +++ b/_security/access-control/api.md @@ -178,7 +178,7 @@ PUT _plugins/_security/api/account ``` {% include copy-curl.html %} -#### Request fields +#### Request body fields | Field | Data type | Description | Required | |:-------------------|:-----------|:-------------------------------|:----------| @@ -206,7 +206,7 @@ PUT _plugins/_security/api/account } ``` -#### Response fields +#### Response body fields | Field | Data type | Description | |:---------|:-----------|:------------------------------| @@ -1426,7 +1426,7 @@ GET _plugins/_security/api/_upgrade_check } ``` -#### Response fields +#### Response body fields | Field | Data type | Description | |:---------|:-----------|:------------------------------| @@ -1453,7 +1453,7 @@ POST _plugins/_security/api/_upgrade_perform ``` {% include copy-curl.html %} -#### Request fields +#### Request body fields | Field | Data type | Description | Required | |:----------------|:-----------|:------------------------------------------------------------------------------------------------------------------|:---------| @@ -1473,7 +1473,7 @@ POST _plugins/_security/api/_upgrade_perform } ``` -#### Response fields +#### Response body fields | Field | Data type | Description | |:---------|:-----------|:------------------------------| @@ -1575,7 +1575,7 @@ PATCH _plugins/_security/api/nodesdn ``` {% include copy-curl.html %} -#### Request fields +#### Request body fields | Field | Data type | Description | Required | |:----------------|:-----------|:------------------------------------------------------------------------------------------------------------------|:---------| @@ -1607,7 +1607,7 @@ PATCH _plugins/_security/api/nodesdn } ``` -#### Response fields +#### Response body fields | Field | Data type | Description | |:--------|:----------|:---------------------| @@ -1705,7 +1705,7 @@ curl -X PUT "https://your-opensearch-cluster/_plugins/_security/api/ssl/transpor } ``` -#### Response fields +#### Response body fields | Field | Data type | Description | |:--------|:----------|:----------------------------------------------------------------------------------| @@ -1741,7 +1741,7 @@ curl -X PUT "https://your-opensearch-cluster/_plugins/_security/api/ssl/http/rel } ``` -#### Response fields +#### Response body fields | Field | Data type | Description | |:--------|:----------|:--------------------------------------------------------------------| @@ -1822,7 +1822,7 @@ For details on using audit logging to track access to OpenSearch clusters, as we You can do an initial configuration of audit logging in the `audit.yml` file, found in the `opensearch-project/security/config` directory. Thereafter, you can use the REST API or Dashboards for further changes to the configuration. {: note.} -#### Request fields +#### Request body fields Field | Data type | Description :--- | :--- | :--- diff --git a/_security/authentication-backends/jwt.md b/_security/authentication-backends/jwt.md index 6c7311e7dc..ef32b9f71a 100644 --- a/_security/authentication-backends/jwt.md +++ b/_security/authentication-backends/jwt.md @@ -177,7 +177,7 @@ The default name of the header is `Authorization`. If required by your authentic As with HTTP basic authentication, you should use HTTPS instead of HTTP when transmitting JWTs in HTTP requests. -### URL parameters for HTTP requests +### Query parameters for HTTP requests Although the most common way to transmit JWTs in HTTP requests is to use a header field, the Security plugin also supports parameters. Configure the name of the `GET` parameter using the following key: diff --git a/_tuning-your-cluster/availability-and-recovery/remote-store/remote-store-stats-api.md b/_tuning-your-cluster/availability-and-recovery/remote-store/remote-store-stats-api.md index b0739c263a..b184930e1d 100644 --- a/_tuning-your-cluster/availability-and-recovery/remote-store/remote-store-stats-api.md +++ b/_tuning-your-cluster/availability-and-recovery/remote-store/remote-store-stats-api.md @@ -257,7 +257,7 @@ GET _remotestore/stats/ ``` -### Response fields +### Response body fields The response body of the Remote Store Stats API is split into three categories: diff --git a/_tuning-your-cluster/availability-and-recovery/search-backpressure.md b/_tuning-your-cluster/availability-and-recovery/search-backpressure.md index 58c0d29883..42cef0a530 100644 --- a/_tuning-your-cluster/availability-and-recovery/search-backpressure.md +++ b/_tuning-your-cluster/availability-and-recovery/search-backpressure.md @@ -216,7 +216,7 @@ The response contains server-side request cancellation statistics: } ``` -### Response fields +### Response body fields The response contains the following fields. diff --git a/_tuning-your-cluster/availability-and-recovery/segment-replication/backpressure.md b/_tuning-your-cluster/availability-and-recovery/segment-replication/backpressure.md index 16b97a380a..498aae55fc 100644 --- a/_tuning-your-cluster/availability-and-recovery/segment-replication/backpressure.md +++ b/_tuning-your-cluster/availability-and-recovery/segment-replication/backpressure.md @@ -13,7 +13,7 @@ Segment replication backpressure is a shard-level rejection mechanism that dynam Replica shards are also monitored to determine whether the shards are stuck or lagging for an extended period of time. When replica shards are stuck or lagging for more than double the amount of time defined by the `segrep.pressure.time.limit` field, the shards are removed and replaced with new replica shards. -## Request fields +## Request body fields Segment replication backpressure is disabled by default. To enable it, set `segrep.pressure.enabled` to `true`. You can update the following dynamic cluster settings using the [cluster settings]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/) API endpoint.