Merge branch 'main' into reindex-template

opensearch-project · Jun 13, 2024 · b016429 · b016429
2 parents e8ccaca + eb9bfca
commit b016429
Show file tree

Hide file tree

Showing 76 changed files with 1,400 additions and 174 deletions.
diff --git a/_aggregations/bucket/geohex-grid.md b/_aggregations/bucket/geohex-grid.md
@@ -5,6 +5,8 @@ parent: Bucket aggregations
 grand_parent: Aggregations
 nav_order: 85
 redirect_from:
+  - /opensearch/geohexgrid-agg/
+  - /query-dsl/aggregations/geohexgrid-agg/
   - /aggregations/geohexgrid/
   - /query-dsl/aggregations/geohexgrid/
   - /query-dsl/aggregations/bucket/geohex-grid/

diff --git a/_aggregations/bucket/multi-terms.md b/_aggregations/bucket/multi-terms.md
@@ -5,6 +5,7 @@ parent: Bucket aggregations
 grand_parent: Aggregations
 nav_order: 130
 redirect_from:
+  - /query-dsl/aggregations/bucket/multi-terms/
   - /query-dsl/aggregations/multi-terms/
 ---
 

diff --git a/_aggregations/bucket/range.md b/_aggregations/bucket/range.md
@@ -5,6 +5,7 @@ parent: Bucket aggregations
 grand_parent: Aggregations
 nav_order: 150
 redirect_from:
+  - /query-dsl/aggregations/bucket/date-range/
   - /query-dsl/aggregations/bucket/range/
 ---
 

diff --git a/_aggregations/bucket/sampler.md b/_aggregations/bucket/sampler.md
@@ -4,6 +4,8 @@ title: Sampler
 parent: Bucket aggregations
 grand_parent: Aggregations
 nav_order: 170
+redirect_from:
+  - /query-dsl/aggregations/bucket/diversified-sampler/
 ---
 
 # Sampler aggregations

diff --git a/_aggregations/bucket/significant-terms.md b/_aggregations/bucket/significant-terms.md
@@ -4,6 +4,8 @@ title: Significant terms
 parent: Bucket aggregations
 grand_parent: Aggregations
 nav_order: 180
+redirect_from:
+  - /query-dsl/aggregations/bucket/significant-terms/
 ---
 
 # Significant terms aggregations

diff --git a/_aggregations/bucket/significant-text.md b/_aggregations/bucket/significant-text.md
@@ -4,6 +4,8 @@ title: Significant text
 parent: Bucket aggregations
 grand_parent: Aggregations
 nav_order: 190
+redirect_from:
+  - /query-dsl/aggregations/bucket/significant-text/
 ---
 
 # Significant text aggregations

diff --git a/_aggregations/bucket/terms.md b/_aggregations/bucket/terms.md
@@ -4,6 +4,8 @@ title: Terms
 parent: Bucket aggregations
 grand_parent: Aggregations
 nav_order: 200
+redirect_from:
+  - /query-dsl/aggregations/bucket/terms/
 ---
 
 # Terms aggregations

diff --git a/_aggregations/index.md b/_aggregations/index.md
@@ -6,6 +6,7 @@ nav_order: 5
 nav_exclude: true
 permalink: /aggregations/
 redirect_from:
+  - /query-dsl/aggregations/aggregations/
   - /opensearch/aggregations/
   - /query-dsl/aggregations/
   - /aggregations/index/

diff --git a/_api-reference/analyze-apis.md b/_api-reference/analyze-apis.md
@@ -4,6 +4,7 @@ title: Analyze API
 has_children: true
 nav_order: 7
 redirect_from:
+  - /api-reference/analyze-apis/perform-text-analysis/
   - /opensearch/rest-api/analyze-apis/
   - /api-reference/analyze-apis/
 ---

diff --git a/_api-reference/document-apis/reindex.md b/_api-reference/document-apis/reindex.md
@@ -57,7 +57,7 @@ Your request body must contain the names of the source index and destination ind
 
 Field | Description
 :--- | :---
-conflicts | Indicates to OpenSearch what should happen if the delete by query operation runs into a version conflict. Valid options are `abort` and `proceed`. Default is abort.
+conflicts | Indicates to OpenSearch what should happen if the Reindex operation runs into a version conflict. Valid options are `abort` and `proceed`. Default is `abort`.
 source | Information about the source index to include. Valid fields are `index`, `max_docs`, `query`, `remote`, `size`, `slice`, and `_source`.
 index | The name of the source index to copy data from.
 max_docs | The maximum number of documents to reindex.

diff --git a/_api-reference/index-apis/get-settings.md b/_api-reference/index-apis/get-settings.md
@@ -4,6 +4,7 @@ title: Get settings
 parent: Index APIs
 nav_order: 45
 redirect_from:
+  - /opensearch/rest-api/index-apis/get-settings/
   - /opensearch/rest-api/index-apis/get-index/
 ---
 

diff --git a/_api-reference/index-apis/index.md b/_api-reference/index-apis/index.md
@@ -4,6 +4,7 @@ title: Index APIs
 has_children: true
 nav_order: 35
 redirect_from:
+  - /opensearch/rest-api/index-apis/index/
   - /opensearch/rest-api/index-apis/
 ---
 

diff --git a/_api-reference/index-apis/put-mapping.md b/_api-reference/index-apis/put-mapping.md
@@ -4,6 +4,7 @@ title: Create or update mappings
 parent: Index APIs
 nav_order: 27
 redirect_from:
+  - /opensearch/rest-api/index-apis/put-mapping/
   - /opensearch/rest-api/index-apis/update-mapping/
   - /opensearch/rest-api/update-mapping/
 ---

diff --git a/_api-reference/msearch-template.md b/_api-reference/msearch-template.md
@@ -0,0 +1,132 @@
+---
+layout: default
+title: Multi-search Template 
+nav_order: 47
+---
+
+# Multi-search Template 
+
+**Introduced 1.0**
+{: .label .label-purple }
+
+The Multi-search Template API runs multiple search template requests in a single API request.
+
+## Path and HTTP methods
+
+The Multi-search Template API uses the following paths:
+
+```
+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
+
+All multi-search template URL parameters are optional. Some can also be applied per search as part of each metadata line.
+
+Parameter | Type | Description | Supported in metadata
+:--- | :--- | :---  | :---
+allow_no_indices | Boolean | Specifies whether to ignore wildcards that don't match any indexes. Default is `true`. | Yes
+cancel_after_time_interval | Time | The interval of time after which the search request will be canceled. Supported at both parent and child request levels. The order of precedence is child-level parameter, parent-level parameter, and [cluster setting]({{site.url}}{{site.baseurl}}/api-reference/cluster-settings/). Default is `-1`. | Yes
+css_minimize_roundtrips | Boolean | Specifies whether OpenSearch should try to minimize the number of network round trips between the coordinating node and remote clusters (only applicable to cross-cluster search requests). Default is `true`. | No
+expand_wildcards | Enum | Expands wildcard expressions to concrete indexes. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`. | Yes
+ignore_unavailable | Boolean | If an index or shard from the index list doesn’t exist, then this setting specifies whether to ignore the missing index or shard rather than fail the query. Default is `false`. | Yes
+max_concurrent_searches | Integer | The maximum number of concurrent searches. The default depends on your node count and search thread pool size. Higher values can improve performance, but there may be a risk of overloading the cluster. | No
+max_concurrent_shard_requests | Integer | The maximum number of concurrent shard requests that each search executes per node. Default is `5`. Higher values can improve performance, but there may be a risk of overloading the cluster. | No
+pre_filter_shard_size | Integer | Default is `128`. | No
+rest_total_hits_as_int | String | Specifies whether the `hits.total` property is returned as an integer (`true`) or an object (`false`). Default is `false`. | No
+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
+
+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.
+
+Option | Type | Description
+:--- | :--- | :---
+index | String, string array | If you don't specify an index or multiple indexes as part of the URL (or want to override the URL value for an individual search), you can include it under this option. Examples include `"logs-*"` and `["my-store", "sample_data_ecommerce"]`.
+preference | String | Specifies the nodes or shards on which you want to perform the search. This setting can be useful for testing, but in most situations, the default behavior provides the best search latencies. Options include `_local`, `_only_local`, `_prefer_nodes`, `_only_nodes`, and `_shards`. These last three options accept a list of nodes or shards. Examples include `"_only_nodes:data-node1,data-node2"` and `"_shards:0,1`.
+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
+
+The following example `msearch/template` API request runs queries against a single index using multiple templates named `line_search_template` and `play_search_template`:
+
+### Request
+
+```json
+GET _msearch/template
+{"index":"shakespeare"}
+{"id":"line_search_template","params":{"text_entry":"All the world's a stage","limit":false,"size":2}}
+{"index":"shakespeare"}
+{"id":"play_search_template","params":{"play_name":"Henry IV"}}
+```
+{% include copy-curl.html %}
+
+### Response
+
+OpenSearch returns an array with the results of each search in the same order as in the multi-search template request:
+
+```json
+{
+  "took": 5,
+  "responses": [
+    {
+      "took": 5,
+      "timed_out": false,
+      "_shards": {
+        "total": 1,
+        "successful": 1,
+        "skipped": 0,
+        "failed": 0
+      },
+      "hits": {
+        "total": {
+          "value": 0,
+          "relation": "eq"
+        },
+        "max_score": null,
+        "hits": []
+      }
+    },
+    {
+      "took": 3,
+      "timed_out": false,
+      "_shards": {
+        "total": 1,
+        "successful": 1,
+        "skipped": 0,
+        "failed": 0
+      },
+      "hits": {
+        "total": {
+          "value": 0,
+          "relation": "eq"
+        },
+        "max_score": null,
+        "hits": []
+      }
+    }
+  ]
+}
+```
diff --git a/_api-reference/multi-search.md b/_api-reference/multi-search.md
@@ -6,12 +6,13 @@ redirect_from:
  - /opensearch/rest-api/multi-search/
 ---
 
-# Multi-search
+# Multi-search 
 **Introduced 1.0**
 {: .label .label-purple }
 
 As the name suggests, the multi-search operation lets you bundle multiple search requests into a single request. OpenSearch then executes the searches in parallel, so you get back the response more quickly compared to sending one request per search. OpenSearch executes each search independently, so the failure of one doesn't affect the others.
 
+
 ## Example
 
 ```json
@@ -27,14 +28,15 @@ GET _msearch
 
 ## Path and HTTP methods
 
+The Multi-search API uses the following paths:
+
 ```
 GET _msearch
 GET <index>/_msearch
 POST _msearch
 POST <index>/_msearch
 ```
 
-
 ## Request body
 
 The multi-search request body follows this pattern:

diff --git a/_api-reference/security-apis.md b/_api-reference/security-apis.md
@@ -0,0 +1,20 @@
+---
+layout: default
+title: Security APIs
+nav_order: 84
+---
+
+# Security APIs
+
+Security APIs provide information that can be very useful in troubleshooting connection and configuration issues.
+
+API | Method | Description
+:--- | :--- | :---
+`/_plugins/_security/whoami` | GET/POST | Returns basic details about the logged-in user.
+`/_opendistro/_security/sslinfo` | GET | Returns details about the SSL connection when using certificate authentication.
+`/_plugins/_security/api/permissionsinfo` | GET | Returns permission details for the logged-in user.
+`/_plugins/_security/authinfo` | GET/POST | Returns the backend roles and OpenSearch roles mapped to the logged-in user.
+`/_plugins/_security/api/ssl/certs` | GET | Displays the details and expiration dates of the certificates used on the OpenSearch HTTP and transport communication layers. Can only be called by users with the `superadmin` certificate.
+`/_plugins/_security/api/ssl/transport/reloadcerts` | PUT | Reloads the certificates on the `transport` layer. For more information, see [Reload TLS certificates on the transport layer]({{site.url}}{{site.baseurl}}/security/configuration/tls/#reload-tls-certificates-on-the-transport-layer).
+`/_plugins/_security/api/ssl/http/reloadcerts` | PUT | Reloads the certificates on the `http` layer. For more information, see [Reload TLS certificates on the http layer]({{site.url}}{{site.baseurl}}/security/configuration/tls/#reload-tls-certificates-on-the-http-layer).
+
diff --git a/_automating-configurations/api/delete-workflow.md b/_automating-configurations/api/delete-workflow.md
@@ -7,9 +7,11 @@ nav_order: 80
 
 # Delete a workflow
 
-When you no longer need a workflow template, you can delete it by calling the Delete Workflow API. 
+When you no longer need a workflow template, you can delete it by calling the Delete Workflow API.
 
-Note that deleting a workflow only deletes the stored template but does not deprovision its resources.  
+Note that deleting a workflow only deletes the stored template---it does not deprovision its resources.
+
+When a workflow is deleted, its corresponding status (returned by the [Workflow State API]({{site.url}}{{site.baseurl}}/automating-configurations/api/get-workflow-status/)) is also deleted unless either the provisioning status is `IN_PROGRESS` or resources have been provisioned.
 
 ## Path and HTTP methods
 
@@ -25,13 +27,26 @@ The following table lists the available path parameters.
 | :--- | :--- | :--- |
 | `workflow_id` | String | The ID of the workflow to be retrieved. Required. |
 
+## Query parameters
+
+The following table lists the available query parameters. All query parameters are optional.
+
+| Parameter | Data type | Description |
+| :--- | :--- | :--- |
+| `clear_status` | Boolean | Determines whether to delete the workflow state (without deprovisioning resources) after deleting the template. OpenSearch deletes the workflow state only if the provisioning status is not `IN_PROGRESS`. Default is `false`. |
+
 #### Example request
 
-```
+```json
 DELETE /_plugins/_flow_framework/workflow/8xL8bowB8y25Tqfenm50
 ```
 {% include copy-curl.html %}
 
+```json
+DELETE /_plugins/_flow_framework/workflow/8xL8bowB8y25Tqfenm50?clear_status=true
+```
+{% include copy-curl.html %}
+
 #### Example response
 
 If the workflow exists, a delete response contains the status of the deletion, where the `result` field is set to `deleted` on success or `not_found` if the workflow does not exist (it may have already been deleted):
@@ -50,4 +65,4 @@ If the workflow exists, a delete response contains the status of the deletion, w
   "_seq_no": 2,
   "_primary_term": 1
 }
-```
+```
diff --git a/_automating-configurations/workflow-steps.md b/_automating-configurations/workflow-steps.md
@@ -42,6 +42,25 @@ The following table lists the workflow step types. The `user_inputs` fields for
 |`create_index`|[Create Index]({{site.url}}{{site.baseurl}}/api-reference/index-apis/create-index/)     | Creates a new OpenSearch index. The inputs include `index_name`, which should be the name of the index to be created, and `configurations`, which contains the payload body of a regular REST request for creating an index.
 |`create_ingest_pipeline`|[Create Ingest Pipeline]({{site.url}}{{site.baseurl}}/ingest-pipelines/create-ingest/) | Creates or updates an ingest pipeline. The inputs include `pipeline_id`, which should be the ID of the pipeline, and `configurations`, which contains the payload body of a regular REST request for creating an ingest pipeline.
 |`create_search_pipeline`|[Create Search Pipeline]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/creating-search-pipeline/) | Creates or updates a search pipeline. The inputs include `pipeline_id`, which should be the ID of the pipeline, and `configurations`, which contains the payload body of a regular REST request for creating a search pipeline.
+|`reindex`|[Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/)  | The reindex document API operation lets you copy all or a subset of your data from a source index into a destination index. The input includes source_index, destination_index, and the following optional parameters from the document reindex API: `refresh`, `requests_per_second`, `require_alias`, `slices`, and `max_docs`. For more information, see [Reindexing considerations](#reindexing-considerations).
+
+## Reindexing considerations
+
+Reindexing can be a resource-intensive operation, and if not managed properly, it can potentially destabilize your cluster. 
+
+When using a `reindex` step, follow these best practices to ensure a smooth reindexing process and prevent cluster instability:
+
+- **Cluster scaling**: Before initiating a reindexing operation, ensure that your OpenSearch cluster is properly scaled to handle the additional workload. Increase the number of nodes and adjust resource allocation (CPU, memory, and disk) as needed to accommodate the reindexing process without impacting other operations.
+
+- **Request rate control**: Use the `requests_per_second` parameter to control the rate at which the reindexing requests are sent to the cluster. This helps to regulate the load on the cluster and prevent resource exhaustion. Start with a lower value and gradually increase it based on your cluster's capacity and performance.
+
+- **Slicing and parallelization**: The `slices` parameter allows you to divide the reindexing process into smaller, parallel tasks. This can help distribute the workload across multiple nodes and improve overall performance. However, be cautious when increasing the number of slices because adding slices can increase resource consumption.
+
+- **Monitoring and adjustments**: Closely monitor your cluster performance metrics (such as CPU, memory, disk usage, and thread pools) during the reindexing process. If you notice any signs of resource contention or performance degradation, adjust the reindexing parameters accordingly or consider pausing the operation until the cluster stabilizes.
+
+- **Prioritization and scheduling**: If possible, schedule reindexing operations during off-peak hours or periods of lower cluster utilization to minimize the impact on other operations and user traffic.
+
+By following these best practices and carefully managing the reindexing process, you can ensure that your OpenSearch cluster remains stable and performant while efficiently copying data between indexes.
 
 ## Additional fields
 

diff --git a/_benchmark/reference/commands/command-flags.md b/_benchmark/reference/commands/command-flags.md
@@ -3,7 +3,8 @@ layout: default
 title: Command flags
 nav_order: 51
 parent: Command reference
-redirect_from: /benchmark/commands/command-flags/
+redirect_from: 
+  - /benchmark/commands/command-flags/
 grand_parent: OpenSearch Benchmark Reference
 ---
 

diff --git a/_benchmark/reference/commands/compare.md b/_benchmark/reference/commands/compare.md
@@ -4,7 +4,8 @@ title: compare
 nav_order: 55
 parent: Command reference
 grand_parent: OpenSearch Benchmark Reference
-redirect_from: /benchmark/commands/compare/
+redirect_from: 
+  - /benchmark/commands/compare/
 ---
 
 <!-- vale off -->