diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 05864a8cdb..7583881a86 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -17001,7 +17001,7 @@ "search" ], "summary": "Run a knn search", - "description": "NOTE: The kNN search API has been replaced by the `knn` option in the search API.\n\nPerform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents.\nGiven a query vector, the API finds the k closest vectors and returns those documents as search hits.\n\nElasticsearch uses the HNSW algorithm to support efficient kNN search.\nLike most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed.\nThis means the results returned are not always the true k closest neighbors.\n\nThe kNN search API supports restricting the search using a filter.\nThe search will return the top k documents that also match the filter query.", + "description": "NOTE: The kNN search API has been replaced by the `knn` option in the search API.\n\nPerform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents.\nGiven a query vector, the API finds the k closest vectors and returns those documents as search hits.\n\nElasticsearch uses the HNSW algorithm to support efficient kNN search.\nLike most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed.\nThis means the results returned are not always the true k closest neighbors.\n\nThe kNN search API supports restricting the search using a filter.\nThe search will return the top k documents that also match the filter query.\n\nA kNN search response has the exact same structure as a search API response.\nHowever, certain sections have a meaning specific to kNN search:\n\n* The document `_score` is determined by the similarity between the query and document vector.\n* The `hits.total` object contains the total number of nearest neighbor candidates considered, which is `num_candidates * num_shards`. The `hits.total.relation` will always be `eq`, indicating an exact value.", "operationId": "knn-search", "parameters": [ { @@ -17027,7 +17027,7 @@ "search" ], "summary": "Run a knn search", - "description": "NOTE: The kNN search API has been replaced by the `knn` option in the search API.\n\nPerform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents.\nGiven a query vector, the API finds the k closest vectors and returns those documents as search hits.\n\nElasticsearch uses the HNSW algorithm to support efficient kNN search.\nLike most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed.\nThis means the results returned are not always the true k closest neighbors.\n\nThe kNN search API supports restricting the search using a filter.\nThe search will return the top k documents that also match the filter query.", + "description": "NOTE: The kNN search API has been replaced by the `knn` option in the search API.\n\nPerform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents.\nGiven a query vector, the API finds the k closest vectors and returns those documents as search hits.\n\nElasticsearch uses the HNSW algorithm to support efficient kNN search.\nLike most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed.\nThis means the results returned are not always the true k closest neighbors.\n\nThe kNN search API supports restricting the search using a filter.\nThe search will return the top k documents that also match the filter query.\n\nA kNN search response has the exact same structure as a search API response.\nHowever, certain sections have a meaning specific to kNN search:\n\n* The document `_score` is determined by the similarity between the query and document vector.\n* The `hits.total` object contains the total number of nearest neighbor candidates considered, which is `num_candidates * num_shards`. The `hits.total.relation` will always be `eq`, indicating an exact value.", "operationId": "knn-search-1", "parameters": [ { @@ -17482,7 +17482,7 @@ "document" ], "summary": "Get multiple documents", - "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.", + "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.\n\n**Filter source fields**\n\nBy default, the `_source` field is returned for every document (if stored).\nUse the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.\nYou can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.\n\n**Get stored fields**\n\nUse the `stored_fields` attribute to specify the set of stored fields you want to retrieve.\nAny requested fields that are not stored are ignored.\nYou can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.", "operationId": "mget", "parameters": [ { @@ -17528,7 +17528,7 @@ "document" ], "summary": "Get multiple documents", - "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.", + "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.\n\n**Filter source fields**\n\nBy default, the `_source` field is returned for every document (if stored).\nUse the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.\nYou can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.\n\n**Get stored fields**\n\nUse the `stored_fields` attribute to specify the set of stored fields you want to retrieve.\nAny requested fields that are not stored are ignored.\nYou can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.", "operationId": "mget-1", "parameters": [ { @@ -17576,7 +17576,7 @@ "document" ], "summary": "Get multiple documents", - "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.", + "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.\n\n**Filter source fields**\n\nBy default, the `_source` field is returned for every document (if stored).\nUse the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.\nYou can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.\n\n**Get stored fields**\n\nUse the `stored_fields` attribute to specify the set of stored fields you want to retrieve.\nAny requested fields that are not stored are ignored.\nYou can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.", "operationId": "mget-2", "parameters": [ { @@ -17625,7 +17625,7 @@ "document" ], "summary": "Get multiple documents", - "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.", + "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.\n\n**Filter source fields**\n\nBy default, the `_source` field is returned for every document (if stored).\nUse the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.\nYou can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.\n\n**Get stored fields**\n\nUse the `stored_fields` attribute to specify the set of stored fields you want to retrieve.\nAny requested fields that are not stored are ignored.\nYou can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.", "operationId": "mget-3", "parameters": [ { @@ -24187,6 +24187,7 @@ "search" ], "summary": "Run multiple templated searches", + "description": "Run multiple templated searches with a single request.\nIf you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.\nFor example:\n\n```\n$ cat requests\n{ \"index\": \"my-index\" }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ \"index\": \"my-other-index\" }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}\n\n$ curl -H \"Content-Type: application/x-ndjson\" -XGET localhost:9200/_msearch/template --data-binary \"@requests\"; echo\n```", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html" }, @@ -24223,6 +24224,7 @@ "search" ], "summary": "Run multiple templated searches", + "description": "Run multiple templated searches with a single request.\nIf you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.\nFor example:\n\n```\n$ cat requests\n{ \"index\": \"my-index\" }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ \"index\": \"my-other-index\" }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}\n\n$ curl -H \"Content-Type: application/x-ndjson\" -XGET localhost:9200/_msearch/template --data-binary \"@requests\"; echo\n```", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html" }, @@ -24261,6 +24263,7 @@ "search" ], "summary": "Run multiple templated searches", + "description": "Run multiple templated searches with a single request.\nIf you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.\nFor example:\n\n```\n$ cat requests\n{ \"index\": \"my-index\" }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ \"index\": \"my-other-index\" }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}\n\n$ curl -H \"Content-Type: application/x-ndjson\" -XGET localhost:9200/_msearch/template --data-binary \"@requests\"; echo\n```", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html" }, @@ -24300,6 +24303,7 @@ "search" ], "summary": "Run multiple templated searches", + "description": "Run multiple templated searches with a single request.\nIf you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.\nFor example:\n\n```\n$ cat requests\n{ \"index\": \"my-index\" }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ \"index\": \"my-other-index\" }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}\n\n$ curl -H \"Content-Type: application/x-ndjson\" -XGET localhost:9200/_msearch/template --data-binary \"@requests\"; echo\n```", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html" }, @@ -24341,7 +24345,7 @@ "document" ], "summary": "Get multiple term vectors", - "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.", + "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.\n\n**Artificial documents**\n\nYou can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request.\nThe mapping used is determined by the specified `_index`.", "operationId": "mtermvectors", "parameters": [ { @@ -24395,7 +24399,7 @@ "document" ], "summary": "Get multiple term vectors", - "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.", + "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.\n\n**Artificial documents**\n\nYou can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request.\nThe mapping used is determined by the specified `_index`.", "operationId": "mtermvectors-1", "parameters": [ { @@ -24451,7 +24455,7 @@ "document" ], "summary": "Get multiple term vectors", - "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.", + "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.\n\n**Artificial documents**\n\nYou can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request.\nThe mapping used is determined by the specified `_index`.", "operationId": "mtermvectors-2", "parameters": [ { @@ -24508,7 +24512,7 @@ "document" ], "summary": "Get multiple term vectors", - "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.", + "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.\n\n**Artificial documents**\n\nYou can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request.\nThe mapping used is determined by the specified `_index`.", "operationId": "mtermvectors-3", "parameters": [ { @@ -28019,7 +28023,10 @@ "search" ], "summary": "Search a vector tile", - "description": "Search a vector tile for geospatial values.", + "description": "Search a vector tile for geospatial values.\nBefore using this API, you should be familiar with the Mapbox vector tile specification.\nThe API returns results as a binary mapbox vector tile.\n\nInternally, Elasticsearch translates a vector tile search API request into a search containing:\n\n* A `geo_bounding_box` query on the ``. The query uses the `//` tile as a bounding box.\n* A `geotile_grid` or `geohex_grid` aggregation on the ``. The `grid_agg` parameter determines the aggregation type. The aggregation uses the `//` tile as a bounding box.\n* Optionally, a `geo_bounds` aggregation on the ``. The search only includes this aggregation if the `exact_bounds` parameter is `true`.\n* If the optional parameter `with_labels` is `true`, the internal search will include a dynamic runtime field that calls the `getLabelPosition` function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.\n\nFor example, Elasticsearch may translate a vector tile search API request with a `grid_agg` argument of `geotile` and an `exact_bounds` argument of `true` into the following search\n\n```\nGET my-index/_search\n{\n \"size\": 10000,\n \"query\": {\n \"geo_bounding_box\": {\n \"my-geo-field\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"aggregations\": {\n \"grid\": {\n \"geotile_grid\": {\n \"field\": \"my-geo-field\",\n \"precision\": 11,\n \"size\": 65536,\n \"bounds\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"bounds\": {\n \"geo_bounds\": {\n \"field\": \"my-geo-field\",\n \"wrap_longitude\": false\n }\n }\n }\n}\n```\n\nThe API returns results as a binary Mapbox vector tile.\nMapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:\n\n* A `hits` layer containing a feature for each `` value matching the `geo_bounding_box` query.\n* An `aggs` layer containing a feature for each cell of the `geotile_grid` or `geohex_grid`. The layer only contains features for cells with matching data.\n* A meta layer containing:\n * A feature containing a bounding box. By default, this is the bounding box of the tile.\n * Value ranges for any sub-aggregations on the `geotile_grid` or `geohex_grid`.\n * Metadata for the search.\n\nThe API only returns features that can display at its zoom level.\nFor example, if a polygon feature has no area at its zoom level, the API omits it.\nThe API returns errors as UTF-8 encoded JSON.\n\nIMPORTANT: You can specify several options for this API as either a query parameter or request body parameter.\nIf you specify both parameters, the query parameter takes precedence.\n\n**Grid precision for geotile**\n\nFor a `grid_agg` of `geotile`, you can use cells in the `aggs` layer as tiles for lower zoom levels.\n`grid_precision` represents the additional zoom levels available through these cells. The final precision is computed by as follows: ` + grid_precision`.\nFor example, if `` is 7 and `grid_precision` is 8, then the `geotile_grid` aggregation will use a precision of 15.\nThe maximum final precision is 29.\nThe `grid_precision` also determines the number of cells for the grid as follows: `(2^grid_precision) x (2^grid_precision)`.\nFor example, a value of 8 divides the tile into a grid of 256 x 256 cells.\nThe `aggs` layer only contains features for cells with matching data.\n\n**Grid precision for geohex**\n\nFor a `grid_agg` of `geohex`, Elasticsearch uses `` and `grid_precision` to calculate a final precision as follows: ` + grid_precision`.\n\nThis precision determines the H3 resolution of the hexagonal cells produced by the `geohex` aggregation.\nThe following table maps the H3 resolution for each precision.\nFor example, if `` is 3 and `grid_precision` is 3, the precision is 6.\nAt a precision of 6, hexagonal cells have an H3 resolution of 2.\nIf `` is 3 and `grid_precision` is 4, the precision is 7.\nAt a precision of 7, hexagonal cells have an H3 resolution of 3.\n\n| Precision | Unique tile bins | H3 resolution | Unique hex bins |\tRatio |\n| --------- | ---------------- | ------------- | ----------------| ----- |\n| 1 | 4 | 0 | 122 | 30.5 |\n| 2 | 16 | 0 | 122 | 7.625 |\n| 3 | 64 | 1 | 842 | 13.15625 |\n| 4 | 256 | 1 | 842 | 3.2890625 |\n| 5 | 1024 | 2 | 5882 | 5.744140625 |\n| 6 | 4096 | 2 | 5882 | 1.436035156 |\n| 7 | 16384 | 3 | 41162 | 2.512329102 |\n| 8 | 65536 | 3 | 41162 | 0.6280822754 |\n| 9 | 262144 | 4 | 288122 | 1.099098206 |\n| 10 | 1048576 | 4 | 288122 | 0.2747745514 |\n| 11 | 4194304 | 5 | 2016842 | 0.4808526039 |\n| 12 | 16777216 | 6 | 14117882 | 0.8414913416 |\n| 13 | 67108864 | 6 | 14117882 | 0.2103728354 |\n| 14 | 268435456 | 7 | 98825162 | 0.3681524172 |\n| 15 | 1073741824 | 8 | 691776122 | 0.644266719 |\n| 16 | 4294967296 | 8 | 691776122 | 0.1610666797 |\n| 17 | 17179869184 | 9 | 4842432842 | 0.2818666889 |\n| 18 | 68719476736 | 10 | 33897029882 | 0.4932667053 |\n| 19 | 274877906944 | 11 | 237279209162 | 0.8632167343 |\n| 20 | 1099511627776 | 11 | 237279209162 | 0.2158041836 |\n| 21 | 4398046511104 | 12 | 1660954464122 | 0.3776573213 |\n| 22 | 17592186044416 | 13 | 11626681248842 | 0.6609003122 |\n| 23 | 70368744177664 | 13 | 11626681248842 | 0.165225078 |\n| 24 | 281474976710656 | 14 | 81386768741882 | 0.2891438866 |\n| 25 | 1125899906842620 | 15 | 569707381193162 | 0.5060018015 |\n| 26 | 4503599627370500 | 15 | 569707381193162 | 0.1265004504 |\n| 27 | 18014398509482000 | 15 | 569707381193162 | 0.03162511259 |\n| 28 | 72057594037927900 | 15 | 569707381193162 | 0.007906278149 |\n| 29 | 288230376151712000 | 15 | 569707381193162 | 0.001976569537 |\n\nHexagonal cells don't align perfectly on a vector tile.\nSome cells may intersect more than one vector tile.\nTo compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level.\nElasticsearch uses the H3 resolution that is closest to the corresponding geotile density.", + "externalDocs": { + "url": "https://github.com/mapbox/vector-tile-spec/blob/master/README.md" + }, "operationId": "search-mvt-1", "parameters": [ { @@ -28074,7 +28081,10 @@ "search" ], "summary": "Search a vector tile", - "description": "Search a vector tile for geospatial values.", + "description": "Search a vector tile for geospatial values.\nBefore using this API, you should be familiar with the Mapbox vector tile specification.\nThe API returns results as a binary mapbox vector tile.\n\nInternally, Elasticsearch translates a vector tile search API request into a search containing:\n\n* A `geo_bounding_box` query on the ``. The query uses the `//` tile as a bounding box.\n* A `geotile_grid` or `geohex_grid` aggregation on the ``. The `grid_agg` parameter determines the aggregation type. The aggregation uses the `//` tile as a bounding box.\n* Optionally, a `geo_bounds` aggregation on the ``. The search only includes this aggregation if the `exact_bounds` parameter is `true`.\n* If the optional parameter `with_labels` is `true`, the internal search will include a dynamic runtime field that calls the `getLabelPosition` function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.\n\nFor example, Elasticsearch may translate a vector tile search API request with a `grid_agg` argument of `geotile` and an `exact_bounds` argument of `true` into the following search\n\n```\nGET my-index/_search\n{\n \"size\": 10000,\n \"query\": {\n \"geo_bounding_box\": {\n \"my-geo-field\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"aggregations\": {\n \"grid\": {\n \"geotile_grid\": {\n \"field\": \"my-geo-field\",\n \"precision\": 11,\n \"size\": 65536,\n \"bounds\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"bounds\": {\n \"geo_bounds\": {\n \"field\": \"my-geo-field\",\n \"wrap_longitude\": false\n }\n }\n }\n}\n```\n\nThe API returns results as a binary Mapbox vector tile.\nMapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:\n\n* A `hits` layer containing a feature for each `` value matching the `geo_bounding_box` query.\n* An `aggs` layer containing a feature for each cell of the `geotile_grid` or `geohex_grid`. The layer only contains features for cells with matching data.\n* A meta layer containing:\n * A feature containing a bounding box. By default, this is the bounding box of the tile.\n * Value ranges for any sub-aggregations on the `geotile_grid` or `geohex_grid`.\n * Metadata for the search.\n\nThe API only returns features that can display at its zoom level.\nFor example, if a polygon feature has no area at its zoom level, the API omits it.\nThe API returns errors as UTF-8 encoded JSON.\n\nIMPORTANT: You can specify several options for this API as either a query parameter or request body parameter.\nIf you specify both parameters, the query parameter takes precedence.\n\n**Grid precision for geotile**\n\nFor a `grid_agg` of `geotile`, you can use cells in the `aggs` layer as tiles for lower zoom levels.\n`grid_precision` represents the additional zoom levels available through these cells. The final precision is computed by as follows: ` + grid_precision`.\nFor example, if `` is 7 and `grid_precision` is 8, then the `geotile_grid` aggregation will use a precision of 15.\nThe maximum final precision is 29.\nThe `grid_precision` also determines the number of cells for the grid as follows: `(2^grid_precision) x (2^grid_precision)`.\nFor example, a value of 8 divides the tile into a grid of 256 x 256 cells.\nThe `aggs` layer only contains features for cells with matching data.\n\n**Grid precision for geohex**\n\nFor a `grid_agg` of `geohex`, Elasticsearch uses `` and `grid_precision` to calculate a final precision as follows: ` + grid_precision`.\n\nThis precision determines the H3 resolution of the hexagonal cells produced by the `geohex` aggregation.\nThe following table maps the H3 resolution for each precision.\nFor example, if `` is 3 and `grid_precision` is 3, the precision is 6.\nAt a precision of 6, hexagonal cells have an H3 resolution of 2.\nIf `` is 3 and `grid_precision` is 4, the precision is 7.\nAt a precision of 7, hexagonal cells have an H3 resolution of 3.\n\n| Precision | Unique tile bins | H3 resolution | Unique hex bins |\tRatio |\n| --------- | ---------------- | ------------- | ----------------| ----- |\n| 1 | 4 | 0 | 122 | 30.5 |\n| 2 | 16 | 0 | 122 | 7.625 |\n| 3 | 64 | 1 | 842 | 13.15625 |\n| 4 | 256 | 1 | 842 | 3.2890625 |\n| 5 | 1024 | 2 | 5882 | 5.744140625 |\n| 6 | 4096 | 2 | 5882 | 1.436035156 |\n| 7 | 16384 | 3 | 41162 | 2.512329102 |\n| 8 | 65536 | 3 | 41162 | 0.6280822754 |\n| 9 | 262144 | 4 | 288122 | 1.099098206 |\n| 10 | 1048576 | 4 | 288122 | 0.2747745514 |\n| 11 | 4194304 | 5 | 2016842 | 0.4808526039 |\n| 12 | 16777216 | 6 | 14117882 | 0.8414913416 |\n| 13 | 67108864 | 6 | 14117882 | 0.2103728354 |\n| 14 | 268435456 | 7 | 98825162 | 0.3681524172 |\n| 15 | 1073741824 | 8 | 691776122 | 0.644266719 |\n| 16 | 4294967296 | 8 | 691776122 | 0.1610666797 |\n| 17 | 17179869184 | 9 | 4842432842 | 0.2818666889 |\n| 18 | 68719476736 | 10 | 33897029882 | 0.4932667053 |\n| 19 | 274877906944 | 11 | 237279209162 | 0.8632167343 |\n| 20 | 1099511627776 | 11 | 237279209162 | 0.2158041836 |\n| 21 | 4398046511104 | 12 | 1660954464122 | 0.3776573213 |\n| 22 | 17592186044416 | 13 | 11626681248842 | 0.6609003122 |\n| 23 | 70368744177664 | 13 | 11626681248842 | 0.165225078 |\n| 24 | 281474976710656 | 14 | 81386768741882 | 0.2891438866 |\n| 25 | 1125899906842620 | 15 | 569707381193162 | 0.5060018015 |\n| 26 | 4503599627370500 | 15 | 569707381193162 | 0.1265004504 |\n| 27 | 18014398509482000 | 15 | 569707381193162 | 0.03162511259 |\n| 28 | 72057594037927900 | 15 | 569707381193162 | 0.007906278149 |\n| 29 | 288230376151712000 | 15 | 569707381193162 | 0.001976569537 |\n\nHexagonal cells don't align perfectly on a vector tile.\nSome cells may intersect more than one vector tile.\nTo compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level.\nElasticsearch uses the H3 resolution that is closest to the corresponding geotile density.", + "externalDocs": { + "url": "https://github.com/mapbox/vector-tile-spec/blob/master/README.md" + }, "operationId": "search-mvt", "parameters": [ { @@ -36064,7 +36074,7 @@ "search" ], "summary": "Get terms in an index", - "description": "Discover terms that match a partial string in an index.\nThis \"terms enum\" API is designed for low-latency look-ups used in auto-complete scenarios.\n\nIf the `complete` property in the response is false, the returned terms set may be incomplete and should be treated as approximate.\nThis can occur due to a few reasons, such as a request timeout or a node error.\n\nNOTE: The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", + "description": "Discover terms that match a partial string in an index.\nThis API is designed for low-latency look-ups used in auto-complete scenarios.\n\n> info\n> The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", "operationId": "terms-enum", "parameters": [ { @@ -36086,7 +36096,7 @@ "search" ], "summary": "Get terms in an index", - "description": "Discover terms that match a partial string in an index.\nThis \"terms enum\" API is designed for low-latency look-ups used in auto-complete scenarios.\n\nIf the `complete` property in the response is false, the returned terms set may be incomplete and should be treated as approximate.\nThis can occur due to a few reasons, such as a request timeout or a node error.\n\nNOTE: The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", + "description": "Discover terms that match a partial string in an index.\nThis API is designed for low-latency look-ups used in auto-complete scenarios.\n\n> info\n> The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", "operationId": "terms-enum-1", "parameters": [ { @@ -81157,7 +81167,7 @@ "type": "boolean" }, "source": { - "description": "An inline search template. Supports the same parameters as the search API's\nrequest body. Also supports Mustache variables. If no id is specified, this\nparameter is required.", + "description": "An inline search template. Supports the same parameters as the search API's\nrequest body. It also supports Mustache variables. If no `id` is specified, this\nparameter is required.", "type": "string" } } @@ -94766,7 +94776,7 @@ "type": "object", "properties": { "took": { - "description": "Milliseconds it took Elasticsearch to execute the request.", + "description": "The milliseconds it took Elasticsearch to run the request.", "type": "number" }, "timed_out": { @@ -94780,14 +94790,14 @@ "$ref": "#/components/schemas/_global.search._types:HitsMetadata" }, "fields": { - "description": "Contains field values for the documents. These fields\nmust be specified in the request using the `fields` parameter.", + "description": "The field values for the documents. These fields\nmust be specified in the request using the `fields` parameter.", "type": "object", "additionalProperties": { "type": "object" } }, "max_score": { - "description": "Highest returned document score. This value is null for requests\nthat do not sort by score.", + "description": "The highest returned document score. This value is null for requests\nthat do not sort by score.", "type": "number" } }, @@ -94847,6 +94857,7 @@ "type": "object", "properties": { "docs": { + "description": "The response includes a docs array that contains the documents in the order specified in the request.\nThe structure of the returned documents is similar to that returned by the get API.\nIf there is a failure getting a particular document, the error is included in place of the document.", "type": "array", "items": { "$ref": "#/components/schemas/_global.mget:ResponseItem" @@ -96646,6 +96657,7 @@ } }, "complete": { + "description": "If `false`, the returned terms set may be incomplete and should be treated as approximate.\nThis can occur due to a few reasons, such as a request timeout or a node error.", "type": "boolean" } }, @@ -99262,7 +99274,7 @@ "field_caps#index": { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.", + "description": "A comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.", "required": true, "deprecated": false, "schema": { @@ -99283,7 +99295,7 @@ "field_caps#expand_wildcards": { "in": "query", "name": "expand_wildcards", - "description": "Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as `open,hidden`.", + "description": "The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as `open,hidden`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:ExpandWildcards" @@ -99293,7 +99305,7 @@ "field_caps#fields": { "in": "query", "name": "fields", - "description": "Comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.", + "description": "A comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -99323,7 +99335,7 @@ "field_caps#filters": { "in": "query", "name": "filters", - "description": "An optional set of filters: can include +metadata,-metadata,-nested,-multifield,-parent", + "description": "A comma-separated list of filters to apply to the response.", "deprecated": false, "schema": { "type": "string" @@ -99333,7 +99345,7 @@ "field_caps#types": { "in": "query", "name": "types", - "description": "Only return results for fields that have one of the types in the list", + "description": "A comma-separated list of field types to include.\nAny fields that do not match one of these types will be excluded from the results.\nIt defaults to empty, meaning that all field types are returned.", "deprecated": false, "schema": { "type": "array", @@ -102253,7 +102265,7 @@ "knn_search#index": { "in": "path", "name": "index", - "description": "A comma-separated list of index names to search;\nuse `_all` or to perform the operation on all indices", + "description": "A comma-separated list of index names to search;\nuse `_all` or to perform the operation on all indices.", "required": true, "deprecated": false, "schema": { @@ -102264,7 +102276,7 @@ "knn_search#routing": { "in": "query", "name": "routing", - "description": "A comma-separated list of specific routing values", + "description": "A comma-separated list of specific routing values.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -103706,7 +103718,7 @@ "msearch_template#index": { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and aliases to search.\nSupports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*`.", + "description": "A comma-separated list of data streams, indices, and aliases to search.\nIt supports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*`.", "required": true, "deprecated": false, "schema": { @@ -103727,7 +103739,7 @@ "msearch_template#max_concurrent_searches": { "in": "query", "name": "max_concurrent_searches", - "description": "Maximum number of concurrent searches the API can run.", + "description": "The maximum number of concurrent searches the API can run.", "deprecated": false, "schema": { "type": "number" @@ -103737,7 +103749,7 @@ "msearch_template#search_type": { "in": "query", "name": "search_type", - "description": "The type of the search operation.\nAvailable options: `query_then_fetch`, `dfs_query_then_fetch`.", + "description": "The type of the search operation.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:SearchType" @@ -104285,7 +104297,7 @@ "rank_eval#index": { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard (`*`) expressions are supported.\nTo target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`.", + "description": "A comma-separated list of data streams, indices, and index aliases used to limit the request.\nWildcard (`*`) expressions are supported.\nTo target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`.", "required": true, "deprecated": false, "schema": { @@ -104411,7 +104423,7 @@ "scroll#scroll": { "in": "query", "name": "scroll", - "description": "Period to retain the search context for scrolling.", + "description": "The period to retain the search context for scrolling.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -105005,7 +105017,7 @@ "search_mvt#exact_bounds": { "in": "query", "name": "exact_bounds", - "description": "If false, the meta layer’s feature is the bounding box of the tile.\nIf true, the meta layer’s feature is a bounding box resulting from a\ngeo_bounds aggregation. The aggregation runs on values that intersect\nthe // tile with wrap_longitude set to false. The resulting\nbounding box may be larger than the vector tile.", + "description": "If `false`, the meta layer's feature is the bounding box of the tile.\nIf true, the meta layer's feature is a bounding box resulting from a\ngeo_bounds aggregation. The aggregation runs on values that intersect\nthe // tile with wrap_longitude set to false. The resulting\nbounding box may be larger than the vector tile.", "deprecated": false, "schema": { "type": "boolean" @@ -105015,7 +105027,7 @@ "search_mvt#extent": { "in": "query", "name": "extent", - "description": "Size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", + "description": "The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", "deprecated": false, "schema": { "type": "number" @@ -105035,7 +105047,7 @@ "search_mvt#grid_precision": { "in": "query", "name": "grid_precision", - "description": "Additional zoom levels available through the aggs layer. For example, if is 7\nand grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon’t include the aggs layer.", + "description": "Additional zoom levels available through the aggs layer. For example, if is 7\nand grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon't include the aggs layer.", "deprecated": false, "schema": { "type": "number" @@ -105055,7 +105067,7 @@ "search_mvt#size": { "in": "query", "name": "size", - "description": "Maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don’t include the hits layer.", + "description": "Maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don't include the hits layer.", "deprecated": false, "schema": { "type": "number" @@ -105065,7 +105077,7 @@ "search_mvt#with_labels": { "in": "query", "name": "with_labels", - "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.", + "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.\n\n* `Point` and `MultiPoint` features will have one of the points selected.\n* `Polygon` and `MultiPolygon` features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.\n* `LineString` features will likewise provide a roughly central point selected from the triangle-tree.\n* The aggregation results will provide one central point for each aggregation bucket.\n\nAll attributes from the original features will also be copied to the new label features.\nIn addition, the new features will be distinguishable using the tag `_mvt_label_position`.", "deprecated": false, "schema": { "type": "boolean" @@ -106140,7 +106152,7 @@ "terms_enum#index": { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and index aliases to search. Wildcard (*) expressions are supported.", + "description": "A comma-separated list of data streams, indices, and index aliases to search.\nWildcard (`*`) expressions are supported.\nTo search all data streams or indices, omit this parameter or use `*` or `_all`.", "required": true, "deprecated": false, "schema": { @@ -107820,7 +107832,7 @@ "$ref": "#/components/schemas/_global.search._types:SourceConfig" }, "docvalue_fields": { - "description": "The request returns doc values for field names matching these patterns\nin the hits.fields property of the response. Accepts wildcard (*) patterns.", + "description": "The request returns doc values for field names matching these patterns\nin the `hits.fields` property of the response.\nIt accepts wildcard (`*`) patterns.", "type": "array", "items": { "$ref": "#/components/schemas/_types.query_dsl:FieldAndFormat" @@ -107833,7 +107845,7 @@ "$ref": "#/components/schemas/_types:Fields" }, "filter": { - "description": "Query to filter the documents that can match. The kNN search will return the top\n`k` documents that also match this filter. The value can be a single query or a\nlist of queries. If `filter` isn't provided, all documents are allowed to match.", + "description": "A query to filter the documents that can match. The kNN search will return the top\n`k` documents that also match this filter. The value can be a single query or a\nlist of queries. If `filter` isn't provided, all documents are allowed to match.", "oneOf": [ { "$ref": "#/components/schemas/_types.query_dsl:QueryContainer" @@ -108644,22 +108656,22 @@ "type": "object", "properties": { "aggs": { - "description": "Sub-aggregations for the geotile_grid.\n\nSupports the following aggregation types:\n- avg\n- cardinality\n- max\n- min\n- sum", + "description": "Sub-aggregations for the geotile_grid.\n\nIt supports the following aggregation types:\n\n- `avg`\n- `boxplot`\n- `cardinality`\n- `extended stats`\n- `max`\n- `median absolute deviation`\n- `min`\n- `percentile`\n- `percentile-rank`\n- `stats`\n- `sum`\n- `value count`\n\nThe aggregation names can't start with `_mvt_`. The `_mvt_` prefix is reserved for internal aggregations.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/_types.aggregations:AggregationContainer" } }, "buffer": { - "description": "Size, in pixels, of a clipping buffer outside the tile. This allows renderers\nto avoid outline artifacts from geometries that extend past the extent of the tile.", + "description": "The size, in pixels, of a clipping buffer outside the tile. This allows renderers\nto avoid outline artifacts from geometries that extend past the extent of the tile.", "type": "number" }, "exact_bounds": { - "description": "If false, the meta layer’s feature is the bounding box of the tile.\nIf true, the meta layer’s feature is a bounding box resulting from a\ngeo_bounds aggregation. The aggregation runs on values that intersect\nthe // tile with wrap_longitude set to false. The resulting\nbounding box may be larger than the vector tile.", + "description": "If `false`, the meta layer's feature is the bounding box of the tile.\nIf `true`, the meta layer's feature is a bounding box resulting from a\n`geo_bounds` aggregation. The aggregation runs on values that intersect\nthe `//` tile with `wrap_longitude` set to `false`. The resulting\nbounding box may be larger than the vector tile.", "type": "boolean" }, "extent": { - "description": "Size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", + "description": "The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", "type": "number" }, "fields": { @@ -108669,7 +108681,7 @@ "$ref": "#/components/schemas/_global.search_mvt._types:GridAggregationType" }, "grid_precision": { - "description": "Additional zoom levels available through the aggs layer. For example, if is 7\nand grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon’t include the aggs layer.", + "description": "Additional zoom levels available through the aggs layer. For example, if `` is `7`\nand `grid_precision` is `8`, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon't include the aggs layer.", "type": "number" }, "grid_type": { @@ -108682,7 +108694,7 @@ "$ref": "#/components/schemas/_types.mapping:RuntimeFields" }, "size": { - "description": "Maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don’t include the hits layer.", + "description": "The maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don't include the hits layer.", "type": "number" }, "sort": { @@ -108692,7 +108704,7 @@ "$ref": "#/components/schemas/_global.search._types:TrackHits" }, "with_labels": { - "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.", + "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.\n\n* `Point` and `MultiPoint` features will have one of the points selected.\n* `Polygon` and `MultiPolygon` features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.\n* `LineString` features will likewise provide a roughly central point selected from the triangle-tree.\n* The aggregation results will provide one central point for each aggregation bucket.\n\nAll attributes from the original features will also be copied to the new label features.\nIn addition, the new features will be distinguishable using the tag `_mvt_label_position`.", "type": "boolean" } } @@ -109406,24 +109418,25 @@ "$ref": "#/components/schemas/_types:Field" }, "size": { - "description": "How many matching terms to return.", + "description": "The number of matching terms to return.", "type": "number" }, "timeout": { "$ref": "#/components/schemas/_types:Duration" }, "case_insensitive": { - "description": "When true the provided search string is matched against index terms without case sensitivity.", + "description": "When `true`, the provided search string is matched against index terms without case sensitivity.", "type": "boolean" }, "index_filter": { "$ref": "#/components/schemas/_types.query_dsl:QueryContainer" }, "string": { - "description": "The string after which terms in the index should be returned. Allows for a form of pagination if the last result from one request is passed as the search_after parameter for a subsequent request.", + "description": "The string to match at the start of indexed terms.\nIf it is not provided, all terms in the field are considered.\n\n> info\n> The prefix string cannot be larger than the largest possible keyword value, which is Lucene's term byte-length limit of 32766.", "type": "string" }, "search_after": { + "description": "The string after which terms in the index should be returned.\nIt allows for a form of pagination if the last result from one request is passed as the `search_after` parameter for a subsequent request.", "type": "string" } }, diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index a29876ec20..6799a1ad2d 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -9704,7 +9704,7 @@ "document" ], "summary": "Get multiple documents", - "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.", + "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.\n\n**Filter source fields**\n\nBy default, the `_source` field is returned for every document (if stored).\nUse the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.\nYou can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.\n\n**Get stored fields**\n\nUse the `stored_fields` attribute to specify the set of stored fields you want to retrieve.\nAny requested fields that are not stored are ignored.\nYou can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.", "operationId": "mget", "parameters": [ { @@ -9747,7 +9747,7 @@ "document" ], "summary": "Get multiple documents", - "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.", + "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.\n\n**Filter source fields**\n\nBy default, the `_source` field is returned for every document (if stored).\nUse the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.\nYou can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.\n\n**Get stored fields**\n\nUse the `stored_fields` attribute to specify the set of stored fields you want to retrieve.\nAny requested fields that are not stored are ignored.\nYou can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.", "operationId": "mget-1", "parameters": [ { @@ -9792,7 +9792,7 @@ "document" ], "summary": "Get multiple documents", - "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.", + "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.\n\n**Filter source fields**\n\nBy default, the `_source` field is returned for every document (if stored).\nUse the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.\nYou can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.\n\n**Get stored fields**\n\nUse the `stored_fields` attribute to specify the set of stored fields you want to retrieve.\nAny requested fields that are not stored are ignored.\nYou can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.", "operationId": "mget-2", "parameters": [ { @@ -9838,7 +9838,7 @@ "document" ], "summary": "Get multiple documents", - "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.", + "description": "Get multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.\n\n**Filter source fields**\n\nBy default, the `_source` field is returned for every document (if stored).\nUse the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.\nYou can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.\n\n**Get stored fields**\n\nUse the `stored_fields` attribute to specify the set of stored fields you want to retrieve.\nAny requested fields that are not stored are ignored.\nYou can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.", "operationId": "mget-3", "parameters": [ { @@ -14394,6 +14394,7 @@ "search" ], "summary": "Run multiple templated searches", + "description": "Run multiple templated searches with a single request.\nIf you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.\nFor example:\n\n```\n$ cat requests\n{ \"index\": \"my-index\" }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ \"index\": \"my-other-index\" }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}\n\n$ curl -H \"Content-Type: application/x-ndjson\" -XGET localhost:9200/_msearch/template --data-binary \"@requests\"; echo\n```", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html" }, @@ -14430,6 +14431,7 @@ "search" ], "summary": "Run multiple templated searches", + "description": "Run multiple templated searches with a single request.\nIf you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.\nFor example:\n\n```\n$ cat requests\n{ \"index\": \"my-index\" }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ \"index\": \"my-other-index\" }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}\n\n$ curl -H \"Content-Type: application/x-ndjson\" -XGET localhost:9200/_msearch/template --data-binary \"@requests\"; echo\n```", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html" }, @@ -14468,6 +14470,7 @@ "search" ], "summary": "Run multiple templated searches", + "description": "Run multiple templated searches with a single request.\nIf you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.\nFor example:\n\n```\n$ cat requests\n{ \"index\": \"my-index\" }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ \"index\": \"my-other-index\" }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}\n\n$ curl -H \"Content-Type: application/x-ndjson\" -XGET localhost:9200/_msearch/template --data-binary \"@requests\"; echo\n```", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html" }, @@ -14507,6 +14510,7 @@ "search" ], "summary": "Run multiple templated searches", + "description": "Run multiple templated searches with a single request.\nIf you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.\nFor example:\n\n```\n$ cat requests\n{ \"index\": \"my-index\" }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ \"index\": \"my-other-index\" }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}\n\n$ curl -H \"Content-Type: application/x-ndjson\" -XGET localhost:9200/_msearch/template --data-binary \"@requests\"; echo\n```", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html" }, @@ -14548,7 +14552,7 @@ "document" ], "summary": "Get multiple term vectors", - "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.", + "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.\n\n**Artificial documents**\n\nYou can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request.\nThe mapping used is determined by the specified `_index`.", "operationId": "mtermvectors", "parameters": [ { @@ -14602,7 +14606,7 @@ "document" ], "summary": "Get multiple term vectors", - "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.", + "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.\n\n**Artificial documents**\n\nYou can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request.\nThe mapping used is determined by the specified `_index`.", "operationId": "mtermvectors-1", "parameters": [ { @@ -14658,7 +14662,7 @@ "document" ], "summary": "Get multiple term vectors", - "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.", + "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.\n\n**Artificial documents**\n\nYou can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request.\nThe mapping used is determined by the specified `_index`.", "operationId": "mtermvectors-2", "parameters": [ { @@ -14715,7 +14719,7 @@ "document" ], "summary": "Get multiple term vectors", - "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.", + "description": "Get multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.\n\n**Artificial documents**\n\nYou can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request.\nThe mapping used is determined by the specified `_index`.", "operationId": "mtermvectors-3", "parameters": [ { @@ -16862,7 +16866,10 @@ "search" ], "summary": "Search a vector tile", - "description": "Search a vector tile for geospatial values.", + "description": "Search a vector tile for geospatial values.\nBefore using this API, you should be familiar with the Mapbox vector tile specification.\nThe API returns results as a binary mapbox vector tile.\n\nInternally, Elasticsearch translates a vector tile search API request into a search containing:\n\n* A `geo_bounding_box` query on the ``. The query uses the `//` tile as a bounding box.\n* A `geotile_grid` or `geohex_grid` aggregation on the ``. The `grid_agg` parameter determines the aggregation type. The aggregation uses the `//` tile as a bounding box.\n* Optionally, a `geo_bounds` aggregation on the ``. The search only includes this aggregation if the `exact_bounds` parameter is `true`.\n* If the optional parameter `with_labels` is `true`, the internal search will include a dynamic runtime field that calls the `getLabelPosition` function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.\n\nFor example, Elasticsearch may translate a vector tile search API request with a `grid_agg` argument of `geotile` and an `exact_bounds` argument of `true` into the following search\n\n```\nGET my-index/_search\n{\n \"size\": 10000,\n \"query\": {\n \"geo_bounding_box\": {\n \"my-geo-field\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"aggregations\": {\n \"grid\": {\n \"geotile_grid\": {\n \"field\": \"my-geo-field\",\n \"precision\": 11,\n \"size\": 65536,\n \"bounds\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"bounds\": {\n \"geo_bounds\": {\n \"field\": \"my-geo-field\",\n \"wrap_longitude\": false\n }\n }\n }\n}\n```\n\nThe API returns results as a binary Mapbox vector tile.\nMapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:\n\n* A `hits` layer containing a feature for each `` value matching the `geo_bounding_box` query.\n* An `aggs` layer containing a feature for each cell of the `geotile_grid` or `geohex_grid`. The layer only contains features for cells with matching data.\n* A meta layer containing:\n * A feature containing a bounding box. By default, this is the bounding box of the tile.\n * Value ranges for any sub-aggregations on the `geotile_grid` or `geohex_grid`.\n * Metadata for the search.\n\nThe API only returns features that can display at its zoom level.\nFor example, if a polygon feature has no area at its zoom level, the API omits it.\nThe API returns errors as UTF-8 encoded JSON.\n\nIMPORTANT: You can specify several options for this API as either a query parameter or request body parameter.\nIf you specify both parameters, the query parameter takes precedence.\n\n**Grid precision for geotile**\n\nFor a `grid_agg` of `geotile`, you can use cells in the `aggs` layer as tiles for lower zoom levels.\n`grid_precision` represents the additional zoom levels available through these cells. The final precision is computed by as follows: ` + grid_precision`.\nFor example, if `` is 7 and `grid_precision` is 8, then the `geotile_grid` aggregation will use a precision of 15.\nThe maximum final precision is 29.\nThe `grid_precision` also determines the number of cells for the grid as follows: `(2^grid_precision) x (2^grid_precision)`.\nFor example, a value of 8 divides the tile into a grid of 256 x 256 cells.\nThe `aggs` layer only contains features for cells with matching data.\n\n**Grid precision for geohex**\n\nFor a `grid_agg` of `geohex`, Elasticsearch uses `` and `grid_precision` to calculate a final precision as follows: ` + grid_precision`.\n\nThis precision determines the H3 resolution of the hexagonal cells produced by the `geohex` aggregation.\nThe following table maps the H3 resolution for each precision.\nFor example, if `` is 3 and `grid_precision` is 3, the precision is 6.\nAt a precision of 6, hexagonal cells have an H3 resolution of 2.\nIf `` is 3 and `grid_precision` is 4, the precision is 7.\nAt a precision of 7, hexagonal cells have an H3 resolution of 3.\n\n| Precision | Unique tile bins | H3 resolution | Unique hex bins |\tRatio |\n| --------- | ---------------- | ------------- | ----------------| ----- |\n| 1 | 4 | 0 | 122 | 30.5 |\n| 2 | 16 | 0 | 122 | 7.625 |\n| 3 | 64 | 1 | 842 | 13.15625 |\n| 4 | 256 | 1 | 842 | 3.2890625 |\n| 5 | 1024 | 2 | 5882 | 5.744140625 |\n| 6 | 4096 | 2 | 5882 | 1.436035156 |\n| 7 | 16384 | 3 | 41162 | 2.512329102 |\n| 8 | 65536 | 3 | 41162 | 0.6280822754 |\n| 9 | 262144 | 4 | 288122 | 1.099098206 |\n| 10 | 1048576 | 4 | 288122 | 0.2747745514 |\n| 11 | 4194304 | 5 | 2016842 | 0.4808526039 |\n| 12 | 16777216 | 6 | 14117882 | 0.8414913416 |\n| 13 | 67108864 | 6 | 14117882 | 0.2103728354 |\n| 14 | 268435456 | 7 | 98825162 | 0.3681524172 |\n| 15 | 1073741824 | 8 | 691776122 | 0.644266719 |\n| 16 | 4294967296 | 8 | 691776122 | 0.1610666797 |\n| 17 | 17179869184 | 9 | 4842432842 | 0.2818666889 |\n| 18 | 68719476736 | 10 | 33897029882 | 0.4932667053 |\n| 19 | 274877906944 | 11 | 237279209162 | 0.8632167343 |\n| 20 | 1099511627776 | 11 | 237279209162 | 0.2158041836 |\n| 21 | 4398046511104 | 12 | 1660954464122 | 0.3776573213 |\n| 22 | 17592186044416 | 13 | 11626681248842 | 0.6609003122 |\n| 23 | 70368744177664 | 13 | 11626681248842 | 0.165225078 |\n| 24 | 281474976710656 | 14 | 81386768741882 | 0.2891438866 |\n| 25 | 1125899906842620 | 15 | 569707381193162 | 0.5060018015 |\n| 26 | 4503599627370500 | 15 | 569707381193162 | 0.1265004504 |\n| 27 | 18014398509482000 | 15 | 569707381193162 | 0.03162511259 |\n| 28 | 72057594037927900 | 15 | 569707381193162 | 0.007906278149 |\n| 29 | 288230376151712000 | 15 | 569707381193162 | 0.001976569537 |\n\nHexagonal cells don't align perfectly on a vector tile.\nSome cells may intersect more than one vector tile.\nTo compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level.\nElasticsearch uses the H3 resolution that is closest to the corresponding geotile density.", + "externalDocs": { + "url": "https://github.com/mapbox/vector-tile-spec/blob/master/README.md" + }, "operationId": "search-mvt-1", "parameters": [ { @@ -16917,7 +16924,10 @@ "search" ], "summary": "Search a vector tile", - "description": "Search a vector tile for geospatial values.", + "description": "Search a vector tile for geospatial values.\nBefore using this API, you should be familiar with the Mapbox vector tile specification.\nThe API returns results as a binary mapbox vector tile.\n\nInternally, Elasticsearch translates a vector tile search API request into a search containing:\n\n* A `geo_bounding_box` query on the ``. The query uses the `//` tile as a bounding box.\n* A `geotile_grid` or `geohex_grid` aggregation on the ``. The `grid_agg` parameter determines the aggregation type. The aggregation uses the `//` tile as a bounding box.\n* Optionally, a `geo_bounds` aggregation on the ``. The search only includes this aggregation if the `exact_bounds` parameter is `true`.\n* If the optional parameter `with_labels` is `true`, the internal search will include a dynamic runtime field that calls the `getLabelPosition` function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.\n\nFor example, Elasticsearch may translate a vector tile search API request with a `grid_agg` argument of `geotile` and an `exact_bounds` argument of `true` into the following search\n\n```\nGET my-index/_search\n{\n \"size\": 10000,\n \"query\": {\n \"geo_bounding_box\": {\n \"my-geo-field\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"aggregations\": {\n \"grid\": {\n \"geotile_grid\": {\n \"field\": \"my-geo-field\",\n \"precision\": 11,\n \"size\": 65536,\n \"bounds\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"bounds\": {\n \"geo_bounds\": {\n \"field\": \"my-geo-field\",\n \"wrap_longitude\": false\n }\n }\n }\n}\n```\n\nThe API returns results as a binary Mapbox vector tile.\nMapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:\n\n* A `hits` layer containing a feature for each `` value matching the `geo_bounding_box` query.\n* An `aggs` layer containing a feature for each cell of the `geotile_grid` or `geohex_grid`. The layer only contains features for cells with matching data.\n* A meta layer containing:\n * A feature containing a bounding box. By default, this is the bounding box of the tile.\n * Value ranges for any sub-aggregations on the `geotile_grid` or `geohex_grid`.\n * Metadata for the search.\n\nThe API only returns features that can display at its zoom level.\nFor example, if a polygon feature has no area at its zoom level, the API omits it.\nThe API returns errors as UTF-8 encoded JSON.\n\nIMPORTANT: You can specify several options for this API as either a query parameter or request body parameter.\nIf you specify both parameters, the query parameter takes precedence.\n\n**Grid precision for geotile**\n\nFor a `grid_agg` of `geotile`, you can use cells in the `aggs` layer as tiles for lower zoom levels.\n`grid_precision` represents the additional zoom levels available through these cells. The final precision is computed by as follows: ` + grid_precision`.\nFor example, if `` is 7 and `grid_precision` is 8, then the `geotile_grid` aggregation will use a precision of 15.\nThe maximum final precision is 29.\nThe `grid_precision` also determines the number of cells for the grid as follows: `(2^grid_precision) x (2^grid_precision)`.\nFor example, a value of 8 divides the tile into a grid of 256 x 256 cells.\nThe `aggs` layer only contains features for cells with matching data.\n\n**Grid precision for geohex**\n\nFor a `grid_agg` of `geohex`, Elasticsearch uses `` and `grid_precision` to calculate a final precision as follows: ` + grid_precision`.\n\nThis precision determines the H3 resolution of the hexagonal cells produced by the `geohex` aggregation.\nThe following table maps the H3 resolution for each precision.\nFor example, if `` is 3 and `grid_precision` is 3, the precision is 6.\nAt a precision of 6, hexagonal cells have an H3 resolution of 2.\nIf `` is 3 and `grid_precision` is 4, the precision is 7.\nAt a precision of 7, hexagonal cells have an H3 resolution of 3.\n\n| Precision | Unique tile bins | H3 resolution | Unique hex bins |\tRatio |\n| --------- | ---------------- | ------------- | ----------------| ----- |\n| 1 | 4 | 0 | 122 | 30.5 |\n| 2 | 16 | 0 | 122 | 7.625 |\n| 3 | 64 | 1 | 842 | 13.15625 |\n| 4 | 256 | 1 | 842 | 3.2890625 |\n| 5 | 1024 | 2 | 5882 | 5.744140625 |\n| 6 | 4096 | 2 | 5882 | 1.436035156 |\n| 7 | 16384 | 3 | 41162 | 2.512329102 |\n| 8 | 65536 | 3 | 41162 | 0.6280822754 |\n| 9 | 262144 | 4 | 288122 | 1.099098206 |\n| 10 | 1048576 | 4 | 288122 | 0.2747745514 |\n| 11 | 4194304 | 5 | 2016842 | 0.4808526039 |\n| 12 | 16777216 | 6 | 14117882 | 0.8414913416 |\n| 13 | 67108864 | 6 | 14117882 | 0.2103728354 |\n| 14 | 268435456 | 7 | 98825162 | 0.3681524172 |\n| 15 | 1073741824 | 8 | 691776122 | 0.644266719 |\n| 16 | 4294967296 | 8 | 691776122 | 0.1610666797 |\n| 17 | 17179869184 | 9 | 4842432842 | 0.2818666889 |\n| 18 | 68719476736 | 10 | 33897029882 | 0.4932667053 |\n| 19 | 274877906944 | 11 | 237279209162 | 0.8632167343 |\n| 20 | 1099511627776 | 11 | 237279209162 | 0.2158041836 |\n| 21 | 4398046511104 | 12 | 1660954464122 | 0.3776573213 |\n| 22 | 17592186044416 | 13 | 11626681248842 | 0.6609003122 |\n| 23 | 70368744177664 | 13 | 11626681248842 | 0.165225078 |\n| 24 | 281474976710656 | 14 | 81386768741882 | 0.2891438866 |\n| 25 | 1125899906842620 | 15 | 569707381193162 | 0.5060018015 |\n| 26 | 4503599627370500 | 15 | 569707381193162 | 0.1265004504 |\n| 27 | 18014398509482000 | 15 | 569707381193162 | 0.03162511259 |\n| 28 | 72057594037927900 | 15 | 569707381193162 | 0.007906278149 |\n| 29 | 288230376151712000 | 15 | 569707381193162 | 0.001976569537 |\n\nHexagonal cells don't align perfectly on a vector tile.\nSome cells may intersect more than one vector tile.\nTo compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level.\nElasticsearch uses the H3 resolution that is closest to the corresponding geotile density.", + "externalDocs": { + "url": "https://github.com/mapbox/vector-tile-spec/blob/master/README.md" + }, "operationId": "search-mvt", "parameters": [ { @@ -18604,7 +18614,7 @@ "search" ], "summary": "Get terms in an index", - "description": "Discover terms that match a partial string in an index.\nThis \"terms enum\" API is designed for low-latency look-ups used in auto-complete scenarios.\n\nIf the `complete` property in the response is false, the returned terms set may be incomplete and should be treated as approximate.\nThis can occur due to a few reasons, such as a request timeout or a node error.\n\nNOTE: The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", + "description": "Discover terms that match a partial string in an index.\nThis API is designed for low-latency look-ups used in auto-complete scenarios.\n\n> info\n> The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", "operationId": "terms-enum", "parameters": [ { @@ -18626,7 +18636,7 @@ "search" ], "summary": "Get terms in an index", - "description": "Discover terms that match a partial string in an index.\nThis \"terms enum\" API is designed for low-latency look-ups used in auto-complete scenarios.\n\nIf the `complete` property in the response is false, the returned terms set may be incomplete and should be treated as approximate.\nThis can occur due to a few reasons, such as a request timeout or a node error.\n\nNOTE: The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", + "description": "Discover terms that match a partial string in an index.\nThis API is designed for low-latency look-ups used in auto-complete scenarios.\n\n> info\n> The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", "operationId": "terms-enum-1", "parameters": [ { @@ -53282,7 +53292,7 @@ "type": "boolean" }, "source": { - "description": "An inline search template. Supports the same parameters as the search API's\nrequest body. Also supports Mustache variables. If no id is specified, this\nparameter is required.", + "description": "An inline search template. Supports the same parameters as the search API's\nrequest body. It also supports Mustache variables. If no `id` is specified, this\nparameter is required.", "type": "string" } } @@ -56574,6 +56584,7 @@ "type": "object", "properties": { "docs": { + "description": "The response includes a docs array that contains the documents in the order specified in the request.\nThe structure of the returned documents is similar to that returned by the get API.\nIf there is a failure getting a particular document, the error is included in place of the document.", "type": "array", "items": { "$ref": "#/components/schemas/_global.mget:ResponseItem" @@ -57388,6 +57399,7 @@ } }, "complete": { + "description": "If `false`, the returned terms set may be incomplete and should be treated as approximate.\nThis can occur due to a few reasons, such as a request timeout or a node error.", "type": "boolean" } }, @@ -59126,7 +59138,7 @@ "field_caps#index": { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.", + "description": "A comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.", "required": true, "deprecated": false, "schema": { @@ -59147,7 +59159,7 @@ "field_caps#expand_wildcards": { "in": "query", "name": "expand_wildcards", - "description": "Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as `open,hidden`.", + "description": "The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as `open,hidden`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:ExpandWildcards" @@ -59157,7 +59169,7 @@ "field_caps#fields": { "in": "query", "name": "fields", - "description": "Comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.", + "description": "A comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -59187,7 +59199,7 @@ "field_caps#filters": { "in": "query", "name": "filters", - "description": "An optional set of filters: can include +metadata,-metadata,-nested,-multifield,-parent", + "description": "A comma-separated list of filters to apply to the response.", "deprecated": false, "schema": { "type": "string" @@ -59197,7 +59209,7 @@ "field_caps#types": { "in": "query", "name": "types", - "description": "Only return results for fields that have one of the types in the list", + "description": "A comma-separated list of field types to include.\nAny fields that do not match one of these types will be excluded from the results.\nIt defaults to empty, meaning that all field types are returned.", "deprecated": false, "schema": { "type": "array", @@ -61370,7 +61382,7 @@ "msearch_template#index": { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and aliases to search.\nSupports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*`.", + "description": "A comma-separated list of data streams, indices, and aliases to search.\nIt supports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*`.", "required": true, "deprecated": false, "schema": { @@ -61391,7 +61403,7 @@ "msearch_template#max_concurrent_searches": { "in": "query", "name": "max_concurrent_searches", - "description": "Maximum number of concurrent searches the API can run.", + "description": "The maximum number of concurrent searches the API can run.", "deprecated": false, "schema": { "type": "number" @@ -61401,7 +61413,7 @@ "msearch_template#search_type": { "in": "query", "name": "search_type", - "description": "The type of the search operation.\nAvailable options: `query_then_fetch`, `dfs_query_then_fetch`.", + "description": "The type of the search operation.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:SearchType" @@ -61617,7 +61629,7 @@ "rank_eval#index": { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard (`*`) expressions are supported.\nTo target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`.", + "description": "A comma-separated list of data streams, indices, and index aliases used to limit the request.\nWildcard (`*`) expressions are supported.\nTo target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`.", "required": true, "deprecated": false, "schema": { @@ -61690,7 +61702,7 @@ "scroll#scroll": { "in": "query", "name": "scroll", - "description": "Period to retain the search context for scrolling.", + "description": "The period to retain the search context for scrolling.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -62274,7 +62286,7 @@ "search_mvt#exact_bounds": { "in": "query", "name": "exact_bounds", - "description": "If false, the meta layer’s feature is the bounding box of the tile.\nIf true, the meta layer’s feature is a bounding box resulting from a\ngeo_bounds aggregation. The aggregation runs on values that intersect\nthe // tile with wrap_longitude set to false. The resulting\nbounding box may be larger than the vector tile.", + "description": "If `false`, the meta layer's feature is the bounding box of the tile.\nIf true, the meta layer's feature is a bounding box resulting from a\ngeo_bounds aggregation. The aggregation runs on values that intersect\nthe // tile with wrap_longitude set to false. The resulting\nbounding box may be larger than the vector tile.", "deprecated": false, "schema": { "type": "boolean" @@ -62284,7 +62296,7 @@ "search_mvt#extent": { "in": "query", "name": "extent", - "description": "Size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", + "description": "The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", "deprecated": false, "schema": { "type": "number" @@ -62304,7 +62316,7 @@ "search_mvt#grid_precision": { "in": "query", "name": "grid_precision", - "description": "Additional zoom levels available through the aggs layer. For example, if is 7\nand grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon’t include the aggs layer.", + "description": "Additional zoom levels available through the aggs layer. For example, if is 7\nand grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon't include the aggs layer.", "deprecated": false, "schema": { "type": "number" @@ -62324,7 +62336,7 @@ "search_mvt#size": { "in": "query", "name": "size", - "description": "Maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don’t include the hits layer.", + "description": "Maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don't include the hits layer.", "deprecated": false, "schema": { "type": "number" @@ -62334,7 +62346,7 @@ "search_mvt#with_labels": { "in": "query", "name": "with_labels", - "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.", + "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.\n\n* `Point` and `MultiPoint` features will have one of the points selected.\n* `Polygon` and `MultiPolygon` features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.\n* `LineString` features will likewise provide a roughly central point selected from the triangle-tree.\n* The aggregation results will provide one central point for each aggregation bucket.\n\nAll attributes from the original features will also be copied to the new label features.\nIn addition, the new features will be distinguishable using the tag `_mvt_label_position`.", "deprecated": false, "schema": { "type": "boolean" @@ -62546,7 +62558,7 @@ "terms_enum#index": { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and index aliases to search. Wildcard (*) expressions are supported.", + "description": "A comma-separated list of data streams, indices, and index aliases to search.\nWildcard (`*`) expressions are supported.\nTo search all data streams or indices, omit this parameter or use `*` or `_all`.", "required": true, "deprecated": false, "schema": { @@ -64135,22 +64147,22 @@ "type": "object", "properties": { "aggs": { - "description": "Sub-aggregations for the geotile_grid.\n\nSupports the following aggregation types:\n- avg\n- cardinality\n- max\n- min\n- sum", + "description": "Sub-aggregations for the geotile_grid.\n\nIt supports the following aggregation types:\n\n- `avg`\n- `boxplot`\n- `cardinality`\n- `extended stats`\n- `max`\n- `median absolute deviation`\n- `min`\n- `percentile`\n- `percentile-rank`\n- `stats`\n- `sum`\n- `value count`\n\nThe aggregation names can't start with `_mvt_`. The `_mvt_` prefix is reserved for internal aggregations.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/_types.aggregations:AggregationContainer" } }, "buffer": { - "description": "Size, in pixels, of a clipping buffer outside the tile. This allows renderers\nto avoid outline artifacts from geometries that extend past the extent of the tile.", + "description": "The size, in pixels, of a clipping buffer outside the tile. This allows renderers\nto avoid outline artifacts from geometries that extend past the extent of the tile.", "type": "number" }, "exact_bounds": { - "description": "If false, the meta layer’s feature is the bounding box of the tile.\nIf true, the meta layer’s feature is a bounding box resulting from a\ngeo_bounds aggregation. The aggregation runs on values that intersect\nthe // tile with wrap_longitude set to false. The resulting\nbounding box may be larger than the vector tile.", + "description": "If `false`, the meta layer's feature is the bounding box of the tile.\nIf `true`, the meta layer's feature is a bounding box resulting from a\n`geo_bounds` aggregation. The aggregation runs on values that intersect\nthe `//` tile with `wrap_longitude` set to `false`. The resulting\nbounding box may be larger than the vector tile.", "type": "boolean" }, "extent": { - "description": "Size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", + "description": "The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", "type": "number" }, "fields": { @@ -64160,7 +64172,7 @@ "$ref": "#/components/schemas/_global.search_mvt._types:GridAggregationType" }, "grid_precision": { - "description": "Additional zoom levels available through the aggs layer. For example, if is 7\nand grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon’t include the aggs layer.", + "description": "Additional zoom levels available through the aggs layer. For example, if `` is `7`\nand `grid_precision` is `8`, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon't include the aggs layer.", "type": "number" }, "grid_type": { @@ -64173,7 +64185,7 @@ "$ref": "#/components/schemas/_types.mapping:RuntimeFields" }, "size": { - "description": "Maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don’t include the hits layer.", + "description": "The maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don't include the hits layer.", "type": "number" }, "sort": { @@ -64183,7 +64195,7 @@ "$ref": "#/components/schemas/_global.search._types:TrackHits" }, "with_labels": { - "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.", + "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.\n\n* `Point` and `MultiPoint` features will have one of the points selected.\n* `Polygon` and `MultiPolygon` features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.\n* `LineString` features will likewise provide a roughly central point selected from the triangle-tree.\n* The aggregation results will provide one central point for each aggregation bucket.\n\nAll attributes from the original features will also be copied to the new label features.\nIn addition, the new features will be distinguishable using the tag `_mvt_label_position`.", "type": "boolean" } } @@ -64443,24 +64455,25 @@ "$ref": "#/components/schemas/_types:Field" }, "size": { - "description": "How many matching terms to return.", + "description": "The number of matching terms to return.", "type": "number" }, "timeout": { "$ref": "#/components/schemas/_types:Duration" }, "case_insensitive": { - "description": "When true the provided search string is matched against index terms without case sensitivity.", + "description": "When `true`, the provided search string is matched against index terms without case sensitivity.", "type": "boolean" }, "index_filter": { "$ref": "#/components/schemas/_types.query_dsl:QueryContainer" }, "string": { - "description": "The string after which terms in the index should be returned. Allows for a form of pagination if the last result from one request is passed as the search_after parameter for a subsequent request.", + "description": "The string to match at the start of indexed terms.\nIf it is not provided, all terms in the field are considered.\n\n> info\n> The prefix string cannot be larger than the largest possible keyword value, which is Lucene's term byte-length limit of 32766.", "type": "string" }, "search_after": { + "description": "The string after which terms in the index should be returned.\nIt allows for a form of pagination if the last result from one request is passed as the `search_after` parameter for a subsequent request.", "type": "string" } }, diff --git a/output/schema/schema.json b/output/schema/schema.json index 5129d056d2..2473f50208 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -5212,8 +5212,9 @@ } }, "description": "Get the field capabilities.\n\nGet information about the capabilities of fields among multiple indices.\n\nFor data streams, the API returns field capabilities among the stream’s backing indices.\nIt returns runtime fields like any other field.\nFor example, a runtime field with a type of keyword is returned the same as any other field that belongs to the `keyword` family.", + "docId": "search-field-caps", "docTag": "search", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/search-field-caps.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-field-caps.html", "name": "field_caps", "privileges": { "index": [ @@ -9594,9 +9595,10 @@ "description": "The kNN search API has been replaced by the `knn` option in the search API.", "version": "8.4.0" }, - "description": "Run a knn search.\n\nNOTE: The kNN search API has been replaced by the `knn` option in the search API.\n\nPerform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents.\nGiven a query vector, the API finds the k closest vectors and returns those documents as search hits.\n\nElasticsearch uses the HNSW algorithm to support efficient kNN search.\nLike most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed.\nThis means the results returned are not always the true k closest neighbors.\n\nThe kNN search API supports restricting the search using a filter.\nThe search will return the top k documents that also match the filter query.", + "description": "Run a knn search.\n\nNOTE: The kNN search API has been replaced by the `knn` option in the search API.\n\nPerform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents.\nGiven a query vector, the API finds the k closest vectors and returns those documents as search hits.\n\nElasticsearch uses the HNSW algorithm to support efficient kNN search.\nLike most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed.\nThis means the results returned are not always the true k closest neighbors.\n\nThe kNN search API supports restricting the search using a filter.\nThe search will return the top k documents that also match the filter query.\n\nA kNN search response has the exact same structure as a search API response.\nHowever, certain sections have a meaning specific to kNN search:\n\n* The document `_score` is determined by the similarity between the query and document vector.\n* The `hits.total` object contains the total number of nearest neighbor candidates considered, which is `num_candidates * num_shards`. The `hits.total.relation` will always be `eq`, indicating an exact value.", + "docId": "search-knn", "docTag": "search", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/search-search.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/knn-search-api.html", "name": "knn_search", "request": { "name": "Request", @@ -10027,9 +10029,10 @@ "stability": "stable" } }, - "description": "Get multiple documents.\n\nGet multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.", + "description": "Get multiple documents.\n\nGet multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.\n\n**Filter source fields**\n\nBy default, the `_source` field is returned for every document (if stored).\nUse the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.\nYou can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.\n\n**Get stored fields**\n\nUse the `stored_fields` attribute to specify the set of stored fields you want to retrieve.\nAny requested fields that are not stored are ignored.\nYou can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.", + "docId": "docs-multi-get", "docTag": "document", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-multi-get.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-multi-get.html", "name": "mget", "privileges": { "index": [ @@ -13590,9 +13593,10 @@ "stability": "stable" } }, - "description": "Run multiple templated searches.", + "description": "Run multiple templated searches.\n\nRun multiple templated searches with a single request.\nIf you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.\nFor example:\n\n```\n$ cat requests\n{ \"index\": \"my-index\" }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ \"index\": \"my-other-index\" }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}\n\n$ curl -H \"Content-Type: application/x-ndjson\" -XGET localhost:9200/_msearch/template --data-binary \"@requests\"; echo\n```", + "docId": "search-multi-search-template", "docTag": "search", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-multi-search.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/multi-search-template.html", "extDocId": "search-templates", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-template.html", "name": "msearch_template", @@ -13643,7 +13647,7 @@ "stability": "stable" } }, - "description": "Get multiple term vectors.\n\nGet multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.", + "description": "Get multiple term vectors.\n\nGet multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.\n\n**Artificial documents**\n\nYou can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request.\nThe mapping used is determined by the specified `_index`.", "docId": "docs-multi-termvectors", "docTag": "document", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-multi-termvectors.html", @@ -15213,11 +15217,17 @@ } }, "description": "Run a scrolling search.\n\nIMPORTANT: The scroll API is no longer recommend for deep pagination. If you need to preserve the index state while paging through more than 10,000 hits, use the `search_after` parameter with a point in time (PIT).\n\nThe scroll API gets large sets of results from a single scrolling search request.\nTo get the necessary scroll ID, submit a search API request that includes an argument for the `scroll` query parameter.\nThe `scroll` parameter indicates how long Elasticsearch should retain the search context for the request.\nThe search response returns a scroll ID in the `_scroll_id` response body parameter.\nYou can then use the scroll ID with the scroll API to retrieve the next batch of results for the request.\nIf the Elasticsearch security features are enabled, the access to the results of a specific scroll ID is restricted to the user or API key that submitted the search.\n\nYou can also use the scroll API to specify a new scroll parameter that extends or shortens the retention period for the search context.\n\nIMPORTANT: Results from a scrolling search reflect the state of the index at the time of the initial search request. Subsequent indexing or document changes only affect later search and scroll requests.", + "docId": "scroll-api", "docTag": "search", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/search-request-body.html#request-body-search-scroll", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/scroll-api.html", "extDocId": "scroll-search-results", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results", "name": "scroll", + "privileges": { + "index": [ + "read" + ] + }, "request": { "name": "Request", "namespace": "_global.scroll" @@ -15265,7 +15275,8 @@ } }, "description": "Run a search.\n\nGet search hits that match the query defined in the request.\nYou can provide search queries using the `q` query string parameter or the request body.\nIf both are specified, only the query parameter is used.\n\nIf the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.\nTo search a point in time (PIT) for an alias, you must have the `read` index privilege for the alias's data streams or indices.\n\n**Search slicing**\n\nWhen paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the `slice` and `pit` properties.\nBy default the splitting is done first on the shards, then locally on each shard.\nThe local splitting partitions the shard into contiguous ranges based on Lucene document IDs.\n\nFor instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.\n\nIMPORTANT: The same point-in-time ID should be used for all slices.\nIf different PIT IDs are used, slices can overlap and miss documents.\nThis situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/search-search.html", + "docId": "search-search", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-search.html", "extDocId": "ccs-privileges", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remote-clusters-cert.html#remote-clusters-privileges-ccs", "name": "search", @@ -15713,10 +15724,18 @@ "stability": "stable" } }, - "description": "Search a vector tile.\n\nSearch a vector tile for geospatial values.", + "description": "Search a vector tile.\n\nSearch a vector tile for geospatial values.\nBefore using this API, you should be familiar with the Mapbox vector tile specification.\nThe API returns results as a binary mapbox vector tile.\n\nInternally, Elasticsearch translates a vector tile search API request into a search containing:\n\n* A `geo_bounding_box` query on the ``. The query uses the `//` tile as a bounding box.\n* A `geotile_grid` or `geohex_grid` aggregation on the ``. The `grid_agg` parameter determines the aggregation type. The aggregation uses the `//` tile as a bounding box.\n* Optionally, a `geo_bounds` aggregation on the ``. The search only includes this aggregation if the `exact_bounds` parameter is `true`.\n* If the optional parameter `with_labels` is `true`, the internal search will include a dynamic runtime field that calls the `getLabelPosition` function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.\n\nFor example, Elasticsearch may translate a vector tile search API request with a `grid_agg` argument of `geotile` and an `exact_bounds` argument of `true` into the following search\n\n```\nGET my-index/_search\n{\n \"size\": 10000,\n \"query\": {\n \"geo_bounding_box\": {\n \"my-geo-field\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"aggregations\": {\n \"grid\": {\n \"geotile_grid\": {\n \"field\": \"my-geo-field\",\n \"precision\": 11,\n \"size\": 65536,\n \"bounds\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"bounds\": {\n \"geo_bounds\": {\n \"field\": \"my-geo-field\",\n \"wrap_longitude\": false\n }\n }\n }\n}\n```\n\nThe API returns results as a binary Mapbox vector tile.\nMapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:\n\n* A `hits` layer containing a feature for each `` value matching the `geo_bounding_box` query.\n* An `aggs` layer containing a feature for each cell of the `geotile_grid` or `geohex_grid`. The layer only contains features for cells with matching data.\n* A meta layer containing:\n * A feature containing a bounding box. By default, this is the bounding box of the tile.\n * Value ranges for any sub-aggregations on the `geotile_grid` or `geohex_grid`.\n * Metadata for the search.\n\nThe API only returns features that can display at its zoom level.\nFor example, if a polygon feature has no area at its zoom level, the API omits it.\nThe API returns errors as UTF-8 encoded JSON.\n\nIMPORTANT: You can specify several options for this API as either a query parameter or request body parameter.\nIf you specify both parameters, the query parameter takes precedence.\n\n**Grid precision for geotile**\n\nFor a `grid_agg` of `geotile`, you can use cells in the `aggs` layer as tiles for lower zoom levels.\n`grid_precision` represents the additional zoom levels available through these cells. The final precision is computed by as follows: ` + grid_precision`.\nFor example, if `` is 7 and `grid_precision` is 8, then the `geotile_grid` aggregation will use a precision of 15.\nThe maximum final precision is 29.\nThe `grid_precision` also determines the number of cells for the grid as follows: `(2^grid_precision) x (2^grid_precision)`.\nFor example, a value of 8 divides the tile into a grid of 256 x 256 cells.\nThe `aggs` layer only contains features for cells with matching data.\n\n**Grid precision for geohex**\n\nFor a `grid_agg` of `geohex`, Elasticsearch uses `` and `grid_precision` to calculate a final precision as follows: ` + grid_precision`.\n\nThis precision determines the H3 resolution of the hexagonal cells produced by the `geohex` aggregation.\nThe following table maps the H3 resolution for each precision.\nFor example, if `` is 3 and `grid_precision` is 3, the precision is 6.\nAt a precision of 6, hexagonal cells have an H3 resolution of 2.\nIf `` is 3 and `grid_precision` is 4, the precision is 7.\nAt a precision of 7, hexagonal cells have an H3 resolution of 3.\n\n| Precision | Unique tile bins | H3 resolution | Unique hex bins |\tRatio |\n| --------- | ---------------- | ------------- | ----------------| ----- |\n| 1 | 4 | 0 | 122 | 30.5 |\n| 2 | 16 | 0 | 122 | 7.625 |\n| 3 | 64 | 1 | 842 | 13.15625 |\n| 4 | 256 | 1 | 842 | 3.2890625 |\n| 5 | 1024 | 2 | 5882 | 5.744140625 |\n| 6 | 4096 | 2 | 5882 | 1.436035156 |\n| 7 | 16384 | 3 | 41162 | 2.512329102 |\n| 8 | 65536 | 3 | 41162 | 0.6280822754 |\n| 9 | 262144 | 4 | 288122 | 1.099098206 |\n| 10 | 1048576 | 4 | 288122 | 0.2747745514 |\n| 11 | 4194304 | 5 | 2016842 | 0.4808526039 |\n| 12 | 16777216 | 6 | 14117882 | 0.8414913416 |\n| 13 | 67108864 | 6 | 14117882 | 0.2103728354 |\n| 14 | 268435456 | 7 | 98825162 | 0.3681524172 |\n| 15 | 1073741824 | 8 | 691776122 | 0.644266719 |\n| 16 | 4294967296 | 8 | 691776122 | 0.1610666797 |\n| 17 | 17179869184 | 9 | 4842432842 | 0.2818666889 |\n| 18 | 68719476736 | 10 | 33897029882 | 0.4932667053 |\n| 19 | 274877906944 | 11 | 237279209162 | 0.8632167343 |\n| 20 | 1099511627776 | 11 | 237279209162 | 0.2158041836 |\n| 21 | 4398046511104 | 12 | 1660954464122 | 0.3776573213 |\n| 22 | 17592186044416 | 13 | 11626681248842 | 0.6609003122 |\n| 23 | 70368744177664 | 13 | 11626681248842 | 0.165225078 |\n| 24 | 281474976710656 | 14 | 81386768741882 | 0.2891438866 |\n| 25 | 1125899906842620 | 15 | 569707381193162 | 0.5060018015 |\n| 26 | 4503599627370500 | 15 | 569707381193162 | 0.1265004504 |\n| 27 | 18014398509482000 | 15 | 569707381193162 | 0.03162511259 |\n| 28 | 72057594037927900 | 15 | 569707381193162 | 0.007906278149 |\n| 29 | 288230376151712000 | 15 | 569707381193162 | 0.001976569537 |\n\nHexagonal cells don't align perfectly on a vector tile.\nSome cells may intersect more than one vector tile.\nTo compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level.\nElasticsearch uses the H3 resolution that is closest to the corresponding geotile density.", + "docId": "search-vector-tile-api", "docTag": "search", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/search-vector-tile-api.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-vector-tile-api.html", + "extDocId": "mapbox-vector-tile", + "extDocUrl": "https://github.com/mapbox/vector-tile-spec/blob/master/README.md", "name": "search_mvt", + "privileges": { + "index": [ + "read" + ] + }, "request": { "name": "Request", "namespace": "_global.search_mvt" @@ -20569,9 +20588,10 @@ "stability": "stable" } }, - "description": "Get terms in an index.\n\nDiscover terms that match a partial string in an index.\nThis \"terms enum\" API is designed for low-latency look-ups used in auto-complete scenarios.\n\nIf the `complete` property in the response is false, the returned terms set may be incomplete and should be treated as approximate.\nThis can occur due to a few reasons, such as a request timeout or a node error.\n\nNOTE: The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", + "description": "Get terms in an index.\n\nDiscover terms that match a partial string in an index.\nThis API is designed for low-latency look-ups used in auto-complete scenarios.\n\n> info\n> The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", + "docId": "search-terms-enum", "docTag": "search", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-terms-enum.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-terms-enum.html", "name": "terms_enum", "request": { "name": "Request", @@ -25603,7 +25623,7 @@ "since": "8.5.0" } }, - "description": "List of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.", + "description": "A list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.", "name": "fields", "required": false, "type": { @@ -25615,7 +25635,7 @@ } }, { - "description": "Allows to filter indices if the provided query rewrites to match_none on every shard.", + "description": "Filter indices if the provided query rewrites to `match_none` on every shard.\n\nIMPORTANT: The filtering is done on a best-effort basis, it uses index statistics and mappings to rewrite queries to `match_none` instead of fully running the request.\nFor instance a range query over a date field can rewrite to `match_none` if all documents within a shard (including deleted documents) are outside of the provided range.\nHowever, not all queries can rewrite to `match_none` so this API may return an index even if the provided filter matches no document.", "name": "index_filter", "required": false, "type": { @@ -25633,7 +25653,7 @@ "since": "7.12.0" } }, - "description": "Defines ad-hoc runtime fields in the request similar to the way it is done in search requests.\nThese fields exist only as part of the query and take precedence over fields defined with the same name in the index mappings.", + "description": "Define ad-hoc runtime fields in the request similar to the way it is done in search requests.\nThese fields exist only as part of the query and take precedence over fields defined with the same name in the index mappings.", "docId": "runtime-search-request", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/runtime-search-request.html", "name": "runtime_mappings", @@ -25661,7 +25681,7 @@ }, "path": [ { - "description": "Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.", + "description": "A comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.", "name": "index", "required": false, "type": { @@ -25688,7 +25708,7 @@ } }, { - "description": "Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as `open,hidden`.", + "description": "The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as `open,hidden`.", "name": "expand_wildcards", "required": false, "serverDefault": "open", @@ -25701,7 +25721,7 @@ } }, { - "description": "Comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.", + "description": "A comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported.", "name": "fields", "required": false, "type": { @@ -25745,7 +25765,7 @@ "since": "8.2.0" } }, - "description": "An optional set of filters: can include +metadata,-metadata,-nested,-multifield,-parent", + "description": "A comma-separated list of filters to apply to the response.", "name": "filters", "required": false, "type": { @@ -25763,7 +25783,7 @@ "since": "8.2.0" } }, - "description": "Only return results for fields that have one of the types in the list", + "description": "A comma-separated list of field types to include.\nAny fields that do not match one of these types will be excluded from the results.\nIt defaults to empty, meaning that all field types are returned.", "name": "types", "required": false, "type": { @@ -25797,7 +25817,7 @@ } } ], - "specLocation": "_global/field_caps/FieldCapabilitiesRequest.ts#L25-L111" + "specLocation": "_global/field_caps/FieldCapabilitiesRequest.ts#L25-L120" }, { "kind": "response", @@ -25805,6 +25825,7 @@ "kind": "properties", "properties": [ { + "description": "The list of indices where this field has the same type family, or null if all indices have the same type family for the field.", "name": "indices", "required": true, "type": { @@ -25854,7 +25875,7 @@ "name": "Response", "namespace": "_global.field_caps" }, - "specLocation": "_global/field_caps/FieldCapabilitiesResponse.ts#L24-L35" + "specLocation": "_global/field_caps/FieldCapabilitiesResponse.ts#L24-L38" }, { "kind": "interface", @@ -28613,9 +28634,10 @@ "kind": "properties", "properties": [ { - "description": "Indicates which source fields are returned for matching documents. These\nfields are returned in the hits._source property of the search response.", + "description": "Indicates which source fields are returned for matching documents. These\nfields are returned in the `hits._source` property of the search response.", "name": "_source", "required": false, + "serverDefault": "true", "type": { "kind": "instance_of", "type": { @@ -28625,7 +28647,7 @@ } }, { - "description": "The request returns doc values for field names matching these patterns\nin the hits.fields property of the response. Accepts wildcard (*) patterns.", + "description": "The request returns doc values for field names matching these patterns\nin the `hits.fields` property of the response.\nIt accepts wildcard (`*`) patterns.", "name": "docvalue_fields", "required": false, "type": { @@ -28640,7 +28662,7 @@ } }, { - "description": "List of stored fields to return as part of a hit. If no fields are specified,\nno stored fields are included in the response. If this field is specified, the _source\nparameter defaults to false. You can pass _source: true to return both source fields\nand stored fields in the search response.", + "description": "A list of stored fields to return as part of a hit. If no fields are specified,\nno stored fields are included in the response. If this field is specified, the `_source`\nparameter defaults to `false`. You can pass `_source: true` to return both source fields\nand stored fields in the search response.", "name": "stored_fields", "required": false, "type": { @@ -28652,7 +28674,7 @@ } }, { - "description": "The request returns values for field names matching these patterns\nin the hits.fields property of the response. Accepts wildcard (*) patterns.", + "description": "The request returns values for field names matching these patterns\nin the `hits.fields` property of the response.\nIt accepts wildcard (`*`) patterns.", "name": "fields", "required": false, "type": { @@ -28670,7 +28692,7 @@ "since": "8.2.0" } }, - "description": "Query to filter the documents that can match. The kNN search will return the top\n`k` documents that also match this filter. The value can be a single query or a\nlist of queries. If `filter` isn't provided, all documents are allowed to match.", + "description": "A query to filter the documents that can match. The kNN search will return the top\n`k` documents that also match this filter. The value can be a single query or a\nlist of queries. If `filter` isn't provided, all documents are allowed to match.", "name": "filter", "required": false, "type": { @@ -28697,7 +28719,7 @@ } }, { - "description": "kNN query to execute", + "description": "The kNN query to run.", "extDocId": "query-dsl-knn-query", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-knn-query.html", "name": "knn", @@ -28716,7 +28738,7 @@ "description": "The kNN search API has been replaced by the `knn` option in the search API.", "version": "8.4.0" }, - "description": "Run a knn search.\n\nNOTE: The kNN search API has been replaced by the `knn` option in the search API.\n\nPerform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents.\nGiven a query vector, the API finds the k closest vectors and returns those documents as search hits.\n\nElasticsearch uses the HNSW algorithm to support efficient kNN search.\nLike most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed.\nThis means the results returned are not always the true k closest neighbors.\n\nThe kNN search API supports restricting the search using a filter.\nThe search will return the top k documents that also match the filter query.", + "description": "Run a knn search.\n\nNOTE: The kNN search API has been replaced by the `knn` option in the search API.\n\nPerform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents.\nGiven a query vector, the API finds the k closest vectors and returns those documents as search hits.\n\nElasticsearch uses the HNSW algorithm to support efficient kNN search.\nLike most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed.\nThis means the results returned are not always the true k closest neighbors.\n\nThe kNN search API supports restricting the search using a filter.\nThe search will return the top k documents that also match the filter query.\n\nA kNN search response has the exact same structure as a search API response.\nHowever, certain sections have a meaning specific to kNN search:\n\n* The document `_score` is determined by the similarity between the query and document vector.\n* The `hits.total` object contains the total number of nearest neighbor candidates considered, which is `num_candidates * num_shards`. The `hits.total.relation` will always be `eq`, indicating an exact value.", "inherits": { "type": { "name": "RequestBase", @@ -28729,7 +28751,7 @@ }, "path": [ { - "description": "A comma-separated list of index names to search;\nuse `_all` or to perform the operation on all indices", + "description": "A comma-separated list of index names to search;\nuse `_all` or to perform the operation on all indices.", "name": "index", "required": true, "type": { @@ -28743,7 +28765,7 @@ ], "query": [ { - "description": "A comma-separated list of specific routing values", + "description": "A comma-separated list of specific routing values.", "name": "routing", "required": false, "type": { @@ -28755,7 +28777,7 @@ } } ], - "specLocation": "_global/knn_search/KnnSearchRequest.ts#L26-L96" + "specLocation": "_global/knn_search/KnnSearchRequest.ts#L26-L106" }, { "kind": "response", @@ -28763,7 +28785,7 @@ "kind": "properties", "properties": [ { - "description": "Milliseconds it took Elasticsearch to execute the request.", + "description": "The milliseconds it took Elasticsearch to run the request.", "name": "took", "required": true, "type": { @@ -28787,7 +28809,7 @@ } }, { - "description": "Contains a count of shards used for the request.", + "description": "A count of shards used for the request.", "name": "_shards", "required": true, "type": { @@ -28799,7 +28821,7 @@ } }, { - "description": "Contains returned documents and metadata.", + "description": "The returned documents and metadata.", "name": "hits", "required": true, "type": { @@ -28820,7 +28842,7 @@ } }, { - "description": "Contains field values for the documents. These fields\nmust be specified in the request using the `fields` parameter.", + "description": "The field values for the documents. These fields\nmust be specified in the request using the `fields` parameter.", "name": "fields", "required": false, "type": { @@ -28839,7 +28861,7 @@ } }, { - "description": "Highest returned document score. This value is null for requests\nthat do not sort by score.", + "description": "The highest returned document score. This value is null for requests\nthat do not sort by score.", "name": "max_score", "required": false, "type": { @@ -29094,7 +29116,7 @@ } ] }, - "description": "Get multiple documents.\n\nGet multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.", + "description": "Get multiple documents.\n\nGet multiple JSON documents by ID from one or more indices.\nIf you specify an index in the request URI, you only need to specify the document IDs in the request body.\nTo ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.\n\n**Filter source fields**\n\nBy default, the `_source` field is returned for every document (if stored).\nUse the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document.\nYou can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions.\n\n**Get stored fields**\n\nUse the `stored_fields` attribute to specify the set of stored fields you want to retrieve.\nAny requested fields that are not stored are ignored.\nYou can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions.", "inherits": { "type": { "name": "RequestBase", @@ -29245,7 +29267,7 @@ } } ], - "specLocation": "_global/mget/MultiGetRequest.ts#L25-L104" + "specLocation": "_global/mget/MultiGetRequest.ts#L25-L117" }, { "kind": "response", @@ -29253,6 +29275,7 @@ "kind": "properties", "properties": [ { + "description": "The response includes a docs array that contains the documents in the order specified in the request.\nThe structure of the returned documents is similar to that returned by the get API.\nIf there is a failure getting a particular document, the error is included in place of the document.", "name": "docs", "required": true, "type": { @@ -29287,7 +29310,7 @@ "name": "Response", "namespace": "_global.mget" }, - "specLocation": "_global/mget/MultiGetResponse.ts#L22-L26" + "specLocation": "_global/mget/MultiGetResponse.ts#L22-L31" }, { "kind": "type_alias", @@ -30362,7 +30385,7 @@ ], "body": { "kind": "value", - "codegenName": "search_templates", + "codegenName": "search_templates\nThe request body must be newline-delimited JSON (NDJSON) in the following format:\n\n```\n
\\n\n\\n\n
\\n\n\\n\n```\n\nEach `
` and `` pair represents a search request.\nThe `
` supports the same parameters as the multi search API's `
`.\nThe `` supports the same parameters as the search template API's request body.\n\nThe `
` contains the parameters used to limit or change the search.\nIt is required for each search body but can be empty `({})` or a blank line.\n\nThe `` contains the parameters for the search.", "value": { "kind": "array_of", "value": { @@ -30374,7 +30397,7 @@ } } }, - "description": "Run multiple templated searches.", + "description": "Run multiple templated searches.\n\nRun multiple templated searches with a single request.\nIf you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines.\nFor example:\n\n```\n$ cat requests\n{ \"index\": \"my-index\" }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ \"index\": \"my-other-index\" }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}\n\n$ curl -H \"Content-Type: application/x-ndjson\" -XGET localhost:9200/_msearch/template --data-binary \"@requests\"; echo\n```", "inherits": { "type": { "name": "RequestBase", @@ -30387,7 +30410,7 @@ }, "path": [ { - "description": "Comma-separated list of data streams, indices, and aliases to search.\nSupports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*`.", + "description": "A comma-separated list of data streams, indices, and aliases to search.\nIt supports wildcards (`*`).\nTo search all data streams and indices, omit this parameter or use `*`.", "name": "index", "required": false, "type": { @@ -30414,7 +30437,7 @@ } }, { - "description": "Maximum number of concurrent searches the API can run.", + "description": "The maximum number of concurrent searches the API can run.", "name": "max_concurrent_searches", "required": false, "type": { @@ -30426,7 +30449,7 @@ } }, { - "description": "The type of the search operation.\nAvailable options: `query_then_fetch`, `dfs_query_then_fetch`.", + "description": "The type of the search operation.", "name": "search_type", "required": false, "type": { @@ -30464,7 +30487,7 @@ } } ], - "specLocation": "_global/msearch_template/MultiSearchTemplateRequest.ts#L25-L72" + "specLocation": "_global/msearch_template/MultiSearchTemplateRequest.ts#L25-L105" }, { "kind": "type_alias", @@ -30528,7 +30551,7 @@ "name": "Response", "namespace": "_global.msearch_template" }, - "specLocation": "_global/msearch_template/MultiSearchTemplateResponse.ts#L22-L24" + "specLocation": "_global/msearch_template/MultiSearchTemplateResponse.ts#L22-L31" }, { "kind": "interface", @@ -30551,7 +30574,7 @@ } }, { - "description": "ID of the search template to use. If no source is specified,\nthis parameter is required.", + "description": "The ID of the search template to use. If no `source` is specified,\nthis parameter is required.", "name": "id", "required": false, "type": { @@ -30595,7 +30618,7 @@ } }, { - "description": "An inline search template. Supports the same parameters as the search API's\nrequest body. Also supports Mustache variables. If no id is specified, this\nparameter is required.", + "description": "An inline search template. Supports the same parameters as the search API's\nrequest body. It also supports Mustache variables. If no `id` is specified, this\nparameter is required.", "name": "source", "required": false, "type": { @@ -30816,7 +30839,7 @@ } ] }, - "description": "Get multiple term vectors.\n\nGet multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.", + "description": "Get multiple term vectors.\n\nGet multiple term vectors with a single request.\nYou can specify existing documents by index and ID or provide artificial documents in the body of the request.\nYou can specify the index in the request body or request URI.\nThe response contains a `docs` array with all the fetched termvectors.\nEach element has the structure provided by the termvectors API.\n\n**Artificial documents**\n\nYou can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request.\nThe mapping used is determined by the specified `_index`.", "inherits": { "type": { "name": "RequestBase", @@ -30998,7 +31021,7 @@ } } ], - "specLocation": "_global/mtermvectors/MultiTermVectorsRequest.ts#L31-L119" + "specLocation": "_global/mtermvectors/MultiTermVectorsRequest.ts#L31-L124" }, { "kind": "response", @@ -32067,7 +32090,7 @@ }, "path": [ { - "description": "Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard (`*`) expressions are supported.\nTo target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`.", + "description": "A comma-separated list of data streams, indices, and index aliases used to limit the request.\nWildcard (`*`) expressions are supported.\nTo target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`.", "name": "index", "required": false, "type": { @@ -32131,7 +32154,7 @@ } } ], - "specLocation": "_global/rank_eval/RankEvalRequest.ts#L24-L64" + "specLocation": "_global/rank_eval/RankEvalRequest.ts#L24-L65" }, { "kind": "response", @@ -33654,7 +33677,7 @@ "kind": "properties", "properties": [ { - "description": "Period to retain the search context for scrolling.", + "description": "The period to retain the search context for scrolling.", "docId": "scroll-search-results", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results", "name": "scroll", @@ -33669,7 +33692,7 @@ } }, { - "description": "Scroll ID of the search.", + "description": "The scroll ID of the search.", "name": "scroll_id", "required": true, "type": { @@ -33713,7 +33736,7 @@ ], "query": [ { - "description": "Period to retain the search context for scrolling.", + "description": "The period to retain the search context for scrolling.", "docId": "scroll-search-results", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results", "name": "scroll", @@ -33757,7 +33780,7 @@ } } ], - "specLocation": "_global/scroll/ScrollRequest.ts#L24-L75" + "specLocation": "_global/scroll/ScrollRequest.ts#L24-L77" }, { "kind": "response", @@ -34976,7 +34999,7 @@ } } ], - "specLocation": "_global/search/SearchRequest.ts#L54-L578" + "specLocation": "_global/search/SearchRequest.ts#L54-L579" }, { "kind": "response", @@ -40852,7 +40875,7 @@ "kind": "properties", "properties": [ { - "description": "Sub-aggregations for the geotile_grid.\n\nSupports the following aggregation types:\n- avg\n- cardinality\n- max\n- min\n- sum", + "description": "Sub-aggregations for the geotile_grid.\n\nIt supports the following aggregation types:\n\n- `avg`\n- `boxplot`\n- `cardinality`\n- `extended stats`\n- `max`\n- `median absolute deviation`\n- `min`\n- `percentile`\n- `percentile-rank`\n- `stats`\n- `sum`\n- `value count`\n\nThe aggregation names can't start with `_mvt_`. The `_mvt_` prefix is reserved for internal aggregations.", "name": "aggs", "required": false, "type": { @@ -40875,7 +40898,7 @@ } }, { - "description": "Size, in pixels, of a clipping buffer outside the tile. This allows renderers\nto avoid outline artifacts from geometries that extend past the extent of the tile.", + "description": "The size, in pixels, of a clipping buffer outside the tile. This allows renderers\nto avoid outline artifacts from geometries that extend past the extent of the tile.", "name": "buffer", "required": false, "serverDefault": 5, @@ -40888,7 +40911,7 @@ } }, { - "description": "If false, the meta layer’s feature is the bounding box of the tile.\nIf true, the meta layer’s feature is a bounding box resulting from a\ngeo_bounds aggregation. The aggregation runs on values that intersect\nthe // tile with wrap_longitude set to false. The resulting\nbounding box may be larger than the vector tile.", + "description": "If `false`, the meta layer's feature is the bounding box of the tile.\nIf `true`, the meta layer's feature is a bounding box resulting from a\n`geo_bounds` aggregation. The aggregation runs on values that intersect\nthe `//` tile with `wrap_longitude` set to `false`. The resulting\nbounding box may be larger than the vector tile.", "name": "exact_bounds", "required": false, "serverDefault": false, @@ -40901,7 +40924,7 @@ } }, { - "description": "Size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", + "description": "The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", "name": "extent", "required": false, "serverDefault": 4096, @@ -40914,7 +40937,7 @@ } }, { - "description": "Fields to return in the `hits` layer. Supports wildcards (`*`).\nThis parameter does not support fields with array values. Fields with array\nvalues may return inconsistent results.", + "description": "The fields to return in the `hits` layer.\nIt supports wildcards (`*`).\nThis parameter does not support fields with array values. Fields with array\nvalues may return inconsistent results.", "name": "fields", "required": false, "type": { @@ -40926,7 +40949,7 @@ } }, { - "description": "Aggregation used to create a grid for the `field`.", + "description": "The aggregation used to create a grid for the `field`.", "name": "grid_agg", "required": false, "type": { @@ -40938,7 +40961,7 @@ } }, { - "description": "Additional zoom levels available through the aggs layer. For example, if is 7\nand grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon’t include the aggs layer.", + "description": "Additional zoom levels available through the aggs layer. For example, if `` is `7`\nand `grid_precision` is `8`, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon't include the aggs layer.", "name": "grid_precision", "required": false, "serverDefault": 8, @@ -40951,7 +40974,7 @@ } }, { - "description": "Determines the geometry type for features in the aggs layer. In the aggs layer,\neach feature represents a geotile_grid cell. If 'grid' each feature is a Polygon\nof the cells bounding box. If 'point' each feature is a Point that is the centroid\nof the cell.", + "description": "Determines the geometry type for features in the aggs layer. In the aggs layer,\neach feature represents a `geotile_grid` cell. If `grid, each feature is a polygon\nof the cells bounding box. If `point`, each feature is a Point that is the centroid\nof the cell.", "name": "grid_type", "required": false, "serverDefault": "grid", @@ -40964,7 +40987,7 @@ } }, { - "description": "Query DSL used to filter documents for the search.", + "description": "The query DSL used to filter documents for the search.", "name": "query", "required": false, "type": { @@ -40988,7 +41011,7 @@ } }, { - "description": "Maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don’t include the hits layer.", + "description": "The maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don't include the hits layer.", "name": "size", "required": false, "serverDefault": 10000, @@ -41001,7 +41024,7 @@ } }, { - "description": "Sorts features in the hits layer. By default, the API calculates a bounding\nbox for each feature. It sorts features based on this box’s diagonal length,\nfrom longest to shortest.", + "description": "Sort the features in the hits layer. By default, the API calculates a bounding\nbox for each feature. It sorts features based on this box's diagonal length,\nfrom longest to shortest.", "name": "sort", "required": false, "type": { @@ -41013,7 +41036,7 @@ } }, { - "description": "Number of hits matching the query to count accurately. If `true`, the exact number\nof hits is returned at the cost of some performance. If `false`, the response does\nnot include the total number of hits matching the query.", + "description": "The number of hits matching the query to count accurately. If `true`, the exact number\nof hits is returned at the cost of some performance. If `false`, the response does\nnot include the total number of hits matching the query.", "name": "track_total_hits", "required": false, "serverDefault": "10000", @@ -41026,7 +41049,7 @@ } }, { - "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.", + "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.\n\n* `Point` and `MultiPoint` features will have one of the points selected.\n* `Polygon` and `MultiPolygon` features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.\n* `LineString` features will likewise provide a roughly central point selected from the triangle-tree.\n* The aggregation results will provide one central point for each aggregation bucket.\n\nAll attributes from the original features will also be copied to the new label features.\nIn addition, the new features will be distinguishable using the tag `_mvt_label_position`.", "name": "with_labels", "required": false, "type": { @@ -41039,7 +41062,7 @@ } ] }, - "description": "Search a vector tile.\n\nSearch a vector tile for geospatial values.", + "description": "Search a vector tile.\n\nSearch a vector tile for geospatial values.\nBefore using this API, you should be familiar with the Mapbox vector tile specification.\nThe API returns results as a binary mapbox vector tile.\n\nInternally, Elasticsearch translates a vector tile search API request into a search containing:\n\n* A `geo_bounding_box` query on the ``. The query uses the `//` tile as a bounding box.\n* A `geotile_grid` or `geohex_grid` aggregation on the ``. The `grid_agg` parameter determines the aggregation type. The aggregation uses the `//` tile as a bounding box.\n* Optionally, a `geo_bounds` aggregation on the ``. The search only includes this aggregation if the `exact_bounds` parameter is `true`.\n* If the optional parameter `with_labels` is `true`, the internal search will include a dynamic runtime field that calls the `getLabelPosition` function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.\n\nFor example, Elasticsearch may translate a vector tile search API request with a `grid_agg` argument of `geotile` and an `exact_bounds` argument of `true` into the following search\n\n```\nGET my-index/_search\n{\n \"size\": 10000,\n \"query\": {\n \"geo_bounding_box\": {\n \"my-geo-field\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"aggregations\": {\n \"grid\": {\n \"geotile_grid\": {\n \"field\": \"my-geo-field\",\n \"precision\": 11,\n \"size\": 65536,\n \"bounds\": {\n \"top_left\": {\n \"lat\": -40.979898069620134,\n \"lon\": -45\n },\n \"bottom_right\": {\n \"lat\": -66.51326044311186,\n \"lon\": 0\n }\n }\n }\n },\n \"bounds\": {\n \"geo_bounds\": {\n \"field\": \"my-geo-field\",\n \"wrap_longitude\": false\n }\n }\n }\n}\n```\n\nThe API returns results as a binary Mapbox vector tile.\nMapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:\n\n* A `hits` layer containing a feature for each `` value matching the `geo_bounding_box` query.\n* An `aggs` layer containing a feature for each cell of the `geotile_grid` or `geohex_grid`. The layer only contains features for cells with matching data.\n* A meta layer containing:\n * A feature containing a bounding box. By default, this is the bounding box of the tile.\n * Value ranges for any sub-aggregations on the `geotile_grid` or `geohex_grid`.\n * Metadata for the search.\n\nThe API only returns features that can display at its zoom level.\nFor example, if a polygon feature has no area at its zoom level, the API omits it.\nThe API returns errors as UTF-8 encoded JSON.\n\nIMPORTANT: You can specify several options for this API as either a query parameter or request body parameter.\nIf you specify both parameters, the query parameter takes precedence.\n\n**Grid precision for geotile**\n\nFor a `grid_agg` of `geotile`, you can use cells in the `aggs` layer as tiles for lower zoom levels.\n`grid_precision` represents the additional zoom levels available through these cells. The final precision is computed by as follows: ` + grid_precision`.\nFor example, if `` is 7 and `grid_precision` is 8, then the `geotile_grid` aggregation will use a precision of 15.\nThe maximum final precision is 29.\nThe `grid_precision` also determines the number of cells for the grid as follows: `(2^grid_precision) x (2^grid_precision)`.\nFor example, a value of 8 divides the tile into a grid of 256 x 256 cells.\nThe `aggs` layer only contains features for cells with matching data.\n\n**Grid precision for geohex**\n\nFor a `grid_agg` of `geohex`, Elasticsearch uses `` and `grid_precision` to calculate a final precision as follows: ` + grid_precision`.\n\nThis precision determines the H3 resolution of the hexagonal cells produced by the `geohex` aggregation.\nThe following table maps the H3 resolution for each precision.\nFor example, if `` is 3 and `grid_precision` is 3, the precision is 6.\nAt a precision of 6, hexagonal cells have an H3 resolution of 2.\nIf `` is 3 and `grid_precision` is 4, the precision is 7.\nAt a precision of 7, hexagonal cells have an H3 resolution of 3.\n\n| Precision | Unique tile bins | H3 resolution | Unique hex bins |\tRatio |\n| --------- | ---------------- | ------------- | ----------------| ----- |\n| 1 | 4 | 0 | 122 | 30.5 |\n| 2 | 16 | 0 | 122 | 7.625 |\n| 3 | 64 | 1 | 842 | 13.15625 |\n| 4 | 256 | 1 | 842 | 3.2890625 |\n| 5 | 1024 | 2 | 5882 | 5.744140625 |\n| 6 | 4096 | 2 | 5882 | 1.436035156 |\n| 7 | 16384 | 3 | 41162 | 2.512329102 |\n| 8 | 65536 | 3 | 41162 | 0.6280822754 |\n| 9 | 262144 | 4 | 288122 | 1.099098206 |\n| 10 | 1048576 | 4 | 288122 | 0.2747745514 |\n| 11 | 4194304 | 5 | 2016842 | 0.4808526039 |\n| 12 | 16777216 | 6 | 14117882 | 0.8414913416 |\n| 13 | 67108864 | 6 | 14117882 | 0.2103728354 |\n| 14 | 268435456 | 7 | 98825162 | 0.3681524172 |\n| 15 | 1073741824 | 8 | 691776122 | 0.644266719 |\n| 16 | 4294967296 | 8 | 691776122 | 0.1610666797 |\n| 17 | 17179869184 | 9 | 4842432842 | 0.2818666889 |\n| 18 | 68719476736 | 10 | 33897029882 | 0.4932667053 |\n| 19 | 274877906944 | 11 | 237279209162 | 0.8632167343 |\n| 20 | 1099511627776 | 11 | 237279209162 | 0.2158041836 |\n| 21 | 4398046511104 | 12 | 1660954464122 | 0.3776573213 |\n| 22 | 17592186044416 | 13 | 11626681248842 | 0.6609003122 |\n| 23 | 70368744177664 | 13 | 11626681248842 | 0.165225078 |\n| 24 | 281474976710656 | 14 | 81386768741882 | 0.2891438866 |\n| 25 | 1125899906842620 | 15 | 569707381193162 | 0.5060018015 |\n| 26 | 4503599627370500 | 15 | 569707381193162 | 0.1265004504 |\n| 27 | 18014398509482000 | 15 | 569707381193162 | 0.03162511259 |\n| 28 | 72057594037927900 | 15 | 569707381193162 | 0.007906278149 |\n| 29 | 288230376151712000 | 15 | 569707381193162 | 0.001976569537 |\n\nHexagonal cells don't align perfectly on a vector tile.\nSome cells may intersect more than one vector tile.\nTo compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level.\nElasticsearch uses the H3 resolution that is closest to the corresponding geotile density.", "inherits": { "type": { "name": "RequestBase", @@ -41114,7 +41137,7 @@ ], "query": [ { - "description": "If false, the meta layer’s feature is the bounding box of the tile.\nIf true, the meta layer’s feature is a bounding box resulting from a\ngeo_bounds aggregation. The aggregation runs on values that intersect\nthe // tile with wrap_longitude set to false. The resulting\nbounding box may be larger than the vector tile.", + "description": "If `false`, the meta layer's feature is the bounding box of the tile.\nIf true, the meta layer's feature is a bounding box resulting from a\ngeo_bounds aggregation. The aggregation runs on values that intersect\nthe // tile with wrap_longitude set to false. The resulting\nbounding box may be larger than the vector tile.", "name": "exact_bounds", "required": false, "serverDefault": false, @@ -41127,7 +41150,7 @@ } }, { - "description": "Size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", + "description": "The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.", "name": "extent", "required": false, "serverDefault": 4096, @@ -41152,7 +41175,7 @@ } }, { - "description": "Additional zoom levels available through the aggs layer. For example, if is 7\nand grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon’t include the aggs layer.", + "description": "Additional zoom levels available through the aggs layer. For example, if is 7\nand grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results\ndon't include the aggs layer.", "name": "grid_precision", "required": false, "serverDefault": 8, @@ -41178,7 +41201,7 @@ } }, { - "description": "Maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don’t include the hits layer.", + "description": "Maximum number of features to return in the hits layer. Accepts 0-10000.\nIf 0, results don't include the hits layer.", "name": "size", "required": false, "serverDefault": 10000, @@ -41191,7 +41214,7 @@ } }, { - "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.", + "description": "If `true`, the hits and aggs layers will contain additional point features representing\nsuggested label positions for the original features.\n\n* `Point` and `MultiPoint` features will have one of the points selected.\n* `Polygon` and `MultiPolygon` features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.\n* `LineString` features will likewise provide a roughly central point selected from the triangle-tree.\n* The aggregation results will provide one central point for each aggregation bucket.\n\nAll attributes from the original features will also be copied to the new label features.\nIn addition, the new features will be distinguishable using the tag `_mvt_label_position`.", "name": "with_labels", "required": false, "type": { @@ -41203,7 +41226,7 @@ } } ], - "specLocation": "_global/search_mvt/SearchMvtRequest.ts#L33-L193" + "specLocation": "_global/search_mvt/SearchMvtRequest.ts#L33-L367" }, { "kind": "response", @@ -42172,7 +42195,7 @@ } }, { - "description": "How many matching terms to return.", + "description": "The number of matching terms to return.", "name": "size", "required": false, "serverDefault": 10, @@ -42185,7 +42208,7 @@ } }, { - "description": "The maximum length of time to spend collecting results. Defaults to \"1s\" (one second). If the timeout is exceeded the complete flag set to false in the response and the results may be partial or empty.", + "description": "The maximum length of time to spend collecting results.\nIf the timeout is exceeded the `complete` flag set to `false` in the response and the results may be partial or empty.", "name": "timeout", "required": false, "serverDefault": "1s", @@ -42198,7 +42221,7 @@ } }, { - "description": "When true the provided search string is matched against index terms without case sensitivity.", + "description": "When `true`, the provided search string is matched against index terms without case sensitivity.", "name": "case_insensitive", "required": false, "serverDefault": false, @@ -42211,7 +42234,7 @@ } }, { - "description": "Allows to filter an index shard if the provided query rewrites to match_none.", + "description": "Filter an index shard if the provided query rewrites to `match_none`.", "docId": "query-dsl", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl.html", "name": "index_filter", @@ -42225,7 +42248,7 @@ } }, { - "description": "The string after which terms in the index should be returned. Allows for a form of pagination if the last result from one request is passed as the search_after parameter for a subsequent request.", + "description": "The string to match at the start of indexed terms.\nIf it is not provided, all terms in the field are considered.\n\n> info\n> The prefix string cannot be larger than the largest possible keyword value, which is Lucene's term byte-length limit of 32766.", "name": "string", "required": false, "type": { @@ -42237,6 +42260,7 @@ } }, { + "description": "The string after which terms in the index should be returned.\nIt allows for a form of pagination if the last result from one request is passed as the `search_after` parameter for a subsequent request.", "name": "search_after", "required": false, "type": { @@ -42249,7 +42273,7 @@ } ] }, - "description": "Get terms in an index.\n\nDiscover terms that match a partial string in an index.\nThis \"terms enum\" API is designed for low-latency look-ups used in auto-complete scenarios.\n\nIf the `complete` property in the response is false, the returned terms set may be incomplete and should be treated as approximate.\nThis can occur due to a few reasons, such as a request timeout or a node error.\n\nNOTE: The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", + "description": "Get terms in an index.\n\nDiscover terms that match a partial string in an index.\nThis API is designed for low-latency look-ups used in auto-complete scenarios.\n\n> info\n> The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.", "inherits": { "type": { "name": "RequestBase", @@ -42262,7 +42286,7 @@ }, "path": [ { - "description": "Comma-separated list of data streams, indices, and index aliases to search. Wildcard (*) expressions are supported.", + "description": "A comma-separated list of data streams, indices, and index aliases to search.\nWildcard (`*`) expressions are supported.\nTo search all data streams or indices, omit this parameter or use `*` or `_all`.", "name": "index", "required": true, "type": { @@ -42275,7 +42299,7 @@ } ], "query": [], - "specLocation": "_global/terms_enum/TermsEnumRequest.ts#L26-L75" + "specLocation": "_global/terms_enum/TermsEnumRequest.ts#L26-L87" }, { "kind": "response", @@ -42308,6 +42332,7 @@ } }, { + "description": "If `false`, the returned terms set may be incomplete and should be treated as approximate.\nThis can occur due to a few reasons, such as a request timeout or a node error.", "name": "complete", "required": true, "type": { @@ -42324,7 +42349,7 @@ "name": "Response", "namespace": "_global.terms_enum" }, - "specLocation": "_global/terms_enum/TermsEnumResponse.ts#L22-L28" + "specLocation": "_global/terms_enum/TermsEnumResponse.ts#L22-L32" }, { "kind": "interface", diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index c46e5f5a94..84268d7faa 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -300,6 +300,7 @@ logstash-centralized-pipeline-management,https://www.elastic.co/guide/en/logstas logstash-configuration-file-structure,https://www.elastic.co/guide/en/logstash/{branch}/configuration-file-structure.html logstash-logstash-settings-file,https://www.elastic.co/guide/en/logstash/{branch}/logstash-settings-file.html lowercase-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/lowercase-processor.html +mapbox-vector-tile,https://github.com/mapbox/vector-tile-spec/blob/master/README.md mapping-date-format,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-date-format.html mapping-meta-field,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-meta-field.html mapping-params,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-params.html @@ -504,6 +505,7 @@ script-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/d script-languages,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-script-languages-api.html script-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/script-processor.html script-put,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/create-stored-script-api.html +scroll-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/scroll-api.html scroll-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results search-after,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#search-after search-aggregations,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations.html @@ -592,8 +594,9 @@ search-render-query,https://www.elastic.co/guide/en/elasticsearch/reference/{bra search-count,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-count.html search-explain,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-explain.html search-field-caps,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-field-caps.html +search-knn,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/knn-search-api.html search-multi-search,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-multi-search.html -search-multi-search,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-multi-search.html +search-multi-search-template,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/multi-search-template.html search-rank-eval,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html search-rank-eval,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html search-request-body,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-request-body.html diff --git a/specification/_global/field_caps/FieldCapabilitiesRequest.ts b/specification/_global/field_caps/FieldCapabilitiesRequest.ts index 6715bd5a5b..d0f735f649 100644 --- a/specification/_global/field_caps/FieldCapabilitiesRequest.ts +++ b/specification/_global/field_caps/FieldCapabilitiesRequest.ts @@ -35,11 +35,12 @@ import { QueryContainer } from '@_types/query_dsl/abstractions' * @availability serverless stability=stable visibility=public * @index_privileges view_index_metadata,read * @doc_tag search + * @doc_id search-field-caps */ export interface Request extends RequestBase { path_parts: { /** - * Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all. + * A comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all. */ index?: Indices } @@ -52,12 +53,12 @@ export interface Request extends RequestBase { */ allow_no_indices?: boolean /** - * Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as `open,hidden`. + * The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as `open,hidden`. * @server_default open */ expand_wildcards?: ExpandWildcards /** - * Comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported. + * A comma-separated list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported. */ fields?: Fields /** @@ -71,11 +72,15 @@ export interface Request extends RequestBase { */ include_unmapped?: boolean /** + * A comma-separated list of filters to apply to the response. * @availability stack since=8.2.0 * @availability serverless */ filters?: string /** + * A comma-separated list of field types to include. + * Any fields that do not match one of these types will be excluded from the results. + * It defaults to empty, meaning that all field types are returned. * @availability stack since=8.2.0 * @availability serverless */ @@ -90,17 +95,21 @@ export interface Request extends RequestBase { } body: { /** - * List of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported. + * A list of fields to retrieve capabilities for. Wildcard (`*`) expressions are supported. * @availability stack since=8.5.0 * @availability serverless */ fields?: Fields /** - * Allows to filter indices if the provided query rewrites to match_none on every shard. + * Filter indices if the provided query rewrites to `match_none` on every shard. + * + * IMPORTANT: The filtering is done on a best-effort basis, it uses index statistics and mappings to rewrite queries to `match_none` instead of fully running the request. + * For instance a range query over a date field can rewrite to `match_none` if all documents within a shard (including deleted documents) are outside of the provided range. + * However, not all queries can rewrite to `match_none` so this API may return an index even if the provided filter matches no document. */ index_filter?: QueryContainer /** - * Defines ad-hoc runtime fields in the request similar to the way it is done in search requests. + * Define ad-hoc runtime fields in the request similar to the way it is done in search requests. * These fields exist only as part of the query and take precedence over fields defined with the same name in the index mappings. * @doc_id runtime-search-request * @availability stack since=7.12.0 diff --git a/specification/_global/field_caps/FieldCapabilitiesResponse.ts b/specification/_global/field_caps/FieldCapabilitiesResponse.ts index 009469a333..7d43b21dd5 100644 --- a/specification/_global/field_caps/FieldCapabilitiesResponse.ts +++ b/specification/_global/field_caps/FieldCapabilitiesResponse.ts @@ -29,6 +29,9 @@ import { FieldCapability } from './types' */ export class Response { body: { + /** + * The list of indices where this field has the same type family, or null if all indices have the same type family for the field. + */ indices: Indices fields: Dictionary> } diff --git a/specification/_global/field_caps/examples/request/FieldCapabilitiesRequestExample1.yaml b/specification/_global/field_caps/examples/request/FieldCapabilitiesRequestExample1.yaml new file mode 100644 index 0000000000..c0c631dbe9 --- /dev/null +++ b/specification/_global/field_caps/examples/request/FieldCapabilitiesRequestExample1.yaml @@ -0,0 +1,16 @@ +# summary: +# method_request: "POST my-index-*/_field_caps?fields=rating" +description: > + Run `POST my-index-*/_field_caps?fields=rating` to get field capabilities and filter indices with a query. + Indices that rewrite the provided filter to `match_none` on every shard will be filtered from the response. +# type: "request" +value: |- + { + "index_filter": { + "range": { + "@timestamp": { + "gte": "2018" + } + } + } + } diff --git a/specification/_global/field_caps/examples/response/FieldCapabilitiesResponseExample1.yaml b/specification/_global/field_caps/examples/response/FieldCapabilitiesResponseExample1.yaml new file mode 100644 index 0000000000..117cdd09a5 --- /dev/null +++ b/specification/_global/field_caps/examples/response/FieldCapabilitiesResponseExample1.yaml @@ -0,0 +1,38 @@ +summary: Get two fields +# type: "response" +description: > + A successful response from `GET _field_caps?fields=rating,title`. + The field `rating` is defined as a long in `index1` and `index2` and as a `keyword` in `index3` and `index4`. + The field `rating` is not aggregatable in `index1`. + The field `rating` is not searchable in `index4`. + The field `title` is defined as text in all indices. +# response_code: 200, +value: |- + { + "indices": [ "index1", "index2", "index3", "index4", "index5" ], + "fields": { + "rating": { + "long": { + "metadata_field": false, + "searchable": true, + "aggregatable": false, + "indices": [ "index1", "index2" ], + "non_aggregatable_indices": [ "index1" ] + }, + "keyword": { + "metadata_field": false, + "searchable": false, + "aggregatable": true, + "indices": [ "index3", "index4" ], + "non_searchable_indices": [ "index4" ] + } + }, + "title": { + "text": { + "metadata_field": false, + "searchable": true, + "aggregatable": false + } + } + } + } diff --git a/specification/_global/field_caps/examples/response/FieldCapabilitiesResponseExample2.yaml b/specification/_global/field_caps/examples/response/FieldCapabilitiesResponseExample2.yaml new file mode 100644 index 0000000000..fcbd78aeef --- /dev/null +++ b/specification/_global/field_caps/examples/response/FieldCapabilitiesResponseExample2.yaml @@ -0,0 +1,36 @@ +summary: Get unmapped fields +# type: "response" +description: > + A successful response from `GET _field_caps?fields=rating,title&include_unmapped`. + The response contains an entry for each field that is present in some indices but not all. + For example, the `rating` and `title` fields are unmapped in `index5`. +# response_code: 200, +value: |- + { + "indices": [ "index1", "index2", "index3", "index4", "index5" ], + "fields": { + "rating": { + "long": { + "metadata_field": false, + "searchable": true, + "aggregatable": false, + "indices": [ "index1", "index2" ], + "non_aggregatable_indices": [ "index1" ] + }, + "keyword": { + "metadata_field": false, + "searchable": false, + "aggregatable": true, + "indices": [ "index3", "index4" ], + "non_searchable_indices": [ "index4" ] + } + }, + "title": { + "text": { + "metadata_field": false, + "searchable": true, + "aggregatable": false + } + } + } + } diff --git a/specification/_global/knn_search/KnnSearchRequest.ts b/specification/_global/knn_search/KnnSearchRequest.ts index c708a05440..a1822b1d9a 100644 --- a/specification/_global/knn_search/KnnSearchRequest.ts +++ b/specification/_global/knn_search/KnnSearchRequest.ts @@ -37,50 +37,60 @@ import { Query } from './_types/Knn' * * The kNN search API supports restricting the search using a filter. * The search will return the top k documents that also match the filter query. + * + * A kNN search response has the exact same structure as a search API response. + * However, certain sections have a meaning specific to kNN search: + * + * * The document `_score` is determined by the similarity between the query and document vector. + * * The `hits.total` object contains the total number of nearest neighbor candidates considered, which is `num_candidates * num_shards`. The `hits.total.relation` will always be `eq`, indicating an exact value. * @rest_spec_name knn_search * @availability stack since=8.0.0 stability=experimental * @deprecated 8.4.0 The kNN search API has been replaced by the `knn` option in the search API. * @doc_tag search + * @doc_id search-knn */ export interface Request extends RequestBase { path_parts: { /** * A comma-separated list of index names to search; - * use `_all` or to perform the operation on all indices + * use `_all` or to perform the operation on all indices. */ index: Indices } query_parameters: { /** - * A comma-separated list of specific routing values + * A comma-separated list of specific routing values. */ routing?: Routing } body: { /** * Indicates which source fields are returned for matching documents. These - * fields are returned in the hits._source property of the search response. + * fields are returned in the `hits._source` property of the search response. + * @server_default true */ _source?: SourceConfig /** * The request returns doc values for field names matching these patterns - * in the hits.fields property of the response. Accepts wildcard (*) patterns. + * in the `hits.fields` property of the response. + * It accepts wildcard (`*`) patterns. */ docvalue_fields?: FieldAndFormat[] /** - * List of stored fields to return as part of a hit. If no fields are specified, - * no stored fields are included in the response. If this field is specified, the _source - * parameter defaults to false. You can pass _source: true to return both source fields + * A list of stored fields to return as part of a hit. If no fields are specified, + * no stored fields are included in the response. If this field is specified, the `_source` + * parameter defaults to `false`. You can pass `_source: true` to return both source fields * and stored fields in the search response. */ stored_fields?: Fields /** * The request returns values for field names matching these patterns - * in the hits.fields property of the response. Accepts wildcard (*) patterns. + * in the `hits.fields` property of the response. + * It accepts wildcard (`*`) patterns. */ fields?: Fields /** - * Query to filter the documents that can match. The kNN search will return the top + * A query to filter the documents that can match. The kNN search will return the top * `k` documents that also match this filter. The value can be a single query or a * list of queries. If `filter` isn't provided, all documents are allowed to match. * @availability stack since=8.2.0 @@ -88,7 +98,7 @@ export interface Request extends RequestBase { */ filter?: QueryContainer | QueryContainer[] /** - * kNN query to execute + * The kNN query to run. * @ext_doc_id query-dsl-knn-query */ knn: Query diff --git a/specification/_global/knn_search/KnnSearchResponse.ts b/specification/_global/knn_search/KnnSearchResponse.ts index 64dde26899..a6f4357800 100644 --- a/specification/_global/knn_search/KnnSearchResponse.ts +++ b/specification/_global/knn_search/KnnSearchResponse.ts @@ -25,7 +25,7 @@ import { ShardStatistics } from '@_types/Stats' export class Response { body: { - /** Milliseconds it took Elasticsearch to execute the request. */ + /** The milliseconds it took Elasticsearch to run the request. */ took: long /** * If true, the request timed out before completion; @@ -33,20 +33,20 @@ export class Response { */ timed_out: boolean /** - * Contains a count of shards used for the request. + * A count of shards used for the request. */ _shards: ShardStatistics /** - * Contains returned documents and metadata. + * The returned documents and metadata. */ hits: HitsMetadata /** - * Contains field values for the documents. These fields + * The field values for the documents. These fields * must be specified in the request using the `fields` parameter. */ fields?: Dictionary /** - * Highest returned document score. This value is null for requests + * The highest returned document score. This value is null for requests * that do not sort by score. */ max_score?: double diff --git a/specification/_global/mget/MultiGetRequest.ts b/specification/_global/mget/MultiGetRequest.ts index a76d011a63..b519b9dd71 100644 --- a/specification/_global/mget/MultiGetRequest.ts +++ b/specification/_global/mget/MultiGetRequest.ts @@ -28,11 +28,24 @@ import { Operation } from './types' * Get multiple JSON documents by ID from one or more indices. * If you specify an index in the request URI, you only need to specify the document IDs in the request body. * To ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail. + * + * **Filter source fields** + * + * By default, the `_source` field is returned for every document (if stored). + * Use the `_source` and `_source_include` or `source_exclude` attributes to filter what fields are returned for a particular document. + * You can include the `_source`, `_source_includes`, and `_source_excludes` query parameters in the request URI to specify the defaults to use when there are no per-document instructions. + * + * **Get stored fields** + * + * Use the `stored_fields` attribute to specify the set of stored fields you want to retrieve. + * Any requested fields that are not stored are ignored. + * You can include the `stored_fields` query parameter in the request URI to specify the defaults to use when there are no per-document instructions. * @rest_spec_name mget * @availability stack since=1.3.0 stability=stable * @availability serverless stability=stable visibility=public * @index_privileges read * @doc_tag document + * @doc_id docs-multi-get */ export interface Request extends RequestBase { path_parts: { diff --git a/specification/_global/mget/MultiGetResponse.ts b/specification/_global/mget/MultiGetResponse.ts index 52a52424ce..f463f6cba4 100644 --- a/specification/_global/mget/MultiGetResponse.ts +++ b/specification/_global/mget/MultiGetResponse.ts @@ -21,6 +21,11 @@ import { ResponseItem } from './types' export class Response { body: { + /** + * The response includes a docs array that contains the documents in the order specified in the request. + * The structure of the returned documents is similar to that returned by the get API. + * If there is a failure getting a particular document, the error is included in place of the document. + */ docs: ResponseItem[] } } diff --git a/specification/_global/mget/examples/request/MultiGetRequestExample1.yaml b/specification/_global/mget/examples/request/MultiGetRequestExample1.yaml new file mode 100644 index 0000000000..ede8f2ac7e --- /dev/null +++ b/specification/_global/mget/examples/request/MultiGetRequestExample1.yaml @@ -0,0 +1,17 @@ +summary: Get documents by ID +# method_request: "GET /my-index-000001/_mget" +description: > + Run `GET /my-index-000001/_mget`. + When you specify an index in the request URI, only the document IDs are required in the request body. +# type: "request" +value: |- + { + "docs": [ + { + "_id": "1" + }, + { + "_id": "2" + } + ] + } diff --git a/specification/_global/mget/examples/request/MultiGetRequestExample2.yaml b/specification/_global/mget/examples/request/MultiGetRequestExample2.yaml new file mode 100644 index 0000000000..b3e291ff59 --- /dev/null +++ b/specification/_global/mget/examples/request/MultiGetRequestExample2.yaml @@ -0,0 +1,31 @@ +summary: Filter source fields +# method_request: "GET /_mget" +description: > + Run `GET /_mget`. + This request sets `_source` to `false` for document 1 to exclude the source entirely. + It retrieves `field3` and `field4` from document 2. + It retrieves the `user` field from document 3 but filters out the `user.location` field. +# type: "request" +value: |- + { + "docs": [ + { + "_index": "test", + "_id": "1", + "_source": false + }, + { + "_index": "test", + "_id": "2", + "_source": [ "field3", "field4" ] + }, + { + "_index": "test", + "_id": "3", + "_source": { + "include": [ "user" ], + "exclude": [ "user.location" ] + } + } + ] + } diff --git a/specification/_global/mget/examples/request/MultiGetRequestExample3.yaml b/specification/_global/mget/examples/request/MultiGetRequestExample3.yaml new file mode 100644 index 0000000000..817ec01873 --- /dev/null +++ b/specification/_global/mget/examples/request/MultiGetRequestExample3.yaml @@ -0,0 +1,21 @@ +summary: Get stored fields +# method_request: "GET /_mget" +description: > + Run `GET /_mget`. + This request retrieves `field1` and `field2` from document 1 and `field3` and `field4` from document 2. +# type: "request" +value: |- + { + "docs": [ + { + "_index": "test", + "_id": "1", + "stored_fields": [ "field1", "field2" ] + }, + { + "_index": "test", + "_id": "2", + "stored_fields": [ "field3", "field4" ] + } + ] + } diff --git a/specification/_global/mget/examples/request/MultiGetRequestExample4.yaml b/specification/_global/mget/examples/request/MultiGetRequestExample4.yaml new file mode 100644 index 0000000000..93f3ea86d0 --- /dev/null +++ b/specification/_global/mget/examples/request/MultiGetRequestExample4.yaml @@ -0,0 +1,22 @@ +summary: Document routing +# method_request: "GET /_mget?routing=key1" +description: > + Run `GET /_mget?routing=key1`. + If routing is used during indexing, you need to specify the routing value to retrieve documents. + This request fetches `test/_doc/2` from the shard corresponding to routing key `key1`. + It fetches `test/_doc/1` from the shard corresponding to routing key `key2`. +# type: "request" +value: |- + { + "docs": [ + { + "_index": "test", + "_id": "1", + "routing": "key2" + }, + { + "_index": "test", + "_id": "2" + } + ] + } diff --git a/specification/_global/msearch_template/MultiSearchTemplateRequest.ts b/specification/_global/msearch_template/MultiSearchTemplateRequest.ts index 9c6552faf8..a28aa2d211 100644 --- a/specification/_global/msearch_template/MultiSearchTemplateRequest.ts +++ b/specification/_global/msearch_template/MultiSearchTemplateRequest.ts @@ -24,18 +24,33 @@ import { RequestItem } from './types' /** * Run multiple templated searches. + * + * Run multiple templated searches with a single request. + * If you are providing a text file or text input to `curl`, use the `--data-binary` flag instead of `-d` to preserve newlines. + * For example: + * + * ``` + * $ cat requests + * { "index": "my-index" } + * { "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }} + * { "index": "my-other-index" } + * { "id": "my-other-search-template", "params": { "query_type": "match_all" }} + * + * $ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/template --data-binary "@requests"; echo + * ``` * @rest_spec_name msearch_template * @availability stack since=5.0.0 stability=stable * @availability serverless stability=stable visibility=public * @index_privileges read * @doc_tag search + * @doc_id search-multi-search-template * @ext_doc_id search-templates */ export interface Request extends RequestBase { path_parts: { /** - * Comma-separated list of data streams, indices, and aliases to search. - * Supports wildcards (`*`). + * A comma-separated list of data streams, indices, and aliases to search. + * It supports wildcards (`*`). * To search all data streams and indices, omit this parameter or use `*`. */ index?: Indices @@ -47,12 +62,11 @@ export interface Request extends RequestBase { */ ccs_minimize_roundtrips?: boolean /** - * Maximum number of concurrent searches the API can run. + * The maximum number of concurrent searches the API can run. */ max_concurrent_searches?: long /** * The type of the search operation. - * Available options: `query_then_fetch`, `dfs_query_then_fetch`. */ search_type?: SearchType /** @@ -67,6 +81,25 @@ export interface Request extends RequestBase { */ typed_keys?: boolean } - /** @codegen_name search_templates */ + /** + * @codegen_name search_templates + * The request body must be newline-delimited JSON (NDJSON) in the following format: + * + * ``` + *
\n + * \n + *
\n + * \n + * ``` + * + * Each `
` and `` pair represents a search request. + * The `
` supports the same parameters as the multi search API's `
`. + * The `` supports the same parameters as the search template API's request body. + * + * The `
` contains the parameters used to limit or change the search. + * It is required for each search body but can be empty `({})` or a blank line. + * + * The `` contains the parameters for the search. + */ body: Array } diff --git a/specification/_global/msearch_template/MultiSearchTemplateResponse.ts b/specification/_global/msearch_template/MultiSearchTemplateResponse.ts index 59773f70db..9abc22d3a8 100644 --- a/specification/_global/msearch_template/MultiSearchTemplateResponse.ts +++ b/specification/_global/msearch_template/MultiSearchTemplateResponse.ts @@ -20,5 +20,12 @@ import { MultiSearchResult } from '@global/msearch/types' export class Response { + /** + * The API returns a 400 status code only if the request itself fails. + * If one or more searches in the request fail, the API returns a 200 status code with an error object for each failed search in the response. + * + * The body contains results for each search, returned in the order submitted. + * Each object uses the same properties as the search API's response. + */ body: MultiSearchResult } diff --git a/specification/_global/msearch_template/examples/request/MultiSearchTemplateRequestExample1.yaml b/specification/_global/msearch_template/examples/request/MultiSearchTemplateRequestExample1.yaml new file mode 100644 index 0000000000..6f8989aef1 --- /dev/null +++ b/specification/_global/msearch_template/examples/request/MultiSearchTemplateRequestExample1.yaml @@ -0,0 +1,9 @@ +# summary: +# method_request: GET my-index/_msearch/template +description: Run `GET my-index/_msearch/template` to run multiple templated searches. +# type: "request" +value: |- + { } + { "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }} + { } + { "id": "my-other-search-template", "params": { "query_type": "match_all" }} diff --git a/specification/_global/msearch_template/types.ts b/specification/_global/msearch_template/types.ts index 9796548f80..0ef505266d 100644 --- a/specification/_global/msearch_template/types.ts +++ b/specification/_global/msearch_template/types.ts @@ -31,7 +31,7 @@ export class TemplateConfig { * @server_default false */ explain?: boolean /** - * ID of the search template to use. If no source is specified, + * The ID of the search template to use. If no `source` is specified, * this parameter is required. */ id?: Id @@ -47,7 +47,7 @@ export class TemplateConfig { profile?: boolean /** * An inline search template. Supports the same parameters as the search API's - * request body. Also supports Mustache variables. If no id is specified, this + * request body. It also supports Mustache variables. If no `id` is specified, this * parameter is required. */ source?: string diff --git a/specification/_global/mtermvectors/MultiTermVectorsRequest.ts b/specification/_global/mtermvectors/MultiTermVectorsRequest.ts index 5c387eea01..7b734b1d30 100644 --- a/specification/_global/mtermvectors/MultiTermVectorsRequest.ts +++ b/specification/_global/mtermvectors/MultiTermVectorsRequest.ts @@ -36,6 +36,11 @@ import { Operation } from './types' * You can specify the index in the request body or request URI. * The response contains a `docs` array with all the fetched termvectors. * Each element has the structure provided by the termvectors API. + * + * **Artificial documents** + * + * You can also use `mtermvectors` to generate term vectors for artificial documents provided in the body of the request. + * The mapping used is determined by the specified `_index`. * @rest_spec_name mtermvectors * @availability stack stability=stable * @availability serverless stability=stable visibility=public diff --git a/specification/_global/mtermvectors/examples/request/MultiTermVectorsRequestExample1.yaml b/specification/_global/mtermvectors/examples/request/MultiTermVectorsRequestExample1.yaml index bc08a26724..910ac5ebef 100644 --- a/specification/_global/mtermvectors/examples/request/MultiTermVectorsRequestExample1.yaml +++ b/specification/_global/mtermvectors/examples/request/MultiTermVectorsRequestExample1.yaml @@ -1,9 +1,9 @@ -summary: Get multi term vectors -# method_request: POST /my-index-000001/_mtermvectors +summary: Get multiple term vectors +# method_request: "POST /my-index-000001/_mtermvectors" description: > Run `POST /my-index-000001/_mtermvectors`. - If you specify an index in the request URI, the index does not need to be specified for each documents in the request body. -# type: request + When you specify an index in the request URI, the index does not need to be specified for each documents in the request body. +# type: "request" value: |- { "docs": [ diff --git a/specification/_global/rank_eval/RankEvalRequest.ts b/specification/_global/rank_eval/RankEvalRequest.ts index f93bd9da7a..70d084772e 100644 --- a/specification/_global/rank_eval/RankEvalRequest.ts +++ b/specification/_global/rank_eval/RankEvalRequest.ts @@ -34,7 +34,8 @@ import { RankEvalMetric, RankEvalRequestItem } from './types' export interface Request extends RequestBase { path_parts: { /** - * Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard (`*`) expressions are supported. + * A comma-separated list of data streams, indices, and index aliases used to limit the request. + * Wildcard (`*`) expressions are supported. * To target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`. */ index?: Indices diff --git a/specification/_global/scroll/ScrollRequest.ts b/specification/_global/scroll/ScrollRequest.ts index 6643e5884f..ec8ef5fcba 100644 --- a/specification/_global/scroll/ScrollRequest.ts +++ b/specification/_global/scroll/ScrollRequest.ts @@ -39,7 +39,9 @@ import { Duration } from '@_types/Time' * @rest_spec_name scroll * @availability stack stability=stable * @availability serverless stability=stable visibility=public + * @index_privileges read * @doc_tag search + * @doc_id scroll-api * @ext_doc_id scroll-search-results */ export interface Request extends RequestBase { @@ -49,7 +51,7 @@ export interface Request extends RequestBase { } query_parameters: { /** - * Period to retain the search context for scrolling. + * The period to retain the search context for scrolling. * @doc_id scroll-search-results * @server_default 1d */ @@ -64,12 +66,12 @@ export interface Request extends RequestBase { } body: { /** - * Period to retain the search context for scrolling. + * The period to retain the search context for scrolling. * @doc_id scroll-search-results * @server_default 1d */ scroll?: Duration - /** Scroll ID of the search. */ + /** The scroll ID of the search. */ scroll_id: ScrollId } } diff --git a/specification/_global/scroll/examples/request/ScrollRequestExample1.yaml b/specification/_global/scroll/examples/request/ScrollRequestExample1.yaml new file mode 100644 index 0000000000..ae539ac6bc --- /dev/null +++ b/specification/_global/scroll/examples/request/ScrollRequestExample1.yaml @@ -0,0 +1,8 @@ +# +# method_request: "GET /_search/scroll" +description: Run `GET /_search/scroll` to get the next batch of results for a scrolling search. +# type: "request" +value: |- + { + "scroll_id" : "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==" + } diff --git a/specification/_global/search/SearchRequest.ts b/specification/_global/search/SearchRequest.ts index 925f0c233a..427da69c6e 100644 --- a/specification/_global/search/SearchRequest.ts +++ b/specification/_global/search/SearchRequest.ts @@ -76,6 +76,7 @@ import { Suggester } from './_types/suggester' * @availability stack stability=stable * @availability serverless stability=stable visibility=public * @index_privileges read + * @doc_id search-search * @ext_doc_id ccs-privileges */ export interface Request extends RequestBase { diff --git a/specification/_global/search_mvt/SearchMvtRequest.ts b/specification/_global/search_mvt/SearchMvtRequest.ts index d8db29efc2..72960da5d7 100644 --- a/specification/_global/search_mvt/SearchMvtRequest.ts +++ b/specification/_global/search_mvt/SearchMvtRequest.ts @@ -34,29 +34,176 @@ import { ZoomLevel } from './_types/ZoomLevel' * Search a vector tile. * * Search a vector tile for geospatial values. + * Before using this API, you should be familiar with the Mapbox vector tile specification. + * The API returns results as a binary mapbox vector tile. + * + * Internally, Elasticsearch translates a vector tile search API request into a search containing: + * + * * A `geo_bounding_box` query on the ``. The query uses the `//` tile as a bounding box. + * * A `geotile_grid` or `geohex_grid` aggregation on the ``. The `grid_agg` parameter determines the aggregation type. The aggregation uses the `//` tile as a bounding box. + * * Optionally, a `geo_bounds` aggregation on the ``. The search only includes this aggregation if the `exact_bounds` parameter is `true`. + * * If the optional parameter `with_labels` is `true`, the internal search will include a dynamic runtime field that calls the `getLabelPosition` function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label. + * + * For example, Elasticsearch may translate a vector tile search API request with a `grid_agg` argument of `geotile` and an `exact_bounds` argument of `true` into the following search + * + * ``` + * GET my-index/_search + * { + * "size": 10000, + * "query": { + * "geo_bounding_box": { + * "my-geo-field": { + * "top_left": { + * "lat": -40.979898069620134, + * "lon": -45 + * }, + * "bottom_right": { + * "lat": -66.51326044311186, + * "lon": 0 + * } + * } + * } + * }, + * "aggregations": { + * "grid": { + * "geotile_grid": { + * "field": "my-geo-field", + * "precision": 11, + * "size": 65536, + * "bounds": { + * "top_left": { + * "lat": -40.979898069620134, + * "lon": -45 + * }, + * "bottom_right": { + * "lat": -66.51326044311186, + * "lon": 0 + * } + * } + * } + * }, + * "bounds": { + * "geo_bounds": { + * "field": "my-geo-field", + * "wrap_longitude": false + * } + * } + * } + * } + * ``` + * + * The API returns results as a binary Mapbox vector tile. + * Mapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers: + * + * * A `hits` layer containing a feature for each `` value matching the `geo_bounding_box` query. + * * An `aggs` layer containing a feature for each cell of the `geotile_grid` or `geohex_grid`. The layer only contains features for cells with matching data. + * * A meta layer containing: + * * A feature containing a bounding box. By default, this is the bounding box of the tile. + * * Value ranges for any sub-aggregations on the `geotile_grid` or `geohex_grid`. + * * Metadata for the search. + * + * The API only returns features that can display at its zoom level. + * For example, if a polygon feature has no area at its zoom level, the API omits it. + * The API returns errors as UTF-8 encoded JSON. + * + * IMPORTANT: You can specify several options for this API as either a query parameter or request body parameter. + * If you specify both parameters, the query parameter takes precedence. + * + * **Grid precision for geotile** + * + * For a `grid_agg` of `geotile`, you can use cells in the `aggs` layer as tiles for lower zoom levels. + * `grid_precision` represents the additional zoom levels available through these cells. The final precision is computed by as follows: ` + grid_precision`. + * For example, if `` is 7 and `grid_precision` is 8, then the `geotile_grid` aggregation will use a precision of 15. + * The maximum final precision is 29. + * The `grid_precision` also determines the number of cells for the grid as follows: `(2^grid_precision) x (2^grid_precision)`. + * For example, a value of 8 divides the tile into a grid of 256 x 256 cells. + * The `aggs` layer only contains features for cells with matching data. + * + * **Grid precision for geohex** + * + * For a `grid_agg` of `geohex`, Elasticsearch uses `` and `grid_precision` to calculate a final precision as follows: ` + grid_precision`. + * + * This precision determines the H3 resolution of the hexagonal cells produced by the `geohex` aggregation. + * The following table maps the H3 resolution for each precision. + * For example, if `` is 3 and `grid_precision` is 3, the precision is 6. + * At a precision of 6, hexagonal cells have an H3 resolution of 2. + * If `` is 3 and `grid_precision` is 4, the precision is 7. + * At a precision of 7, hexagonal cells have an H3 resolution of 3. + * + * | Precision | Unique tile bins | H3 resolution | Unique hex bins | Ratio | + * | --------- | ---------------- | ------------- | ----------------| ----- | + * | 1 | 4 | 0 | 122 | 30.5 | + * | 2 | 16 | 0 | 122 | 7.625 | + * | 3 | 64 | 1 | 842 | 13.15625 | + * | 4 | 256 | 1 | 842 | 3.2890625 | + * | 5 | 1024 | 2 | 5882 | 5.744140625 | + * | 6 | 4096 | 2 | 5882 | 1.436035156 | + * | 7 | 16384 | 3 | 41162 | 2.512329102 | + * | 8 | 65536 | 3 | 41162 | 0.6280822754 | + * | 9 | 262144 | 4 | 288122 | 1.099098206 | + * | 10 | 1048576 | 4 | 288122 | 0.2747745514 | + * | 11 | 4194304 | 5 | 2016842 | 0.4808526039 | + * | 12 | 16777216 | 6 | 14117882 | 0.8414913416 | + * | 13 | 67108864 | 6 | 14117882 | 0.2103728354 | + * | 14 | 268435456 | 7 | 98825162 | 0.3681524172 | + * | 15 | 1073741824 | 8 | 691776122 | 0.644266719 | + * | 16 | 4294967296 | 8 | 691776122 | 0.1610666797 | + * | 17 | 17179869184 | 9 | 4842432842 | 0.2818666889 | + * | 18 | 68719476736 | 10 | 33897029882 | 0.4932667053 | + * | 19 | 274877906944 | 11 | 237279209162 | 0.8632167343 | + * | 20 | 1099511627776 | 11 | 237279209162 | 0.2158041836 | + * | 21 | 4398046511104 | 12 | 1660954464122 | 0.3776573213 | + * | 22 | 17592186044416 | 13 | 11626681248842 | 0.6609003122 | + * | 23 | 70368744177664 | 13 | 11626681248842 | 0.165225078 | + * | 24 | 281474976710656 | 14 | 81386768741882 | 0.2891438866 | + * | 25 | 1125899906842620 | 15 | 569707381193162 | 0.5060018015 | + * | 26 | 4503599627370500 | 15 | 569707381193162 | 0.1265004504 | + * | 27 | 18014398509482000 | 15 | 569707381193162 | 0.03162511259 | + * | 28 | 72057594037927900 | 15 | 569707381193162 | 0.007906278149 | + * | 29 | 288230376151712000 | 15 | 569707381193162 | 0.001976569537 | + * + * Hexagonal cells don't align perfectly on a vector tile. + * Some cells may intersect more than one vector tile. + * To compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level. + * Elasticsearch uses the H3 resolution that is closest to the corresponding geotile density. * @rest_spec_name search_mvt * @availability stack since=7.15.0 stability=stable * @availability serverless stability=stable visibility=public + * @index_privileges read * @doc_tag search - * + * @doc_id search-vector-tile-api + * @ext_doc_id mapbox-vector-tile */ export interface Request extends RequestBase { path_parts: { - /* List of indices, data streams, or aliases to search */ + /* + * A list of indices, data streams, or aliases to search. + * It supports wildcards (`*`). + * To search all data streams and indices, omit this parameter or use `*` or `_all`. + * To search a remote cluster, use the `:` syntax. + */ index: Indices - /* Field containing geospatial data to return */ + /* + * A field that contains the geospatial data to return. + * It must be a `geo_point` or `geo_shape` field. + * The field must have doc values enabled. It cannot be a nested field. + * + * NOTE: Vector tiles do not natively support geometry collections. + * For `geometrycollection` values in a `geo_shape` field, the API returns a hits layer feature for each element of the collection. + * This behavior may change in a future release. + */ field: Field - /* Zoom level of the vector tile to search */ + /* The zoom level of the vector tile to search. It accepts `0` to `29`. */ zoom: ZoomLevel - /* X coordinate for the vector tile to search */ + /* The X coordinate for the vector tile to search. */ x: Coordinate - /* Y coordinate for the vector tile to search */ + /* The Y coordinate for the vector tile to search. */ y: Coordinate } query_parameters: { /** - * If false, the meta layer’s feature is the bounding box of the tile. - * If true, the meta layer’s feature is a bounding box resulting from a + * If `false`, the meta layer's feature is the bounding box of the tile. + * If true, the meta layer's feature is a bounding box resulting from a * geo_bounds aggregation. The aggregation runs on values that intersect * the // tile with wrap_longitude set to false. The resulting * bounding box may be larger than the vector tile. @@ -64,7 +211,7 @@ export interface Request extends RequestBase { */ exact_bounds?: boolean /** - * Size, in pixels, of a side of the tile. Vector tiles are square with equal sides. + * The size, in pixels, of a side of the tile. Vector tiles are square with equal sides. * @server_default 4096 */ extent?: integer @@ -75,7 +222,7 @@ export interface Request extends RequestBase { /** * Additional zoom levels available through the aggs layer. For example, if is 7 * and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results - * don’t include the aggs layer. + * don't include the aggs layer. * @server_default 8 */ grid_precision?: integer @@ -89,13 +236,21 @@ export interface Request extends RequestBase { grid_type?: GridType /** * Maximum number of features to return in the hits layer. Accepts 0-10000. - * If 0, results don’t include the hits layer. + * If 0, results don't include the hits layer. * @server_default 10000 */ size?: integer /** * If `true`, the hits and aggs layers will contain additional point features representing * suggested label positions for the original features. + * + * * `Point` and `MultiPoint` features will have one of the points selected. + * * `Polygon` and `MultiPolygon` features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree. + * * `LineString` features will likewise provide a roughly central point selected from the triangle-tree. + * * The aggregation results will provide one central point for each aggregation bucket. + * + * All attributes from the original features will also be copied to the new label features. + * In addition, the new features will be distinguishable using the tag `_mvt_label_position`. */ with_labels?: boolean } @@ -103,61 +258,72 @@ export interface Request extends RequestBase { /** * Sub-aggregations for the geotile_grid. * - * Supports the following aggregation types: - * - avg - * - cardinality - * - max - * - min - * - sum + * It supports the following aggregation types: + * + * - `avg` + * - `boxplot` + * - `cardinality` + * - `extended stats` + * - `max` + * - `median absolute deviation` + * - `min` + * - `percentile` + * - `percentile-rank` + * - `stats` + * - `sum` + * - `value count` + * + * The aggregation names can't start with `_mvt_`. The `_mvt_` prefix is reserved for internal aggregations. */ aggs?: Dictionary /** - * Size, in pixels, of a clipping buffer outside the tile. This allows renderers + * The size, in pixels, of a clipping buffer outside the tile. This allows renderers * to avoid outline artifacts from geometries that extend past the extent of the tile. * @server_default 5 */ buffer?: integer /** - * If false, the meta layer’s feature is the bounding box of the tile. - * If true, the meta layer’s feature is a bounding box resulting from a - * geo_bounds aggregation. The aggregation runs on values that intersect - * the // tile with wrap_longitude set to false. The resulting + * If `false`, the meta layer's feature is the bounding box of the tile. + * If `true`, the meta layer's feature is a bounding box resulting from a + * `geo_bounds` aggregation. The aggregation runs on values that intersect + * the `//` tile with `wrap_longitude` set to `false`. The resulting * bounding box may be larger than the vector tile. * @server_default false */ exact_bounds?: boolean /** - * Size, in pixels, of a side of the tile. Vector tiles are square with equal sides. + * The size, in pixels, of a side of the tile. Vector tiles are square with equal sides. * @server_default 4096 */ extent?: integer /** - * Fields to return in the `hits` layer. Supports wildcards (`*`). + * The fields to return in the `hits` layer. + * It supports wildcards (`*`). * This parameter does not support fields with array values. Fields with array * values may return inconsistent results. */ fields?: Fields /** - * Aggregation used to create a grid for the `field`. + * The aggregation used to create a grid for the `field`. */ grid_agg?: GridAggregationType /** - * Additional zoom levels available through the aggs layer. For example, if is 7 - * and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results - * don’t include the aggs layer. + * Additional zoom levels available through the aggs layer. For example, if `` is `7` + * and `grid_precision` is `8`, you can zoom in up to level 15. Accepts 0-8. If 0, results + * don't include the aggs layer. * @server_default 8 */ grid_precision?: integer /** * Determines the geometry type for features in the aggs layer. In the aggs layer, - * each feature represents a geotile_grid cell. If 'grid' each feature is a Polygon - * of the cells bounding box. If 'point' each feature is a Point that is the centroid + * each feature represents a `geotile_grid` cell. If `grid, each feature is a polygon + * of the cells bounding box. If `point`, each feature is a Point that is the centroid * of the cell. * @server_default grid */ grid_type?: GridType /** - * Query DSL used to filter documents for the search. + * The query DSL used to filter documents for the search. */ query?: QueryContainer /** @@ -166,19 +332,19 @@ export interface Request extends RequestBase { */ runtime_mappings?: RuntimeFields /** - * Maximum number of features to return in the hits layer. Accepts 0-10000. - * If 0, results don’t include the hits layer. + * The maximum number of features to return in the hits layer. Accepts 0-10000. + * If 0, results don't include the hits layer. * @server_default 10000 */ size?: integer /** - * Sorts features in the hits layer. By default, the API calculates a bounding - * box for each feature. It sorts features based on this box’s diagonal length, + * Sort the features in the hits layer. By default, the API calculates a bounding + * box for each feature. It sorts features based on this box's diagonal length, * from longest to shortest. */ sort?: Sort /** - * Number of hits matching the query to count accurately. If `true`, the exact number + * The number of hits matching the query to count accurately. If `true`, the exact number * of hits is returned at the cost of some performance. If `false`, the response does * not include the total number of hits matching the query. * @server_default 10000 @@ -187,6 +353,14 @@ export interface Request extends RequestBase { /** * If `true`, the hits and aggs layers will contain additional point features representing * suggested label positions for the original features. + * + * * `Point` and `MultiPoint` features will have one of the points selected. + * * `Polygon` and `MultiPolygon` features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree. + * * `LineString` features will likewise provide a roughly central point selected from the triangle-tree. + * * The aggregation results will provide one central point for each aggregation bucket. + * + * All attributes from the original features will also be copied to the new label features. + * In addition, the new features will be distinguishable using the tag `_mvt_label_position`. */ with_labels?: boolean } diff --git a/specification/_global/search_mvt/examples/request/SearchMvtRequestExample1.yaml b/specification/_global/search_mvt/examples/request/SearchMvtRequestExample1.yaml new file mode 100644 index 0000000000..ccb46be8e0 --- /dev/null +++ b/specification/_global/search_mvt/examples/request/SearchMvtRequestExample1.yaml @@ -0,0 +1,36 @@ +# summary: +# method_request: "GET museums/_mvt/location/13/4207/2692" +description: > + Run `GET museums/_mvt/location/13/4207/2692` to search an index for `location` values that intersect the `13/4207/2692` vector tile. +# type: "request" +value: |- + { + "grid_agg": "geotile", + "grid_precision": 2, + "fields": [ + "name", + "price" + ], + "query": { + "term": { + "included": true + } + }, + "aggs": { + "min_price": { + "min": { + "field": "price" + } + }, + "max_price": { + "max": { + "field": "price" + } + }, + "avg_price": { + "avg": { + "field": "price" + } + } + } + } diff --git a/specification/_global/search_mvt/examples/response/SearchMvtResponseExample1.yaml b/specification/_global/search_mvt/examples/response/SearchMvtResponseExample1.yaml new file mode 100644 index 0000000000..8fbf08ded2 --- /dev/null +++ b/specification/_global/search_mvt/examples/response/SearchMvtResponseExample1.yaml @@ -0,0 +1,173 @@ +# summary: +description: > + A successful response from `GET museums/_mvt/location/13/4207/2692`. + It returns results as a binary vector tile. + When decoded into JSON, the tile contains the following data. +# type: "response", +# response_code: 200, +value: |- + { + "hits": { + "extent": 4096, + "version": 2, + "features": [ + { + "geometry": { + "type": "Point", + "coordinates": [ + 3208, + 3864 + ] + }, + "properties": { + "_id": "1", + "_index": "museums", + "name": "NEMO Science Museum", + "price": 1750 + }, + "type": 1 + }, + { + "geometry": { + "type": "Point", + "coordinates": [ + 3429, + 3496 + ] + }, + "properties": { + "_id": "3", + "_index": "museums", + "name": "Nederlands Scheepvaartmuseum", + "price": 1650 + }, + "type": 1 + }, + { + "geometry": { + "type": "Point", + "coordinates": [ + 3429, + 3496 + ] + }, + "properties": { + "_id": "4", + "_index": "museums", + "name": "Amsterdam Centre for Architecture", + "price": 0 + }, + "type": 1 + } + ] + }, + "aggs": { + "extent": 4096, + "version": 2, + "features": [ + { + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + 3072, + 3072 + ], + [ + 4096, + 3072 + ], + [ + 4096, + 4096 + ], + [ + 3072, + 4096 + ], + [ + 3072, + 3072 + ] + ] + ] + }, + "properties": { + "_count": 3, + "max_price.value": 1750.0, + "min_price.value": 0.0, + "avg_price.value": 1133.3333333333333 + }, + "type": 3 + } + ] + }, + "meta": { + "extent": 4096, + "version": 2, + "features": [ + { + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + 0, + 0 + ], + [ + 4096, + 0 + ], + [ + 4096, + 4096 + ], + [ + 0, + 4096 + ], + [ + 0, + 0 + ] + ] + ] + }, + "properties": { + "_shards.failed": 0, + "_shards.skipped": 0, + "_shards.successful": 1, + "_shards.total": 1, + "aggregations._count.avg": 3.0, + "aggregations._count.count": 1, + "aggregations._count.max": 3.0, + "aggregations._count.min": 3.0, + "aggregations._count.sum": 3.0, + "aggregations.avg_price.avg": 1133.3333333333333, + "aggregations.avg_price.count": 1, + "aggregations.avg_price.max": 1133.3333333333333, + "aggregations.avg_price.min": 1133.3333333333333, + "aggregations.avg_price.sum": 1133.3333333333333, + "aggregations.max_price.avg": 1750.0, + "aggregations.max_price.count": 1, + "aggregations.max_price.max": 1750.0, + "aggregations.max_price.min": 1750.0, + "aggregations.max_price.sum": 1750.0, + "aggregations.min_price.avg": 0.0, + "aggregations.min_price.count": 1, + "aggregations.min_price.max": 0.0, + "aggregations.min_price.min": 0.0, + "aggregations.min_price.sum": 0.0, + "hits.max_score": 0.0, + "hits.total.relation": "eq", + "hits.total.value": 3, + "timed_out": false, + "took": 2 + }, + "type": 3 + } + ] + } + } diff --git a/specification/_global/terms_enum/TermsEnumRequest.ts b/specification/_global/terms_enum/TermsEnumRequest.ts index c2aae9ee99..60a8365290 100644 --- a/specification/_global/terms_enum/TermsEnumRequest.ts +++ b/specification/_global/terms_enum/TermsEnumRequest.ts @@ -27,49 +27,61 @@ import { Duration } from '@_types/Time' * Get terms in an index. * * Discover terms that match a partial string in an index. - * This "terms enum" API is designed for low-latency look-ups used in auto-complete scenarios. + * This API is designed for low-latency look-ups used in auto-complete scenarios. * - * If the `complete` property in the response is false, the returned terms set may be incomplete and should be treated as approximate. - * This can occur due to a few reasons, such as a request timeout or a node error. - * - * NOTE: The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents. + * > info + * > The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents. * @rest_spec_name terms_enum * @availability stack since=7.14.0 stability=stable * @availability serverless stability=stable visibility=public * @doc_tag search + * @doc_id search-terms-enum */ export interface Request extends RequestBase { path_parts: { - /** Comma-separated list of data streams, indices, and index aliases to search. Wildcard (*) expressions are supported. */ + /** + * A comma-separated list of data streams, indices, and index aliases to search. + * Wildcard (`*`) expressions are supported. + * To search all data streams or indices, omit this parameter or use `*` or `_all`. + */ index: IndexName } body: { /** The string to match at the start of indexed terms. If not provided, all terms in the field are considered. */ field: Field /** - * How many matching terms to return. + * The number of matching terms to return. * @server_default 10 */ size?: integer /** - * The maximum length of time to spend collecting results. Defaults to "1s" (one second). If the timeout is exceeded the complete flag set to false in the response and the results may be partial or empty. + * The maximum length of time to spend collecting results. + * If the timeout is exceeded the `complete` flag set to `false` in the response and the results may be partial or empty. * @server_default 1s */ timeout?: Duration /** - * When true the provided search string is matched against index terms without case sensitivity. + * When `true`, the provided search string is matched against index terms without case sensitivity. * @server_default false */ case_insensitive?: boolean /** - * Allows to filter an index shard if the provided query rewrites to match_none. + * Filter an index shard if the provided query rewrites to `match_none`. * @doc_id query-dsl */ index_filter?: QueryContainer /** - * The string after which terms in the index should be returned. Allows for a form of pagination if the last result from one request is passed as the search_after parameter for a subsequent request. + * The string to match at the start of indexed terms. + * If it is not provided, all terms in the field are considered. + * + * > info + * > The prefix string cannot be larger than the largest possible keyword value, which is Lucene's term byte-length limit of 32766. */ string?: string + /** + * The string after which terms in the index should be returned. + * It allows for a form of pagination if the last result from one request is passed as the `search_after` parameter for a subsequent request. + */ search_after?: string } } diff --git a/specification/_global/terms_enum/TermsEnumResponse.ts b/specification/_global/terms_enum/TermsEnumResponse.ts index 4d9780d7d3..835836544c 100644 --- a/specification/_global/terms_enum/TermsEnumResponse.ts +++ b/specification/_global/terms_enum/TermsEnumResponse.ts @@ -23,6 +23,10 @@ export class Response { body: { _shards: ShardStatistics terms: string[] + /** + * If `false`, the returned terms set may be incomplete and should be treated as approximate. + * This can occur due to a few reasons, such as a request timeout or a node error. + */ complete: boolean } } diff --git a/specification/_global/terms_enum/examples/request/TermsEnumRequestExample1.yaml b/specification/_global/terms_enum/examples/request/TermsEnumRequestExample1.yaml new file mode 100644 index 0000000000..4123480449 --- /dev/null +++ b/specification/_global/terms_enum/examples/request/TermsEnumRequestExample1.yaml @@ -0,0 +1,9 @@ +# summary: +# method_request: "POST stackoverflow/_terms_enum" +description: Run `POST stackoverflow/_terms_enum`. +# type: "request" +value: |- + { + "field" : "tags", + "string" : "kiba" + } diff --git a/specification/_global/terms_enum/examples/response/TermsEnumResponseExample1.yaml b/specification/_global/terms_enum/examples/response/TermsEnumResponseExample1.yaml new file mode 100644 index 0000000000..7f12af5e41 --- /dev/null +++ b/specification/_global/terms_enum/examples/response/TermsEnumResponseExample1.yaml @@ -0,0 +1,16 @@ +# summary: +description: A successful response from `POST stackoverflow/_terms_enum`. +# type: "response", +# response_code: 200, +value: |- + { + "_shards": { + "total": 1, + "successful": 1, + "failed": 0 + }, + "terms": [ + "kibana" + ], + "complete" : true + }