diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml new file mode 100644 index 000000000..532e5120f --- /dev/null +++ b/.github/workflows/coverage.yml @@ -0,0 +1,55 @@ +name: API Coverage + +on: [push, pull_request_target] + +env: + JAVA_VERSION: 11 + OPENSEARCH_INITIAL_ADMIN_PASSWORD: BobgG7YrtsdKf9M + +jobs: + coverage: + permissions: + pull-requests: write + runs-on: ubuntu-latest + steps: + - name: Checkout Repo + uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.head.sha }} + - name: Build and Run Docker Container + run: | + docker build coverage --tag opensearch-with-api-plugin + docker run -d -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" -e OPENSEARCH_INITIAL_ADMIN_PASSWORD="$OPENSEARCH_INITIAL_ADMIN_PASSWORD" opensearch-with-api-plugin + sleep 15 + - name: Display OpenSearch Info + run: | + curl -ks -u "admin:$OPENSEARCH_INITIAL_ADMIN_PASSWORD" https://localhost:9200/ | jq + - name: Dump and Compare API + run: | + curl -ks -u "admin:$OPENSEARCH_INITIAL_ADMIN_PASSWORD" https://localhost:9200/_plugins/api | jq > OpenSearch.auto.openapi.json + docker run --rm --mount type=bind,source=.,target=/specs openapitools/openapi-diff:latest /specs/OpenSearch.openapi.json /specs/OpenSearch.auto.openapi.json --json /specs/diff.json + - name: Show Diff + run: | + echo "-------- Missing APIs" + jq -r '.newEndpoints | group_by(.pathUrl)[] | "\(.[0].pathUrl): \([.[].method])"' diff.json + echo "-------- Legacy APIs" + jq -r '.missingEndpoints | group_by(.pathUrl)[] | "\(.[0].pathUrl): \([.[].method])"' diff.json + - name: Gather Coverage + id: coverage + shell: bash + run: | + current=`jq -r '.paths | keys | length' OpenSearch.openapi.json` + total=`jq -r '.paths | keys | length' OpenSearch.auto.openapi.json` + percent=$((current * 100 / total)) + echo "API specs implemented for $current/$total ($percent%) APIs." + cat >>"$GITHUB_OUTPUT" <.smithy` format. There are a few things to note when defining common parameters: +Common parameters that are used across OpenSearch namespaces are defined in the root folder, `model/`, and grouped by data-type in files of `common_.smithy` format. There are a few things to note when defining global common parameters: - All path parameters should be prefixed with `Path` like `PathIndex` and `PathDocumentID`. - Smithy doesn't support _enum_ or _list_ as path parameters. We, therefore, have to define such parameters as _string_ and use `x-data-type` vendor extension to denote their actual types (More on this in the traits section). - Parameters of type `time` are defined as `string` and has `@pattern("^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$")` trait to denote that they are in the format of ``. E.g. `1d`, `2h`, `3m`, `4s`, `5ms`, `6micros`, `7nanos`. We use `x-data-type: "time"` vendor extension for this type. - Path parameters that are defined as strings must be accompanied by a `@pattern` trait and should be default to `^[^_][\\d\\w-*]*$` to signify that they are not allowed to start with `_` to avoid URI Conflict errors. - The `@documentation`, `@default`, and `@deprecation` traits can later be overridden by the operations that use these parameters. +Common parameters that are used within a namespace, especially namespaces representing plugins like `security` are defined in the namespace folder (e.g. `model/security`) + ## Smithy Traits We use Smithy traits extensively in this project to work around some limitations of Smithy and to deal with some quirks of the OpenSearch API. Here are some of the traits that you should be aware of: -- `@vendorExtensions`: Used to add metadata that are not supported by Smithy. Check OpenAPI Vendor Extensions section for more details. - `@suppress(["HttpMethodSemantics.UnexpectedPayload"])`: Used in DELETE operations with request body to suppress the UnexpectedPayload error. - `@suppress(["HttpUriConflict"])`: Used to suppress the HttpUriConflict error that is thrown when two operations have conflicting URI. Unfortunately, this happens a lot in OpenSearch API. When in doubt, add this trait to the operation. - `@pattern("^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless)")`: Required for most Path parameters to avoid URI Conflict errors. This is often used in tandem with the @suppress trait above. To denote the actual pattern of the parameter, use `x-string-pattern` vendor extension. diff --git a/OpenSearch.openapi.json b/OpenSearch.openapi.json index a4ba7bf8d..aa4420c5a 100644 --- a/OpenSearch.openapi.json +++ b/OpenSearch.openapi.json @@ -1323,7 +1323,7 @@ } }, "x-operation-group": "cat.cluster_manager", - "x-version-added": "1.0" + "x-version-added": "2.0" } }, "/_cat/count": { @@ -2239,7 +2239,7 @@ "x-deprecation-message": "To promote inclusive language, please use '/_cat/cluster_manager' instead.", "x-operation-group": "cat.master", "x-version-added": "1.0", - "x-version-deprecated": "1.0" + "x-version-deprecated": "2.0" } }, "/_cat/nodeattrs": { @@ -2632,13 +2632,80 @@ } } }, + "parameters": [ + { + "name": "format", + "in": "query", + "description": "A short version of the Accept header, e.g. json, yaml.", + "schema": { + "type": "string", + "description": "A short version of the Accept header, e.g. json, yaml." + } + }, + { + "name": "h", + "in": "query", + "description": "Comma-separated list of column names to display.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of column names to display." + }, + "explode": true + }, + { + "name": "help", + "in": "query", + "description": "Return help information.", + "schema": { + "type": "boolean", + "default": false, + "description": "Return help information." + } + }, + { + "name": "s", + "in": "query", + "description": "Comma-separated list of column names or column aliases to sort by.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of column names or column aliases to sort by." + }, + "explode": true + }, + { + "name": "v", + "in": "query", + "description": "Verbose mode. Display column headers.", + "schema": { + "type": "boolean", + "default": false, + "description": "Verbose mode. Display column headers." + } + }, + { + "name": "bytes", + "in": "query", + "description": "The unit in which to display byte values.", + "schema": { + "$ref": "#/components/schemas/Bytes" + } + } + ], "responses": { "200": { "description": "CatPitSegments 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CatPitSegmentsResponseContent" + "$ref": "#/components/schemas/CatPitSegmentsOutputPayload" } } } @@ -2656,13 +2723,80 @@ "url": "https://opensearch.org/docs/latest/search-plugins/point-in-time-api/" }, "operationId": "CatAllPitSegments", + "parameters": [ + { + "name": "format", + "in": "query", + "description": "A short version of the Accept header, e.g. json, yaml.", + "schema": { + "type": "string", + "description": "A short version of the Accept header, e.g. json, yaml." + } + }, + { + "name": "h", + "in": "query", + "description": "Comma-separated list of column names to display.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of column names to display." + }, + "explode": true + }, + { + "name": "help", + "in": "query", + "description": "Return help information.", + "schema": { + "type": "boolean", + "default": false, + "description": "Return help information." + } + }, + { + "name": "s", + "in": "query", + "description": "Comma-separated list of column names or column aliases to sort by.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of column names or column aliases to sort by." + }, + "explode": true + }, + { + "name": "v", + "in": "query", + "description": "Verbose mode. Display column headers.", + "schema": { + "type": "boolean", + "default": false, + "description": "Verbose mode. Display column headers." + } + }, + { + "name": "bytes", + "in": "query", + "description": "The unit in which to display byte values.", + "schema": { + "$ref": "#/components/schemas/Bytes" + } + } + ], "responses": { "200": { "description": "CatAllPitSegments 200 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CatAllPitSegmentsResponseContent" + "$ref": "#/components/schemas/CatAllPitSegmentsOutputPayload" } } } @@ -3174,6 +3308,89 @@ "description": "A short version of the Accept header, e.g. json, yaml." } }, + { + "name": "h", + "in": "query", + "description": "Comma-separated list of column names to display.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of column names to display." + }, + "explode": true + }, + { + "name": "help", + "in": "query", + "description": "Return help information.", + "schema": { + "type": "boolean", + "default": false, + "description": "Return help information." + } + }, + { + "name": "s", + "in": "query", + "description": "Comma-separated list of column names or column aliases to sort by.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of column names or column aliases to sort by." + }, + "explode": true + }, + { + "name": "v", + "in": "query", + "description": "Verbose mode. Display column headers.", + "schema": { + "type": "boolean", + "default": false, + "description": "Verbose mode. Display column headers." + } + }, + { + "name": "allow_no_indices", + "in": "query", + "description": "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified).", + "schema": { + "type": "boolean", + "description": "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)." + } + }, + { + "name": "expand_wildcards", + "in": "query", + "description": "Whether to expand wildcard expression to concrete indices that are open, closed or both.", + "schema": { + "$ref": "#/components/schemas/ExpandWildcards" + } + }, + { + "name": "ignore_throttled", + "in": "query", + "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled.", + "schema": { + "type": "boolean", + "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled." + } + }, + { + "name": "ignore_unavailable", + "in": "query", + "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed).", + "schema": { + "type": "boolean", + "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed)." + } + }, { "name": "active_only", "in": "query", @@ -3227,83 +3444,53 @@ "explode": true }, { - "name": "h", + "name": "index", "in": "query", - "description": "Comma-separated list of column names to display.", + "description": "Comma-separated list or wildcard expression of index names to limit the returned information.", "style": "form", "schema": { "type": "array", "items": { "type": "string" }, - "description": "Comma-separated list of column names to display." + "description": "Comma-separated list or wildcard expression of index names to limit the returned information." }, "explode": true }, { - "name": "help", + "name": "time", "in": "query", - "description": "Return help information.", + "description": "The unit in which to display time values.", "schema": { - "type": "boolean", - "default": false, - "description": "Return help information." + "$ref": "#/components/schemas/Time" } }, { - "name": "index", - "in": "query", - "description": "Comma-separated list or wildcard expression of index names to limit the returned information.", - "style": "form", - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Comma-separated list or wildcard expression of index names to limit the returned information." - }, - "explode": true - }, - { - "name": "s", + "name": "timeout", "in": "query", - "description": "Comma-separated list of column names or column aliases to sort by.", - "style": "form", + "description": "Operation timeout.", "schema": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Comma-separated list of column names or column aliases to sort by." - }, - "explode": true - }, - { - "name": "time", - "in": "query", - "description": "The unit in which to display time values.", - "schema": { - "$ref": "#/components/schemas/Time" - } - }, - { - "name": "v", - "in": "query", - "description": "Verbose mode. Display column headers.", - "schema": { - "type": "boolean", - "default": false, - "description": "Verbose mode. Display column headers." + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Operation timeout.", + "x-data-type": "time" } } ], "responses": { "200": { - "description": "CatSegmentReplication 200 response" + "description": "CatSegmentReplication 200 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CatSegmentReplicationOutputPayload" + } + } + } } }, "x-operation-group": "cat.segment_replication", - "x-version-added": "1.0" + "x-version-added": "2.6.0" } }, "/_cat/segment_replication/{index}": { @@ -3332,6 +3519,89 @@ "description": "A short version of the Accept header, e.g. json, yaml." } }, + { + "name": "h", + "in": "query", + "description": "Comma-separated list of column names to display.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of column names to display." + }, + "explode": true + }, + { + "name": "help", + "in": "query", + "description": "Return help information.", + "schema": { + "type": "boolean", + "default": false, + "description": "Return help information." + } + }, + { + "name": "s", + "in": "query", + "description": "Comma-separated list of column names or column aliases to sort by.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of column names or column aliases to sort by." + }, + "explode": true + }, + { + "name": "v", + "in": "query", + "description": "Verbose mode. Display column headers.", + "schema": { + "type": "boolean", + "default": false, + "description": "Verbose mode. Display column headers." + } + }, + { + "name": "allow_no_indices", + "in": "query", + "description": "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified).", + "schema": { + "type": "boolean", + "description": "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)." + } + }, + { + "name": "expand_wildcards", + "in": "query", + "description": "Whether to expand wildcard expression to concrete indices that are open, closed or both.", + "schema": { + "$ref": "#/components/schemas/ExpandWildcards" + } + }, + { + "name": "ignore_throttled", + "in": "query", + "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled.", + "schema": { + "type": "boolean", + "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled." + } + }, + { + "name": "ignore_unavailable", + "in": "query", + "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed).", + "schema": { + "type": "boolean", + "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed)." + } + }, { "name": "active_only", "in": "query", @@ -3384,30 +3654,6 @@ }, "explode": true }, - { - "name": "h", - "in": "query", - "description": "Comma-separated list of column names to display.", - "style": "form", - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Comma-separated list of column names to display." - }, - "explode": true - }, - { - "name": "help", - "in": "query", - "description": "Return help information.", - "schema": { - "type": "boolean", - "default": false, - "description": "Return help information." - } - }, { "name": "index", "in": "query", @@ -3422,20 +3668,6 @@ }, "explode": true }, - { - "name": "s", - "in": "query", - "description": "Comma-separated list of column names or column aliases to sort by.", - "style": "form", - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Comma-separated list of column names or column aliases to sort by." - }, - "explode": true - }, { "name": "time", "in": "query", @@ -3445,23 +3677,31 @@ } }, { - "name": "v", + "name": "timeout", "in": "query", - "description": "Verbose mode. Display column headers.", + "description": "Operation timeout.", "schema": { - "type": "boolean", - "default": false, - "description": "Verbose mode. Display column headers." + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Operation timeout.", + "x-data-type": "time" } } ], "responses": { "200": { - "description": "CatSegmentReplication_WithIndex 200 response" + "description": "CatSegmentReplication_WithIndex 200 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CatSegmentReplication_WithIndexOutputPayload" + } + } + } } }, "x-operation-group": "cat.segment_replication", - "x-version-added": "1.0" + "x-version-added": "2.6.0" } }, "/_cat/segments": { @@ -4899,7 +5139,7 @@ "x-version-added": "1.0" } }, - "/_cluster/decommission/awareness/": { + "/_cluster/decommission/awareness": { "delete": { "description": "Delete any existing decommission.", "externalDocs": { @@ -7988,6 +8228,16 @@ "description": "Specify whether the index should be flushed after performing the operation." } }, + { + "name": "primary_only", + "in": "query", + "description": "Specify whether the operation should only perform on primary shards. Defaults to false.", + "schema": { + "type": "boolean", + "default": false, + "description": "Specify whether the operation should only perform on primary shards. Defaults to false." + } + }, { "name": "ignore_unavailable", "in": "query", @@ -8032,6 +8282,16 @@ "type": "boolean", "description": "Specify whether the operation should only expunge deleted documents." } + }, + { + "name": "wait_for_completion", + "in": "query", + "description": "Should this request wait until the operation has completed before returning.", + "schema": { + "type": "boolean", + "default": true, + "description": "Should this request wait until the operation has completed before returning." + } } ], "responses": { @@ -10494,7 +10754,8 @@ "thread_pool", "transport", "discovery", - "indexing_pressure" + "indexing_pressure", + "search_pipeline" ], "x-data-type": "array" }, @@ -10634,7 +10895,8 @@ "thread_pool", "transport", "discovery", - "indexing_pressure" + "indexing_pressure", + "search_pipeline" ], "x-data-type": "array" }, @@ -11282,7 +11544,8 @@ "thread_pool", "transport", "discovery", - "indexing_pressure" + "indexing_pressure", + "search_pipeline" ], "x-data-type": "array" }, @@ -11434,7 +11697,8 @@ "thread_pool", "transport", "discovery", - "indexing_pressure" + "indexing_pressure", + "search_pipeline" ], "x-data-type": "array" }, @@ -11527,41 +11791,1294 @@ "explode": true }, { - "name": "groups", - "in": "query", - "description": "Comma-separated list of search groups for `search` index metric.", - "style": "form", + "name": "groups", + "in": "query", + "description": "Comma-separated list of search groups for `search` index metric.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of search groups for `search` index metric." + }, + "explode": true + }, + { + "name": "level", + "in": "query", + "description": "Return indices stats aggregated at index, node or shard level.", + "schema": { + "$ref": "#/components/schemas/NodesStatLevel" + } + }, + { + "name": "types", + "in": "query", + "description": "Comma-separated list of document types for the `indexing` index metric.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of document types for the `indexing` index metric." + }, + "explode": true + }, + { + "name": "timeout", + "in": "query", + "description": "Operation timeout.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Operation timeout.", + "x-data-type": "time" + } + }, + { + "name": "include_segment_file_sizes", + "in": "query", + "description": "Whether to report the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).", + "schema": { + "type": "boolean", + "default": false, + "description": "Whether to report the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested)." + } + } + ], + "responses": { + "200": { + "description": "NodesStats_WithIndexMetricMetricNodeId 200 response" + } + }, + "x-operation-group": "nodes.stats", + "x-version-added": "1.0" + } + }, + "/_nodes/{node_id}/usage": { + "get": { + "description": "Returns low-level information about REST actions usage on nodes.", + "operationId": "NodesUsage_WithNodeId", + "parameters": [ + { + "name": "node_id", + "in": "path", + "description": "Comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes.", + "schema": { + "type": "string", + "pattern": "^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$", + "description": "Comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes.", + "x-data-type": "array" + }, + "required": true + }, + { + "name": "timeout", + "in": "query", + "description": "Operation timeout.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Operation timeout.", + "x-data-type": "time" + } + } + ], + "responses": { + "200": { + "description": "NodesUsage_WithNodeId 200 response" + } + }, + "x-operation-group": "nodes.usage", + "x-version-added": "1.0" + } + }, + "/_nodes/{node_id}/usage/{metric}": { + "get": { + "description": "Returns low-level information about REST actions usage on nodes.", + "operationId": "NodesUsage_WithMetricNodeId", + "parameters": [ + { + "name": "metric", + "in": "path", + "description": "Limit the information returned to the specified metrics.", + "schema": { + "type": "string", + "pattern": "^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$", + "description": "Limit the information returned to the specified metrics.", + "x-enum-options": [ + "_all", + "rest_actions" + ], + "x-data-type": "array" + }, + "required": true + }, + { + "name": "node_id", + "in": "path", + "description": "Comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes.", + "schema": { + "type": "string", + "pattern": "^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$", + "description": "Comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes.", + "x-data-type": "array" + }, + "required": true + }, + { + "name": "timeout", + "in": "query", + "description": "Operation timeout.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Operation timeout.", + "x-data-type": "time" + } + } + ], + "responses": { + "200": { + "description": "NodesUsage_WithMetricNodeId 200 response" + } + }, + "x-operation-group": "nodes.usage", + "x-version-added": "1.0" + } + }, + "/_nodes/{node_id}/{metric}": { + "get": { + "description": "Returns information about nodes in the cluster.", + "operationId": "NodesInfo_WithMetricNodeId", + "parameters": [ + { + "name": "node_id", + "in": "path", + "description": "Comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes.", + "schema": { + "type": "string", + "pattern": "^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$", + "description": "Comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes.", + "x-data-type": "array" + }, + "required": true + }, + { + "name": "metric", + "in": "path", + "description": "Comma-separated list of metrics you wish returned. Leave empty to return all.", + "schema": { + "type": "string", + "pattern": "^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$", + "description": "Comma-separated list of metrics you wish returned. Leave empty to return all.", + "x-enum-options": [ + "settings", + "os", + "process", + "jvm", + "thread_pool", + "transport", + "http", + "plugins", + "ingest" + ], + "x-data-type": "array" + }, + "required": true + }, + { + "name": "flat_settings", + "in": "query", + "description": "Return settings in flat format.", + "schema": { + "type": "boolean", + "default": false, + "description": "Return settings in flat format." + } + }, + { + "name": "timeout", + "in": "query", + "description": "Operation timeout.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Operation timeout.", + "x-data-type": "time" + } + } + ], + "responses": { + "200": { + "description": "NodesInfo_WithMetricNodeId 200 response" + } + }, + "x-operation-group": "nodes.info", + "x-version-added": "1.0" + } + }, + "/_plugins/_knn/models/_search": { + "get": { + "description": "Use an OpenSearch query to search for models in the index.", + "externalDocs": { + "description": "API Reference", + "url": "https://opensearch.org/docs/latest/search-plugins/knn/api/#search-model" + }, + "operationId": "KNNSearchModels_Get", + "parameters": [ + { + "name": "analyzer", + "in": "query", + "description": "The analyzer to use for the query string.", + "schema": { + "type": "string", + "description": "The analyzer to use for the query string." + } + }, + { + "name": "analyze_wildcard", + "in": "query", + "description": "Specify whether wildcard and prefix queries should be analyzed.", + "schema": { + "type": "boolean", + "default": false, + "description": "Specify whether wildcard and prefix queries should be analyzed." + } + }, + { + "name": "ccs_minimize_roundtrips", + "in": "query", + "description": "Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution.", + "schema": { + "type": "boolean", + "default": true, + "description": "Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution." + } + }, + { + "name": "default_operator", + "in": "query", + "description": "The default operator for query string query (AND or OR).", + "schema": { + "$ref": "#/components/schemas/DefaultOperator" + } + }, + { + "name": "df", + "in": "query", + "description": "The field to use as default where no field prefix is given in the query string.", + "schema": { + "type": "string", + "description": "The field to use as default where no field prefix is given in the query string." + } + }, + { + "name": "explain", + "in": "query", + "description": "Specify whether to return detailed information about score computation as part of a hit.", + "schema": { + "type": "boolean", + "description": "Specify whether to return detailed information about score computation as part of a hit." + } + }, + { + "name": "stored_fields", + "in": "query", + "description": "Comma-separated list of stored fields to return.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of stored fields to return." + }, + "explode": true + }, + { + "name": "docvalue_fields", + "in": "query", + "description": "Comma-separated list of fields to return as the docvalue representation of a field for each hit.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of fields to return as the docvalue representation of a field for each hit." + }, + "explode": true + }, + { + "name": "from", + "in": "query", + "description": "Starting offset.", + "schema": { + "type": "integer", + "default": 0, + "description": "Starting offset.", + "format": "int32" + } + }, + { + "name": "ignore_unavailable", + "in": "query", + "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed).", + "schema": { + "type": "boolean", + "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed)." + } + }, + { + "name": "ignore_throttled", + "in": "query", + "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled.", + "schema": { + "type": "boolean", + "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled." + } + }, + { + "name": "allow_no_indices", + "in": "query", + "description": "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified).", + "schema": { + "type": "boolean", + "description": "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)." + } + }, + { + "name": "expand_wildcards", + "in": "query", + "description": "Whether to expand wildcard expression to concrete indices that are open, closed or both.", + "schema": { + "$ref": "#/components/schemas/ExpandWildcards" + } + }, + { + "name": "lenient", + "in": "query", + "description": "Specify whether format-based query failures (such as providing text to a numeric field) should be ignored.", + "schema": { + "type": "boolean", + "description": "Specify whether format-based query failures (such as providing text to a numeric field) should be ignored." + } + }, + { + "name": "preference", + "in": "query", + "description": "Specify the node or shard the operation should be performed on.", + "schema": { + "type": "string", + "default": "random", + "description": "Specify the node or shard the operation should be performed on." + } + }, + { + "name": "q", + "in": "query", + "description": "Query in the Lucene query string syntax.", + "schema": { + "type": "string", + "description": "Query in the Lucene query string syntax." + } + }, + { + "name": "routing", + "in": "query", + "description": "Comma-separated list of specific routing values.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of specific routing values." + }, + "explode": true + }, + { + "name": "scroll", + "in": "query", + "description": "Specify how long a consistent view of the index should be maintained for scrolled search.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Specify how long a consistent view of the index should be maintained for scrolled search.", + "x-data-type": "time" + } + }, + { + "name": "search_type", + "in": "query", + "description": "Search operation type.", + "schema": { + "$ref": "#/components/schemas/SearchType" + } + }, + { + "name": "size", + "in": "query", + "description": "Number of hits to return.", + "schema": { + "type": "integer", + "default": 10, + "description": "Number of hits to return.", + "format": "int32" + } + }, + { + "name": "sort", + "in": "query", + "description": "Comma-separated list of : pairs.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of : pairs." + }, + "explode": true + }, + { + "name": "_source", + "in": "query", + "description": "True or false to return the _source field or not, or a list of fields to return.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "True or false to return the _source field or not, or a list of fields to return." + }, + "explode": true + }, + { + "name": "_source_excludes", + "in": "query", + "description": "List of fields to exclude from the returned _source field.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of fields to exclude from the returned _source field." + }, + "explode": true + }, + { + "name": "_source_includes", + "in": "query", + "description": "List of fields to extract and return from the _source field.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of fields to extract and return from the _source field." + }, + "explode": true + }, + { + "name": "terminate_after", + "in": "query", + "description": "The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early.", + "schema": { + "type": "integer", + "description": "The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early.", + "format": "int32" + } + }, + { + "name": "stats", + "in": "query", + "description": "Specific 'tag' of the request for logging and statistical purposes.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Specific 'tag' of the request for logging and statistical purposes." + }, + "explode": true + }, + { + "name": "suggest_field", + "in": "query", + "description": "Specify which field to use for suggestions.", + "schema": { + "type": "string", + "description": "Specify which field to use for suggestions." + } + }, + { + "name": "suggest_mode", + "in": "query", + "description": "Specify suggest mode.", + "schema": { + "$ref": "#/components/schemas/SuggestMode" + } + }, + { + "name": "suggest_size", + "in": "query", + "description": "How many suggestions to return in response.", + "schema": { + "type": "integer", + "description": "How many suggestions to return in response.", + "format": "int32" + } + }, + { + "name": "suggest_text", + "in": "query", + "description": "The source text for which the suggestions should be returned.", + "schema": { + "type": "string", + "description": "The source text for which the suggestions should be returned." + } + }, + { + "name": "timeout", + "in": "query", + "description": "Operation timeout.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Operation timeout.", + "x-data-type": "time" + } + }, + { + "name": "track_scores", + "in": "query", + "description": "Whether to calculate and return scores even if they are not used for sorting.", + "schema": { + "type": "boolean", + "description": "Whether to calculate and return scores even if they are not used for sorting." + } + }, + { + "name": "track_total_hits", + "in": "query", + "description": "Indicate if the number of documents that match the query should be tracked.", + "schema": { + "type": "boolean", + "description": "Indicate if the number of documents that match the query should be tracked." + } + }, + { + "name": "allow_partial_search_results", + "in": "query", + "description": "Indicate if an error should be returned if there is a partial search failure or timeout.", + "schema": { + "type": "boolean", + "default": true, + "description": "Indicate if an error should be returned if there is a partial search failure or timeout." + } + }, + { + "name": "typed_keys", + "in": "query", + "description": "Specify whether aggregation and suggester names should be prefixed by their respective types in the response.", + "schema": { + "type": "boolean", + "description": "Specify whether aggregation and suggester names should be prefixed by their respective types in the response." + } + }, + { + "name": "version", + "in": "query", + "description": "Whether to return document version as part of a hit.", + "schema": { + "type": "boolean", + "description": "Whether to return document version as part of a hit." + } + }, + { + "name": "seq_no_primary_term", + "in": "query", + "description": "Specify whether to return sequence number and primary term of the last modification of each hit.", + "schema": { + "type": "boolean", + "description": "Specify whether to return sequence number and primary term of the last modification of each hit." + } + }, + { + "name": "request_cache", + "in": "query", + "description": "Specify if request cache should be used for this request or not, defaults to index level setting.", + "schema": { + "type": "boolean", + "description": "Specify if request cache should be used for this request or not, defaults to index level setting." + } + }, + { + "name": "batched_reduce_size", + "in": "query", + "description": "The number of shard results that should be reduced at once on the coordinating node. This value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.", + "schema": { + "type": "integer", + "default": 512, + "description": "The number of shard results that should be reduced at once on the coordinating node. This value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.", + "format": "int32" + } + }, + { + "name": "max_concurrent_shard_requests", + "in": "query", + "description": "The number of concurrent shard requests per node this search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.", + "schema": { + "type": "integer", + "default": 5, + "description": "The number of concurrent shard requests per node this search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.", + "format": "int32" + } + }, + { + "name": "pre_filter_shard_size", + "in": "query", + "description": "Threshold that enforces a pre-filter round-trip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter round-trip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method ie. if date filters are mandatory to match but the shard bounds and the query are disjoint.", + "schema": { + "type": "integer", + "description": "Threshold that enforces a pre-filter round-trip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter round-trip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method ie. if date filters are mandatory to match but the shard bounds and the query are disjoint.", + "format": "int32" + } + }, + { + "name": "rest_total_hits_as_int", + "in": "query", + "description": "Indicates whether hits.total should be rendered as an integer or an object in the rest search response.", + "schema": { + "type": "boolean", + "default": false, + "description": "Indicates whether hits.total should be rendered as an integer or an object in the rest search response." + } + } + ], + "responses": { + "200": { + "description": "KNNSearchModels_Get 200 response" + } + }, + "x-operation-group": "knn.search_models", + "x-version-added": "1.0" + }, + "post": { + "description": "Use an OpenSearch query to search for models in the index.", + "operationId": "KNNSearchModels_Post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KNNSearchModels_BodyParams" + } + } + } + }, + "parameters": [ + { + "name": "analyzer", + "in": "query", + "description": "The analyzer to use for the query string.", + "schema": { + "type": "string", + "description": "The analyzer to use for the query string." + } + }, + { + "name": "analyze_wildcard", + "in": "query", + "description": "Specify whether wildcard and prefix queries should be analyzed.", + "schema": { + "type": "boolean", + "default": false, + "description": "Specify whether wildcard and prefix queries should be analyzed." + } + }, + { + "name": "ccs_minimize_roundtrips", + "in": "query", + "description": "Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution.", + "schema": { + "type": "boolean", + "default": true, + "description": "Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution." + } + }, + { + "name": "default_operator", + "in": "query", + "description": "The default operator for query string query (AND or OR).", + "schema": { + "$ref": "#/components/schemas/DefaultOperator" + } + }, + { + "name": "df", + "in": "query", + "description": "The field to use as default where no field prefix is given in the query string.", + "schema": { + "type": "string", + "description": "The field to use as default where no field prefix is given in the query string." + } + }, + { + "name": "explain", + "in": "query", + "description": "Specify whether to return detailed information about score computation as part of a hit.", + "schema": { + "type": "boolean", + "description": "Specify whether to return detailed information about score computation as part of a hit." + } + }, + { + "name": "stored_fields", + "in": "query", + "description": "Comma-separated list of stored fields to return.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of stored fields to return." + }, + "explode": true + }, + { + "name": "docvalue_fields", + "in": "query", + "description": "Comma-separated list of fields to return as the docvalue representation of a field for each hit.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of fields to return as the docvalue representation of a field for each hit." + }, + "explode": true + }, + { + "name": "from", + "in": "query", + "description": "Starting offset.", + "schema": { + "type": "integer", + "default": 0, + "description": "Starting offset.", + "format": "int32" + } + }, + { + "name": "ignore_unavailable", + "in": "query", + "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed).", + "schema": { + "type": "boolean", + "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed)." + } + }, + { + "name": "ignore_throttled", + "in": "query", + "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled.", + "schema": { + "type": "boolean", + "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled." + } + }, + { + "name": "allow_no_indices", + "in": "query", + "description": "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified).", + "schema": { + "type": "boolean", + "description": "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)." + } + }, + { + "name": "expand_wildcards", + "in": "query", + "description": "Whether to expand wildcard expression to concrete indices that are open, closed or both.", + "schema": { + "$ref": "#/components/schemas/ExpandWildcards" + } + }, + { + "name": "lenient", + "in": "query", + "description": "Specify whether format-based query failures (such as providing text to a numeric field) should be ignored.", + "schema": { + "type": "boolean", + "description": "Specify whether format-based query failures (such as providing text to a numeric field) should be ignored." + } + }, + { + "name": "preference", + "in": "query", + "description": "Specify the node or shard the operation should be performed on.", + "schema": { + "type": "string", + "default": "random", + "description": "Specify the node or shard the operation should be performed on." + } + }, + { + "name": "q", + "in": "query", + "description": "Query in the Lucene query string syntax.", + "schema": { + "type": "string", + "description": "Query in the Lucene query string syntax." + } + }, + { + "name": "routing", + "in": "query", + "description": "Comma-separated list of specific routing values.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of specific routing values." + }, + "explode": true + }, + { + "name": "scroll", + "in": "query", + "description": "Specify how long a consistent view of the index should be maintained for scrolled search.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Specify how long a consistent view of the index should be maintained for scrolled search.", + "x-data-type": "time" + } + }, + { + "name": "search_type", + "in": "query", + "description": "Search operation type.", + "schema": { + "$ref": "#/components/schemas/SearchType" + } + }, + { + "name": "size", + "in": "query", + "description": "Number of hits to return.", + "schema": { + "type": "integer", + "default": 10, + "description": "Number of hits to return.", + "format": "int32" + } + }, + { + "name": "sort", + "in": "query", + "description": "Comma-separated list of : pairs.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Comma-separated list of : pairs." + }, + "explode": true + }, + { + "name": "_source", + "in": "query", + "description": "True or false to return the _source field or not, or a list of fields to return.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "True or false to return the _source field or not, or a list of fields to return." + }, + "explode": true + }, + { + "name": "_source_excludes", + "in": "query", + "description": "List of fields to exclude from the returned _source field.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of fields to exclude from the returned _source field." + }, + "explode": true + }, + { + "name": "_source_includes", + "in": "query", + "description": "List of fields to extract and return from the _source field.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of fields to extract and return from the _source field." + }, + "explode": true + }, + { + "name": "terminate_after", + "in": "query", + "description": "The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early.", + "schema": { + "type": "integer", + "description": "The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early.", + "format": "int32" + } + }, + { + "name": "stats", + "in": "query", + "description": "Specific 'tag' of the request for logging and statistical purposes.", + "style": "form", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Specific 'tag' of the request for logging and statistical purposes." + }, + "explode": true + }, + { + "name": "suggest_field", + "in": "query", + "description": "Specify which field to use for suggestions.", + "schema": { + "type": "string", + "description": "Specify which field to use for suggestions." + } + }, + { + "name": "suggest_mode", + "in": "query", + "description": "Specify suggest mode.", + "schema": { + "$ref": "#/components/schemas/SuggestMode" + } + }, + { + "name": "suggest_size", + "in": "query", + "description": "How many suggestions to return in response.", + "schema": { + "type": "integer", + "description": "How many suggestions to return in response.", + "format": "int32" + } + }, + { + "name": "suggest_text", + "in": "query", + "description": "The source text for which the suggestions should be returned.", + "schema": { + "type": "string", + "description": "The source text for which the suggestions should be returned." + } + }, + { + "name": "timeout", + "in": "query", + "description": "Operation timeout.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Operation timeout.", + "x-data-type": "time" + } + }, + { + "name": "track_scores", + "in": "query", + "description": "Whether to calculate and return scores even if they are not used for sorting.", + "schema": { + "type": "boolean", + "description": "Whether to calculate and return scores even if they are not used for sorting." + } + }, + { + "name": "track_total_hits", + "in": "query", + "description": "Indicate if the number of documents that match the query should be tracked.", + "schema": { + "type": "boolean", + "description": "Indicate if the number of documents that match the query should be tracked." + } + }, + { + "name": "allow_partial_search_results", + "in": "query", + "description": "Indicate if an error should be returned if there is a partial search failure or timeout.", + "schema": { + "type": "boolean", + "default": true, + "description": "Indicate if an error should be returned if there is a partial search failure or timeout." + } + }, + { + "name": "typed_keys", + "in": "query", + "description": "Specify whether aggregation and suggester names should be prefixed by their respective types in the response.", + "schema": { + "type": "boolean", + "description": "Specify whether aggregation and suggester names should be prefixed by their respective types in the response." + } + }, + { + "name": "version", + "in": "query", + "description": "Whether to return document version as part of a hit.", + "schema": { + "type": "boolean", + "description": "Whether to return document version as part of a hit." + } + }, + { + "name": "seq_no_primary_term", + "in": "query", + "description": "Specify whether to return sequence number and primary term of the last modification of each hit.", + "schema": { + "type": "boolean", + "description": "Specify whether to return sequence number and primary term of the last modification of each hit." + } + }, + { + "name": "request_cache", + "in": "query", + "description": "Specify if request cache should be used for this request or not, defaults to index level setting.", + "schema": { + "type": "boolean", + "description": "Specify if request cache should be used for this request or not, defaults to index level setting." + } + }, + { + "name": "batched_reduce_size", + "in": "query", + "description": "The number of shard results that should be reduced at once on the coordinating node. This value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.", + "schema": { + "type": "integer", + "default": 512, + "description": "The number of shard results that should be reduced at once on the coordinating node. This value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.", + "format": "int32" + } + }, + { + "name": "max_concurrent_shard_requests", + "in": "query", + "description": "The number of concurrent shard requests per node this search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.", + "schema": { + "type": "integer", + "default": 5, + "description": "The number of concurrent shard requests per node this search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.", + "format": "int32" + } + }, + { + "name": "pre_filter_shard_size", + "in": "query", + "description": "Threshold that enforces a pre-filter round-trip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter round-trip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method ie. if date filters are mandatory to match but the shard bounds and the query are disjoint.", + "schema": { + "type": "integer", + "description": "Threshold that enforces a pre-filter round-trip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter round-trip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method ie. if date filters are mandatory to match but the shard bounds and the query are disjoint.", + "format": "int32" + } + }, + { + "name": "rest_total_hits_as_int", + "in": "query", + "description": "Indicates whether hits.total should be rendered as an integer or an object in the rest search response.", + "schema": { + "type": "boolean", + "default": false, + "description": "Indicates whether hits.total should be rendered as an integer or an object in the rest search response." + } + } + ], + "responses": { + "200": { + "description": "KNNSearchModels_Post 200 response" + } + }, + "x-operation-group": "knn.search_models", + "x-version-added": "1.0" + } + }, + "/_plugins/_knn/models/_train": { + "post": { + "description": "Create and train a model that can be used for initializing k-NN native library indexes during indexing.", + "externalDocs": { + "description": "API Reference", + "url": "https://opensearch.org/docs/latest/search-plugins/knn/api/#train-model" + }, + "operationId": "KNNTrainModel", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KNNTrainModel_BodyParams" + } + } + }, + "required": true + }, + "parameters": [ + { + "name": "preference", + "in": "query", + "description": "Preferred node to execute training.", + "schema": { + "type": "string", + "description": "Preferred node to execute training." + } + } + ], + "responses": { + "200": { + "description": "KNNTrainModel 200 response" + } + }, + "x-operation-group": "knn.train_model", + "x-version-added": "1.0" + } + }, + "/_plugins/_knn/models/{model_id}": { + "delete": { + "description": "Used to delete a particular model in the cluster.", + "externalDocs": { + "description": "API Reference", + "url": "https://opensearch.org/docs/latest/search-plugins/knn/api/#delete-model" + }, + "operationId": "KNNDeleteModel", + "parameters": [ + { + "name": "model_id", + "in": "path", + "description": "The id of the model.", + "schema": { + "type": "string", + "pattern": "^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$", + "description": "The id of the model." + }, + "required": true + } + ], + "responses": { + "200": { + "description": "KNNDeleteModel 200 response" + } + }, + "x-operation-group": "knn.delete_model", + "x-version-added": "1.0" + }, + "get": { + "description": "Used to retrieve information about models present in the cluster.", + "externalDocs": { + "description": "API Reference", + "url": "https://opensearch.org/docs/latest/search-plugins/knn/api/#get-model" + }, + "operationId": "KNNGetModel", + "parameters": [ + { + "name": "model_id", + "in": "path", + "description": "The id of the model.", + "schema": { + "type": "string", + "pattern": "^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$", + "description": "The id of the model." + }, + "required": true + } + ], + "responses": { + "200": { + "description": "KNNGetModel 200 response" + } + }, + "x-operation-group": "knn.get_model", + "x-version-added": "1.0" + } + }, + "/_plugins/_knn/models/{model_id}/_train": { + "post": { + "description": "Create and train a model that can be used for initializing k-NN native library indexes during indexing.", + "operationId": "KNNTrainModel_WithModelId", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KNNTrainModel_BodyParams" + } + } + }, + "required": true + }, + "parameters": [ + { + "name": "model_id", + "in": "path", + "description": "The id of the model.", "schema": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Comma-separated list of search groups for `search` index metric." + "type": "string", + "pattern": "^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$", + "description": "The id of the model." }, - "explode": true + "required": true }, { - "name": "level", + "name": "preference", "in": "query", - "description": "Return indices stats aggregated at index, node or shard level.", + "description": "Preferred node to execute training.", "schema": { - "$ref": "#/components/schemas/NodesStatLevel" + "type": "string", + "description": "Preferred node to execute training." } - }, - { - "name": "types", - "in": "query", - "description": "Comma-separated list of document types for the `indexing` index metric.", - "style": "form", - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Comma-separated list of document types for the `indexing` index metric." - }, - "explode": true - }, + } + ], + "responses": { + "200": { + "description": "KNNTrainModel_WithModelId 200 response" + } + }, + "x-operation-group": "knn.train_model", + "x-version-added": "1.0" + } + }, + "/_plugins/_knn/stats": { + "get": { + "description": "Provides information about the current status of the k-NN plugin.", + "externalDocs": { + "description": "API Reference", + "url": "https://opensearch.org/docs/latest/search-plugins/knn/api/#stats" + }, + "operationId": "KNNStats", + "parameters": [ { "name": "timeout", "in": "query", @@ -11572,40 +13089,60 @@ "description": "Operation timeout.", "x-data-type": "time" } - }, - { - "name": "include_segment_file_sizes", - "in": "query", - "description": "Whether to report the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).", - "schema": { - "type": "boolean", - "default": false, - "description": "Whether to report the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested)." - } } ], "responses": { "200": { - "description": "NodesStats_WithIndexMetricMetricNodeId 200 response" + "description": "KNNStats 200 response" } }, - "x-operation-group": "nodes.stats", + "x-operation-group": "knn.stats", "x-version-added": "1.0" } }, - "/_nodes/{node_id}/usage": { + "/_plugins/_knn/stats/{stat}": { "get": { - "description": "Returns low-level information about REST actions usage on nodes.", - "operationId": "NodesUsage_WithNodeId", + "description": "Provides information about the current status of the k-NN plugin.", + "operationId": "KNNStats_WithStat", "parameters": [ { - "name": "node_id", + "name": "stat", "in": "path", - "description": "Comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes.", + "description": "Comma-separated list of stats to retrieve; use `_all` or empty string to retrieve all stats.", "schema": { "type": "string", "pattern": "^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$", - "description": "Comma-separated list of node IDs or names to limit the returned information; use `_local` to return information from the node you're connecting to, leave empty to get information from all nodes.", + "description": "Comma-separated list of stats to retrieve; use `_all` or empty string to retrieve all stats.", + "x-enum-options": [ + "circuit_breaker_triggered", + "total_load_time", + "eviction_count", + "hit_count", + "miss_count", + "graph_memory_usage", + "graph_memory_usage_percentage", + "graph_index_requests", + "graph_index_errors", + "graph_query_requests", + "graph_query_errors", + "knn_query_requests", + "cache_capacity_reached", + "load_success_count", + "load_exception_count", + "indices_in_cache", + "script_compilations", + "script_compilation_errors", + "script_query_requests", + "script_query_errors", + "nmslib_initialized", + "faiss_initialized", + "model_index_status", + "indexing_from_model_degraded", + "training_requests", + "training_errors", + "training_memory_usage", + "training_memory_usage_percentage" + ], "x-data-type": "array" }, "required": true @@ -11624,34 +13161,49 @@ ], "responses": { "200": { - "description": "NodesUsage_WithNodeId 200 response" + "description": "KNNStats_WithStat 200 response" } }, - "x-operation-group": "nodes.usage", + "x-operation-group": "knn.stats", "x-version-added": "1.0" } }, - "/_nodes/{node_id}/usage/{metric}": { + "/_plugins/_knn/warmup/{index}": { "get": { - "description": "Returns low-level information about REST actions usage on nodes.", - "operationId": "NodesUsage_WithMetricNodeId", + "description": "Preloads native library files into memory, reducing initial search latency for specified indexes", + "externalDocs": { + "description": "API Reference", + "url": "https://opensearch.org/docs/latest/search-plugins/knn/api/#warmup-operation" + }, + "operationId": "KNNWarmup", "parameters": [ { - "name": "metric", + "name": "index", "in": "path", - "description": "Limit the information returned to the specified metrics.", + "description": "Comma-separated list of indices; use `_all` or empty string to perform the operation on all indices.", "schema": { "type": "string", "pattern": "^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$", - "description": "Limit the information returned to the specified metrics.", - "x-enum-options": [ - "_all", - "rest_actions" - ], + "description": "Comma-separated list of indices; use `_all` or empty string to perform the operation on all indices.", "x-data-type": "array" }, "required": true - }, + } + ], + "responses": { + "200": { + "description": "KNNWarmup 200 response" + } + }, + "x-operation-group": "knn.warmup", + "x-version-added": "1.0" + } + }, + "/_plugins/_knn/{node_id}/stats": { + "get": { + "description": "Provides information about the current status of the k-NN plugin.", + "operationId": "KNNStats_WithNodeId", + "parameters": [ { "name": "node_id", "in": "path", @@ -11678,17 +13230,17 @@ ], "responses": { "200": { - "description": "NodesUsage_WithMetricNodeId 200 response" + "description": "KNNStats_WithNodeId 200 response" } }, - "x-operation-group": "nodes.usage", + "x-operation-group": "knn.stats", "x-version-added": "1.0" } }, - "/_nodes/{node_id}/{metric}": { + "/_plugins/_knn/{node_id}/stats/{stat}": { "get": { - "description": "Returns information about nodes in the cluster.", - "operationId": "NodesInfo_WithMetricNodeId", + "description": "Provides information about the current status of the k-NN plugin.", + "operationId": "KNNStats_WithStatNodeId", "parameters": [ { "name": "node_id", @@ -11703,38 +13255,47 @@ "required": true }, { - "name": "metric", + "name": "stat", "in": "path", - "description": "Comma-separated list of metrics you wish returned. Leave empty to return all.", + "description": "Comma-separated list of stats to retrieve; use `_all` or empty string to retrieve all stats.", "schema": { "type": "string", "pattern": "^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$", - "description": "Comma-separated list of metrics you wish returned. Leave empty to return all.", + "description": "Comma-separated list of stats to retrieve; use `_all` or empty string to retrieve all stats.", "x-enum-options": [ - "settings", - "os", - "process", - "jvm", - "thread_pool", - "transport", - "http", - "plugins", - "ingest" + "circuit_breaker_triggered", + "total_load_time", + "eviction_count", + "hit_count", + "miss_count", + "graph_memory_usage", + "graph_memory_usage_percentage", + "graph_index_requests", + "graph_index_errors", + "graph_query_requests", + "graph_query_errors", + "knn_query_requests", + "cache_capacity_reached", + "load_success_count", + "load_exception_count", + "indices_in_cache", + "script_compilations", + "script_compilation_errors", + "script_query_requests", + "script_query_errors", + "nmslib_initialized", + "faiss_initialized", + "model_index_status", + "indexing_from_model_degraded", + "training_requests", + "training_errors", + "training_memory_usage", + "training_memory_usage_percentage" ], "x-data-type": "array" }, "required": true }, - { - "name": "flat_settings", - "in": "query", - "description": "Return settings in flat format.", - "schema": { - "type": "boolean", - "default": false, - "description": "Return settings in flat format." - } - }, { "name": "timeout", "in": "query", @@ -11749,10 +13310,10 @@ ], "responses": { "200": { - "description": "NodesInfo_WithMetricNodeId 200 response" + "description": "KNNStats_WithStatNodeId 200 response" } }, - "x-operation-group": "nodes.info", + "x-operation-group": "knn.stats", "x-version-added": "1.0" } }, @@ -11813,6 +13374,28 @@ } }, "/_plugins/_security/api/actiongroups": { + "get": { + "description": "Retrieves all action groups.", + "externalDocs": { + "description": "API Reference", + "url": "https://opensearch.org/docs/latest/security/access-control/api/#get-action-groups" + }, + "operationId": "GetActionGroups", + "responses": { + "200": { + "description": "GetActionGroups 200 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ActionGroupsMap" + } + } + } + } + }, + "x-operation-group": "security.get_action_groups", + "x-version-added": "1.0" + }, "patch": { "description": "Creates, updates, or deletes multiple action groups in a single call.", "externalDocs": { @@ -11846,30 +13429,6 @@ "x-version-added": "1.0" } }, - "/_plugins/_security/api/actiongroups/": { - "get": { - "description": "Retrieves all action groups.", - "externalDocs": { - "description": "API Reference", - "url": "https://opensearch.org/docs/latest/security/access-control/api/#get-action-groups" - }, - "operationId": "GetActionGroups", - "responses": { - "200": { - "description": "GetActionGroups 200 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ActionGroupsMap" - } - } - } - } - }, - "x-operation-group": "security.get_action_groups", - "x-version-added": "1.0" - } - }, "/_plugins/_security/api/actiongroups/{action_group}": { "delete": { "description": "Delete a specified action group.", @@ -14875,6 +16434,25 @@ "default": false, "description": "Indicates whether hits.total should be rendered as an integer or an object in the rest search response." } + }, + { + "name": "search_pipeline", + "in": "query", + "description": "Customizable sequence of processing stages applied to search queries.", + "schema": { + "type": "string", + "description": "Customizable sequence of processing stages applied to search queries." + } + }, + { + "name": "include_named_queries_score", + "in": "query", + "description": "Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false)", + "schema": { + "type": "boolean", + "default": false, + "description": "Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false)" + } } ], "responses": { @@ -15359,6 +16937,25 @@ "default": false, "description": "Indicates whether hits.total should be rendered as an integer or an object in the rest search response." } + }, + { + "name": "search_pipeline", + "in": "query", + "description": "Customizable sequence of processing stages applied to search queries.", + "schema": { + "type": "string", + "description": "Customizable sequence of processing stages applied to search queries." + } + }, + { + "name": "include_named_queries_score", + "in": "query", + "description": "Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false)", + "schema": { + "type": "boolean", + "default": false, + "description": "Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false)" + } } ], "responses": { @@ -21175,6 +22772,27 @@ "type": "string", "description": "Set the number of active shards to wait for on the cloned index before the operation returns." } + }, + { + "name": "wait_for_completion", + "in": "query", + "description": "Should this request wait until the operation has completed before returning.", + "schema": { + "type": "boolean", + "default": true, + "description": "Should this request wait until the operation has completed before returning." + } + }, + { + "name": "task_execution_timeout", + "in": "query", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "x-data-type": "time" + } } ], "responses": { @@ -21269,6 +22887,27 @@ "type": "string", "description": "Set the number of active shards to wait for on the cloned index before the operation returns." } + }, + { + "name": "wait_for_completion", + "in": "query", + "description": "Should this request wait until the operation has completed before returning.", + "schema": { + "type": "boolean", + "default": true, + "description": "Should this request wait until the operation has completed before returning." + } + }, + { + "name": "task_execution_timeout", + "in": "query", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "x-data-type": "time" + } } ], "responses": { @@ -23875,13 +25514,23 @@ "required": true }, { - "name": "flush", + "name": "flush", + "in": "query", + "description": "Specify whether the index should be flushed after performing the operation.", + "schema": { + "type": "boolean", + "default": true, + "description": "Specify whether the index should be flushed after performing the operation." + } + }, + { + "name": "primary_only", "in": "query", - "description": "Specify whether the index should be flushed after performing the operation.", + "description": "Specify whether the operation should only perform on primary shards. Defaults to false.", "schema": { "type": "boolean", - "default": true, - "description": "Specify whether the index should be flushed after performing the operation." + "default": false, + "description": "Specify whether the operation should only perform on primary shards. Defaults to false." } }, { @@ -23928,6 +25577,16 @@ "type": "boolean", "description": "Specify whether the operation should only expunge deleted documents." } + }, + { + "name": "wait_for_completion", + "in": "query", + "description": "Should this request wait until the operation has completed before returning.", + "schema": { + "type": "boolean", + "default": true, + "description": "Should this request wait until the operation has completed before returning." + } } ], "responses": { @@ -25350,6 +27009,27 @@ "type": "string", "description": "Sets the number of active shards to wait for before the operation returns." } + }, + { + "name": "wait_for_completion", + "in": "query", + "description": "Should this request wait until the operation has completed before returning.", + "schema": { + "type": "boolean", + "default": true, + "description": "Should this request wait until the operation has completed before returning." + } + }, + { + "name": "task_execution_timeout", + "in": "query", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "x-data-type": "time" + } } ], "responses": { @@ -26092,6 +27772,25 @@ "default": false, "description": "Indicates whether hits.total should be rendered as an integer or an object in the rest search response." } + }, + { + "name": "search_pipeline", + "in": "query", + "description": "Customizable sequence of processing stages applied to search queries.", + "schema": { + "type": "string", + "description": "Customizable sequence of processing stages applied to search queries." + } + }, + { + "name": "include_named_queries_score", + "in": "query", + "description": "Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false)", + "schema": { + "type": "boolean", + "default": false, + "description": "Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false)" + } } ], "responses": { @@ -26595,6 +28294,25 @@ "default": false, "description": "Indicates whether hits.total should be rendered as an integer or an object in the rest search response." } + }, + { + "name": "search_pipeline", + "in": "query", + "description": "Customizable sequence of processing stages applied to search queries.", + "schema": { + "type": "string", + "description": "Customizable sequence of processing stages applied to search queries." + } + }, + { + "name": "include_named_queries_score", + "in": "query", + "description": "Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false)", + "schema": { + "type": "boolean", + "default": false, + "description": "Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false)" + } } ], "responses": { @@ -27789,6 +29507,27 @@ "type": "string", "description": "Set the number of active shards to wait for on the shrunken index before the operation returns." } + }, + { + "name": "wait_for_completion", + "in": "query", + "description": "Should this request wait until the operation has completed before returning.", + "schema": { + "type": "boolean", + "default": true, + "description": "Should this request wait until the operation has completed before returning." + } + }, + { + "name": "task_execution_timeout", + "in": "query", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "x-data-type": "time" + } } ], "responses": { @@ -27893,6 +29632,27 @@ "type": "string", "description": "Set the number of active shards to wait for on the shrunken index before the operation returns." } + }, + { + "name": "wait_for_completion", + "in": "query", + "description": "Should this request wait until the operation has completed before returning.", + "schema": { + "type": "boolean", + "default": true, + "description": "Should this request wait until the operation has completed before returning." + } + }, + { + "name": "task_execution_timeout", + "in": "query", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "x-data-type": "time" + } } ], "responses": { @@ -28283,6 +30043,27 @@ "type": "string", "description": "Set the number of active shards to wait for on the shrunken index before the operation returns." } + }, + { + "name": "wait_for_completion", + "in": "query", + "description": "Should this request wait until the operation has completed before returning.", + "schema": { + "type": "boolean", + "default": true, + "description": "Should this request wait until the operation has completed before returning." + } + }, + { + "name": "task_execution_timeout", + "in": "query", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "x-data-type": "time" + } } ], "responses": { @@ -28387,6 +30168,27 @@ "type": "string", "description": "Set the number of active shards to wait for on the shrunken index before the operation returns." } + }, + { + "name": "wait_for_completion", + "in": "query", + "description": "Should this request wait until the operation has completed before returning.", + "schema": { + "type": "boolean", + "default": true, + "description": "Should this request wait until the operation has completed before returning." + } + }, + { + "name": "task_execution_timeout", + "in": "query", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "schema": { + "type": "string", + "pattern": "^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$", + "description": "Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.", + "x-data-type": "time" + } } ], "responses": { @@ -30436,27 +32238,29 @@ "pb" ] }, - "CatAllPitSegmentsResponseContent": { - "type": "object", - "properties": { - "content": { - "$ref": "#/components/schemas/CatPitSegment" - } + "CatAllPitSegmentsOutputPayload": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CatPitSegmentsRecord" + } + }, + "CatPitSegmentsOutputPayload": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CatPitSegmentsRecord" } }, - "CatPitSegment": { + "CatPitSegmentsRecord": { "type": "object", "properties": { "index": { "type": "string" }, "shard": { - "type": "integer", - "format": "int32" + "type": "string" }, "prirep": { - "type": "boolean", - "description": "Set to true to return stats only for primary shards." + "type": "string" }, "ip": { "type": "string" @@ -30465,43 +32269,31 @@ "type": "string" }, "generation": { - "type": "integer", - "format": "int32" + "type": "string" }, - "docs_count": { - "type": "integer", - "format": "int32" + "docs.count": { + "type": "string" }, - "docs_deleted": { - "type": "integer", - "format": "int32" + "docs.deleted": { + "type": "string" }, "size": { "type": "string" }, - "size_memory": { - "type": "integer", - "format": "int32" + "size.memory": { + "type": "string" }, "committed": { - "type": "boolean" + "type": "string" }, "searchable": { - "type": "boolean" + "type": "string" }, "version": { "type": "string" }, "compound": { - "type": "boolean" - } - } - }, - "CatPitSegmentsResponseContent": { - "type": "object", - "properties": { - "content": { - "$ref": "#/components/schemas/CatPitSegment" + "type": "string" } } }, @@ -30519,6 +32311,98 @@ "pit_id" ] }, + "CatSegmentReplicationOutputPayload": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CatSegmentReplicationRecord" + } + }, + "CatSegmentReplicationRecord": { + "type": "object", + "properties": { + "shardId": { + "type": "string" + }, + "target_node": { + "type": "string" + }, + "target_host": { + "type": "string" + }, + "checkpoints_behind": { + "type": "string" + }, + "bytes_behind": { + "type": "string" + }, + "current_lag": { + "type": "string" + }, + "last_completed_lag": { + "type": "string" + }, + "rejected_requests": { + "type": "string" + }, + "stage": { + "type": "string" + }, + "time": { + "type": "string" + }, + "files_fetched": { + "type": "string" + }, + "files_percent": { + "type": "string" + }, + "bytes_fetched": { + "type": "string" + }, + "bytes_percent": { + "type": "string" + }, + "start_time": { + "type": "string" + }, + "stop_time": { + "type": "string" + }, + "files": { + "type": "string" + }, + "files_total": { + "type": "string" + }, + "bytes": { + "type": "string" + }, + "bytes_total": { + "type": "string" + }, + "replicating_stage_time_taken": { + "type": "string" + }, + "get_checkpoint_info_stage_time_taken": { + "type": "string" + }, + "file_diff_stage_time_taken": { + "type": "string" + }, + "get_files_stage_time_taken": { + "type": "string" + }, + "finalize_replication_stage_time_taken": { + "type": "string" + } + } + }, + "CatSegmentReplication_WithIndexOutputPayload": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CatSegmentReplicationRecord" + } + }, "CertificatesDetail": { "type": "object", "properties": { @@ -31481,6 +33365,44 @@ "type": "object", "description": "The simulate definition" }, + "KNNSearchModels_BodyParams": { + "type": "object" + }, + "KNNTrainModel_BodyParams": { + "type": "object", + "properties": { + "training_index": { + "type": "string" + }, + "training_field": { + "type": "string" + }, + "dimension": { + "type": "integer", + "format": "int32" + }, + "max_training_vector_count": { + "type": "integer", + "format": "int32" + }, + "search_size": { + "type": "integer", + "format": "int32" + }, + "description": { + "type": "string" + }, + "method": { + "type": "string" + } + }, + "required": [ + "dimension", + "method", + "training_field", + "training_index" + ] + }, "Mget_BodyParams": { "type": "object", "description": "Document identifiers; can be either `docs` (containing full document information) or `ids` (when index is provided in the URL." diff --git a/coverage/Dockerfile b/coverage/Dockerfile new file mode 100644 index 000000000..3f34b3b3b --- /dev/null +++ b/coverage/Dockerfile @@ -0,0 +1,7 @@ +ARG OPENSEARCH_VERSION=2.12.0 +FROM opensearchproject/opensearch:${OPENSEARCH_VERSION} +ARG OPENSEARCH_VERSION +RUN /usr/share/opensearch/bin/opensearch-plugin \ + install \ + --batch \ + https://github.com/dblock/opensearch-api/releases/download/v${OPENSEARCH_VERSION}/opensearch-api-${OPENSEARCH_VERSION}.0.zip diff --git a/coverage/README.md b/coverage/README.md new file mode 100644 index 000000000..f88aca974 --- /dev/null +++ b/coverage/README.md @@ -0,0 +1,7 @@ +### API Coverage + +Uses the [opensearch-api plugin](https://github.com/dblock/opensearch-api), and [openapi-diff](https://github.com/OpenAPITools/openapi-diff) to show the difference between OpenSearch APIs, and the [OpenAPI spec checked into this repo](../OpenSearch.openapi.json). + +API coverage is run on all pull requests via the [coverage workflow](../.github/workflows/coverage.yml). + + diff --git a/model/_global/search/structures.smithy b/model/_global/search/structures.smithy index 4954a3e54..510099646 100644 --- a/model/_global/search/structures.smithy +++ b/model/_global/search/structures.smithy @@ -149,6 +149,13 @@ structure Search_QueryParams { @httpQuery("rest_total_hits_as_int") @default(false) rest_total_hits_as_int: RestTotalHitsAsInt, + + @httpQuery("search_pipeline") + search_pipeline: SearchPipeline, + + @httpQuery("include_named_queries_score") + @default(false) + include_named_queries_score: IncludeNamedQueriesScore } @documentation("The search definition using the Query DSL") diff --git a/model/cat/cluster_manager/operations.smithy b/model/cat/cluster_manager/operations.smithy index 5bbf84f3c..c7fc80d83 100644 --- a/model/cat/cluster_manager/operations.smithy +++ b/model/cat/cluster_manager/operations.smithy @@ -12,7 +12,7 @@ namespace OpenSearch ) @xOperationGroup("cat.cluster_manager") -@xVersionAdded("1.0") +@xVersionAdded("2.0") @readonly @suppress(["HttpUriConflict"]) @http(method: "GET", uri: "/_cat/cluster_manager") diff --git a/model/cat/common_params.smithy b/model/cat/common_params.smithy new file mode 100644 index 000000000..49ada2e16 --- /dev/null +++ b/model/cat/common_params.smithy @@ -0,0 +1,28 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@mixin +structure CommonCatQueryParams { + @httpQuery("format") + format: Format, + + @httpQuery("h") + h: H, + + @httpQuery("help") + @default(false) + help: Help, + + @httpQuery("s") + s: S, + + @httpQuery("v") + @default(false) + v: V, +} diff --git a/model/cat/master/operations.smithy b/model/cat/master/operations.smithy index c1bca28bf..e2b61b1c2 100644 --- a/model/cat/master/operations.smithy +++ b/model/cat/master/operations.smithy @@ -15,7 +15,7 @@ namespace OpenSearch @xOperationGroup("cat.master") @xVersionAdded("1.0") @xDeprecationMessage("To promote inclusive language, please use '/_cat/cluster_manager' instead.") -@xVersionDeprecated("1.0") +@xVersionDeprecated("2.0") @readonly @suppress(["HttpUriConflict"]) @http(method: "GET", uri: "/_cat/master") diff --git a/model/cat/pit_segment.smithy b/model/cat/pit_segment.smithy deleted file mode 100644 index 8455974ac..000000000 --- a/model/cat/pit_segment.smithy +++ /dev/null @@ -1,25 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 -// -// The OpenSearch Contributors require contributions made to -// this file be licensed under the Apache-2.0 license or a -// compatible open source license. - -$version: "2" -namespace OpenSearch - -structure CatPitSegment { - index: Index, - shard: Integer, - prirep: Pri, - ip: String, - segment: String , - generation: Integer, - docs_count: Integer, - docs_deleted: Integer, - size: String, - size_memory: Size, - committed: Boolean, - searchable: Boolean, - version: String, - compound: Boolean, -} diff --git a/model/cat/pit_segments/operations.smithy b/model/cat/pit_segments/operations.smithy index d44f219cf..3e5bbd2b5 100644 --- a/model/cat/pit_segments/operations.smithy +++ b/model/cat/pit_segments/operations.smithy @@ -10,7 +10,6 @@ namespace OpenSearch @externalDocumentation( "API Reference": "https://opensearch.org/docs/latest/search-plugins/point-in-time-api/" ) - @xOperationGroup("cat.pit_segments") @xVersionAdded("2.4") @readonly @@ -21,3 +20,17 @@ operation CatPitSegments { input: CatPitSegments_Input, output: CatPitSegments_Output } + +@externalDocumentation( + "API Reference": "https://opensearch.org/docs/latest/search-plugins/point-in-time-api/" +) +@xOperationGroup("cat.all_pit_segments") +@xVersionAdded("2.4") +@readonly +@suppress(["HttpUriConflict"]) +@http(method: "GET", uri: "/_cat/pit_segments/_all") +@documentation("Lists all active point-in-time segments.") +operation CatAllPitSegments { + input: CatAllPitSegments_Input, + output: CatAllPitSegments_Output +} diff --git a/model/cat/pit_segments/structures.smithy b/model/cat/pit_segments/structures.smithy index 953195e67..ff25f460c 100644 --- a/model/cat/pit_segments/structures.smithy +++ b/model/cat/pit_segments/structures.smithy @@ -7,6 +7,12 @@ $version: "2" namespace OpenSearch +@mixin +structure CatPitSegments_QueryParams with [CommonCatQueryParams] { + @httpQuery("bytes") + bytes: Bytes +} + structure CatPitSegments_BodyParams { @required pit_id: PitIds @@ -17,12 +23,47 @@ list PitIds{ } @input -structure CatPitSegments_Input{ +structure CatPitSegments_Input with [CatPitSegments_QueryParams] { @httpPayload - pit_id: CatPitSegments_BodyParams + content: CatPitSegments_BodyParams +} + +@input +structure CatAllPitSegments_Input with [CatPitSegments_QueryParams] { } @output structure CatPitSegments_Output { - content: CatPitSegment + @httpPayload + content: CatPitSegmentsRecords +} + +@output +structure CatAllPitSegments_Output { + @httpPayload + content: CatPitSegmentsRecords +} + +list CatPitSegmentsRecords { + member: CatPitSegmentsRecord +} + +structure CatPitSegmentsRecord { + index: String, + shard: String, + prirep: String, + ip: String, + segment: String, + generation: String, + @jsonName("docs.count") + docs_count: String, + @jsonName("docs.deleted") + docs_deleted: String, + size: String, + @jsonName("size.memory") + size_memory: String, + committed: String, + searchable: String, + version: String, + compound: String, } diff --git a/model/cat/segment_replication/operations.smithy b/model/cat/segment_replication/operations.smithy index 853fd69b2..f003c8a13 100644 --- a/model/cat/segment_replication/operations.smithy +++ b/model/cat/segment_replication/operations.smithy @@ -12,7 +12,7 @@ namespace OpenSearch ) @xOperationGroup("cat.segment_replication") -@xVersionAdded("1.0") +@xVersionAdded("2.6.0") @readonly @suppress(["HttpUriConflict"]) @http(method: "GET", uri: "/_cat/segment_replication") @@ -23,7 +23,7 @@ operation CatSegmentReplication { } @xOperationGroup("cat.segment_replication") -@xVersionAdded("1.0") +@xVersionAdded("2.6.0") @readonly @suppress(["HttpUriConflict"]) @http(method: "GET", uri: "/_cat/segment_replication/{index}") diff --git a/model/cat/segment_replication/structures.smithy b/model/cat/segment_replication/structures.smithy index 06aba99a4..0fc33c6be 100644 --- a/model/cat/segment_replication/structures.smithy +++ b/model/cat/segment_replication/structures.smithy @@ -8,10 +8,10 @@ $version: "2" namespace OpenSearch @mixin -structure CatSegmentReplication_QueryParams { - @httpQuery("format") - format: Format, - +structure CatSegmentReplication_QueryParams with [ + CommonCatQueryParams, + IndicesOptionsQueryParams, +] { @httpQuery("active_only") @documentation("If `true`, the response only includes ongoing segment replication events.") @default(false) @@ -32,26 +32,15 @@ structure CatSegmentReplication_QueryParams { @httpQuery("shards") shards: Shards, - @httpQuery("h") - h: H, - - @httpQuery("help") - @default(false) - help: Help, - @httpQuery("index") @documentation("Comma-separated list or wildcard expression of index names to limit the returned information.") query_index: Indices, - @httpQuery("s") - s: S, - @httpQuery("time") time: Time, - @httpQuery("v") - @default(false) - v: V, + @httpQuery("timeout") + timeout: Timeout, } @@ -67,5 +56,40 @@ structure CatSegmentReplication_WithIndex_Input with [CatSegmentReplication_Quer index: PathIndices, } -// TODO: Fill in Output Structure -structure CatSegmentReplication_Output {} +structure CatSegmentReplication_Output { + @httpPayload + content: CatSegmentReplicationRecords +} + +list CatSegmentReplicationRecords { + member: CatSegmentReplicationRecord +} + +structure CatSegmentReplicationRecord { + shardId: String, + target_node: String, + target_host: String, + checkpoints_behind: String, + bytes_behind: String, + current_lag: String, + last_completed_lag: String, + rejected_requests: String, + + stage: String, + time: String, + files_fetched: String, + files_percent: String, + bytes_fetched: String, + bytes_percent: String, + start_time: String, + stop_time: String, + files: String, + files_total: String, + bytes: String, + bytes_total: String, + replicating_stage_time_taken: String, + get_checkpoint_info_stage_time_taken: String, + file_diff_stage_time_taken: String, + get_files_stage_time_taken: String, + finalize_replication_stage_time_taken: String, +} diff --git a/model/cluster/delete_decommission_awareness/operations.smithy b/model/cluster/delete_decommission_awareness/operations.smithy index e3d0364ba..78caee215 100644 --- a/model/cluster/delete_decommission_awareness/operations.smithy +++ b/model/cluster/delete_decommission_awareness/operations.smithy @@ -15,7 +15,7 @@ namespace OpenSearch @xVersionAdded("1.0") @idempotent @suppress(["HttpUriConflict"]) -@http(method: "DELETE", uri: "/_cluster/decommission/awareness/") +@http(method: "DELETE", uri: "/_cluster/decommission/awareness") @documentation("Delete any existing decommission.") operation ClusterDeleteDecommissionAwareness { input: ClusterDeleteDecommissionAwareness_Input, diff --git a/model/common_booleans.smithy b/model/common_booleans.smithy index e3dc25fde..8221b08c1 100644 --- a/model/common_booleans.smithy +++ b/model/common_booleans.smithy @@ -89,6 +89,9 @@ boolean IncludeDefaults @documentation("Return information about disk usage and shard sizes.") boolean IncludeDiskInfo +@documentation("Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false)") +boolean IncludeNamedQueriesScore + @documentation("Whether to report the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).") boolean IncludeSegmentFileSizes @@ -131,6 +134,9 @@ boolean PreserveExisting @documentation("Set to true to return stats only for primary shards.") boolean Pri +@documentation("Specify whether the operation should only perform on primary shards. Defaults to false.") +boolean PrimaryOnly + @documentation("Specify whether to profile the query execution.") boolean Profile diff --git a/model/common_strings.smithy b/model/common_strings.smithy index 361f29b59..4850744a5 100644 --- a/model/common_strings.smithy +++ b/model/common_strings.smithy @@ -104,7 +104,7 @@ string PathNodeId string PathNodesInfoMetric @xDataType("array") -@xEnumOptions(["_all", "breaker", "fs", "http", "indices", "jvm", "os", "process", "thread_pool", "transport", "discovery", "indexing_pressure"]) +@xEnumOptions(["_all", "breaker", "fs", "http", "indices", "jvm", "os", "process", "thread_pool", "transport", "discovery", "indexing_pressure", "search_pipeline"]) @pattern("^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$") @documentation("Limit the information returned to the specified metrics.") string PathNodesStatsMetric @@ -247,6 +247,16 @@ string PathTaskId @documentation("The name of the template.") string PathTemplateName +@xDataType("array") +@xEnumOptions(["circuit_breaker_triggered", "total_load_time", "eviction_count", "hit_count", "miss_count", "graph_memory_usage", "graph_memory_usage_percentage", "graph_index_requests", "graph_index_errors", "graph_query_requests", "graph_query_errors", "knn_query_requests", "cache_capacity_reached", "load_success_count", "load_exception_count", "indices_in_cache", "script_compilations", "script_compilation_errors", "script_query_requests", "script_query_errors", "nmslib_initialized", "faiss_initialized", "model_index_status", "indexing_from_model_degraded", "training_requests", "training_errors", "training_memory_usage", "training_memory_usage_percentage"]) +@pattern("^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$") +@documentation("Comma-separated list of stats to retrieve; use `_all` or empty string to retrieve all stats.") +string PathStats + +@pattern("^(?!_|template|query|field|point|clear|usage|stats|hot|reload|painless).+$") +@documentation("The id of the model.") +string PathModelId + @documentation("The analyzer to use for the query string.") string Analyzer @@ -281,6 +291,9 @@ string Lang @documentation("Comma-separated list of the persistent ids of the nodes to exclude from the voting configuration. If specified, you may not also specify ?node_names.") string NodeIds +@documentation("Preferred node to execute training.") +string NodeId + @documentation("Comma-separated list of the names of the nodes to exclude from the voting configuration. If specified, you may not also specify ?node_ids.") string NodeNames @@ -289,6 +302,9 @@ string ParentTaskId @documentation("The pipeline id to preprocess incoming documents with.") string Pipeline +@documentation("Customizable sequence of processing stages applied to search queries.") +string SearchPipeline + @documentation("Specify the node or shard the operation should be performed on.") string Preference @@ -358,3 +374,8 @@ string Timeout @pattern("^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$") @documentation("The maximum time to wait for wait_for_metadata_version before timing out.") string WaitForTimeout + +@xDataType("time") +@pattern("^([0-9]+)(?:d|h|m|s|ms|micros|nanos)$") +@documentation("Explicit task execution timeout, only useful when wait_for_completion is false, defaults to 1h.") +string TaskExecutionTimeout diff --git a/model/indices/clone/structures.smithy b/model/indices/clone/structures.smithy index b538f6fe8..b84cb4b0c 100644 --- a/model/indices/clone/structures.smithy +++ b/model/indices/clone/structures.smithy @@ -21,6 +21,13 @@ structure IndicesClone_QueryParams { @httpQuery("wait_for_active_shards") @documentation("Set the number of active shards to wait for on the cloned index before the operation returns.") wait_for_active_shards: WaitForActiveShards, + + @httpQuery("wait_for_completion") + @default(true) + wait_for_completion: WaitForCompletionTrue, + + @httpQuery("task_execution_timeout") + task_execution_timeout: TaskExecutionTimeout, } // TODO: Fill in Body Parameters diff --git a/model/indices/forcemerge/structures.smithy b/model/indices/forcemerge/structures.smithy index 8f291ef79..81b47f468 100644 --- a/model/indices/forcemerge/structures.smithy +++ b/model/indices/forcemerge/structures.smithy @@ -13,6 +13,10 @@ structure IndicesForcemerge_QueryParams { @default(true) flush: Flush, + @httpQuery("primary_only") + @default(false) + primary_only: PrimaryOnly, + @httpQuery("ignore_unavailable") ignore_unavailable: IgnoreUnavailable, @@ -28,6 +32,10 @@ structure IndicesForcemerge_QueryParams { @httpQuery("only_expunge_deletes") only_expunge_deletes: OnlyExpungeDeletes, + + @httpQuery("wait_for_completion") + @default(true) + wait_for_completion: WaitForCompletionTrue, } diff --git a/model/indices/indices_options.smithy b/model/indices/indices_options.smithy new file mode 100644 index 000000000..b595c2e49 --- /dev/null +++ b/model/indices/indices_options.smithy @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@mixin +structure IndicesOptionsQueryParams { + @httpQuery("allow_no_indices") + allow_no_indices: AllowNoIndices, + + @httpQuery("expand_wildcards") + expand_wildcards: ExpandWildcards, + + @httpQuery("ignore_throttled") + ignore_throttled: IgnoreThrottled, + + @httpQuery("ignore_unavailable") + ignore_unavailable: IgnoreUnavailable, +} diff --git a/model/indices/open/structures.smithy b/model/indices/open/structures.smithy index 5719ca606..f99cdf1ab 100644 --- a/model/indices/open/structures.smithy +++ b/model/indices/open/structures.smithy @@ -31,6 +31,13 @@ structure IndicesOpen_QueryParams { @httpQuery("wait_for_active_shards") @documentation("Sets the number of active shards to wait for before the operation returns.") wait_for_active_shards: WaitForActiveShards, + + @httpQuery("wait_for_completion") + @default(true) + wait_for_completion: WaitForCompletionTrue, + + @httpQuery("task_execution_timeout") + task_execution_timeout: TaskExecutionTimeout, } diff --git a/model/indices/shrink/structures.smithy b/model/indices/shrink/structures.smithy index 15b0b9248..5fdb7d997 100644 --- a/model/indices/shrink/structures.smithy +++ b/model/indices/shrink/structures.smithy @@ -25,6 +25,13 @@ structure IndicesShrink_QueryParams { @httpQuery("wait_for_active_shards") @documentation("Set the number of active shards to wait for on the shrunken index before the operation returns.") wait_for_active_shards: WaitForActiveShards, + + @httpQuery("wait_for_completion") + @default(true) + wait_for_completion: WaitForCompletionTrue, + + @httpQuery("task_execution_timeout") + task_execution_timeout: TaskExecutionTimeout, } // TODO: Fill in Body Parameters diff --git a/model/indices/split/structures.smithy b/model/indices/split/structures.smithy index 72ef2086c..c21d1c74d 100644 --- a/model/indices/split/structures.smithy +++ b/model/indices/split/structures.smithy @@ -25,6 +25,13 @@ structure IndicesSplit_QueryParams { @httpQuery("wait_for_active_shards") @documentation("Set the number of active shards to wait for on the shrunken index before the operation returns.") wait_for_active_shards: WaitForActiveShards, + + @httpQuery("wait_for_completion") + @default(true) + wait_for_completion: WaitForCompletionTrue, + + @httpQuery("task_execution_timeout") + task_execution_timeout: TaskExecutionTimeout, } // TODO: Fill in Body Parameters diff --git a/model/knn/delete_model/operations.smithy b/model/knn/delete_model/operations.smithy new file mode 100644 index 000000000..7bc4459f2 --- /dev/null +++ b/model/knn/delete_model/operations.smithy @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@externalDocumentation( + "API Reference": "https://opensearch.org/docs/latest/search-plugins/knn/api/#delete-model" +) + +@xOperationGroup("knn.delete_model") +@xVersionAdded("1.0") +@suppress(["HttpMethodSemantics.UnexpectedPayload"]) +@suppress(["HttpUriConflict"]) +@http(method: "DELETE", uri: "/_plugins/_knn/models/{model_id}") +@documentation("Used to delete a particular model in the cluster.") +operation KNNDeleteModel { + input: KNNDeleteModel_Input, + output: KNNDeleteModel_Output +} diff --git a/model/knn/delete_model/structures.smithy b/model/knn/delete_model/structures.smithy new file mode 100644 index 000000000..2f9fe30e0 --- /dev/null +++ b/model/knn/delete_model/structures.smithy @@ -0,0 +1,18 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@input +structure KNNDeleteModel_Input { + @required + @httpLabel + model_id: PathModelId, +} + +// TODO: Fill in Output Structure +structure KNNDeleteModel_Output {} diff --git a/model/cat/all_pit_segments/operations.smithy b/model/knn/get_model/operations.smithy similarity index 54% rename from model/cat/all_pit_segments/operations.smithy rename to model/knn/get_model/operations.smithy index 01969215e..557678686 100644 --- a/model/cat/all_pit_segments/operations.smithy +++ b/model/knn/get_model/operations.smithy @@ -8,16 +8,16 @@ $version: "2" namespace OpenSearch @externalDocumentation( - "API Reference": "https://opensearch.org/docs/latest/search-plugins/point-in-time-api/" + "API Reference": "https://opensearch.org/docs/latest/search-plugins/knn/api/#get-model" ) -@xOperationGroup("cat.all_pit_segments") -@xVersionAdded("2.4") +@xOperationGroup("knn.get_model") +@xVersionAdded("1.0") @readonly @suppress(["HttpUriConflict"]) -@http(method: "GET", uri: "/_cat/pit_segments/_all") -@documentation("Lists all active point-in-time segments.") -operation CatAllPitSegments { - input: CatAllPitSegments_Input, - output: CatAllPitSegments_Output +@http(method: "GET", uri: "/_plugins/_knn/models/{model_id}") +@documentation("Used to retrieve information about models present in the cluster.") +operation KNNGetModel { + input: KNNGetModel_Input, + output: KNNGetModel_Output } diff --git a/model/knn/get_model/structures.smithy b/model/knn/get_model/structures.smithy new file mode 100644 index 000000000..ad0bafd49 --- /dev/null +++ b/model/knn/get_model/structures.smithy @@ -0,0 +1,18 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@input +structure KNNGetModel_Input { + @required + @httpLabel + model_id: PathModelId, +} + +// TODO: Fill in Output Structure +structure KNNGetModel_Output {} diff --git a/model/knn/search_model/operations.smithy b/model/knn/search_model/operations.smithy new file mode 100644 index 000000000..a6becc931 --- /dev/null +++ b/model/knn/search_model/operations.smithy @@ -0,0 +1,33 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@externalDocumentation( + "API Reference": "https://opensearch.org/docs/latest/search-plugins/knn/api/#search-model" +) + +@xOperationGroup("knn.search_models") +@xVersionAdded("1.0") +@readonly +@suppress(["HttpUriConflict"]) +@http(method: "GET", uri: "/_plugins/_knn/models/_search") +@documentation("Use an OpenSearch query to search for models in the index.") +operation KNNSearchModels_Get { + input: KNNSearchModels_Get_Input, + output: KNNSearchModels_Output +} + +@xOperationGroup("knn.search_models") +@xVersionAdded("1.0") +@suppress(["HttpUriConflict"]) +@http(method: "POST", uri: "/_plugins/_knn/models/_search") +@documentation("Use an OpenSearch query to search for models in the index.") +operation KNNSearchModels_Post { + input: KNNSearchModels_Post_Input, + output: KNNSearchModels_Output +} diff --git a/model/knn/search_model/structures.smithy b/model/knn/search_model/structures.smithy new file mode 100644 index 000000000..c21a945f4 --- /dev/null +++ b/model/knn/search_model/structures.smithy @@ -0,0 +1,167 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@mixin +structure KNNSearchModels_QueryParams { + @httpQuery("analyzer") + analyzer: Analyzer, + + @httpQuery("analyze_wildcard") + @default(false) + analyze_wildcard: AnalyzeWildcard, + + @httpQuery("ccs_minimize_roundtrips") + @default(true) + ccs_minimize_roundtrips: CcsMinimizeRoundtrips, + + @httpQuery("default_operator") + @default("OR") + default_operator: DefaultOperator, + + @httpQuery("df") + df: Df, + + @httpQuery("explain") + @documentation("Specify whether to return detailed information about score computation as part of a hit.") + explain: Explain, + + @httpQuery("stored_fields") + stored_fields: StoredFields, + + @httpQuery("docvalue_fields") + docvalue_fields: DocvalueFields, + + @httpQuery("from") + @default(0) + from: From, + + @httpQuery("ignore_unavailable") + ignore_unavailable: IgnoreUnavailable, + + @httpQuery("ignore_throttled") + ignore_throttled: IgnoreThrottled, + + @httpQuery("allow_no_indices") + allow_no_indices: AllowNoIndices, + + @httpQuery("expand_wildcards") + @default("open") + expand_wildcards: ExpandWildcards, + + @httpQuery("lenient") + lenient: Lenient, + + @httpQuery("preference") + @default("random") + preference: Preference, + + @httpQuery("q") + q: Q, + + @httpQuery("routing") + routing: Routings, + + @httpQuery("scroll") + scroll: Scroll, + + @httpQuery("search_type") + search_type: SearchType, + + @httpQuery("size") + @documentation("Number of hits to return.") + @default(10) + size: Size, + + @httpQuery("sort") + sort: Sort, + + @httpQuery("_source") + _source: Source, + + @httpQuery("_source_excludes") + _source_excludes: SourceExcludes, + + @httpQuery("_source_includes") + _source_includes: SourceIncludes, + + @httpQuery("terminate_after") + terminate_after: TerminateAfter, + + @httpQuery("stats") + stats: Stats, + + @httpQuery("suggest_field") + suggest_field: SuggestField, + + @httpQuery("suggest_mode") + @default("missing") + suggest_mode: SuggestMode, + + @httpQuery("suggest_size") + suggest_size: SuggestSize, + + @httpQuery("suggest_text") + suggest_text: SuggestText, + + @httpQuery("timeout") + timeout: Timeout, + + @httpQuery("track_scores") + track_scores: TrackScores, + + @httpQuery("track_total_hits") + track_total_hits: TrackTotalHits, + + @httpQuery("allow_partial_search_results") + @default(true) + allow_partial_search_results: AllowPartialSearchResults, + + @httpQuery("typed_keys") + typed_keys: TypedKeys, + + @httpQuery("version") + version: WithVersion, + + @httpQuery("seq_no_primary_term") + seq_no_primary_term: SeqNoPrimaryTerm, + + @httpQuery("request_cache") + request_cache: RequestCache, + + @httpQuery("batched_reduce_size") + @default(512) + batched_reduce_size: BatchedReduceSize, + + @httpQuery("max_concurrent_shard_requests") + @documentation("The number of concurrent shard requests per node this search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.") + @default(5) + max_concurrent_shard_requests: MaxConcurrentShardRequests, + + @httpQuery("pre_filter_shard_size") + pre_filter_shard_size: PreFilterShardSize, + + @httpQuery("rest_total_hits_as_int") + @default(false) + rest_total_hits_as_int: RestTotalHitsAsInt, +} + +// TODO: Fill in Body Parameters +structure KNNSearchModels_BodyParams {} + +@input +structure KNNSearchModels_Get_Input with [KNNSearchModels_QueryParams] {} + +@input +structure KNNSearchModels_Post_Input with [KNNSearchModels_QueryParams] { + @httpPayload + content: KNNSearchModels_BodyParams, +} + +// TODO: Fill in Output Structure +structure KNNSearchModels_Output {} diff --git a/model/knn/stats/operations.smithy b/model/knn/stats/operations.smithy new file mode 100644 index 000000000..dd4a3b985 --- /dev/null +++ b/model/knn/stats/operations.smithy @@ -0,0 +1,56 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@externalDocumentation( + "API Reference": "https://opensearch.org/docs/latest/search-plugins/knn/api/#stats" +) + +@xOperationGroup("knn.stats") +@xVersionAdded("1.0") +@readonly +@suppress(["HttpUriConflict"]) +@http(method: "GET", uri: "/_plugins/_knn/stats") +@documentation("Provides information about the current status of the k-NN plugin.") +operation KNNStats { + input: KNNStats_Input, + output: KNNStats_Output +} + +@xOperationGroup("knn.stats") +@xVersionAdded("1.0") +@readonly +@suppress(["HttpUriConflict"]) +@http(method: "GET", uri: "/_plugins/_knn/{node_id}/stats") +@documentation("Provides information about the current status of the k-NN plugin.") +operation KNNStats_WithNodeId { + input: KNNStats_WithNodeId_Input, + output: KNNStats_Output +} + +@xOperationGroup("knn.stats") +@xVersionAdded("1.0") +@readonly +@suppress(["HttpUriConflict"]) +@http(method: "GET", uri: "/_plugins/_knn/stats/{stat}") +@documentation("Provides information about the current status of the k-NN plugin.") +operation KNNStats_WithStat { + input: KNNStats_WithStat_Input, + output: KNNStats_Output +} + +@xOperationGroup("knn.stats") +@xVersionAdded("1.0") +@readonly +@suppress(["HttpUriConflict"]) +@http(method: "GET", uri: "/_plugins/_knn/{node_id}/stats/{stat}") +@documentation("Provides information about the current status of the k-NN plugin.") +operation KNNStats_WithStatNodeId { + input: KNNStats_WithStatNodeId_Input, + output: KNNStats_Output +} diff --git a/model/knn/stats/structures.smithy b/model/knn/stats/structures.smithy new file mode 100644 index 000000000..340e9f10c --- /dev/null +++ b/model/knn/stats/structures.smithy @@ -0,0 +1,46 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@mixin +structure KNNStats_QueryParams { + @httpQuery("timeout") + timeout: Timeout, +} + +@input +structure KNNStats_Input with [KNNStats_QueryParams] { +} + +@input +structure KNNStats_WithNodeId_Input with [KNNStats_QueryParams] { + @required + @httpLabel + node_id: PathNodeId, +} + +@input +structure KNNStats_WithStat_Input with [KNNStats_QueryParams] { + @required + @httpLabel + stat: PathStats, +} + +@input +structure KNNStats_WithStatNodeId_Input with [KNNStats_QueryParams] { + @required + @httpLabel + node_id: PathNodeId, + + @required + @httpLabel + stat: PathStats, +} + +// TODO: Fill in Output Structure +structure KNNStats_Output{} diff --git a/model/knn/train_model/operations.smithy b/model/knn/train_model/operations.smithy new file mode 100644 index 000000000..a65032765 --- /dev/null +++ b/model/knn/train_model/operations.smithy @@ -0,0 +1,32 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@externalDocumentation( + "API Reference": "https://opensearch.org/docs/latest/search-plugins/knn/api/#train-model" +) + +@xOperationGroup("knn.train_model") +@xVersionAdded("1.0") +@suppress(["HttpUriConflict"]) +@http(method: "POST", uri: "/_plugins/_knn/models/_train") +@documentation("Create and train a model that can be used for initializing k-NN native library indexes during indexing.") +operation KNNTrainModel { + input: KNNTrainModel_Input, + output: KNNTrainModel_Output +} + +@xOperationGroup("knn.train_model") +@xVersionAdded("1.0") +@suppress(["HttpUriConflict"]) +@http(method: "POST", uri: "/_plugins/_knn/models/{model_id}/_train") +@documentation("Create and train a model that can be used for initializing k-NN native library indexes during indexing.") +operation KNNTrainModel_WithModelId { + input: KNNTrainModel_WithModelId_Input, + output: KNNTrainModel_Output +} diff --git a/model/knn/train_model/structures.smithy b/model/knn/train_model/structures.smithy new file mode 100644 index 000000000..096667250 --- /dev/null +++ b/model/knn/train_model/structures.smithy @@ -0,0 +1,55 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@mixin +structure KNNTrainModel_QueryParams { + @httpQuery("preference") + preference: NodeId, +} + +structure KNNTrainModel_BodyParams { + @required + training_index: String, + + @required + training_field: String, + + @required + dimension: Integer, + + max_training_vector_count: Integer, + + search_size: Integer, + + description: String, + + @required + method: String, +} + +@input +structure KNNTrainModel_Input with [KNNTrainModel_QueryParams] { + @required + @httpPayload + content: KNNTrainModel_BodyParams, +} + +@input +structure KNNTrainModel_WithModelId_Input with [KNNTrainModel_QueryParams] { + @required + @httpPayload + content: KNNTrainModel_BodyParams, + + @required + @httpLabel + model_id: PathModelId, +} + +// TODO: Fill in Output Structure +structure KNNTrainModel_Output {} diff --git a/model/knn/warmup/operations.smithy b/model/knn/warmup/operations.smithy new file mode 100644 index 000000000..485c56bf0 --- /dev/null +++ b/model/knn/warmup/operations.smithy @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// The OpenSearch Contributors require contributions made to +// this file be licensed under the Apache-2.0 license or a +// compatible open source license. + +$version: "2" +namespace OpenSearch + +@externalDocumentation( + "API Reference": "https://opensearch.org/docs/latest/search-plugins/knn/api/#warmup-operation" +) + +@xOperationGroup("knn.warmup") +@xVersionAdded("1.0") +@readonly +@suppress(["HttpUriConflict"]) +@http(method: "GET", uri: "/_plugins/_knn/warmup/{index}") +@documentation("Preloads native library files into memory, reducing initial search latency for specified indexes") +operation KNNWarmup { + input: KNNWarmup_Input, + output: KNNWarmup_Output +} diff --git a/model/cat/all_pit_segments/structures.smithy b/model/knn/warmup/structures.smithy similarity index 63% rename from model/cat/all_pit_segments/structures.smithy rename to model/knn/warmup/structures.smithy index 3fb51cfe1..febefdbc8 100644 --- a/model/cat/all_pit_segments/structures.smithy +++ b/model/knn/warmup/structures.smithy @@ -8,10 +8,11 @@ $version: "2" namespace OpenSearch @input -structure CatAllPitSegments_Input { +structure KNNWarmup_Input { + @required + @httpLabel + index: PathIndices, } -@output -structure CatAllPitSegments_Output { - content: CatPitSegment -} +// TODO: Fill in Output Structure +structure KNNWarmup_Output{} diff --git a/model/opensearch.smithy b/model/opensearch.smithy index cfdd44fb3..94b08cdb3 100644 --- a/model/opensearch.smithy +++ b/model/opensearch.smithy @@ -256,6 +256,17 @@ service OpenSearch { IngestSimulate_Get_WithId, IngestSimulate_Post, IngestSimulate_Post_WithId, + KNNDeleteModel, + KNNGetModel, + KNNSearchModels_Get, + KNNSearchModels_Post, + KNNStats, + KNNStats_WithNodeId, + KNNStats_WithStat, + KNNStats_WithStatNodeId, + KNNTrainModel, + KNNTrainModel_WithModelId, + KNNWarmup, Mget_Get, Mget_Get_WithIndex, Mget_Post, diff --git a/model/security/get_action_groups/operations.smithy b/model/security/get_action_groups/operations.smithy index 69e063652..605eca625 100644 --- a/model/security/get_action_groups/operations.smithy +++ b/model/security/get_action_groups/operations.smithy @@ -15,7 +15,7 @@ namespace OpenSearch @xVersionAdded("1.0") @readonly @suppress(["HttpUriConflict"]) -@http(method: "GET", uri: "/_plugins/_security/api/actiongroups/") +@http(method: "GET", uri: "/_plugins/_security/api/actiongroups") @documentation("Retrieves all action groups.") operation GetActionGroups { input: GetActionGroups_Input, diff --git a/test/opensearch/Dockerfile b/test/opensearch/Dockerfile index 569375bfb..01c073740 100644 --- a/test/opensearch/Dockerfile +++ b/test/opensearch/Dockerfile @@ -1,7 +1,7 @@ -FROM opensearchproject/opensearch:latest +FROM opensearchproject/opensearch:2.11.1 USER root RUN mkdir -p /mnt/snapshots && chown -R opensearch:opensearch /mnt/snapshots USER opensearch -VOLUME /mnt/snapshots \ No newline at end of file +VOLUME /mnt/snapshots