diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 60b4231a27..98ee64426d 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -6516,8 +6516,11 @@ "tags": [ "document" ], - "summary": "Index a document", - "description": "Adds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "summary": "Create a new document in the index", + "description": "You can index a new JSON document with the `//_doc/` or `//_create/<_id>` APIs\nUsing `_create` guarantees that the document is indexed only if it does not already exist.\nIt returns a 409 response when a document with a same ID already exists in the index.\nTo update an existing document, you must use the `//_doc/` API.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add a document using the `PUT //_create/<_id>` or `POST //_create/<_id>` request formats, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html" + }, "operationId": "create", "parameters": [ { @@ -6562,8 +6565,11 @@ "tags": [ "document" ], - "summary": "Index a document", - "description": "Adds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "summary": "Create a new document in the index", + "description": "You can index a new JSON document with the `//_doc/` or `//_create/<_id>` APIs\nUsing `_create` guarantees that the document is indexed only if it does not already exist.\nIt returns a 409 response when a document with a same ID already exists in the index.\nTo update an existing document, you must use the `//_doc/` API.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add a document using the `PUT //_create/<_id>` or `POST //_create/<_id>` request formats, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html" + }, "operationId": "create-1", "parameters": [ { @@ -6777,13 +6783,13 @@ "document" ], "summary": "Get a document by its ID", - "description": "Retrieves the document with the specified ID from an index.", + "description": "Get a document and its source or stored fields from an index.\n\nBy default, this API is realtime and is not affected by the refresh rate of the index (when data will become visible for search).\nIn the case where stored fields are requested with the `stored_fields` parameter and the document has been updated but is not yet refreshed, the API will have to parse and analyze the source to extract the stored fields.\nTo turn off realtime behavior, set the `realtime` parameter to false.\n\n**Source filtering**\n\nBy default, the API returns the contents of the `_source` field unless you have used the `stored_fields` parameter or the `_source` field is turned off.\nYou can turn off `_source` retrieval by using the `_source` parameter:\n\n```\nGET my-index-000001/_doc/0?_source=false\n```\n\nIf you only need one or two fields from the `_source`, use the `_source_includes` or `_source_excludes` parameters to include or filter out particular fields.\nThis can be helpful with large documents where partial retrieval can save on network overhead\nBoth parameters take a comma separated list of fields or wildcard expressions.\nFor example:\n\n```\nGET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities\n```\n\nIf you only want to specify includes, you can use a shorter notation:\n\n```\nGET my-index-000001/_doc/0?_source=*.id\n```\n\n**Routing**\n\nIf routing is used during indexing, the routing value also needs to be specified to retrieve a document.\nFor example:\n\n```\nGET my-index-000001/_doc/2?routing=user1\n```\n\nThis request gets the document with ID 2, but it is routed based on the user.\nThe document is not fetched if the correct routing is not specified.\n\n**Distributed**\n\nThe GET operation is hashed into a specific shard ID.\nIt is then redirected to one of the replicas within that shard ID and returns the result.\nThe replicas are the primary shard and its replicas within that shard ID group.\nThis means that the more replicas you have, the better your GET scaling will be.\n\n**Versioning support**\n\nYou can use the `version` parameter to retrieve the document only if its current version is equal to the specified one.\n\nInternally, Elasticsearch has marked the old document as deleted and added an entirely new document.\nThe old version of the document doesn't disappear immediately, although you won't be able to access it.\nElasticsearch cleans up deleted documents in the background as you continue to index more data.", "operationId": "get", "parameters": [ { "in": "path", "name": "index", - "description": "Name of the index that contains the document.", + "description": "The name of the index that contains the document.", "required": true, "deprecated": false, "schema": { @@ -6794,7 +6800,7 @@ { "in": "path", "name": "id", - "description": "Unique identifier of the document.", + "description": "A unique document identifier.", "required": true, "deprecated": false, "schema": { @@ -6805,7 +6811,7 @@ { "in": "query", "name": "force_synthetic_source", - "description": "Should this request force synthetic _source?\nUse this to test if the mapping supports synthetic _source and to get a sense of the worst case performance.\nFetches with this enabled will be slower the enabling synthetic source natively in the index.", + "description": "Indicates whether the request forces synthetic `_source`.\nUse this paramater to test if the mapping supports synthetic `_source` and to get a sense of the worst case performance.\nFetches with this parameter enabled will be slower than enabling synthetic source natively in the index.", "deprecated": false, "schema": { "type": "boolean" @@ -6815,7 +6821,7 @@ { "in": "query", "name": "preference", - "description": "Specifies the node or shard the operation should be performed on. Random by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.\n\nIf it is set to `_local`, the operation will prefer to be run on a local allocated shard when possible.\nIf it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value.\nThis can help with \"jumping values\" when hitting different shards in different refresh states.\nA sample value can be something like the web session ID or the user name.", "deprecated": false, "schema": { "type": "string" @@ -6835,7 +6841,7 @@ { "in": "query", "name": "refresh", - "description": "If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "deprecated": false, "schema": { "type": "boolean" @@ -6845,7 +6851,7 @@ { "in": "query", "name": "routing", - "description": "Target the specified primary shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -6855,7 +6861,7 @@ { "in": "query", "name": "_source", - "description": "True or false to return the _source field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -6865,7 +6871,7 @@ { "in": "query", "name": "_source_excludes", - "description": "A comma-separated list of source fields to exclude in the response.", + "description": "A comma-separated list of source fields to exclude from the response.\nYou can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -6875,7 +6881,7 @@ { "in": "query", "name": "_source_includes", - "description": "A comma-separated list of source fields to include in the response.", + "description": "A comma-separated list of source fields to include in the response.\nIf this parameter is specified, only these source fields are returned.\nYou can exclude fields from this subset using the `_source_excludes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -6885,7 +6891,7 @@ { "in": "query", "name": "stored_fields", - "description": "List of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to false.", + "description": "A comma-separated list of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to `false`.\nOnly leaf fields can be retrieved with the `stored_field` option.\nObject fields can't be returned;​if specified, the request fails.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -6895,7 +6901,7 @@ { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.", + "description": "The version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -6905,7 +6911,7 @@ { "in": "query", "name": "version_type", - "description": "Specific version type: internal, external, external_gte.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -6930,8 +6936,11 @@ "tags": [ "document" ], - "summary": "Index a document", - "description": "Adds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "summary": "Create or update a document in an index", + "description": "Add a JSON document to the specified data stream or index and make it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.\n\nNOTE: You cannot use this API to send update requests for existing documents in a data stream.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add or overwrite a document using the `PUT //_doc/<_id>` request format, you must have the `create`, `index`, or `write` index privilege.\n* To add a document using the `POST //_doc/` request format, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nNOTE: Replica shards might not all be started when an indexing operation returns successfully.\nBy default, only the primary is required. Set `wait_for_active_shards` to change this default behavior.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Optimistic concurrency control**\n\nIndex operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n * ** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.\n\n**No operation (noop) updates**\n\nWhen updating a document by using this API, a new version of the document is always created even if the document hasn't changed.\nIf this isn't acceptable use the `_update` API with `detect_noop` set to `true`.\nThe `detect_noop` option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.\n\nThere isn't a definitive rule for when noop updates aren't acceptable.\nIt's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.\n\n**Versioning**\n\nEach indexed document is given a version number.\nBy default, internal versioning is used that starts at 1 and increments with each update, deletes included.\nOptionally, the version number can be set to an external value (for example, if maintained in a database).\nTo enable this functionality, `version_type` should be set to `external`.\nThe value provided must be a numeric, long value greater than or equal to 0, and less than around `9.2e+18`.\n\nNOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations.\nIf no version is provided, the operation runs without any version checks.\n\nWhen using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document.\nIf true, the document will be indexed and the new version number used.\nIf the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:\n\n```\nPUT my-index-000001/_doc/1?version=2&version_type=external\n{\n \"user\": {\n \"id\": \"elkbee\"\n }\n}\n\nIn this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.\nIf the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).\n\nA nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.\nEven the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html" + }, "operationId": "index", "parameters": [ { @@ -6987,8 +6996,11 @@ "tags": [ "document" ], - "summary": "Index a document", - "description": "Adds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "summary": "Create or update a document in an index", + "description": "Add a JSON document to the specified data stream or index and make it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.\n\nNOTE: You cannot use this API to send update requests for existing documents in a data stream.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add or overwrite a document using the `PUT //_doc/<_id>` request format, you must have the `create`, `index`, or `write` index privilege.\n* To add a document using the `POST //_doc/` request format, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nNOTE: Replica shards might not all be started when an indexing operation returns successfully.\nBy default, only the primary is required. Set `wait_for_active_shards` to change this default behavior.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Optimistic concurrency control**\n\nIndex operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n * ** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.\n\n**No operation (noop) updates**\n\nWhen updating a document by using this API, a new version of the document is always created even if the document hasn't changed.\nIf this isn't acceptable use the `_update` API with `detect_noop` set to `true`.\nThe `detect_noop` option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.\n\nThere isn't a definitive rule for when noop updates aren't acceptable.\nIt's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.\n\n**Versioning**\n\nEach indexed document is given a version number.\nBy default, internal versioning is used that starts at 1 and increments with each update, deletes included.\nOptionally, the version number can be set to an external value (for example, if maintained in a database).\nTo enable this functionality, `version_type` should be set to `external`.\nThe value provided must be a numeric, long value greater than or equal to 0, and less than around `9.2e+18`.\n\nNOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations.\nIf no version is provided, the operation runs without any version checks.\n\nWhen using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document.\nIf true, the document will be indexed and the new version number used.\nIf the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:\n\n```\nPUT my-index-000001/_doc/1?version=2&version_type=external\n{\n \"user\": {\n \"id\": \"elkbee\"\n }\n}\n\nIn this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.\nIf the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).\n\nA nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.\nEven the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html" + }, "operationId": "index-1", "parameters": [ { @@ -7045,13 +7057,13 @@ "document" ], "summary": "Delete a document", - "description": "Removes a JSON document from the specified index.", + "description": "Remove a JSON document from the specified index.\n\nNOTE: You cannot send deletion requests directly to a data stream.\nTo delete a document in a data stream, you must target the backing index containing the document.\n\n**Optimistic concurrency control**\n\nDelete operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Versioning**\n\nEach document indexed is versioned.\nWhen deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime.\nEvery write operation run on a document, deletes included, causes its version to be incremented.\nThe version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations.\nThe length of time for which a deleted document's version remains available is determined by the `index.gc_deletes` index setting.\n\n**Routing**\n\nIf routing is used during indexing, the routing value also needs to be specified to delete a document.\n\nIf the `_routing` mapping is set to `required` and no routing value is specified, the delete API throws a `RoutingMissingException` and rejects the request.\n\nFor example:\n\n```\nDELETE /my-index-000001/_doc/1?routing=shard-1\n```\n\nThis request deletes the document with ID 1, but it is routed based on the user.\nThe document is not deleted if the correct routing is not specified.\n\n**Distributed**\n\nThe delete operation gets hashed into a specific shard ID.\nIt then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group.", "operationId": "delete", "parameters": [ { "in": "path", "name": "index", - "description": "Name of the target index.", + "description": "The name of the target index.", "required": true, "deprecated": false, "schema": { @@ -7062,7 +7074,7 @@ { "in": "path", "name": "id", - "description": "Unique identifier for the document.", + "description": "A unique identifier for the document.", "required": true, "deprecated": false, "schema": { @@ -7093,7 +7105,7 @@ { "in": "query", "name": "refresh", - "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.\nValid values: `true`, `false`, `wait_for`.", + "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf `wait_for`, it waits for a refresh to make this operation visible to search.\nIf `false`, it does nothing with refreshes.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -7103,7 +7115,7 @@ { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -7113,7 +7125,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for active shards.", + "description": "The period to wait for active shards.\n\nThis parameter is useful for situations where the primary shard assigned to perform the delete operation might not be available when the delete operation runs.\nSome reasons for this might be that the primary shard is currently recovering from a store or undergoing relocation.\nBy default, the delete operation will wait on the primary shard to become available for up to 1 minute before failing and responding with an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -7123,7 +7135,7 @@ { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "An explicit version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -7133,7 +7145,7 @@ { "in": "query", "name": "version_type", - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -7143,7 +7155,7 @@ { "in": "query", "name": "wait_for_active_shards", - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The minimum number of shard copies that must be active before proceeding with the operation.\nYou can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value of `1` means it waits for each primary shard to be active.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:WaitForActiveShards" @@ -7169,13 +7181,13 @@ "document" ], "summary": "Check a document", - "description": "Checks if a specified document exists.", + "description": "Verify that a document exists.\nFor example, check to see if a document with the `_id` 0 exists:\n\n```\nHEAD my-index-000001/_doc/0\n```\n\nIf the document exists, the API returns a status code of `200 - OK`.\nIf the document doesn’t exist, the API returns `404 - Not Found`.\n\n**Versioning support**\n\nYou can use the `version` parameter to check the document only if its current version is equal to the specified one.\n\nInternally, Elasticsearch has marked the old document as deleted and added an entirely new document.\nThe old version of the document doesn't disappear immediately, although you won't be able to access it.\nElasticsearch cleans up deleted documents in the background as you continue to index more data.", "operationId": "exists", "parameters": [ { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and aliases.\nSupports wildcards (`*`).", + "description": "A comma-separated list of data streams, indices, and aliases.\nIt supports wildcards (`*`).", "required": true, "deprecated": false, "schema": { @@ -7186,7 +7198,7 @@ { "in": "path", "name": "id", - "description": "Identifier of the document.", + "description": "A unique document identifier.", "required": true, "deprecated": false, "schema": { @@ -7197,7 +7209,7 @@ { "in": "query", "name": "preference", - "description": "Specifies the node or shard the operation should be performed on.\nRandom by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.\n\nIf it is set to `_local`, the operation will prefer to be run on a local allocated shard when possible.\nIf it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value.\nThis can help with \"jumping values\" when hitting different shards in different refresh states.\nA sample value can be something like the web session ID or the user name.", "deprecated": false, "schema": { "type": "string" @@ -7217,7 +7229,7 @@ { "in": "query", "name": "refresh", - "description": "If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "deprecated": false, "schema": { "type": "boolean" @@ -7227,7 +7239,7 @@ { "in": "query", "name": "routing", - "description": "Target the specified primary shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -7237,7 +7249,7 @@ { "in": "query", "name": "_source", - "description": "`true` or `false` to return the `_source` field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -7247,7 +7259,7 @@ { "in": "query", "name": "_source_excludes", - "description": "A comma-separated list of source fields to exclude in the response.", + "description": "A comma-separated list of source fields to exclude from the response.\nYou can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -7257,7 +7269,7 @@ { "in": "query", "name": "_source_includes", - "description": "A comma-separated list of source fields to include in the response.", + "description": "A comma-separated list of source fields to include in the response.\nIf this parameter is specified, only these source fields are returned.\nYou can exclude fields from this subset using the `_source_excludes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -7267,7 +7279,7 @@ { "in": "query", "name": "stored_fields", - "description": "List of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to false.", + "description": "A comma-separated list of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to `false`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -7287,7 +7299,7 @@ { "in": "query", "name": "version_type", - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -8782,13 +8794,16 @@ "document" ], "summary": "Get a document's source", - "description": "Returns the source of a document.", + "description": "Get the source of a document.\nFor example:\n\n```\nGET my-index-000001/_source/1\n```\n\nYou can use the source filtering parameters to control which parts of the `_source` are returned:\n\n```\nGET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities\n```", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html" + }, "operationId": "get-source", "parameters": [ { "in": "path", "name": "index", - "description": "Name of the index that contains the document.", + "description": "The name of the index that contains the document.", "required": true, "deprecated": false, "schema": { @@ -8799,7 +8814,7 @@ { "in": "path", "name": "id", - "description": "Unique identifier of the document.", + "description": "A unique document identifier.", "required": true, "deprecated": false, "schema": { @@ -8810,7 +8825,7 @@ { "in": "query", "name": "preference", - "description": "Specifies the node or shard the operation should be performed on. Random by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.", "deprecated": false, "schema": { "type": "string" @@ -8820,7 +8835,7 @@ { "in": "query", "name": "realtime", - "description": "Boolean) If true, the request is real-time as opposed to near-real-time.", + "description": "If `true`, the request is real-time as opposed to near-real-time.", "deprecated": false, "schema": { "type": "boolean" @@ -8830,7 +8845,7 @@ { "in": "query", "name": "refresh", - "description": "If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "deprecated": false, "schema": { "type": "boolean" @@ -8840,7 +8855,7 @@ { "in": "query", "name": "routing", - "description": "Target the specified primary shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -8850,7 +8865,7 @@ { "in": "query", "name": "_source", - "description": "True or false to return the _source field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -8880,6 +8895,7 @@ { "in": "query", "name": "stored_fields", + "description": "A comma-separated list of stored fields to return as part of a hit.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -8889,7 +8905,7 @@ { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.", + "description": "The version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -8899,7 +8915,7 @@ { "in": "query", "name": "version_type", - "description": "Specific version type: internal, external, external_gte.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -8925,13 +8941,16 @@ "document" ], "summary": "Check for a document source", - "description": "Checks if a document's `_source` is stored.", + "description": "Check whether a document source exists in an index.\nFor example:\n\n```\nHEAD my-index-000001/_source/1\n```\n\nA document's source is not available if it is disabled in the mapping.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html" + }, "operationId": "exists-source", "parameters": [ { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and aliases.\nSupports wildcards (`*`).", + "description": "A comma-separated list of data streams, indices, and aliases.\nIt supports wildcards (`*`).", "required": true, "deprecated": false, "schema": { @@ -8942,7 +8961,7 @@ { "in": "path", "name": "id", - "description": "Identifier of the document.", + "description": "A unique identifier for the document.", "required": true, "deprecated": false, "schema": { @@ -8953,7 +8972,7 @@ { "in": "query", "name": "preference", - "description": "Specifies the node or shard the operation should be performed on.\nRandom by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.", "deprecated": false, "schema": { "type": "string" @@ -8963,7 +8982,7 @@ { "in": "query", "name": "realtime", - "description": "If true, the request is real-time as opposed to near-real-time.", + "description": "If `true`, the request is real-time as opposed to near-real-time.", "deprecated": false, "schema": { "type": "boolean" @@ -8973,7 +8992,7 @@ { "in": "query", "name": "refresh", - "description": "If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "deprecated": false, "schema": { "type": "boolean" @@ -8983,7 +9002,7 @@ { "in": "query", "name": "routing", - "description": "Target the specified primary shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -8993,7 +9012,7 @@ { "in": "query", "name": "_source", - "description": "`true` or `false` to return the `_source` field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -9023,7 +9042,7 @@ { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "The version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -9033,7 +9052,7 @@ { "in": "query", "name": "version_type", - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -10907,8 +10926,11 @@ "tags": [ "document" ], - "summary": "Index a document", - "description": "Adds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "summary": "Create or update a document in an index", + "description": "Add a JSON document to the specified data stream or index and make it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.\n\nNOTE: You cannot use this API to send update requests for existing documents in a data stream.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add or overwrite a document using the `PUT //_doc/<_id>` request format, you must have the `create`, `index`, or `write` index privilege.\n* To add a document using the `POST //_doc/` request format, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nNOTE: Replica shards might not all be started when an indexing operation returns successfully.\nBy default, only the primary is required. Set `wait_for_active_shards` to change this default behavior.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Optimistic concurrency control**\n\nIndex operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n * ** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.\n\n**No operation (noop) updates**\n\nWhen updating a document by using this API, a new version of the document is always created even if the document hasn't changed.\nIf this isn't acceptable use the `_update` API with `detect_noop` set to `true`.\nThe `detect_noop` option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.\n\nThere isn't a definitive rule for when noop updates aren't acceptable.\nIt's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.\n\n**Versioning**\n\nEach indexed document is given a version number.\nBy default, internal versioning is used that starts at 1 and increments with each update, deletes included.\nOptionally, the version number can be set to an external value (for example, if maintained in a database).\nTo enable this functionality, `version_type` should be set to `external`.\nThe value provided must be a numeric, long value greater than or equal to 0, and less than around `9.2e+18`.\n\nNOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations.\nIf no version is provided, the operation runs without any version checks.\n\nWhen using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document.\nIf true, the document will be indexed and the new version number used.\nIf the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:\n\n```\nPUT my-index-000001/_doc/1?version=2&version_type=external\n{\n \"user\": {\n \"id\": \"elkbee\"\n }\n}\n\nIn this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.\nIf the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).\n\nA nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.\nEven the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html" + }, "operationId": "index-2", "parameters": [ { @@ -26048,7 +26070,7 @@ "document" ], "summary": "Reindex documents", - "description": "Copies documents from a source to a destination. The source can be any existing index, alias, or data stream. The destination must differ from the source. For example, you cannot reindex a data stream into itself.", + "description": "Copy documents from a source to a destination.\nYou can copy all documents to the destination index or reindex a subset of the documents.\nThe source can be any existing index, alias, or data stream.\nThe destination must differ from the source.\nFor example, you cannot reindex a data stream into itself.\n\nIMPORTANT: Reindex requires `_source` to be enabled for all documents in the source.\nThe destination should be configured as wanted before calling the reindex API.\nReindex does not copy the settings from the source or its associated template.\nMappings, shard counts, and replicas, for example, must be configured ahead of time.\n\nIf the Elasticsearch security features are enabled, you must have the following security privileges:\n\n* The `read` index privilege for the source data stream, index, or alias.\n* The `write` index privilege for the destination data stream, index, or index alias.\n* To automatically create a data stream or index with a reindex API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege for the destination data stream, index, or alias.\n* If reindexing from a remote cluster, the `source.remote.user` must have the `monitor` cluster privilege and the `read` index privilege for the source data stream, index, or alias.\n\nIf reindexing from a remote cluster, you must explicitly allow the remote host in the `reindex.remote.whitelist` setting.\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nThe `dest` element can be configured like the index API to control optimistic concurrency control.\nOmitting `version_type` or setting it to `internal` causes Elasticsearch to blindly dump documents into the destination, overwriting any that happen to have the same ID.\n\nSetting `version_type` to `external` causes Elasticsearch to preserve the `version` from the source, create any documents that are missing, and update any documents that have an older version in the destination than they do in the source.\n\nSetting `op_type` to `create` causes the reindex API to create only missing documents in the destination.\nAll existing documents will cause a version conflict.\n\nIMPORTANT: Because data streams are append-only, any reindex request to a destination data stream must have an `op_type` of `create`.\nA reindex can only add new documents to a destination data stream.\nIt cannot update existing documents in a destination data stream.\n\nBy default, version conflicts abort the reindex process.\nTo continue reindexing if there are conflicts, set the `conflicts` request body property to `proceed`.\nIn this case, the response includes a count of the version conflicts that were encountered.\nNote that the handling of other error types is unaffected by the `conflicts` property.\nAdditionally, if you opt to count version conflicts, the operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query.\n\nNOTE: The reindex API makes no effort to handle ID collisions.\nThe last document written will \"win\" but the order isn't usually predictable so it is not a good idea to rely on this behavior.\nInstead, make sure that IDs are unique by using a script.\n\n**Running reindex asynchronously**\n\nIf the request contains `wait_for_completion=false`, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task.\nElasticsearch creates a record of this task as a document at `_tasks/`.\n\n**Reindex from multiple sources**\n\nIf you have many sources to reindex it is generally better to reindex them one at a time rather than using a glob pattern to pick up multiple sources.\nThat way you can resume the process if there are any errors by removing the partially completed source and starting over.\nIt also makes parallelizing the process fairly simple: split the list of sources to reindex and run each list in parallel.\n\nFor example, you can use a bash script like this:\n\n```\nfor index in i1 i2 i3 i4 i5; do\n curl -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{\n \"source\": {\n \"index\": \"'$index'\"\n },\n \"dest\": {\n \"index\": \"'$index'-reindexed\"\n }\n }'\ndone\n```\n\n** Throttling**\n\nSet `requests_per_second` to any positive decimal number (`1.4`, `6`, `1000`, for example) to throttle the rate at which reindex issues batches of index operations.\nRequests are throttled by padding each batch with a wait time.\nTo turn off throttling, set `requests_per_second` to `-1`.\n\nThe throttling is done by waiting between batches so that the scroll that reindex uses internally can be given a timeout that takes into account the padding.\nThe padding time is the difference between the batch size divided by the `requests_per_second` and the time spent writing.\nBy default the batch size is `1000`, so if `requests_per_second` is set to `500`:\n\n```\ntarget_time = 1000 / 500 per second = 2 seconds\nwait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds\n```\n\nSince the batch is issued as a single bulk request, large batch sizes cause Elasticsearch to create many requests and then wait for a while before starting the next set.\nThis is \"bursty\" instead of \"smooth\".\n\n**Slicing**\n\nReindex supports sliced scroll to parallelize the reindexing process.\nThis parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts.\n\nNOTE: Reindexing from remote clusters does not support manual or automatic slicing.\n\nYou can slice a reindex request manually by providing a slice ID and total number of slices to each request.\nYou can also let reindex automatically parallelize by using sliced scroll to slice on `_id`.\nThe `slices` parameter specifies the number of slices to use.\n\nAdding `slices` to the reindex request just automates the manual process, creating sub-requests which means it has some quirks:\n\n* You can see these requests in the tasks API. These sub-requests are \"child\" tasks of the task for the request with slices.\n* Fetching the status of the task for the request with `slices` only contains the status of completed slices.\n* These sub-requests are individually addressable for things like cancellation and rethrottling.\n* Rethrottling the request with `slices` will rethrottle the unfinished sub-request proportionally.\n* Canceling the request with `slices` will cancel each sub-request.\n* Due to the nature of `slices`, each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.\n* Parameters like `requests_per_second` and `max_docs` on a request with `slices` are distributed proportionally to each sub-request. Combine that with the previous point about distribution being uneven and you should conclude that using `max_docs` with `slices` might not result in exactly `max_docs` documents being reindexed.\n* Each sub-request gets a slightly different snapshot of the source, though these are all taken at approximately the same time.\n\nIf slicing automatically, setting `slices` to `auto` will choose a reasonable number for most indices.\nIf slicing manually or otherwise tuning automatic slicing, use the following guidelines.\n\nQuery performance is most efficient when the number of slices is equal to the number of shards in the index.\nIf that number is large (for example, `500`), choose a lower number as too many slices will hurt performance.\nSetting slices higher than the number of shards generally does not improve efficiency and adds overhead.\n\nIndexing performance scales linearly across available resources with the number of slices.\n\nWhether query or indexing performance dominates the runtime depends on the documents being reindexed and cluster resources.\n\n**Modify documents during reindexing**\n\nLike `_update_by_query`, reindex operations support a script that modifies the document.\nUnlike `_update_by_query`, the script is allowed to modify the document's metadata.\n\nJust as in `_update_by_query`, you can set `ctx.op` to change the operation that is run on the destination.\nFor example, set `ctx.op` to `noop` if your script decides that the document doesn’t have to be indexed in the destination. This \"no operation\" will be reported in the `noop` counter in the response body.\nSet `ctx.op` to `delete` if your script decides that the document must be deleted from the destination.\nThe deletion will be reported in the `deleted` counter in the response body.\nSetting `ctx.op` to anything else will return an error, as will setting any other field in `ctx`.\n\nThink of the possibilities! Just be careful; you are able to change:\n\n* `_id`\n* `_index`\n* `_version`\n* `_routing`\n\nSetting `_version` to `null` or clearing it from the `ctx` map is just like not sending the version in an indexing request.\nIt will cause the document to be overwritten in the destination regardless of the version on the target or the version type you use in the reindex API.\n\n**Reindex from remote**\n\nReindex supports reindexing from a remote Elasticsearch cluster.\nThe `host` parameter must contain a scheme, host, port, and optional path.\nThe `username` and `password` parameters are optional and when they are present the reindex operation will connect to the remote Elasticsearch node using basic authentication.\nBe sure to use HTTPS when using basic authentication or the password will be sent in plain text.\nThere are a range of settings available to configure the behavior of the HTTPS connection.\n\nWhen using Elastic Cloud, it is also possible to authenticate against the remote cluster through the use of a valid API key.\nRemote hosts must be explicitly allowed with the `reindex.remote.whitelist` setting.\nIt can be set to a comma delimited list of allowed remote host and port combinations.\nScheme is ignored; only the host and port are used.\nFor example:\n\n```\nreindex.remote.whitelist: [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*\"]\n```\n\nThe list of allowed hosts must be configured on any nodes that will coordinate the reindex.\nThis feature should work with remote clusters of any version of Elasticsearch.\nThis should enable you to upgrade from any version of Elasticsearch to the current version by reindexing from a cluster of the old version.\n\nWARNING: Elasticsearch does not support forward compatibility across major versions.\nFor example, you cannot reindex from a 7.x cluster into a 6.x cluster.\n\nTo enable queries sent to older versions of Elasticsearch, the `query` parameter is sent directly to the remote host without validation or modification.\n\nNOTE: Reindexing from remote clusters does not support manual or automatic slicing.\n\nReindexing from a remote server uses an on-heap buffer that defaults to a maximum size of 100mb.\nIf the remote index includes very large documents you'll need to use a smaller batch size.\nIt is also possible to set the socket read timeout on the remote connection with the `socket_timeout` field and the connection timeout with the `connect_timeout` field.\nBoth default to 30 seconds.\n\n**Configuring SSL parameters**\n\nReindex from remote supports configurable SSL settings.\nThese must be specified in the `elasticsearch.yml` file, with the exception of the secure settings, which you add in the Elasticsearch keystore.\nIt is not possible to configure SSL in the body of the reindex request.", "operationId": "reindex", "parameters": [ { @@ -26064,7 +26086,7 @@ { "in": "query", "name": "requests_per_second", - "description": "The throttle for this request in sub-requests per second.\nDefaults to no throttle.", + "description": "The throttle for this request in sub-requests per second.\nBy default, there is no throttle.", "deprecated": false, "schema": { "type": "number" @@ -26074,7 +26096,7 @@ { "in": "query", "name": "scroll", - "description": "Specifies how long a consistent view of the index should be maintained for scrolled search.", + "description": "The period of time that a consistent view of the index should be maintained for scrolled search.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -26084,7 +26106,7 @@ { "in": "query", "name": "slices", - "description": "The number of slices this task should be divided into.\nDefaults to 1 slice, meaning the task isn’t sliced into subtasks.", + "description": "The number of slices this task should be divided into.\nIt defaults to one slice, which means the task isn't sliced into subtasks.\n\nReindex supports sliced scroll to parallelize the reindexing process.\nThis parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts.\n\nNOTE: Reindexing from remote clusters does not support manual or automatic slicing.\n\nIf set to `auto`, Elasticsearch chooses the number of slices to use.\nThis setting will use one slice per shard, up to a certain limit.\nIf there are multiple sources, it will choose the number of slices based on the index or backing index with the smallest number of shards.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Slices" @@ -26094,7 +26116,7 @@ { "in": "query", "name": "timeout", - "description": "Period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards.", + "description": "The period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards.\nBy default, Elasticsearch waits for at least one minute before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -26104,7 +26126,7 @@ { "in": "query", "name": "wait_for_active_shards", - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The number of shard copies that must be active before proceeding with the operation.\nSet it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value is one, which means it waits for each primary shard to be active.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:WaitForActiveShards" @@ -26145,7 +26167,7 @@ "$ref": "#/components/schemas/_global.reindex:Destination" }, "max_docs": { - "description": "The maximum number of documents to reindex.", + "description": "The maximum number of documents to reindex.\nBy default, all documents are reindexed.\nIf it is a value less then or equal to `scroll_size`, a scroll will not be used to retrieve the results for the operation.\n\nIf `conflicts` is set to `proceed`, the reindex operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query.", "type": "number" }, "script": { @@ -26176,27 +26198,33 @@ "type": "object", "properties": { "batches": { + "description": "The number of scroll responses that were pulled back by the reindex.", "type": "number" }, "created": { + "description": "The number of documents that were successfully created.", "type": "number" }, "deleted": { + "description": "The number of documents that were successfully deleted.", "type": "number" }, "failures": { + "description": "If there were any unrecoverable errors during the process, it is an array of those failures.\nIf this array is not empty, the request ended because of those failures.\nReindex is implemented using batches and any failure causes the entire process to end but all failures in the current batch are collected into the array.\nYou can use the `conflicts` option to prevent the reindex from ending on version conflicts.", "type": "array", "items": { "$ref": "#/components/schemas/_types:BulkIndexByScrollFailure" } }, "noops": { + "description": "The number of documents that were ignored because the script used for the reindex returned a `noop` value for `ctx.op`.", "type": "number" }, "retries": { "$ref": "#/components/schemas/_types:Retries" }, "requests_per_second": { + "description": "The number of requests per second effectively run during the reindex.", "type": "number" }, "slice_id": { @@ -26212,18 +26240,22 @@ "$ref": "#/components/schemas/_types:EpochTimeUnitMillis" }, "timed_out": { + "description": "If any of the requests that ran during the reindex timed out, it is `true`.", "type": "boolean" }, "took": { "$ref": "#/components/schemas/_types:DurationValueUnitMillis" }, "total": { + "description": "The number of documents that were successfully processed.", "type": "number" }, "updated": { + "description": "The number of documents that were successfully updated.\nThat is to say, a document with the same ID already existed before the reindex updated it.", "type": "number" }, "version_conflicts": { + "description": "The number of version conflicts that occurred.", "type": "number" } } @@ -26241,13 +26273,13 @@ "document" ], "summary": "Throttle a reindex operation", - "description": "Change the number of requests per second for a particular reindex operation.", + "description": "Change the number of requests per second for a particular reindex operation.\nFor example:\n\n```\nPOST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1\n```\n\nRethrottling that speeds up the query takes effect immediately.\nRethrottling that slows down the query will take effect after completing the current batch.\nThis behavior prevents scroll timeouts.", "operationId": "reindex-rethrottle", "parameters": [ { "in": "path", "name": "task_id", - "description": "Identifier for the task.", + "description": "The task identifier, which can be found by using the tasks API.", "required": true, "deprecated": false, "schema": { @@ -26258,7 +26290,7 @@ { "in": "query", "name": "requests_per_second", - "description": "The throttle for this request in sub-requests per second.", + "description": "The throttle for this request in sub-requests per second.\nIt can be either `-1` to turn off throttling or any decimal number like `1.7` or `12` to throttle to that level.", "deprecated": false, "schema": { "type": "number" @@ -37763,13 +37795,13 @@ "document" ], "summary": "Update a document", - "description": "Updates a document by running a script or passing a partial document.", + "description": "Update a document by running a script or passing a partial document.\n\nIf the Elasticsearch security features are enabled, you must have the `index` or `write` index privilege for the target index or index alias.\n\nThe script can update, delete, or skip modifying the document.\nThe API also supports passing a partial document, which is merged into the existing document.\nTo fully replace an existing document, use the index API.\nThis operation:\n\n* Gets the document (collocated with the shard) from the index.\n* Runs the specified script.\n* Indexes the result.\n\nThe document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.\n\nThe `_source` field must be enabled to use this API.\nIn addition to `_source`, you can access the following variables through the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`, and `_now` (the current timestamp).", "operationId": "update", "parameters": [ { "in": "path", "name": "index", - "description": "The name of the index", + "description": "The name of the target index.\nBy default, the index is created automatically if it doesn't exist.", "required": true, "deprecated": false, "schema": { @@ -37780,7 +37812,7 @@ { "in": "path", "name": "id", - "description": "Document ID", + "description": "A unique identifier for the document to be updated.", "required": true, "deprecated": false, "schema": { @@ -37821,7 +37853,7 @@ { "in": "query", "name": "refresh", - "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search, if 'wait_for' then wait for a refresh to make this operation\nvisible to search, if 'false' do nothing with refreshes.", + "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf 'wait_for', it waits for a refresh to make this operation visible to search.\nIf 'false', it does nothing with refreshes.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -37831,7 +37863,7 @@ { "in": "query", "name": "require_alias", - "description": "If true, the destination must be an index alias.", + "description": "If `true`, the destination must be an index alias.", "deprecated": false, "schema": { "type": "boolean" @@ -37841,7 +37873,7 @@ { "in": "query", "name": "retry_on_conflict", - "description": "Specify how many times should the operation be retried when a conflict occurs.", + "description": "The number of times the operation should be retried when a conflict occurs.", "deprecated": false, "schema": { "type": "number" @@ -37851,7 +37883,7 @@ { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -37861,7 +37893,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for dynamic mapping updates and active shards.\nThis guarantees Elasticsearch waits for at least the timeout before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.", + "description": "The period to wait for the following operations: dynamic mapping updates and waiting for active shards.\nElasticsearch waits for at least the timeout period before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -37871,7 +37903,7 @@ { "in": "query", "name": "wait_for_active_shards", - "description": "The number of shard copies that must be active before proceeding with the operations.\nSet to 'all' or any positive integer up to the total number of shards in the index\n(number_of_replicas+1). Defaults to 1 meaning the primary shard.", + "description": "The number of copies of each shard that must be active before proceeding with the operation.\nSet to 'all' or any positive integer up to the total number of shards in the index (`number_of_replicas`+1).\nThe default value of `1` means it waits for each primary shard to be active.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:WaitForActiveShards" @@ -37881,7 +37913,7 @@ { "in": "query", "name": "_source", - "description": "Set to false to disable source retrieval. You can also specify a comma-separated\nlist of the fields you want to retrieve.", + "description": "If `false`, source retrieval is turned off.\nYou can also specify a comma-separated list of the fields you want to retrieve.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -37891,7 +37923,7 @@ { "in": "query", "name": "_source_excludes", - "description": "Specify the source fields you want to exclude.", + "description": "The source fields you want to exclude.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -37901,7 +37933,7 @@ { "in": "query", "name": "_source_includes", - "description": "Specify the source fields you want to retrieve.", + "description": "The source fields you want to retrieve.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -37916,29 +37948,29 @@ "type": "object", "properties": { "detect_noop": { - "description": "Set to false to disable setting 'result' in the response\nto 'noop' if no change to the document occurred.", + "description": "If `true`, the `result` in the response is set to `noop` (no operation) when there are no changes to the document.", "type": "boolean" }, "doc": { - "description": "A partial update to an existing document.", + "description": "A partial update to an existing document.\nIf both `doc` and `script` are specified, `doc` is ignored.", "type": "object" }, "doc_as_upsert": { - "description": "Set to true to use the contents of 'doc' as the value of 'upsert'", + "description": "If `true`, use the contents of 'doc' as the value of 'upsert'.\nNOTE: Using ingest pipelines with `doc_as_upsert` is not supported.", "type": "boolean" }, "script": { "$ref": "#/components/schemas/_types:Script" }, "scripted_upsert": { - "description": "Set to true to execute the script whether or not the document exists.", + "description": "If `true`, run the script whether or not the document exists.", "type": "boolean" }, "_source": { "$ref": "#/components/schemas/_global.search._types:SourceConfig" }, "upsert": { - "description": "If the document does not already exist, the contents of 'upsert' are inserted as a\nnew document. If the document exists, the 'script' is executed.", + "description": "If the document does not already exist, the contents of 'upsert' are inserted as a new document.\nIf the document exists, the 'script' is run.", "type": "object" } } @@ -67779,6 +67811,7 @@ "$ref": "#/components/schemas/_types:IndexName" }, "_primary_term": { + "description": "The primary term assigned to the document for the indexing operation.", "type": "number" }, "result": { @@ -67883,9 +67916,11 @@ "type": "object", "properties": { "bulk": { + "description": "The number of bulk actions retried.", "type": "number" }, "search": { + "description": "The number of search actions retried.", "type": "number" } }, @@ -68874,6 +68909,7 @@ "$ref": "#/components/schemas/_types:IndexName" }, "fields": { + "description": "If the `stored_fields` parameter is set to `true` and `found` is `true`, it contains the document fields stored in the index.", "type": "object", "additionalProperties": { "type": "object" @@ -68886,21 +68922,25 @@ } }, "found": { + "description": "Indicates whether the document exists.", "type": "boolean" }, "_id": { "$ref": "#/components/schemas/_types:Id" }, "_primary_term": { + "description": "The primary term assigned to the document for the indexing operation.", "type": "number" }, "_routing": { + "description": "The explicit routing, if set.", "type": "string" }, "_seq_no": { "$ref": "#/components/schemas/_types:SequenceNumber" }, "_source": { + "description": "If `found` is `true`, it contains the document data formatted in JSON.\nIf the `_source` parameter is set to `false` or the `stored_fields` parameter is set to `true`, it is excluded.", "type": "object" }, "_version": { @@ -84172,7 +84212,7 @@ "$ref": "#/components/schemas/_global.reindex:RemoteSource" }, "size": { - "description": "The number of documents to index per batch.\nUse when indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB.", + "description": "The number of documents to index per batch.\nUse it when you are indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB.", "type": "number" }, "slice": { @@ -98705,7 +98745,7 @@ "create#id": { "in": "path", "name": "id", - "description": "Unique identifier for the document.", + "description": "A unique identifier for the document.\nTo automatically generate a document ID, use the `POST //_doc/` request format.", "required": true, "deprecated": false, "schema": { @@ -98716,7 +98756,7 @@ "create#index": { "in": "path", "name": "index", - "description": "Name of the data stream or index to target.\nIf the target doesn’t exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream.\nIf the target doesn’t exist and doesn’t match a data stream template, this request creates the index.", + "description": "The name of the data stream or index to target.\nIf the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream.\nIf the target doesn't exist and doesn’t match a data stream template, this request creates the index.", "required": true, "deprecated": false, "schema": { @@ -98727,7 +98767,7 @@ "create#pipeline": { "in": "query", "name": "pipeline", - "description": "ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.\nIf a final pipeline is configured it will always run, regardless of the value of this parameter.", + "description": "The ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, setting the value to `_none` turns off the default ingest pipeline for this request.\nIf a final pipeline is configured, it will always run regardless of the value of this parameter.", "deprecated": false, "schema": { "type": "string" @@ -98737,7 +98777,7 @@ "create#refresh": { "in": "query", "name": "refresh", - "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.\nValid values: `true`, `false`, `wait_for`.", + "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf `wait_for`, it waits for a refresh to make this operation visible to search.\nIf `false`, it does nothing with refreshes.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -98747,7 +98787,7 @@ "create#routing": { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -98757,7 +98797,7 @@ "create#timeout": { "in": "query", "name": "timeout", - "description": "Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.", + "description": "The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.\nElasticsearch waits for at least the specified timeout period before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.\n\nThis parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs.\nSome reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation.\nBy default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error.\nThe actual wait time could be longer, particularly when multiple waits occur.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -98767,7 +98807,7 @@ "create#version": { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "The explicit version number for concurrency control.\nIt must be a non-negative long number.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -98777,7 +98817,7 @@ "create#version_type": { "in": "query", "name": "version_type", - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -98787,7 +98827,7 @@ "create#wait_for_active_shards": { "in": "query", "name": "wait_for_active_shards", - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The number of shard copies that must be active before proceeding with the operation.\nYou can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value of `1` means it waits for each primary shard to be active.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:WaitForActiveShards" @@ -99811,7 +99851,7 @@ "index#id": { "in": "path", "name": "id", - "description": "Unique identifier for the document.", + "description": "A unique identifier for the document.\nTo automatically generate a document ID, use the `POST //_doc/` request format and omit this parameter.", "required": true, "deprecated": false, "schema": { @@ -99822,7 +99862,7 @@ "index#index": { "in": "path", "name": "index", - "description": "Name of the data stream or index to target.", + "description": "The name of the data stream or index to target.\nIf the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream.\nIf the target doesn't exist and doesn't match a data stream template, this request creates the index.\nYou can check for existing targets with the resolve index API.", "required": true, "deprecated": false, "schema": { @@ -99853,7 +99893,7 @@ "index#op_type": { "in": "query", "name": "op_type", - "description": "Set to create to only index the document if it does not already exist (put if absent).\nIf a document with the specified `_id` already exists, the indexing operation will fail.\nSame as using the `/_create` endpoint.\nValid values: `index`, `create`.\nIf document id is specified, it defaults to `index`.\nOtherwise, it defaults to `create`.", + "description": "Set to `create` to only index the document if it does not already exist (put if absent).\nIf a document with the specified `_id` already exists, the indexing operation will fail.\nThe behavior is the same as using the `/_create` endpoint.\nIf a document ID is specified, this paramater defaults to `index`.\nOtherwise, it defaults to `create`.\nIf the request targets a data stream, an `op_type` of `create` is required.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:OpType" @@ -99863,7 +99903,7 @@ "index#pipeline": { "in": "query", "name": "pipeline", - "description": "ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.\nIf a final pipeline is configured it will always run, regardless of the value of this parameter.", + "description": "The ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.\nIf a final pipeline is configured it will always run, regardless of the value of this parameter.", "deprecated": false, "schema": { "type": "string" @@ -99873,7 +99913,7 @@ "index#refresh": { "in": "query", "name": "refresh", - "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.\nValid values: `true`, `false`, `wait_for`.", + "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf `wait_for`, it waits for a refresh to make this operation visible to search.\nIf `false`, it does nothing with refreshes.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -99883,7 +99923,7 @@ "index#routing": { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -99893,7 +99933,7 @@ "index#timeout": { "in": "query", "name": "timeout", - "description": "Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.", + "description": "The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.\n\nThis parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs.\nSome reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation.\nBy default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error.\nThe actual wait time could be longer, particularly when multiple waits occur.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -99903,7 +99943,7 @@ "index#version": { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "An explicit version number for concurrency control.\nIt must be a non-negative long number.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -99913,7 +99953,7 @@ "index#version_type": { "in": "query", "name": "version_type", - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -99923,7 +99963,7 @@ "index#wait_for_active_shards": { "in": "query", "name": "wait_for_active_shards", - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to all or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The number of shard copies that must be active before proceeding with the operation.\nYou can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value of `1` means it waits for each primary shard to be active.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:WaitForActiveShards" diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index 2ac6065e22..2c2e6f02b0 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -3433,8 +3433,11 @@ "tags": [ "document" ], - "summary": "Index a document", - "description": "Adds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "summary": "Create a new document in the index", + "description": "You can index a new JSON document with the `//_doc/` or `//_create/<_id>` APIs\nUsing `_create` guarantees that the document is indexed only if it does not already exist.\nIt returns a 409 response when a document with a same ID already exists in the index.\nTo update an existing document, you must use the `//_doc/` API.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add a document using the `PUT //_create/<_id>` or `POST //_create/<_id>` request formats, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html" + }, "operationId": "create", "parameters": [ { @@ -3479,8 +3482,11 @@ "tags": [ "document" ], - "summary": "Index a document", - "description": "Adds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "summary": "Create a new document in the index", + "description": "You can index a new JSON document with the `//_doc/` or `//_create/<_id>` APIs\nUsing `_create` guarantees that the document is indexed only if it does not already exist.\nIt returns a 409 response when a document with a same ID already exists in the index.\nTo update an existing document, you must use the `//_doc/` API.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add a document using the `PUT //_create/<_id>` or `POST //_create/<_id>` request formats, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html" + }, "operationId": "create-1", "parameters": [ { @@ -3528,13 +3534,13 @@ "document" ], "summary": "Get a document by its ID", - "description": "Retrieves the document with the specified ID from an index.", + "description": "Get a document and its source or stored fields from an index.\n\nBy default, this API is realtime and is not affected by the refresh rate of the index (when data will become visible for search).\nIn the case where stored fields are requested with the `stored_fields` parameter and the document has been updated but is not yet refreshed, the API will have to parse and analyze the source to extract the stored fields.\nTo turn off realtime behavior, set the `realtime` parameter to false.\n\n**Source filtering**\n\nBy default, the API returns the contents of the `_source` field unless you have used the `stored_fields` parameter or the `_source` field is turned off.\nYou can turn off `_source` retrieval by using the `_source` parameter:\n\n```\nGET my-index-000001/_doc/0?_source=false\n```\n\nIf you only need one or two fields from the `_source`, use the `_source_includes` or `_source_excludes` parameters to include or filter out particular fields.\nThis can be helpful with large documents where partial retrieval can save on network overhead\nBoth parameters take a comma separated list of fields or wildcard expressions.\nFor example:\n\n```\nGET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities\n```\n\nIf you only want to specify includes, you can use a shorter notation:\n\n```\nGET my-index-000001/_doc/0?_source=*.id\n```\n\n**Routing**\n\nIf routing is used during indexing, the routing value also needs to be specified to retrieve a document.\nFor example:\n\n```\nGET my-index-000001/_doc/2?routing=user1\n```\n\nThis request gets the document with ID 2, but it is routed based on the user.\nThe document is not fetched if the correct routing is not specified.\n\n**Distributed**\n\nThe GET operation is hashed into a specific shard ID.\nIt is then redirected to one of the replicas within that shard ID and returns the result.\nThe replicas are the primary shard and its replicas within that shard ID group.\nThis means that the more replicas you have, the better your GET scaling will be.\n\n**Versioning support**\n\nYou can use the `version` parameter to retrieve the document only if its current version is equal to the specified one.\n\nInternally, Elasticsearch has marked the old document as deleted and added an entirely new document.\nThe old version of the document doesn't disappear immediately, although you won't be able to access it.\nElasticsearch cleans up deleted documents in the background as you continue to index more data.", "operationId": "get", "parameters": [ { "in": "path", "name": "index", - "description": "Name of the index that contains the document.", + "description": "The name of the index that contains the document.", "required": true, "deprecated": false, "schema": { @@ -3545,7 +3551,7 @@ { "in": "path", "name": "id", - "description": "Unique identifier of the document.", + "description": "A unique document identifier.", "required": true, "deprecated": false, "schema": { @@ -3556,7 +3562,7 @@ { "in": "query", "name": "preference", - "description": "Specifies the node or shard the operation should be performed on. Random by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.\n\nIf it is set to `_local`, the operation will prefer to be run on a local allocated shard when possible.\nIf it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value.\nThis can help with \"jumping values\" when hitting different shards in different refresh states.\nA sample value can be something like the web session ID or the user name.", "deprecated": false, "schema": { "type": "string" @@ -3576,7 +3582,7 @@ { "in": "query", "name": "refresh", - "description": "If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "deprecated": false, "schema": { "type": "boolean" @@ -3586,7 +3592,7 @@ { "in": "query", "name": "routing", - "description": "Target the specified primary shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -3596,7 +3602,7 @@ { "in": "query", "name": "_source", - "description": "True or false to return the _source field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -3606,7 +3612,7 @@ { "in": "query", "name": "_source_excludes", - "description": "A comma-separated list of source fields to exclude in the response.", + "description": "A comma-separated list of source fields to exclude from the response.\nYou can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -3616,7 +3622,7 @@ { "in": "query", "name": "_source_includes", - "description": "A comma-separated list of source fields to include in the response.", + "description": "A comma-separated list of source fields to include in the response.\nIf this parameter is specified, only these source fields are returned.\nYou can exclude fields from this subset using the `_source_excludes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -3626,7 +3632,7 @@ { "in": "query", "name": "stored_fields", - "description": "List of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to false.", + "description": "A comma-separated list of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to `false`.\nOnly leaf fields can be retrieved with the `stored_field` option.\nObject fields can't be returned;​if specified, the request fails.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -3636,7 +3642,7 @@ { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.", + "description": "The version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -3646,7 +3652,7 @@ { "in": "query", "name": "version_type", - "description": "Specific version type: internal, external, external_gte.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -3671,8 +3677,11 @@ "tags": [ "document" ], - "summary": "Index a document", - "description": "Adds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "summary": "Create or update a document in an index", + "description": "Add a JSON document to the specified data stream or index and make it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.\n\nNOTE: You cannot use this API to send update requests for existing documents in a data stream.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add or overwrite a document using the `PUT //_doc/<_id>` request format, you must have the `create`, `index`, or `write` index privilege.\n* To add a document using the `POST //_doc/` request format, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nNOTE: Replica shards might not all be started when an indexing operation returns successfully.\nBy default, only the primary is required. Set `wait_for_active_shards` to change this default behavior.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Optimistic concurrency control**\n\nIndex operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n * ** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.\n\n**No operation (noop) updates**\n\nWhen updating a document by using this API, a new version of the document is always created even if the document hasn't changed.\nIf this isn't acceptable use the `_update` API with `detect_noop` set to `true`.\nThe `detect_noop` option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.\n\nThere isn't a definitive rule for when noop updates aren't acceptable.\nIt's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.\n\n**Versioning**\n\nEach indexed document is given a version number.\nBy default, internal versioning is used that starts at 1 and increments with each update, deletes included.\nOptionally, the version number can be set to an external value (for example, if maintained in a database).\nTo enable this functionality, `version_type` should be set to `external`.\nThe value provided must be a numeric, long value greater than or equal to 0, and less than around `9.2e+18`.\n\nNOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations.\nIf no version is provided, the operation runs without any version checks.\n\nWhen using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document.\nIf true, the document will be indexed and the new version number used.\nIf the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:\n\n```\nPUT my-index-000001/_doc/1?version=2&version_type=external\n{\n \"user\": {\n \"id\": \"elkbee\"\n }\n}\n\nIn this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.\nIf the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).\n\nA nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.\nEven the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html" + }, "operationId": "index", "parameters": [ { @@ -3728,8 +3737,11 @@ "tags": [ "document" ], - "summary": "Index a document", - "description": "Adds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "summary": "Create or update a document in an index", + "description": "Add a JSON document to the specified data stream or index and make it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.\n\nNOTE: You cannot use this API to send update requests for existing documents in a data stream.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add or overwrite a document using the `PUT //_doc/<_id>` request format, you must have the `create`, `index`, or `write` index privilege.\n* To add a document using the `POST //_doc/` request format, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nNOTE: Replica shards might not all be started when an indexing operation returns successfully.\nBy default, only the primary is required. Set `wait_for_active_shards` to change this default behavior.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Optimistic concurrency control**\n\nIndex operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n * ** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.\n\n**No operation (noop) updates**\n\nWhen updating a document by using this API, a new version of the document is always created even if the document hasn't changed.\nIf this isn't acceptable use the `_update` API with `detect_noop` set to `true`.\nThe `detect_noop` option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.\n\nThere isn't a definitive rule for when noop updates aren't acceptable.\nIt's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.\n\n**Versioning**\n\nEach indexed document is given a version number.\nBy default, internal versioning is used that starts at 1 and increments with each update, deletes included.\nOptionally, the version number can be set to an external value (for example, if maintained in a database).\nTo enable this functionality, `version_type` should be set to `external`.\nThe value provided must be a numeric, long value greater than or equal to 0, and less than around `9.2e+18`.\n\nNOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations.\nIf no version is provided, the operation runs without any version checks.\n\nWhen using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document.\nIf true, the document will be indexed and the new version number used.\nIf the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:\n\n```\nPUT my-index-000001/_doc/1?version=2&version_type=external\n{\n \"user\": {\n \"id\": \"elkbee\"\n }\n}\n\nIn this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.\nIf the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).\n\nA nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.\nEven the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html" + }, "operationId": "index-1", "parameters": [ { @@ -3786,13 +3798,13 @@ "document" ], "summary": "Delete a document", - "description": "Removes a JSON document from the specified index.", + "description": "Remove a JSON document from the specified index.\n\nNOTE: You cannot send deletion requests directly to a data stream.\nTo delete a document in a data stream, you must target the backing index containing the document.\n\n**Optimistic concurrency control**\n\nDelete operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Versioning**\n\nEach document indexed is versioned.\nWhen deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime.\nEvery write operation run on a document, deletes included, causes its version to be incremented.\nThe version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations.\nThe length of time for which a deleted document's version remains available is determined by the `index.gc_deletes` index setting.\n\n**Routing**\n\nIf routing is used during indexing, the routing value also needs to be specified to delete a document.\n\nIf the `_routing` mapping is set to `required` and no routing value is specified, the delete API throws a `RoutingMissingException` and rejects the request.\n\nFor example:\n\n```\nDELETE /my-index-000001/_doc/1?routing=shard-1\n```\n\nThis request deletes the document with ID 1, but it is routed based on the user.\nThe document is not deleted if the correct routing is not specified.\n\n**Distributed**\n\nThe delete operation gets hashed into a specific shard ID.\nIt then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group.", "operationId": "delete", "parameters": [ { "in": "path", "name": "index", - "description": "Name of the target index.", + "description": "The name of the target index.", "required": true, "deprecated": false, "schema": { @@ -3803,7 +3815,7 @@ { "in": "path", "name": "id", - "description": "Unique identifier for the document.", + "description": "A unique identifier for the document.", "required": true, "deprecated": false, "schema": { @@ -3834,7 +3846,7 @@ { "in": "query", "name": "refresh", - "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.\nValid values: `true`, `false`, `wait_for`.", + "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf `wait_for`, it waits for a refresh to make this operation visible to search.\nIf `false`, it does nothing with refreshes.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -3844,7 +3856,7 @@ { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -3854,7 +3866,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for active shards.", + "description": "The period to wait for active shards.\n\nThis parameter is useful for situations where the primary shard assigned to perform the delete operation might not be available when the delete operation runs.\nSome reasons for this might be that the primary shard is currently recovering from a store or undergoing relocation.\nBy default, the delete operation will wait on the primary shard to become available for up to 1 minute before failing and responding with an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -3864,7 +3876,7 @@ { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "An explicit version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -3874,7 +3886,7 @@ { "in": "query", "name": "version_type", - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -3884,7 +3896,7 @@ { "in": "query", "name": "wait_for_active_shards", - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The minimum number of shard copies that must be active before proceeding with the operation.\nYou can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value of `1` means it waits for each primary shard to be active.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:WaitForActiveShards" @@ -3910,13 +3922,13 @@ "document" ], "summary": "Check a document", - "description": "Checks if a specified document exists.", + "description": "Verify that a document exists.\nFor example, check to see if a document with the `_id` 0 exists:\n\n```\nHEAD my-index-000001/_doc/0\n```\n\nIf the document exists, the API returns a status code of `200 - OK`.\nIf the document doesn’t exist, the API returns `404 - Not Found`.\n\n**Versioning support**\n\nYou can use the `version` parameter to check the document only if its current version is equal to the specified one.\n\nInternally, Elasticsearch has marked the old document as deleted and added an entirely new document.\nThe old version of the document doesn't disappear immediately, although you won't be able to access it.\nElasticsearch cleans up deleted documents in the background as you continue to index more data.", "operationId": "exists", "parameters": [ { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and aliases.\nSupports wildcards (`*`).", + "description": "A comma-separated list of data streams, indices, and aliases.\nIt supports wildcards (`*`).", "required": true, "deprecated": false, "schema": { @@ -3927,7 +3939,7 @@ { "in": "path", "name": "id", - "description": "Identifier of the document.", + "description": "A unique document identifier.", "required": true, "deprecated": false, "schema": { @@ -3938,7 +3950,7 @@ { "in": "query", "name": "preference", - "description": "Specifies the node or shard the operation should be performed on.\nRandom by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.\n\nIf it is set to `_local`, the operation will prefer to be run on a local allocated shard when possible.\nIf it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value.\nThis can help with \"jumping values\" when hitting different shards in different refresh states.\nA sample value can be something like the web session ID or the user name.", "deprecated": false, "schema": { "type": "string" @@ -3958,7 +3970,7 @@ { "in": "query", "name": "refresh", - "description": "If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "deprecated": false, "schema": { "type": "boolean" @@ -3968,7 +3980,7 @@ { "in": "query", "name": "routing", - "description": "Target the specified primary shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -3978,7 +3990,7 @@ { "in": "query", "name": "_source", - "description": "`true` or `false` to return the `_source` field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -3988,7 +4000,7 @@ { "in": "query", "name": "_source_excludes", - "description": "A comma-separated list of source fields to exclude in the response.", + "description": "A comma-separated list of source fields to exclude from the response.\nYou can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -3998,7 +4010,7 @@ { "in": "query", "name": "_source_includes", - "description": "A comma-separated list of source fields to include in the response.", + "description": "A comma-separated list of source fields to include in the response.\nIf this parameter is specified, only these source fields are returned.\nYou can exclude fields from this subset using the `_source_excludes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -4008,7 +4020,7 @@ { "in": "query", "name": "stored_fields", - "description": "List of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to false.", + "description": "A comma-separated list of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to `false`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -4028,7 +4040,7 @@ { "in": "query", "name": "version_type", - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -5205,13 +5217,16 @@ "document" ], "summary": "Get a document's source", - "description": "Returns the source of a document.", + "description": "Get the source of a document.\nFor example:\n\n```\nGET my-index-000001/_source/1\n```\n\nYou can use the source filtering parameters to control which parts of the `_source` are returned:\n\n```\nGET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities\n```", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html" + }, "operationId": "get-source", "parameters": [ { "in": "path", "name": "index", - "description": "Name of the index that contains the document.", + "description": "The name of the index that contains the document.", "required": true, "deprecated": false, "schema": { @@ -5222,7 +5237,7 @@ { "in": "path", "name": "id", - "description": "Unique identifier of the document.", + "description": "A unique document identifier.", "required": true, "deprecated": false, "schema": { @@ -5233,7 +5248,7 @@ { "in": "query", "name": "preference", - "description": "Specifies the node or shard the operation should be performed on. Random by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.", "deprecated": false, "schema": { "type": "string" @@ -5243,7 +5258,7 @@ { "in": "query", "name": "realtime", - "description": "Boolean) If true, the request is real-time as opposed to near-real-time.", + "description": "If `true`, the request is real-time as opposed to near-real-time.", "deprecated": false, "schema": { "type": "boolean" @@ -5253,7 +5268,7 @@ { "in": "query", "name": "refresh", - "description": "If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "deprecated": false, "schema": { "type": "boolean" @@ -5263,7 +5278,7 @@ { "in": "query", "name": "routing", - "description": "Target the specified primary shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -5273,7 +5288,7 @@ { "in": "query", "name": "_source", - "description": "True or false to return the _source field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -5303,6 +5318,7 @@ { "in": "query", "name": "stored_fields", + "description": "A comma-separated list of stored fields to return as part of a hit.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -5312,7 +5328,7 @@ { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.", + "description": "The version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -5322,7 +5338,7 @@ { "in": "query", "name": "version_type", - "description": "Specific version type: internal, external, external_gte.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -5348,13 +5364,16 @@ "document" ], "summary": "Check for a document source", - "description": "Checks if a document's `_source` is stored.", + "description": "Check whether a document source exists in an index.\nFor example:\n\n```\nHEAD my-index-000001/_source/1\n```\n\nA document's source is not available if it is disabled in the mapping.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-source-field.html" + }, "operationId": "exists-source", "parameters": [ { "in": "path", "name": "index", - "description": "Comma-separated list of data streams, indices, and aliases.\nSupports wildcards (`*`).", + "description": "A comma-separated list of data streams, indices, and aliases.\nIt supports wildcards (`*`).", "required": true, "deprecated": false, "schema": { @@ -5365,7 +5384,7 @@ { "in": "path", "name": "id", - "description": "Identifier of the document.", + "description": "A unique identifier for the document.", "required": true, "deprecated": false, "schema": { @@ -5376,7 +5395,7 @@ { "in": "query", "name": "preference", - "description": "Specifies the node or shard the operation should be performed on.\nRandom by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.", "deprecated": false, "schema": { "type": "string" @@ -5386,7 +5405,7 @@ { "in": "query", "name": "realtime", - "description": "If true, the request is real-time as opposed to near-real-time.", + "description": "If `true`, the request is real-time as opposed to near-real-time.", "deprecated": false, "schema": { "type": "boolean" @@ -5396,7 +5415,7 @@ { "in": "query", "name": "refresh", - "description": "If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "deprecated": false, "schema": { "type": "boolean" @@ -5406,7 +5425,7 @@ { "in": "query", "name": "routing", - "description": "Target the specified primary shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -5416,7 +5435,7 @@ { "in": "query", "name": "_source", - "description": "`true` or `false` to return the `_source` field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -5446,7 +5465,7 @@ { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "The version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -5456,7 +5475,7 @@ { "in": "query", "name": "version_type", - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -5846,8 +5865,11 @@ "tags": [ "document" ], - "summary": "Index a document", - "description": "Adds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "summary": "Create or update a document in an index", + "description": "Add a JSON document to the specified data stream or index and make it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.\n\nNOTE: You cannot use this API to send update requests for existing documents in a data stream.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add or overwrite a document using the `PUT //_doc/<_id>` request format, you must have the `create`, `index`, or `write` index privilege.\n* To add a document using the `POST //_doc/` request format, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nNOTE: Replica shards might not all be started when an indexing operation returns successfully.\nBy default, only the primary is required. Set `wait_for_active_shards` to change this default behavior.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Optimistic concurrency control**\n\nIndex operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n * ** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.\n\n**No operation (noop) updates**\n\nWhen updating a document by using this API, a new version of the document is always created even if the document hasn't changed.\nIf this isn't acceptable use the `_update` API with `detect_noop` set to `true`.\nThe `detect_noop` option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.\n\nThere isn't a definitive rule for when noop updates aren't acceptable.\nIt's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.\n\n**Versioning**\n\nEach indexed document is given a version number.\nBy default, internal versioning is used that starts at 1 and increments with each update, deletes included.\nOptionally, the version number can be set to an external value (for example, if maintained in a database).\nTo enable this functionality, `version_type` should be set to `external`.\nThe value provided must be a numeric, long value greater than or equal to 0, and less than around `9.2e+18`.\n\nNOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations.\nIf no version is provided, the operation runs without any version checks.\n\nWhen using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document.\nIf true, the document will be indexed and the new version number used.\nIf the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:\n\n```\nPUT my-index-000001/_doc/1?version=2&version_type=external\n{\n \"user\": {\n \"id\": \"elkbee\"\n }\n}\n\nIn this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.\nIf the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).\n\nA nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.\nEven the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html" + }, "operationId": "index-2", "parameters": [ { @@ -15515,7 +15537,7 @@ "document" ], "summary": "Reindex documents", - "description": "Copies documents from a source to a destination. The source can be any existing index, alias, or data stream. The destination must differ from the source. For example, you cannot reindex a data stream into itself.", + "description": "Copy documents from a source to a destination.\nYou can copy all documents to the destination index or reindex a subset of the documents.\nThe source can be any existing index, alias, or data stream.\nThe destination must differ from the source.\nFor example, you cannot reindex a data stream into itself.\n\nIMPORTANT: Reindex requires `_source` to be enabled for all documents in the source.\nThe destination should be configured as wanted before calling the reindex API.\nReindex does not copy the settings from the source or its associated template.\nMappings, shard counts, and replicas, for example, must be configured ahead of time.\n\nIf the Elasticsearch security features are enabled, you must have the following security privileges:\n\n* The `read` index privilege for the source data stream, index, or alias.\n* The `write` index privilege for the destination data stream, index, or index alias.\n* To automatically create a data stream or index with a reindex API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege for the destination data stream, index, or alias.\n* If reindexing from a remote cluster, the `source.remote.user` must have the `monitor` cluster privilege and the `read` index privilege for the source data stream, index, or alias.\n\nIf reindexing from a remote cluster, you must explicitly allow the remote host in the `reindex.remote.whitelist` setting.\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nThe `dest` element can be configured like the index API to control optimistic concurrency control.\nOmitting `version_type` or setting it to `internal` causes Elasticsearch to blindly dump documents into the destination, overwriting any that happen to have the same ID.\n\nSetting `version_type` to `external` causes Elasticsearch to preserve the `version` from the source, create any documents that are missing, and update any documents that have an older version in the destination than they do in the source.\n\nSetting `op_type` to `create` causes the reindex API to create only missing documents in the destination.\nAll existing documents will cause a version conflict.\n\nIMPORTANT: Because data streams are append-only, any reindex request to a destination data stream must have an `op_type` of `create`.\nA reindex can only add new documents to a destination data stream.\nIt cannot update existing documents in a destination data stream.\n\nBy default, version conflicts abort the reindex process.\nTo continue reindexing if there are conflicts, set the `conflicts` request body property to `proceed`.\nIn this case, the response includes a count of the version conflicts that were encountered.\nNote that the handling of other error types is unaffected by the `conflicts` property.\nAdditionally, if you opt to count version conflicts, the operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query.\n\nNOTE: The reindex API makes no effort to handle ID collisions.\nThe last document written will \"win\" but the order isn't usually predictable so it is not a good idea to rely on this behavior.\nInstead, make sure that IDs are unique by using a script.\n\n**Running reindex asynchronously**\n\nIf the request contains `wait_for_completion=false`, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task.\nElasticsearch creates a record of this task as a document at `_tasks/`.\n\n**Reindex from multiple sources**\n\nIf you have many sources to reindex it is generally better to reindex them one at a time rather than using a glob pattern to pick up multiple sources.\nThat way you can resume the process if there are any errors by removing the partially completed source and starting over.\nIt also makes parallelizing the process fairly simple: split the list of sources to reindex and run each list in parallel.\n\nFor example, you can use a bash script like this:\n\n```\nfor index in i1 i2 i3 i4 i5; do\n curl -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{\n \"source\": {\n \"index\": \"'$index'\"\n },\n \"dest\": {\n \"index\": \"'$index'-reindexed\"\n }\n }'\ndone\n```\n\n** Throttling**\n\nSet `requests_per_second` to any positive decimal number (`1.4`, `6`, `1000`, for example) to throttle the rate at which reindex issues batches of index operations.\nRequests are throttled by padding each batch with a wait time.\nTo turn off throttling, set `requests_per_second` to `-1`.\n\nThe throttling is done by waiting between batches so that the scroll that reindex uses internally can be given a timeout that takes into account the padding.\nThe padding time is the difference between the batch size divided by the `requests_per_second` and the time spent writing.\nBy default the batch size is `1000`, so if `requests_per_second` is set to `500`:\n\n```\ntarget_time = 1000 / 500 per second = 2 seconds\nwait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds\n```\n\nSince the batch is issued as a single bulk request, large batch sizes cause Elasticsearch to create many requests and then wait for a while before starting the next set.\nThis is \"bursty\" instead of \"smooth\".\n\n**Slicing**\n\nReindex supports sliced scroll to parallelize the reindexing process.\nThis parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts.\n\nNOTE: Reindexing from remote clusters does not support manual or automatic slicing.\n\nYou can slice a reindex request manually by providing a slice ID and total number of slices to each request.\nYou can also let reindex automatically parallelize by using sliced scroll to slice on `_id`.\nThe `slices` parameter specifies the number of slices to use.\n\nAdding `slices` to the reindex request just automates the manual process, creating sub-requests which means it has some quirks:\n\n* You can see these requests in the tasks API. These sub-requests are \"child\" tasks of the task for the request with slices.\n* Fetching the status of the task for the request with `slices` only contains the status of completed slices.\n* These sub-requests are individually addressable for things like cancellation and rethrottling.\n* Rethrottling the request with `slices` will rethrottle the unfinished sub-request proportionally.\n* Canceling the request with `slices` will cancel each sub-request.\n* Due to the nature of `slices`, each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.\n* Parameters like `requests_per_second` and `max_docs` on a request with `slices` are distributed proportionally to each sub-request. Combine that with the previous point about distribution being uneven and you should conclude that using `max_docs` with `slices` might not result in exactly `max_docs` documents being reindexed.\n* Each sub-request gets a slightly different snapshot of the source, though these are all taken at approximately the same time.\n\nIf slicing automatically, setting `slices` to `auto` will choose a reasonable number for most indices.\nIf slicing manually or otherwise tuning automatic slicing, use the following guidelines.\n\nQuery performance is most efficient when the number of slices is equal to the number of shards in the index.\nIf that number is large (for example, `500`), choose a lower number as too many slices will hurt performance.\nSetting slices higher than the number of shards generally does not improve efficiency and adds overhead.\n\nIndexing performance scales linearly across available resources with the number of slices.\n\nWhether query or indexing performance dominates the runtime depends on the documents being reindexed and cluster resources.\n\n**Modify documents during reindexing**\n\nLike `_update_by_query`, reindex operations support a script that modifies the document.\nUnlike `_update_by_query`, the script is allowed to modify the document's metadata.\n\nJust as in `_update_by_query`, you can set `ctx.op` to change the operation that is run on the destination.\nFor example, set `ctx.op` to `noop` if your script decides that the document doesn’t have to be indexed in the destination. This \"no operation\" will be reported in the `noop` counter in the response body.\nSet `ctx.op` to `delete` if your script decides that the document must be deleted from the destination.\nThe deletion will be reported in the `deleted` counter in the response body.\nSetting `ctx.op` to anything else will return an error, as will setting any other field in `ctx`.\n\nThink of the possibilities! Just be careful; you are able to change:\n\n* `_id`\n* `_index`\n* `_version`\n* `_routing`\n\nSetting `_version` to `null` or clearing it from the `ctx` map is just like not sending the version in an indexing request.\nIt will cause the document to be overwritten in the destination regardless of the version on the target or the version type you use in the reindex API.\n\n**Reindex from remote**\n\nReindex supports reindexing from a remote Elasticsearch cluster.\nThe `host` parameter must contain a scheme, host, port, and optional path.\nThe `username` and `password` parameters are optional and when they are present the reindex operation will connect to the remote Elasticsearch node using basic authentication.\nBe sure to use HTTPS when using basic authentication or the password will be sent in plain text.\nThere are a range of settings available to configure the behavior of the HTTPS connection.\n\nWhen using Elastic Cloud, it is also possible to authenticate against the remote cluster through the use of a valid API key.\nRemote hosts must be explicitly allowed with the `reindex.remote.whitelist` setting.\nIt can be set to a comma delimited list of allowed remote host and port combinations.\nScheme is ignored; only the host and port are used.\nFor example:\n\n```\nreindex.remote.whitelist: [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*\"]\n```\n\nThe list of allowed hosts must be configured on any nodes that will coordinate the reindex.\nThis feature should work with remote clusters of any version of Elasticsearch.\nThis should enable you to upgrade from any version of Elasticsearch to the current version by reindexing from a cluster of the old version.\n\nWARNING: Elasticsearch does not support forward compatibility across major versions.\nFor example, you cannot reindex from a 7.x cluster into a 6.x cluster.\n\nTo enable queries sent to older versions of Elasticsearch, the `query` parameter is sent directly to the remote host without validation or modification.\n\nNOTE: Reindexing from remote clusters does not support manual or automatic slicing.\n\nReindexing from a remote server uses an on-heap buffer that defaults to a maximum size of 100mb.\nIf the remote index includes very large documents you'll need to use a smaller batch size.\nIt is also possible to set the socket read timeout on the remote connection with the `socket_timeout` field and the connection timeout with the `connect_timeout` field.\nBoth default to 30 seconds.\n\n**Configuring SSL parameters**\n\nReindex from remote supports configurable SSL settings.\nThese must be specified in the `elasticsearch.yml` file, with the exception of the secure settings, which you add in the Elasticsearch keystore.\nIt is not possible to configure SSL in the body of the reindex request.", "operationId": "reindex", "parameters": [ { @@ -15531,7 +15553,7 @@ { "in": "query", "name": "requests_per_second", - "description": "The throttle for this request in sub-requests per second.\nDefaults to no throttle.", + "description": "The throttle for this request in sub-requests per second.\nBy default, there is no throttle.", "deprecated": false, "schema": { "type": "number" @@ -15541,7 +15563,7 @@ { "in": "query", "name": "scroll", - "description": "Specifies how long a consistent view of the index should be maintained for scrolled search.", + "description": "The period of time that a consistent view of the index should be maintained for scrolled search.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -15551,7 +15573,7 @@ { "in": "query", "name": "slices", - "description": "The number of slices this task should be divided into.\nDefaults to 1 slice, meaning the task isn’t sliced into subtasks.", + "description": "The number of slices this task should be divided into.\nIt defaults to one slice, which means the task isn't sliced into subtasks.\n\nReindex supports sliced scroll to parallelize the reindexing process.\nThis parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts.\n\nNOTE: Reindexing from remote clusters does not support manual or automatic slicing.\n\nIf set to `auto`, Elasticsearch chooses the number of slices to use.\nThis setting will use one slice per shard, up to a certain limit.\nIf there are multiple sources, it will choose the number of slices based on the index or backing index with the smallest number of shards.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Slices" @@ -15561,7 +15583,7 @@ { "in": "query", "name": "timeout", - "description": "Period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards.", + "description": "The period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards.\nBy default, Elasticsearch waits for at least one minute before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -15571,7 +15593,7 @@ { "in": "query", "name": "wait_for_active_shards", - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The number of shard copies that must be active before proceeding with the operation.\nSet it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value is one, which means it waits for each primary shard to be active.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:WaitForActiveShards" @@ -15612,7 +15634,7 @@ "$ref": "#/components/schemas/_global.reindex:Destination" }, "max_docs": { - "description": "The maximum number of documents to reindex.", + "description": "The maximum number of documents to reindex.\nBy default, all documents are reindexed.\nIf it is a value less then or equal to `scroll_size`, a scroll will not be used to retrieve the results for the operation.\n\nIf `conflicts` is set to `proceed`, the reindex operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query.", "type": "number" }, "script": { @@ -15643,27 +15665,33 @@ "type": "object", "properties": { "batches": { + "description": "The number of scroll responses that were pulled back by the reindex.", "type": "number" }, "created": { + "description": "The number of documents that were successfully created.", "type": "number" }, "deleted": { + "description": "The number of documents that were successfully deleted.", "type": "number" }, "failures": { + "description": "If there were any unrecoverable errors during the process, it is an array of those failures.\nIf this array is not empty, the request ended because of those failures.\nReindex is implemented using batches and any failure causes the entire process to end but all failures in the current batch are collected into the array.\nYou can use the `conflicts` option to prevent the reindex from ending on version conflicts.", "type": "array", "items": { "$ref": "#/components/schemas/_types:BulkIndexByScrollFailure" } }, "noops": { + "description": "The number of documents that were ignored because the script used for the reindex returned a `noop` value for `ctx.op`.", "type": "number" }, "retries": { "$ref": "#/components/schemas/_types:Retries" }, "requests_per_second": { + "description": "The number of requests per second effectively run during the reindex.", "type": "number" }, "slice_id": { @@ -15679,18 +15707,22 @@ "$ref": "#/components/schemas/_types:EpochTimeUnitMillis" }, "timed_out": { + "description": "If any of the requests that ran during the reindex timed out, it is `true`.", "type": "boolean" }, "took": { "$ref": "#/components/schemas/_types:DurationValueUnitMillis" }, "total": { + "description": "The number of documents that were successfully processed.", "type": "number" }, "updated": { + "description": "The number of documents that were successfully updated.\nThat is to say, a document with the same ID already existed before the reindex updated it.", "type": "number" }, "version_conflicts": { + "description": "The number of version conflicts that occurred.", "type": "number" } } @@ -19596,13 +19628,13 @@ "document" ], "summary": "Update a document", - "description": "Updates a document by running a script or passing a partial document.", + "description": "Update a document by running a script or passing a partial document.\n\nIf the Elasticsearch security features are enabled, you must have the `index` or `write` index privilege for the target index or index alias.\n\nThe script can update, delete, or skip modifying the document.\nThe API also supports passing a partial document, which is merged into the existing document.\nTo fully replace an existing document, use the index API.\nThis operation:\n\n* Gets the document (collocated with the shard) from the index.\n* Runs the specified script.\n* Indexes the result.\n\nThe document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.\n\nThe `_source` field must be enabled to use this API.\nIn addition to `_source`, you can access the following variables through the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`, and `_now` (the current timestamp).", "operationId": "update", "parameters": [ { "in": "path", "name": "index", - "description": "The name of the index", + "description": "The name of the target index.\nBy default, the index is created automatically if it doesn't exist.", "required": true, "deprecated": false, "schema": { @@ -19613,7 +19645,7 @@ { "in": "path", "name": "id", - "description": "Document ID", + "description": "A unique identifier for the document to be updated.", "required": true, "deprecated": false, "schema": { @@ -19654,7 +19686,7 @@ { "in": "query", "name": "refresh", - "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search, if 'wait_for' then wait for a refresh to make this operation\nvisible to search, if 'false' do nothing with refreshes.", + "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf 'wait_for', it waits for a refresh to make this operation visible to search.\nIf 'false', it does nothing with refreshes.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -19664,7 +19696,7 @@ { "in": "query", "name": "require_alias", - "description": "If true, the destination must be an index alias.", + "description": "If `true`, the destination must be an index alias.", "deprecated": false, "schema": { "type": "boolean" @@ -19674,7 +19706,7 @@ { "in": "query", "name": "retry_on_conflict", - "description": "Specify how many times should the operation be retried when a conflict occurs.", + "description": "The number of times the operation should be retried when a conflict occurs.", "deprecated": false, "schema": { "type": "number" @@ -19684,7 +19716,7 @@ { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -19694,7 +19726,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for dynamic mapping updates and active shards.\nThis guarantees Elasticsearch waits for at least the timeout before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.", + "description": "The period to wait for the following operations: dynamic mapping updates and waiting for active shards.\nElasticsearch waits for at least the timeout period before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -19704,7 +19736,7 @@ { "in": "query", "name": "wait_for_active_shards", - "description": "The number of shard copies that must be active before proceeding with the operations.\nSet to 'all' or any positive integer up to the total number of shards in the index\n(number_of_replicas+1). Defaults to 1 meaning the primary shard.", + "description": "The number of copies of each shard that must be active before proceeding with the operation.\nSet to 'all' or any positive integer up to the total number of shards in the index (`number_of_replicas`+1).\nThe default value of `1` means it waits for each primary shard to be active.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:WaitForActiveShards" @@ -19714,7 +19746,7 @@ { "in": "query", "name": "_source", - "description": "Set to false to disable source retrieval. You can also specify a comma-separated\nlist of the fields you want to retrieve.", + "description": "If `false`, source retrieval is turned off.\nYou can also specify a comma-separated list of the fields you want to retrieve.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_global.search._types:SourceConfigParam" @@ -19724,7 +19756,7 @@ { "in": "query", "name": "_source_excludes", - "description": "Specify the source fields you want to exclude.", + "description": "The source fields you want to exclude.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -19734,7 +19766,7 @@ { "in": "query", "name": "_source_includes", - "description": "Specify the source fields you want to retrieve.", + "description": "The source fields you want to retrieve.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Fields" @@ -19749,29 +19781,29 @@ "type": "object", "properties": { "detect_noop": { - "description": "Set to false to disable setting 'result' in the response\nto 'noop' if no change to the document occurred.", + "description": "If `true`, the `result` in the response is set to `noop` (no operation) when there are no changes to the document.", "type": "boolean" }, "doc": { - "description": "A partial update to an existing document.", + "description": "A partial update to an existing document.\nIf both `doc` and `script` are specified, `doc` is ignored.", "type": "object" }, "doc_as_upsert": { - "description": "Set to true to use the contents of 'doc' as the value of 'upsert'", + "description": "If `true`, use the contents of 'doc' as the value of 'upsert'.\nNOTE: Using ingest pipelines with `doc_as_upsert` is not supported.", "type": "boolean" }, "script": { "$ref": "#/components/schemas/_types:Script" }, "scripted_upsert": { - "description": "Set to true to execute the script whether or not the document exists.", + "description": "If `true`, run the script whether or not the document exists.", "type": "boolean" }, "_source": { "$ref": "#/components/schemas/_global.search._types:SourceConfig" }, "upsert": { - "description": "If the document does not already exist, the contents of 'upsert' are inserted as a\nnew document. If the document exists, the 'script' is executed.", + "description": "If the document does not already exist, the contents of 'upsert' are inserted as a new document.\nIf the document exists, the 'script' is run.", "type": "object" } } @@ -44198,6 +44230,7 @@ "$ref": "#/components/schemas/_types:IndexName" }, "_primary_term": { + "description": "The primary term assigned to the document for the indexing operation.", "type": "number" }, "result": { @@ -44279,9 +44312,11 @@ "type": "object", "properties": { "bulk": { + "description": "The number of bulk actions retried.", "type": "number" }, "search": { + "description": "The number of search actions retried.", "type": "number" } }, @@ -44813,6 +44848,7 @@ "$ref": "#/components/schemas/_types:IndexName" }, "fields": { + "description": "If the `stored_fields` parameter is set to `true` and `found` is `true`, it contains the document fields stored in the index.", "type": "object", "additionalProperties": { "type": "object" @@ -44825,21 +44861,25 @@ } }, "found": { + "description": "Indicates whether the document exists.", "type": "boolean" }, "_id": { "$ref": "#/components/schemas/_types:Id" }, "_primary_term": { + "description": "The primary term assigned to the document for the indexing operation.", "type": "number" }, "_routing": { + "description": "The explicit routing, if set.", "type": "string" }, "_seq_no": { "$ref": "#/components/schemas/_types:SequenceNumber" }, "_source": { + "description": "If `found` is `true`, it contains the document data formatted in JSON.\nIf the `_source` parameter is set to `false` or the `stored_fields` parameter is set to `true`, it is excluded.", "type": "object" }, "_version": { @@ -53807,7 +53847,7 @@ "$ref": "#/components/schemas/_global.reindex:RemoteSource" }, "size": { - "description": "The number of documents to index per batch.\nUse when indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB.", + "description": "The number of documents to index per batch.\nUse it when you are indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB.", "type": "number" }, "slice": { @@ -58649,7 +58689,7 @@ "create#id": { "in": "path", "name": "id", - "description": "Unique identifier for the document.", + "description": "A unique identifier for the document.\nTo automatically generate a document ID, use the `POST //_doc/` request format.", "required": true, "deprecated": false, "schema": { @@ -58660,7 +58700,7 @@ "create#index": { "in": "path", "name": "index", - "description": "Name of the data stream or index to target.\nIf the target doesn’t exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream.\nIf the target doesn’t exist and doesn’t match a data stream template, this request creates the index.", + "description": "The name of the data stream or index to target.\nIf the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream.\nIf the target doesn't exist and doesn’t match a data stream template, this request creates the index.", "required": true, "deprecated": false, "schema": { @@ -58671,7 +58711,7 @@ "create#pipeline": { "in": "query", "name": "pipeline", - "description": "ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.\nIf a final pipeline is configured it will always run, regardless of the value of this parameter.", + "description": "The ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, setting the value to `_none` turns off the default ingest pipeline for this request.\nIf a final pipeline is configured, it will always run regardless of the value of this parameter.", "deprecated": false, "schema": { "type": "string" @@ -58681,7 +58721,7 @@ "create#refresh": { "in": "query", "name": "refresh", - "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.\nValid values: `true`, `false`, `wait_for`.", + "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf `wait_for`, it waits for a refresh to make this operation visible to search.\nIf `false`, it does nothing with refreshes.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -58691,7 +58731,7 @@ "create#routing": { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -58701,7 +58741,7 @@ "create#timeout": { "in": "query", "name": "timeout", - "description": "Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.", + "description": "The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.\nElasticsearch waits for at least the specified timeout period before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.\n\nThis parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs.\nSome reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation.\nBy default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error.\nThe actual wait time could be longer, particularly when multiple waits occur.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -58711,7 +58751,7 @@ "create#version": { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "The explicit version number for concurrency control.\nIt must be a non-negative long number.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -58721,7 +58761,7 @@ "create#version_type": { "in": "query", "name": "version_type", - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -58731,7 +58771,7 @@ "create#wait_for_active_shards": { "in": "query", "name": "wait_for_active_shards", - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The number of shard copies that must be active before proceeding with the operation.\nYou can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value of `1` means it waits for each primary shard to be active.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:WaitForActiveShards" @@ -59088,7 +59128,7 @@ "index#id": { "in": "path", "name": "id", - "description": "Unique identifier for the document.", + "description": "A unique identifier for the document.\nTo automatically generate a document ID, use the `POST //_doc/` request format and omit this parameter.", "required": true, "deprecated": false, "schema": { @@ -59099,7 +59139,7 @@ "index#index": { "in": "path", "name": "index", - "description": "Name of the data stream or index to target.", + "description": "The name of the data stream or index to target.\nIf the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream.\nIf the target doesn't exist and doesn't match a data stream template, this request creates the index.\nYou can check for existing targets with the resolve index API.", "required": true, "deprecated": false, "schema": { @@ -59130,7 +59170,7 @@ "index#op_type": { "in": "query", "name": "op_type", - "description": "Set to create to only index the document if it does not already exist (put if absent).\nIf a document with the specified `_id` already exists, the indexing operation will fail.\nSame as using the `/_create` endpoint.\nValid values: `index`, `create`.\nIf document id is specified, it defaults to `index`.\nOtherwise, it defaults to `create`.", + "description": "Set to `create` to only index the document if it does not already exist (put if absent).\nIf a document with the specified `_id` already exists, the indexing operation will fail.\nThe behavior is the same as using the `/_create` endpoint.\nIf a document ID is specified, this paramater defaults to `index`.\nOtherwise, it defaults to `create`.\nIf the request targets a data stream, an `op_type` of `create` is required.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:OpType" @@ -59140,7 +59180,7 @@ "index#pipeline": { "in": "query", "name": "pipeline", - "description": "ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.\nIf a final pipeline is configured it will always run, regardless of the value of this parameter.", + "description": "The ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.\nIf a final pipeline is configured it will always run, regardless of the value of this parameter.", "deprecated": false, "schema": { "type": "string" @@ -59150,7 +59190,7 @@ "index#refresh": { "in": "query", "name": "refresh", - "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.\nValid values: `true`, `false`, `wait_for`.", + "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf `wait_for`, it waits for a refresh to make this operation visible to search.\nIf `false`, it does nothing with refreshes.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -59160,7 +59200,7 @@ "index#routing": { "in": "query", "name": "routing", - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Routing" @@ -59170,7 +59210,7 @@ "index#timeout": { "in": "query", "name": "timeout", - "description": "Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.", + "description": "The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.\n\nThis parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs.\nSome reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation.\nBy default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error.\nThe actual wait time could be longer, particularly when multiple waits occur.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -59180,7 +59220,7 @@ "index#version": { "in": "query", "name": "version", - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "An explicit version number for concurrency control.\nIt must be a non-negative long number.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionNumber" @@ -59190,7 +59230,7 @@ "index#version_type": { "in": "query", "name": "version_type", - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:VersionType" @@ -59200,7 +59240,7 @@ "index#wait_for_active_shards": { "in": "query", "name": "wait_for_active_shards", - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to all or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The number of shard copies that must be active before proceeding with the operation.\nYou can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value of `1` means it waits for each primary shard to be active.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:WaitForActiveShards" diff --git a/output/schema/schema.json b/output/schema/schema.json index c945b628d9..90224378cc 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -4206,10 +4206,18 @@ "stability": "stable" } }, - "description": "Index a document.\nAdds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "description": "Create a new document in the index.\n\nYou can index a new JSON document with the `//_doc/` or `//_create/<_id>` APIs\nUsing `_create` guarantees that the document is indexed only if it does not already exist.\nIt returns a 409 response when a document with a same ID already exists in the index.\nTo update an existing document, you must use the `//_doc/` API.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add a document using the `PUT //_create/<_id>` or `POST //_create/<_id>` request formats, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.", + "docId": "docs-index", "docTag": "document", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-index_.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-index_.html", + "extDocId": "data-streams", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/data-streams.html", "name": "create", + "privileges": { + "index": [ + "create" + ] + }, "request": { "name": "Request", "namespace": "_global.create" @@ -4359,10 +4367,16 @@ "stability": "stable" } }, - "description": "Delete a document.\nRemoves a JSON document from the specified index.", + "description": "Delete a document.\n\nRemove a JSON document from the specified index.\n\nNOTE: You cannot send deletion requests directly to a data stream.\nTo delete a document in a data stream, you must target the backing index containing the document.\n\n**Optimistic concurrency control**\n\nDelete operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Versioning**\n\nEach document indexed is versioned.\nWhen deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime.\nEvery write operation run on a document, deletes included, causes its version to be incremented.\nThe version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations.\nThe length of time for which a deleted document's version remains available is determined by the `index.gc_deletes` index setting.\n\n**Routing**\n\nIf routing is used during indexing, the routing value also needs to be specified to delete a document.\n\nIf the `_routing` mapping is set to `required` and no routing value is specified, the delete API throws a `RoutingMissingException` and rejects the request.\n\nFor example:\n\n```\nDELETE /my-index-000001/_doc/1?routing=shard-1\n```\n\nThis request deletes the document with ID 1, but it is routed based on the user.\nThe document is not deleted if the correct routing is not specified.\n\n**Distributed**\n\nThe delete operation gets hashed into a specific shard ID.\nIt then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group.", + "docId": "docs-delete", "docTag": "document", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-delete.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-delete.html", "name": "delete", + "privileges": { + "index": [ + "delete" + ] + }, "request": { "name": "Request", "namespace": "_global.delete" @@ -4988,9 +5002,10 @@ "stability": "stable" } }, - "description": "Check a document.\nChecks if a specified document exists.", + "description": "Check a document.\n\nVerify that a document exists.\nFor example, check to see if a document with the `_id` 0 exists:\n\n```\nHEAD my-index-000001/_doc/0\n```\n\nIf the document exists, the API returns a status code of `200 - OK`.\nIf the document doesn’t exist, the API returns `404 - Not Found`.\n\n**Versioning support**\n\nYou can use the `version` parameter to check the document only if its current version is equal to the specified one.\n\nInternally, Elasticsearch has marked the old document as deleted and added an entirely new document.\nThe old version of the document doesn't disappear immediately, although you won't be able to access it.\nElasticsearch cleans up deleted documents in the background as you continue to index more data.", + "docId": "docs-get", "docTag": "document", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html", "name": "exists", "request": { "name": "Request", @@ -5024,10 +5039,18 @@ "stability": "stable" } }, - "description": "Check for a document source.\nChecks if a document's `_source` is stored.", + "description": "Check for a document source.\n\nCheck whether a document source exists in an index.\nFor example:\n\n```\nHEAD my-index-000001/_source/1\n```\n\nA document's source is not available if it is disabled in the mapping.", + "docId": "docs-get", "docTag": "document", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html", + "extDocId": "mapping-source-field", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-source-field.html", "name": "exists_source", + "privileges": { + "index": [ + "read" + ] + }, "request": { "name": "Request", "namespace": "_global.exists_source" @@ -5427,10 +5450,16 @@ "stability": "stable" } }, - "description": "Get a document by its ID.\nRetrieves the document with the specified ID from an index.", + "description": "Get a document by its ID.\n\nGet a document and its source or stored fields from an index.\n\nBy default, this API is realtime and is not affected by the refresh rate of the index (when data will become visible for search).\nIn the case where stored fields are requested with the `stored_fields` parameter and the document has been updated but is not yet refreshed, the API will have to parse and analyze the source to extract the stored fields.\nTo turn off realtime behavior, set the `realtime` parameter to false.\n\n**Source filtering**\n\nBy default, the API returns the contents of the `_source` field unless you have used the `stored_fields` parameter or the `_source` field is turned off.\nYou can turn off `_source` retrieval by using the `_source` parameter:\n\n```\nGET my-index-000001/_doc/0?_source=false\n```\n\nIf you only need one or two fields from the `_source`, use the `_source_includes` or `_source_excludes` parameters to include or filter out particular fields.\nThis can be helpful with large documents where partial retrieval can save on network overhead\nBoth parameters take a comma separated list of fields or wildcard expressions.\nFor example:\n\n```\nGET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities\n```\n\nIf you only want to specify includes, you can use a shorter notation:\n\n```\nGET my-index-000001/_doc/0?_source=*.id\n```\n\n**Routing**\n\nIf routing is used during indexing, the routing value also needs to be specified to retrieve a document.\nFor example:\n\n```\nGET my-index-000001/_doc/2?routing=user1\n```\n\nThis request gets the document with ID 2, but it is routed based on the user.\nThe document is not fetched if the correct routing is not specified.\n\n**Distributed**\n\nThe GET operation is hashed into a specific shard ID.\nIt is then redirected to one of the replicas within that shard ID and returns the result.\nThe replicas are the primary shard and its replicas within that shard ID group.\nThis means that the more replicas you have, the better your GET scaling will be.\n\n**Versioning support**\n\nYou can use the `version` parameter to retrieve the document only if its current version is equal to the specified one.\n\nInternally, Elasticsearch has marked the old document as deleted and added an entirely new document.\nThe old version of the document doesn't disappear immediately, although you won't be able to access it.\nElasticsearch cleans up deleted documents in the background as you continue to index more data.", + "docId": "docs-get", "docTag": "document", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html", "name": "get", + "privileges": { + "index": [ + "read" + ] + }, "request": { "name": "Request", "namespace": "_global.get" @@ -5559,10 +5588,18 @@ "stability": "stable" } }, - "description": "Get a document's source.\nReturns the source of a document.", + "description": "Get a document's source.\n\nGet the source of a document.\nFor example:\n\n```\nGET my-index-000001/_source/1\n```\n\nYou can use the source filtering parameters to control which parts of the `_source` are returned:\n\n```\nGET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities\n```", + "docId": "docs-get", "docTag": "document", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html", + "extDocId": "mapping-source-field", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-source-field.html", "name": "get_source", + "privileges": { + "index": [ + "read" + ] + }, "request": { "name": "Request", "namespace": "_global.get_source" @@ -6091,10 +6128,18 @@ "stability": "stable" } }, - "description": "Index a document.\nAdds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "description": "Create or update a document in an index.\n\nAdd a JSON document to the specified data stream or index and make it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.\n\nNOTE: You cannot use this API to send update requests for existing documents in a data stream.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add or overwrite a document using the `PUT //_doc/<_id>` request format, you must have the `create`, `index`, or `write` index privilege.\n* To add a document using the `POST //_doc/` request format, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nNOTE: Replica shards might not all be started when an indexing operation returns successfully.\nBy default, only the primary is required. Set `wait_for_active_shards` to change this default behavior.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Optimistic concurrency control**\n\nIndex operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n * ** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.\n\n**No operation (noop) updates**\n\nWhen updating a document by using this API, a new version of the document is always created even if the document hasn't changed.\nIf this isn't acceptable use the `_update` API with `detect_noop` set to `true`.\nThe `detect_noop` option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.\n\nThere isn't a definitive rule for when noop updates aren't acceptable.\nIt's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.\n\n**Versioning**\n\nEach indexed document is given a version number.\nBy default, internal versioning is used that starts at 1 and increments with each update, deletes included.\nOptionally, the version number can be set to an external value (for example, if maintained in a database).\nTo enable this functionality, `version_type` should be set to `external`.\nThe value provided must be a numeric, long value greater than or equal to 0, and less than around `9.2e+18`.\n\nNOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations.\nIf no version is provided, the operation runs without any version checks.\n\nWhen using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document.\nIf true, the document will be indexed and the new version number used.\nIf the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:\n\n```\nPUT my-index-000001/_doc/1?version=2&version_type=external\n{\n \"user\": {\n \"id\": \"elkbee\"\n }\n}\n\nIn this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.\nIf the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).\n\nA nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.\nEven the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.", + "docId": "docs-index", "docTag": "document", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-index_.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-index_.html", + "extDocId": "data-streams", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/data-streams.html", "name": "index", + "privileges": { + "index": [ + "index" + ] + }, "request": { "name": "Request", "namespace": "_global.index" @@ -14598,10 +14643,17 @@ "stability": "stable" } }, - "description": "Reindex documents.\nCopies documents from a source to a destination. The source can be any existing index, alias, or data stream. The destination must differ from the source. For example, you cannot reindex a data stream into itself.", + "description": "Reindex documents.\n\nCopy documents from a source to a destination.\nYou can copy all documents to the destination index or reindex a subset of the documents.\nThe source can be any existing index, alias, or data stream.\nThe destination must differ from the source.\nFor example, you cannot reindex a data stream into itself.\n\nIMPORTANT: Reindex requires `_source` to be enabled for all documents in the source.\nThe destination should be configured as wanted before calling the reindex API.\nReindex does not copy the settings from the source or its associated template.\nMappings, shard counts, and replicas, for example, must be configured ahead of time.\n\nIf the Elasticsearch security features are enabled, you must have the following security privileges:\n\n* The `read` index privilege for the source data stream, index, or alias.\n* The `write` index privilege for the destination data stream, index, or index alias.\n* To automatically create a data stream or index with a reindex API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege for the destination data stream, index, or alias.\n* If reindexing from a remote cluster, the `source.remote.user` must have the `monitor` cluster privilege and the `read` index privilege for the source data stream, index, or alias.\n\nIf reindexing from a remote cluster, you must explicitly allow the remote host in the `reindex.remote.whitelist` setting.\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nThe `dest` element can be configured like the index API to control optimistic concurrency control.\nOmitting `version_type` or setting it to `internal` causes Elasticsearch to blindly dump documents into the destination, overwriting any that happen to have the same ID.\n\nSetting `version_type` to `external` causes Elasticsearch to preserve the `version` from the source, create any documents that are missing, and update any documents that have an older version in the destination than they do in the source.\n\nSetting `op_type` to `create` causes the reindex API to create only missing documents in the destination.\nAll existing documents will cause a version conflict.\n\nIMPORTANT: Because data streams are append-only, any reindex request to a destination data stream must have an `op_type` of `create`.\nA reindex can only add new documents to a destination data stream.\nIt cannot update existing documents in a destination data stream.\n\nBy default, version conflicts abort the reindex process.\nTo continue reindexing if there are conflicts, set the `conflicts` request body property to `proceed`.\nIn this case, the response includes a count of the version conflicts that were encountered.\nNote that the handling of other error types is unaffected by the `conflicts` property.\nAdditionally, if you opt to count version conflicts, the operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query.\n\nNOTE: The reindex API makes no effort to handle ID collisions.\nThe last document written will \"win\" but the order isn't usually predictable so it is not a good idea to rely on this behavior.\nInstead, make sure that IDs are unique by using a script.\n\n**Running reindex asynchronously**\n\nIf the request contains `wait_for_completion=false`, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task.\nElasticsearch creates a record of this task as a document at `_tasks/`.\n\n**Reindex from multiple sources**\n\nIf you have many sources to reindex it is generally better to reindex them one at a time rather than using a glob pattern to pick up multiple sources.\nThat way you can resume the process if there are any errors by removing the partially completed source and starting over.\nIt also makes parallelizing the process fairly simple: split the list of sources to reindex and run each list in parallel.\n\nFor example, you can use a bash script like this:\n\n```\nfor index in i1 i2 i3 i4 i5; do\n curl -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{\n \"source\": {\n \"index\": \"'$index'\"\n },\n \"dest\": {\n \"index\": \"'$index'-reindexed\"\n }\n }'\ndone\n```\n\n** Throttling**\n\nSet `requests_per_second` to any positive decimal number (`1.4`, `6`, `1000`, for example) to throttle the rate at which reindex issues batches of index operations.\nRequests are throttled by padding each batch with a wait time.\nTo turn off throttling, set `requests_per_second` to `-1`.\n\nThe throttling is done by waiting between batches so that the scroll that reindex uses internally can be given a timeout that takes into account the padding.\nThe padding time is the difference between the batch size divided by the `requests_per_second` and the time spent writing.\nBy default the batch size is `1000`, so if `requests_per_second` is set to `500`:\n\n```\ntarget_time = 1000 / 500 per second = 2 seconds\nwait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds\n```\n\nSince the batch is issued as a single bulk request, large batch sizes cause Elasticsearch to create many requests and then wait for a while before starting the next set.\nThis is \"bursty\" instead of \"smooth\".\n\n**Slicing**\n\nReindex supports sliced scroll to parallelize the reindexing process.\nThis parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts.\n\nNOTE: Reindexing from remote clusters does not support manual or automatic slicing.\n\nYou can slice a reindex request manually by providing a slice ID and total number of slices to each request.\nYou can also let reindex automatically parallelize by using sliced scroll to slice on `_id`.\nThe `slices` parameter specifies the number of slices to use.\n\nAdding `slices` to the reindex request just automates the manual process, creating sub-requests which means it has some quirks:\n\n* You can see these requests in the tasks API. These sub-requests are \"child\" tasks of the task for the request with slices.\n* Fetching the status of the task for the request with `slices` only contains the status of completed slices.\n* These sub-requests are individually addressable for things like cancellation and rethrottling.\n* Rethrottling the request with `slices` will rethrottle the unfinished sub-request proportionally.\n* Canceling the request with `slices` will cancel each sub-request.\n* Due to the nature of `slices`, each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.\n* Parameters like `requests_per_second` and `max_docs` on a request with `slices` are distributed proportionally to each sub-request. Combine that with the previous point about distribution being uneven and you should conclude that using `max_docs` with `slices` might not result in exactly `max_docs` documents being reindexed.\n* Each sub-request gets a slightly different snapshot of the source, though these are all taken at approximately the same time.\n\nIf slicing automatically, setting `slices` to `auto` will choose a reasonable number for most indices.\nIf slicing manually or otherwise tuning automatic slicing, use the following guidelines.\n\nQuery performance is most efficient when the number of slices is equal to the number of shards in the index.\nIf that number is large (for example, `500`), choose a lower number as too many slices will hurt performance.\nSetting slices higher than the number of shards generally does not improve efficiency and adds overhead.\n\nIndexing performance scales linearly across available resources with the number of slices.\n\nWhether query or indexing performance dominates the runtime depends on the documents being reindexed and cluster resources.\n\n**Modify documents during reindexing**\n\nLike `_update_by_query`, reindex operations support a script that modifies the document.\nUnlike `_update_by_query`, the script is allowed to modify the document's metadata.\n\nJust as in `_update_by_query`, you can set `ctx.op` to change the operation that is run on the destination.\nFor example, set `ctx.op` to `noop` if your script decides that the document doesn’t have to be indexed in the destination. This \"no operation\" will be reported in the `noop` counter in the response body.\nSet `ctx.op` to `delete` if your script decides that the document must be deleted from the destination.\nThe deletion will be reported in the `deleted` counter in the response body.\nSetting `ctx.op` to anything else will return an error, as will setting any other field in `ctx`.\n\nThink of the possibilities! Just be careful; you are able to change:\n\n* `_id`\n* `_index`\n* `_version`\n* `_routing`\n\nSetting `_version` to `null` or clearing it from the `ctx` map is just like not sending the version in an indexing request.\nIt will cause the document to be overwritten in the destination regardless of the version on the target or the version type you use in the reindex API.\n\n**Reindex from remote**\n\nReindex supports reindexing from a remote Elasticsearch cluster.\nThe `host` parameter must contain a scheme, host, port, and optional path.\nThe `username` and `password` parameters are optional and when they are present the reindex operation will connect to the remote Elasticsearch node using basic authentication.\nBe sure to use HTTPS when using basic authentication or the password will be sent in plain text.\nThere are a range of settings available to configure the behavior of the HTTPS connection.\n\nWhen using Elastic Cloud, it is also possible to authenticate against the remote cluster through the use of a valid API key.\nRemote hosts must be explicitly allowed with the `reindex.remote.whitelist` setting.\nIt can be set to a comma delimited list of allowed remote host and port combinations.\nScheme is ignored; only the host and port are used.\nFor example:\n\n```\nreindex.remote.whitelist: [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*\"]\n```\n\nThe list of allowed hosts must be configured on any nodes that will coordinate the reindex.\nThis feature should work with remote clusters of any version of Elasticsearch.\nThis should enable you to upgrade from any version of Elasticsearch to the current version by reindexing from a cluster of the old version.\n\nWARNING: Elasticsearch does not support forward compatibility across major versions.\nFor example, you cannot reindex from a 7.x cluster into a 6.x cluster.\n\nTo enable queries sent to older versions of Elasticsearch, the `query` parameter is sent directly to the remote host without validation or modification.\n\nNOTE: Reindexing from remote clusters does not support manual or automatic slicing.\n\nReindexing from a remote server uses an on-heap buffer that defaults to a maximum size of 100mb.\nIf the remote index includes very large documents you'll need to use a smaller batch size.\nIt is also possible to set the socket read timeout on the remote connection with the `socket_timeout` field and the connection timeout with the `connect_timeout` field.\nBoth default to 30 seconds.\n\n**Configuring SSL parameters**\n\nReindex from remote supports configurable SSL settings.\nThese must be specified in the `elasticsearch.yml` file, with the exception of the secure settings, which you add in the Elasticsearch keystore.\nIt is not possible to configure SSL in the body of the reindex request.", + "docId": "docs-reindex", "docTag": "document", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-reindex.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-reindex.html", "name": "reindex", + "privileges": { + "index": [ + "read", + "write" + ] + }, "request": { "name": "Request", "namespace": "_global.reindex" @@ -14637,9 +14689,10 @@ "stability": "stable" } }, - "description": "Throttle a reindex operation.\n\nChange the number of requests per second for a particular reindex operation.", + "description": "Throttle a reindex operation.\n\nChange the number of requests per second for a particular reindex operation.\nFor example:\n\n```\nPOST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1\n```\n\nRethrottling that speeds up the query takes effect immediately.\nRethrottling that slows down the query will take effect after completing the current batch.\nThis behavior prevents scroll timeouts.", + "docId": "docs-reindex", "docTag": "document", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-reindex.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-reindex.html", "name": "reindex_rethrottle", "request": { "name": "Request", @@ -21196,10 +21249,16 @@ "stability": "stable" } }, - "description": "Update a document.\nUpdates a document by running a script or passing a partial document.", + "description": "Update a document.\n\nUpdate a document by running a script or passing a partial document.\n\nIf the Elasticsearch security features are enabled, you must have the `index` or `write` index privilege for the target index or index alias.\n\nThe script can update, delete, or skip modifying the document.\nThe API also supports passing a partial document, which is merged into the existing document.\nTo fully replace an existing document, use the index API.\nThis operation:\n\n* Gets the document (collocated with the shard) from the index.\n* Runs the specified script.\n* Indexes the result.\n\nThe document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.\n\nThe `_source` field must be enabled to use this API.\nIn addition to `_source`, you can access the following variables through the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`, and `_now` (the current timestamp).", + "docId": "docs-update", "docTag": "document", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-update.html", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-update.html", "name": "update", + "privileges": { + "index": [ + "write" + ] + }, "request": { "name": "Request", "namespace": "_global.update" @@ -23312,7 +23371,7 @@ } } }, - "description": "Index a document.\nAdds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "description": "Create a new document in the index.\n\nYou can index a new JSON document with the `//_doc/` or `//_create/<_id>` APIs\nUsing `_create` guarantees that the document is indexed only if it does not already exist.\nIt returns a 409 response when a document with a same ID already exists in the index.\nTo update an existing document, you must use the `//_doc/` API.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add a document using the `PUT //_create/<_id>` or `POST //_create/<_id>` request formats, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.", "generics": [ { "name": "TDocument", @@ -23331,7 +23390,7 @@ }, "path": [ { - "description": "Unique identifier for the document.", + "description": "A unique identifier for the document.\nTo automatically generate a document ID, use the `POST //_doc/` request format.", "name": "id", "required": true, "type": { @@ -23343,7 +23402,7 @@ } }, { - "description": "Name of the data stream or index to target.\nIf the target doesn’t exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream.\nIf the target doesn’t exist and doesn’t match a data stream template, this request creates the index.", + "description": "The name of the data stream or index to target.\nIf the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream.\nIf the target doesn't exist and doesn’t match a data stream template, this request creates the index.", "name": "index", "required": true, "type": { @@ -23357,7 +23416,7 @@ ], "query": [ { - "description": "ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.\nIf a final pipeline is configured it will always run, regardless of the value of this parameter.", + "description": "The ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, setting the value to `_none` turns off the default ingest pipeline for this request.\nIf a final pipeline is configured, it will always run regardless of the value of this parameter.", "name": "pipeline", "required": false, "type": { @@ -23369,7 +23428,7 @@ } }, { - "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.\nValid values: `true`, `false`, `wait_for`.", + "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf `wait_for`, it waits for a refresh to make this operation visible to search.\nIf `false`, it does nothing with refreshes.", "name": "refresh", "required": false, "serverDefault": "false", @@ -23382,7 +23441,7 @@ } }, { - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "name": "routing", "required": false, "type": { @@ -23394,7 +23453,7 @@ } }, { - "description": "Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.", + "description": "The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.\nElasticsearch waits for at least the specified timeout period before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.\n\nThis parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs.\nSome reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation.\nBy default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error.\nThe actual wait time could be longer, particularly when multiple waits occur.", "name": "timeout", "required": false, "serverDefault": "1m", @@ -23407,7 +23466,7 @@ } }, { - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "The explicit version number for concurrency control.\nIt must be a non-negative long number.", "name": "version", "required": false, "type": { @@ -23419,7 +23478,7 @@ } }, { - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "name": "version_type", "required": false, "type": { @@ -23431,7 +23490,7 @@ } }, { - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The number of shard copies that must be active before proceeding with the operation.\nYou can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value of `1` means it waits for each primary shard to be active.", "name": "wait_for_active_shards", "required": false, "serverDefault": "1", @@ -23444,7 +23503,7 @@ } } ], - "specLocation": "_global/create/CreateRequest.ts#L32-L96" + "specLocation": "_global/create/CreateRequest.ts#L32-L178" }, { "kind": "response", @@ -23472,7 +23531,7 @@ "body": { "kind": "no_body" }, - "description": "Delete a document.\nRemoves a JSON document from the specified index.", + "description": "Delete a document.\n\nRemove a JSON document from the specified index.\n\nNOTE: You cannot send deletion requests directly to a data stream.\nTo delete a document in a data stream, you must target the backing index containing the document.\n\n**Optimistic concurrency control**\n\nDelete operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Versioning**\n\nEach document indexed is versioned.\nWhen deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime.\nEvery write operation run on a document, deletes included, causes its version to be incremented.\nThe version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations.\nThe length of time for which a deleted document's version remains available is determined by the `index.gc_deletes` index setting.\n\n**Routing**\n\nIf routing is used during indexing, the routing value also needs to be specified to delete a document.\n\nIf the `_routing` mapping is set to `required` and no routing value is specified, the delete API throws a `RoutingMissingException` and rejects the request.\n\nFor example:\n\n```\nDELETE /my-index-000001/_doc/1?routing=shard-1\n```\n\nThis request deletes the document with ID 1, but it is routed based on the user.\nThe document is not deleted if the correct routing is not specified.\n\n**Distributed**\n\nThe delete operation gets hashed into a specific shard ID.\nIt then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group.", "inherits": { "type": { "name": "RequestBase", @@ -23485,7 +23544,7 @@ }, "path": [ { - "description": "Unique identifier for the document.", + "description": "A unique identifier for the document.", "name": "id", "required": true, "type": { @@ -23497,7 +23556,7 @@ } }, { - "description": "Name of the target index.", + "description": "The name of the target index.", "name": "index", "required": true, "type": { @@ -23512,6 +23571,8 @@ "query": [ { "description": "Only perform the operation if the document has this primary term.", + "extDocId": "optimistic-concurrency", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/optimistic-concurrency-control.html", "name": "if_primary_term", "required": false, "type": { @@ -23524,6 +23585,8 @@ }, { "description": "Only perform the operation if the document has this sequence number.", + "extDocId": "optimistic-concurrency", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/optimistic-concurrency-control.html", "name": "if_seq_no", "required": false, "type": { @@ -23535,7 +23598,7 @@ } }, { - "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.\nValid values: `true`, `false`, `wait_for`.", + "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf `wait_for`, it waits for a refresh to make this operation visible to search.\nIf `false`, it does nothing with refreshes.", "name": "refresh", "required": false, "serverDefault": "false", @@ -23548,7 +23611,7 @@ } }, { - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value used to route operations to a specific shard.", "name": "routing", "required": false, "type": { @@ -23560,7 +23623,7 @@ } }, { - "description": "Period to wait for active shards.", + "description": "The period to wait for active shards.\n\nThis parameter is useful for situations where the primary shard assigned to perform the delete operation might not be available when the delete operation runs.\nSome reasons for this might be that the primary shard is currently recovering from a store or undergoing relocation.\nBy default, the delete operation will wait on the primary shard to become available for up to 1 minute before failing and responding with an error.", "name": "timeout", "required": false, "serverDefault": "1m", @@ -23573,7 +23636,7 @@ } }, { - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "An explicit version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "name": "version", "required": false, "type": { @@ -23585,7 +23648,7 @@ } }, { - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "name": "version_type", "required": false, "type": { @@ -23597,7 +23660,7 @@ } }, { - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The minimum number of shard copies that must be active before proceeding with the operation.\nYou can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value of `1` means it waits for each primary shard to be active.", "name": "wait_for_active_shards", "required": false, "serverDefault": "1", @@ -23610,7 +23673,7 @@ } } ], - "specLocation": "_global/delete/DeleteRequest.ts#L34-L93" + "specLocation": "_global/delete/DeleteRequest.ts#L34-L140" }, { "kind": "response", @@ -24477,7 +24540,7 @@ "body": { "kind": "no_body" }, - "description": "Check a document.\nChecks if a specified document exists.", + "description": "Check a document.\n\nVerify that a document exists.\nFor example, check to see if a document with the `_id` 0 exists:\n\n```\nHEAD my-index-000001/_doc/0\n```\n\nIf the document exists, the API returns a status code of `200 - OK`.\nIf the document doesn’t exist, the API returns `404 - Not Found`.\n\n**Versioning support**\n\nYou can use the `version` parameter to check the document only if its current version is equal to the specified one.\n\nInternally, Elasticsearch has marked the old document as deleted and added an entirely new document.\nThe old version of the document doesn't disappear immediately, although you won't be able to access it.\nElasticsearch cleans up deleted documents in the background as you continue to index more data.", "inherits": { "type": { "name": "RequestBase", @@ -24490,7 +24553,7 @@ }, "path": [ { - "description": "Identifier of the document.", + "description": "A unique document identifier.", "name": "id", "required": true, "type": { @@ -24502,7 +24565,7 @@ } }, { - "description": "Comma-separated list of data streams, indices, and aliases.\nSupports wildcards (`*`).", + "description": "A comma-separated list of data streams, indices, and aliases.\nIt supports wildcards (`*`).", "name": "index", "required": true, "type": { @@ -24516,7 +24579,7 @@ ], "query": [ { - "description": "Specifies the node or shard the operation should be performed on.\nRandom by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.\n\nIf it is set to `_local`, the operation will prefer to be run on a local allocated shard when possible.\nIf it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value.\nThis can help with \"jumping values\" when hitting different shards in different refresh states.\nA sample value can be something like the web session ID or the user name.", "name": "preference", "required": false, "type": { @@ -24543,7 +24606,7 @@ } }, { - "description": "If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "name": "refresh", "required": false, "serverDefault": false, @@ -24556,9 +24619,9 @@ } }, { - "description": "Target the specified primary shard.", - "docId": "routing", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#get-routing", + "description": "A custom value used to route operations to a specific shard.", + "extDocId": "routing", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#get-routing", "name": "routing", "required": false, "type": { @@ -24570,7 +24633,7 @@ } }, { - "description": "`true` or `false` to return the `_source` field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "name": "_source", "required": false, "type": { @@ -24582,7 +24645,7 @@ } }, { - "description": "A comma-separated list of source fields to exclude in the response.", + "description": "A comma-separated list of source fields to exclude from the response.\nYou can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "name": "_source_excludes", "required": false, "type": { @@ -24594,7 +24657,7 @@ } }, { - "description": "A comma-separated list of source fields to include in the response.", + "description": "A comma-separated list of source fields to include in the response.\nIf this parameter is specified, only these source fields are returned.\nYou can exclude fields from this subset using the `_source_excludes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "name": "_source_includes", "required": false, "type": { @@ -24606,7 +24669,7 @@ } }, { - "description": "List of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to false.", + "description": "A comma-separated list of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to `false`.", "name": "stored_fields", "required": false, "type": { @@ -24630,7 +24693,7 @@ } }, { - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "name": "version_type", "required": false, "type": { @@ -24642,7 +24705,7 @@ } } ], - "specLocation": "_global/exists/DocumentExistsRequest.ts#L31-L101" + "specLocation": "_global/exists/DocumentExistsRequest.ts#L31-L130" }, { "kind": "response", @@ -24663,7 +24726,7 @@ "body": { "kind": "no_body" }, - "description": "Check for a document source.\nChecks if a document's `_source` is stored.", + "description": "Check for a document source.\n\nCheck whether a document source exists in an index.\nFor example:\n\n```\nHEAD my-index-000001/_source/1\n```\n\nA document's source is not available if it is disabled in the mapping.", "inherits": { "type": { "name": "RequestBase", @@ -24676,7 +24739,7 @@ }, "path": [ { - "description": "Identifier of the document.", + "description": "A unique identifier for the document.", "name": "id", "required": true, "type": { @@ -24688,7 +24751,7 @@ } }, { - "description": "Comma-separated list of data streams, indices, and aliases.\nSupports wildcards (`*`).", + "description": "A comma-separated list of data streams, indices, and aliases.\nIt supports wildcards (`*`).", "name": "index", "required": true, "type": { @@ -24702,7 +24765,7 @@ ], "query": [ { - "description": "Specifies the node or shard the operation should be performed on.\nRandom by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.", "name": "preference", "required": false, "type": { @@ -24714,9 +24777,9 @@ } }, { - "description": "If true, the request is real-time as opposed to near-real-time.", - "docId": "realtime", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#realtime", + "description": "If `true`, the request is real-time as opposed to near-real-time.", + "extDocId": "realtime", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#realtime", "name": "realtime", "required": false, "serverDefault": true, @@ -24729,7 +24792,7 @@ } }, { - "description": "If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "name": "refresh", "required": false, "serverDefault": false, @@ -24742,9 +24805,9 @@ } }, { - "description": "Target the specified primary shard.", - "docId": "routing", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#get-routing", + "description": "A custom value used to route operations to a specific shard.", + "extDocId": "routing", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#get-routing", "name": "routing", "required": false, "type": { @@ -24756,7 +24819,7 @@ } }, { - "description": "`true` or `false` to return the `_source` field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "name": "_source", "required": false, "type": { @@ -24792,7 +24855,7 @@ } }, { - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "The version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "name": "version", "required": false, "type": { @@ -24804,7 +24867,7 @@ } }, { - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "name": "version_type", "required": false, "type": { @@ -24816,7 +24879,7 @@ } } ], - "specLocation": "_global/exists_source/SourceExistsRequest.ts#L31-L95" + "specLocation": "_global/exists_source/SourceExistsRequest.ts#L31-L107" }, { "kind": "response", @@ -25693,6 +25756,7 @@ }, "properties": [ { + "description": "The name of the index the document belongs to.", "name": "_index", "required": true, "type": { @@ -25704,6 +25768,7 @@ } }, { + "description": "If the `stored_fields` parameter is set to `true` and `found` is `true`, it contains the document fields stored in the index.", "name": "fields", "required": false, "type": { @@ -25736,6 +25801,7 @@ } }, { + "description": "Indicates whether the document exists.", "name": "found", "required": true, "type": { @@ -25747,6 +25813,7 @@ } }, { + "description": "The unique identifier for the document.", "name": "_id", "required": true, "type": { @@ -25758,6 +25825,8 @@ } }, { + "description": "The primary term assigned to the document for the indexing operation.", + "extDocId": "optimistic_concurrency", "name": "_primary_term", "required": false, "type": { @@ -25769,6 +25838,7 @@ } }, { + "description": "The explicit routing, if set.", "name": "_routing", "required": false, "type": { @@ -25780,6 +25850,8 @@ } }, { + "description": "The sequence number assigned to the document for the indexing operation.\nSequence numbers are used to ensure an older version of a document doesn't overwrite a newer version.", + "extDocId": "optimistic_concurrency", "name": "_seq_no", "required": false, "type": { @@ -25791,6 +25863,7 @@ } }, { + "description": "If `found` is `true`, it contains the document data formatted in JSON.\nIf the `_source` parameter is set to `false` or the `stored_fields` parameter is set to `true`, it is excluded.", "name": "_source", "required": false, "type": { @@ -25802,6 +25875,7 @@ } }, { + "description": "The document version, which is ncremented each time the document is updated.", "name": "_version", "required": false, "type": { @@ -25813,7 +25887,7 @@ } } ], - "specLocation": "_global/get/types.ts#L25-L36" + "specLocation": "_global/get/types.ts#L25-L67" }, { "kind": "request", @@ -25823,7 +25897,7 @@ "body": { "kind": "no_body" }, - "description": "Get a document by its ID.\nRetrieves the document with the specified ID from an index.", + "description": "Get a document by its ID.\n\nGet a document and its source or stored fields from an index.\n\nBy default, this API is realtime and is not affected by the refresh rate of the index (when data will become visible for search).\nIn the case where stored fields are requested with the `stored_fields` parameter and the document has been updated but is not yet refreshed, the API will have to parse and analyze the source to extract the stored fields.\nTo turn off realtime behavior, set the `realtime` parameter to false.\n\n**Source filtering**\n\nBy default, the API returns the contents of the `_source` field unless you have used the `stored_fields` parameter or the `_source` field is turned off.\nYou can turn off `_source` retrieval by using the `_source` parameter:\n\n```\nGET my-index-000001/_doc/0?_source=false\n```\n\nIf you only need one or two fields from the `_source`, use the `_source_includes` or `_source_excludes` parameters to include or filter out particular fields.\nThis can be helpful with large documents where partial retrieval can save on network overhead\nBoth parameters take a comma separated list of fields or wildcard expressions.\nFor example:\n\n```\nGET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities\n```\n\nIf you only want to specify includes, you can use a shorter notation:\n\n```\nGET my-index-000001/_doc/0?_source=*.id\n```\n\n**Routing**\n\nIf routing is used during indexing, the routing value also needs to be specified to retrieve a document.\nFor example:\n\n```\nGET my-index-000001/_doc/2?routing=user1\n```\n\nThis request gets the document with ID 2, but it is routed based on the user.\nThe document is not fetched if the correct routing is not specified.\n\n**Distributed**\n\nThe GET operation is hashed into a specific shard ID.\nIt is then redirected to one of the replicas within that shard ID and returns the result.\nThe replicas are the primary shard and its replicas within that shard ID group.\nThis means that the more replicas you have, the better your GET scaling will be.\n\n**Versioning support**\n\nYou can use the `version` parameter to retrieve the document only if its current version is equal to the specified one.\n\nInternally, Elasticsearch has marked the old document as deleted and added an entirely new document.\nThe old version of the document doesn't disappear immediately, although you won't be able to access it.\nElasticsearch cleans up deleted documents in the background as you continue to index more data.", "inherits": { "type": { "name": "RequestBase", @@ -25836,7 +25910,7 @@ }, "path": [ { - "description": "Unique identifier of the document.", + "description": "A unique document identifier.", "name": "id", "required": true, "type": { @@ -25848,7 +25922,7 @@ } }, { - "description": "Name of the index that contains the document.", + "description": "The name of the index that contains the document.", "name": "index", "required": true, "type": { @@ -25869,7 +25943,7 @@ "visibility": "feature_flag" } }, - "description": "Should this request force synthetic _source?\nUse this to test if the mapping supports synthetic _source and to get a sense of the worst case performance.\nFetches with this enabled will be slower the enabling synthetic source natively in the index.", + "description": "Indicates whether the request forces synthetic `_source`.\nUse this paramater to test if the mapping supports synthetic `_source` and to get a sense of the worst case performance.\nFetches with this parameter enabled will be slower than enabling synthetic source natively in the index.", "name": "force_synthetic_source", "required": false, "type": { @@ -25881,7 +25955,7 @@ } }, { - "description": "Specifies the node or shard the operation should be performed on. Random by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.\n\nIf it is set to `_local`, the operation will prefer to be run on a local allocated shard when possible.\nIf it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value.\nThis can help with \"jumping values\" when hitting different shards in different refresh states.\nA sample value can be something like the web session ID or the user name.", "name": "preference", "required": false, "type": { @@ -25908,7 +25982,7 @@ } }, { - "description": "If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "name": "refresh", "required": false, "serverDefault": false, @@ -25921,9 +25995,9 @@ } }, { - "description": "Target the specified primary shard.", - "docId": "routing", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#get-routing", + "description": "A custom value used to route operations to a specific shard.", + "extDocId": "routing", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#get-routing", "name": "routing", "required": false, "type": { @@ -25935,7 +26009,7 @@ } }, { - "description": "True or false to return the _source field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "name": "_source", "required": false, "type": { @@ -25947,7 +26021,7 @@ } }, { - "description": "A comma-separated list of source fields to exclude in the response.", + "description": "A comma-separated list of source fields to exclude from the response.\nYou can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "name": "_source_excludes", "required": false, "type": { @@ -25959,7 +26033,7 @@ } }, { - "description": "A comma-separated list of source fields to include in the response.", + "description": "A comma-separated list of source fields to include in the response.\nIf this parameter is specified, only these source fields are returned.\nYou can exclude fields from this subset using the `_source_excludes` query parameter.\nIf the `_source` parameter is `false`, this parameter is ignored.", "name": "_source_includes", "required": false, "type": { @@ -25971,7 +26045,7 @@ } }, { - "description": "List of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to false.", + "description": "A comma-separated list of stored fields to return as part of a hit.\nIf no fields are specified, no stored fields are included in the response.\nIf this field is specified, the `_source` parameter defaults to `false`.\nOnly leaf fields can be retrieved with the `stored_field` option.\nObject fields can't be returned;​if specified, the request fails.", "name": "stored_fields", "required": false, "type": { @@ -25983,7 +26057,7 @@ } }, { - "description": "Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.", + "description": "The version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "name": "version", "required": false, "type": { @@ -25995,7 +26069,7 @@ } }, { - "description": "Specific version type: internal, external, external_gte.", + "description": "The version type.", "name": "version_type", "required": false, "type": { @@ -26007,7 +26081,7 @@ } } ], - "specLocation": "_global/get/GetRequest.ts#L31-L101" + "specLocation": "_global/get/GetRequest.ts#L31-L174" }, { "kind": "response", @@ -26445,7 +26519,7 @@ "body": { "kind": "no_body" }, - "description": "Get a document's source.\nReturns the source of a document.", + "description": "Get a document's source.\n\nGet the source of a document.\nFor example:\n\n```\nGET my-index-000001/_source/1\n```\n\nYou can use the source filtering parameters to control which parts of the `_source` are returned:\n\n```\nGET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities\n```", "inherits": { "type": { "name": "RequestBase", @@ -26458,7 +26532,7 @@ }, "path": [ { - "description": "Unique identifier of the document.", + "description": "A unique document identifier.", "name": "id", "required": true, "type": { @@ -26470,7 +26544,7 @@ } }, { - "description": "Name of the index that contains the document.", + "description": "The name of the index that contains the document.", "name": "index", "required": true, "type": { @@ -26484,7 +26558,7 @@ ], "query": [ { - "description": "Specifies the node or shard the operation should be performed on. Random by default.", + "description": "The node or shard the operation should be performed on.\nBy default, the operation is randomized between the shard replicas.", "name": "preference", "required": false, "type": { @@ -26496,7 +26570,7 @@ } }, { - "description": "Boolean) If true, the request is real-time as opposed to near-real-time.", + "description": "If `true`, the request is real-time as opposed to near-real-time.", "docId": "realtiime", "name": "realtime", "required": false, @@ -26510,7 +26584,7 @@ } }, { - "description": "If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes.", + "description": "If `true`, the request refreshes the relevant shards before retrieving the document.\nSetting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).", "name": "refresh", "required": false, "serverDefault": false, @@ -26523,9 +26597,9 @@ } }, { - "description": "Target the specified primary shard.", - "docId": "routing", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#get-routing", + "description": "A custom value used to route operations to a specific shard.", + "extDocId": "routing", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#get-routing", "name": "routing", "required": false, "type": { @@ -26537,7 +26611,7 @@ } }, { - "description": "True or false to return the _source field or not, or a list of fields to return.", + "description": "Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return.", "name": "_source", "required": false, "type": { @@ -26573,6 +26647,7 @@ } }, { + "description": "A comma-separated list of stored fields to return as part of a hit.", "name": "stored_fields", "required": false, "type": { @@ -26584,7 +26659,7 @@ } }, { - "description": "Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed.", + "description": "The version number for concurrency control.\nIt must match the current version of the document for the request to succeed.", "name": "version", "required": false, "type": { @@ -26596,7 +26671,7 @@ } }, { - "description": "Specific version type: internal, external, external_gte.", + "description": "The version type.", "name": "version_type", "required": false, "type": { @@ -26608,7 +26683,7 @@ } } ], - "specLocation": "_global/get_source/SourceRequest.ts#L31-L89" + "specLocation": "_global/get_source/SourceRequest.ts#L31-L110" }, { "kind": "response", @@ -28115,7 +28190,7 @@ } } }, - "description": "Index a document.\nAdds a JSON document to the specified data stream or index and makes it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.", + "description": "Create or update a document in an index.\n\nAdd a JSON document to the specified data stream or index and make it searchable.\nIf the target is an index and the document already exists, the request updates the document and increments its version.\n\nNOTE: You cannot use this API to send update requests for existing documents in a data stream.\n\nIf the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:\n\n* To add or overwrite a document using the `PUT //_doc/<_id>` request format, you must have the `create`, `index`, or `write` index privilege.\n* To add a document using the `POST //_doc/` request format, you must have the `create_doc`, `create`, `index`, or `write` index privilege.\n* To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege.\n\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nNOTE: Replica shards might not all be started when an indexing operation returns successfully.\nBy default, only the primary is required. Set `wait_for_active_shards` to change this default behavior.\n\n**Automatically create data streams and indices**\n\nIf the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream.\n\nIf the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.\n\nNOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.\n\nIf no mapping exists, the index operation creates a dynamic mapping.\nBy default, new fields and objects are automatically added to the mapping if needed.\n\nAutomatic index creation is controlled by the `action.auto_create_index` setting.\nIf it is `true`, any index can be created automatically.\nYou can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely.\nSpecify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked.\nWhen a list is specified, the default behaviour is to disallow.\n\nNOTE: The `action.auto_create_index` setting affects the automatic creation of indices only.\nIt does not affect the creation of data streams.\n\n**Optimistic concurrency control**\n\nIndex operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters.\nIf a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`.\n\n**Routing**\n\nBy default, shard placement — or routing — is controlled by using a hash of the document's ID value.\nFor more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter.\n\nWhen setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself.\nThis does come at the (very minimal) cost of an additional document parsing pass.\nIf the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.\n\nNOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template.\n\n * ** Distributed**\n\nThe index operation is directed to the primary shard based on its route and performed on the actual node containing this shard.\nAfter the primary shard completes the operation, if needed, the update is distributed to applicable replicas.\n\n**Active shards**\n\nTo improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.\nIf the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.\nBy default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`).\nThis default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`.\nTo alter this behavior per operation, use the `wait_for_active_shards request` parameter.\n\nValid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1).\nSpecifying a negative value or a number greater than the number of shard copies will throw an error.\n\nFor example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).\nIf you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.\nThis means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.\nIf `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.\nThis requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.\nHowever, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.\nThe operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.\n\nIt is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.\nAfter the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.\nThe `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed.\n\n**No operation (noop) updates**\n\nWhen updating a document by using this API, a new version of the document is always created even if the document hasn't changed.\nIf this isn't acceptable use the `_update` API with `detect_noop` set to `true`.\nThe `detect_noop` option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.\n\nThere isn't a definitive rule for when noop updates aren't acceptable.\nIt's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.\n\n**Versioning**\n\nEach indexed document is given a version number.\nBy default, internal versioning is used that starts at 1 and increments with each update, deletes included.\nOptionally, the version number can be set to an external value (for example, if maintained in a database).\nTo enable this functionality, `version_type` should be set to `external`.\nThe value provided must be a numeric, long value greater than or equal to 0, and less than around `9.2e+18`.\n\nNOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations.\nIf no version is provided, the operation runs without any version checks.\n\nWhen using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document.\nIf true, the document will be indexed and the new version number used.\nIf the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:\n\n```\nPUT my-index-000001/_doc/1?version=2&version_type=external\n{\n \"user\": {\n \"id\": \"elkbee\"\n }\n}\n\nIn this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.\nIf the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).\n\nA nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.\nEven the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.", "generics": [ { "name": "TDocument", @@ -28134,7 +28209,7 @@ }, "path": [ { - "description": "Unique identifier for the document.", + "description": "A unique identifier for the document.\nTo automatically generate a document ID, use the `POST //_doc/` request format and omit this parameter.", "name": "id", "required": false, "type": { @@ -28146,7 +28221,7 @@ } }, { - "description": "Name of the data stream or index to target.", + "description": "The name of the data stream or index to target.\nIf the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream.\nIf the target doesn't exist and doesn't match a data stream template, this request creates the index.\nYou can check for existing targets with the resolve index API.", "name": "index", "required": true, "type": { @@ -28161,6 +28236,8 @@ "query": [ { "description": "Only perform the operation if the document has this primary term.", + "extDocId": "optimistic-concurrency", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/optimistic-concurrency-control.html", "name": "if_primary_term", "required": false, "type": { @@ -28173,6 +28250,8 @@ }, { "description": "Only perform the operation if the document has this sequence number.", + "extDocId": "optimistic-concurrency", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/optimistic-concurrency-control.html", "name": "if_seq_no", "required": false, "type": { @@ -28184,7 +28263,7 @@ } }, { - "description": "Set to create to only index the document if it does not already exist (put if absent).\nIf a document with the specified `_id` already exists, the indexing operation will fail.\nSame as using the `/_create` endpoint.\nValid values: `index`, `create`.\nIf document id is specified, it defaults to `index`.\nOtherwise, it defaults to `create`.", + "description": "Set to `create` to only index the document if it does not already exist (put if absent).\nIf a document with the specified `_id` already exists, the indexing operation will fail.\nThe behavior is the same as using the `/_create` endpoint.\nIf a document ID is specified, this paramater defaults to `index`.\nOtherwise, it defaults to `create`.\nIf the request targets a data stream, an `op_type` of `create` is required.", "name": "op_type", "required": false, "type": { @@ -28196,7 +28275,7 @@ } }, { - "description": "ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.\nIf a final pipeline is configured it will always run, regardless of the value of this parameter.", + "description": "The ID of the pipeline to use to preprocess incoming documents.\nIf the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request.\nIf a final pipeline is configured it will always run, regardless of the value of this parameter.", "name": "pipeline", "required": false, "type": { @@ -28208,9 +28287,10 @@ } }, { - "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes.\nValid values: `true`, `false`, `wait_for`.", + "description": "If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf `wait_for`, it waits for a refresh to make this operation visible to search.\nIf `false`, it does nothing with refreshes.", "name": "refresh", "required": false, + "serverDefault": "false", "type": { "kind": "instance_of", "type": { @@ -28220,7 +28300,7 @@ } }, { - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value that is used to route operations to a specific shard.", "name": "routing", "required": false, "type": { @@ -28232,7 +28312,7 @@ } }, { - "description": "Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.", + "description": "The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.\n\nThis parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs.\nSome reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation.\nBy default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error.\nThe actual wait time could be longer, particularly when multiple waits occur.", "name": "timeout", "required": false, "serverDefault": "1m", @@ -28245,7 +28325,7 @@ } }, { - "description": "Explicit version number for concurrency control.\nThe specified version must match the current version of the document for the request to succeed.", + "description": "An explicit version number for concurrency control.\nIt must be a non-negative long number.", "name": "version", "required": false, "type": { @@ -28257,7 +28337,7 @@ } }, { - "description": "Specific version type: `external`, `external_gte`.", + "description": "The version type.", "name": "version_type", "required": false, "type": { @@ -28269,7 +28349,7 @@ } }, { - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to all or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The number of shard copies that must be active before proceeding with the operation.\nYou can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value of `1` means it waits for each primary shard to be active.", "name": "wait_for_active_shards", "required": false, "serverDefault": "1", @@ -28295,7 +28375,7 @@ } } ], - "specLocation": "_global/index/IndexRequest.ts#L35-L119" + "specLocation": "_global/index/IndexRequest.ts#L35-L253" }, { "kind": "response", @@ -32044,7 +32124,7 @@ } }, { - "description": "Set to `create` to only index documents that do not already exist.\nImportant: To reindex to a data stream destination, this argument must be `create`.", + "description": "If it is `create`, the operation will only index documents that do not already exist (also known as \"put if absent\").\n\nIMPORTANT: To reindex to a data stream destination, this argument must be `create`.", "name": "op_type", "required": false, "serverDefault": "index", @@ -32069,7 +32149,7 @@ } }, { - "description": "By default, a document's routing is preserved unless it’s changed by the script.\nSet to `discard` to set routing to `null`, or `=value` to route using the specified `value`.", + "description": "By default, a document's routing is preserved unless it's changed by the script.\nIf it is `keep`, the routing on the bulk request sent for each match is set to the routing on the match.\nIf it is `discard`, the routing on the bulk request sent for each match is set to `null`.\nIf it is `=value`, the routing on the bulk request sent for each match is set to all value specified after the equals sign (`=`).", "name": "routing", "required": false, "serverDefault": "keep", @@ -32094,7 +32174,7 @@ } } ], - "specLocation": "_global/reindex/types.ts#L39-L64" + "specLocation": "_global/reindex/types.ts#L39-L67" }, { "kind": "interface", @@ -32104,9 +32184,10 @@ }, "properties": [ { - "description": "The remote connection timeout.\nDefaults to 30 seconds.", + "description": "The remote connection timeout.", "name": "connect_timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -32139,7 +32220,7 @@ } }, { - "description": "The URL for the remote instance of Elasticsearch that you want to index from.", + "description": "The URL for the remote instance of Elasticsearch that you want to index from.\nThis information is required when you're indexing from remote.", "name": "host", "required": true, "type": { @@ -32175,9 +32256,10 @@ } }, { - "description": "The remote socket read timeout. Defaults to 30 seconds.", + "description": "The remote socket read timeout.", "name": "socket_timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -32187,7 +32269,7 @@ } } ], - "specLocation": "_global/reindex/types.ts#L99-L125" + "specLocation": "_global/reindex/types.ts#L112-L140" }, { "kind": "request", @@ -32198,7 +32280,7 @@ "kind": "properties", "properties": [ { - "description": "Set to proceed to continue reindexing even if there are conflicts.", + "description": "Indicates whether to continue reindexing even when there are conflicts.", "name": "conflicts", "required": false, "serverDefault": "abort", @@ -32223,7 +32305,7 @@ } }, { - "description": "The maximum number of documents to reindex.", + "description": "The maximum number of documents to reindex.\nBy default, all documents are reindexed.\nIf it is a value less then or equal to `scroll_size`, a scroll will not be used to retrieve the results for the operation.\n\nIf `conflicts` is set to `proceed`, the reindex operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query.", "name": "max_docs", "required": false, "type": { @@ -32271,7 +32353,7 @@ } ] }, - "description": "Reindex documents.\nCopies documents from a source to a destination. The source can be any existing index, alias, or data stream. The destination must differ from the source. For example, you cannot reindex a data stream into itself.", + "description": "Reindex documents.\n\nCopy documents from a source to a destination.\nYou can copy all documents to the destination index or reindex a subset of the documents.\nThe source can be any existing index, alias, or data stream.\nThe destination must differ from the source.\nFor example, you cannot reindex a data stream into itself.\n\nIMPORTANT: Reindex requires `_source` to be enabled for all documents in the source.\nThe destination should be configured as wanted before calling the reindex API.\nReindex does not copy the settings from the source or its associated template.\nMappings, shard counts, and replicas, for example, must be configured ahead of time.\n\nIf the Elasticsearch security features are enabled, you must have the following security privileges:\n\n* The `read` index privilege for the source data stream, index, or alias.\n* The `write` index privilege for the destination data stream, index, or index alias.\n* To automatically create a data stream or index with a reindex API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege for the destination data stream, index, or alias.\n* If reindexing from a remote cluster, the `source.remote.user` must have the `monitor` cluster privilege and the `read` index privilege for the source data stream, index, or alias.\n\nIf reindexing from a remote cluster, you must explicitly allow the remote host in the `reindex.remote.whitelist` setting.\nAutomatic data stream creation requires a matching index template with data stream enabled.\n\nThe `dest` element can be configured like the index API to control optimistic concurrency control.\nOmitting `version_type` or setting it to `internal` causes Elasticsearch to blindly dump documents into the destination, overwriting any that happen to have the same ID.\n\nSetting `version_type` to `external` causes Elasticsearch to preserve the `version` from the source, create any documents that are missing, and update any documents that have an older version in the destination than they do in the source.\n\nSetting `op_type` to `create` causes the reindex API to create only missing documents in the destination.\nAll existing documents will cause a version conflict.\n\nIMPORTANT: Because data streams are append-only, any reindex request to a destination data stream must have an `op_type` of `create`.\nA reindex can only add new documents to a destination data stream.\nIt cannot update existing documents in a destination data stream.\n\nBy default, version conflicts abort the reindex process.\nTo continue reindexing if there are conflicts, set the `conflicts` request body property to `proceed`.\nIn this case, the response includes a count of the version conflicts that were encountered.\nNote that the handling of other error types is unaffected by the `conflicts` property.\nAdditionally, if you opt to count version conflicts, the operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query.\n\nNOTE: The reindex API makes no effort to handle ID collisions.\nThe last document written will \"win\" but the order isn't usually predictable so it is not a good idea to rely on this behavior.\nInstead, make sure that IDs are unique by using a script.\n\n**Running reindex asynchronously**\n\nIf the request contains `wait_for_completion=false`, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task.\nElasticsearch creates a record of this task as a document at `_tasks/`.\n\n**Reindex from multiple sources**\n\nIf you have many sources to reindex it is generally better to reindex them one at a time rather than using a glob pattern to pick up multiple sources.\nThat way you can resume the process if there are any errors by removing the partially completed source and starting over.\nIt also makes parallelizing the process fairly simple: split the list of sources to reindex and run each list in parallel.\n\nFor example, you can use a bash script like this:\n\n```\nfor index in i1 i2 i3 i4 i5; do\n curl -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{\n \"source\": {\n \"index\": \"'$index'\"\n },\n \"dest\": {\n \"index\": \"'$index'-reindexed\"\n }\n }'\ndone\n```\n\n** Throttling**\n\nSet `requests_per_second` to any positive decimal number (`1.4`, `6`, `1000`, for example) to throttle the rate at which reindex issues batches of index operations.\nRequests are throttled by padding each batch with a wait time.\nTo turn off throttling, set `requests_per_second` to `-1`.\n\nThe throttling is done by waiting between batches so that the scroll that reindex uses internally can be given a timeout that takes into account the padding.\nThe padding time is the difference between the batch size divided by the `requests_per_second` and the time spent writing.\nBy default the batch size is `1000`, so if `requests_per_second` is set to `500`:\n\n```\ntarget_time = 1000 / 500 per second = 2 seconds\nwait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds\n```\n\nSince the batch is issued as a single bulk request, large batch sizes cause Elasticsearch to create many requests and then wait for a while before starting the next set.\nThis is \"bursty\" instead of \"smooth\".\n\n**Slicing**\n\nReindex supports sliced scroll to parallelize the reindexing process.\nThis parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts.\n\nNOTE: Reindexing from remote clusters does not support manual or automatic slicing.\n\nYou can slice a reindex request manually by providing a slice ID and total number of slices to each request.\nYou can also let reindex automatically parallelize by using sliced scroll to slice on `_id`.\nThe `slices` parameter specifies the number of slices to use.\n\nAdding `slices` to the reindex request just automates the manual process, creating sub-requests which means it has some quirks:\n\n* You can see these requests in the tasks API. These sub-requests are \"child\" tasks of the task for the request with slices.\n* Fetching the status of the task for the request with `slices` only contains the status of completed slices.\n* These sub-requests are individually addressable for things like cancellation and rethrottling.\n* Rethrottling the request with `slices` will rethrottle the unfinished sub-request proportionally.\n* Canceling the request with `slices` will cancel each sub-request.\n* Due to the nature of `slices`, each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.\n* Parameters like `requests_per_second` and `max_docs` on a request with `slices` are distributed proportionally to each sub-request. Combine that with the previous point about distribution being uneven and you should conclude that using `max_docs` with `slices` might not result in exactly `max_docs` documents being reindexed.\n* Each sub-request gets a slightly different snapshot of the source, though these are all taken at approximately the same time.\n\nIf slicing automatically, setting `slices` to `auto` will choose a reasonable number for most indices.\nIf slicing manually or otherwise tuning automatic slicing, use the following guidelines.\n\nQuery performance is most efficient when the number of slices is equal to the number of shards in the index.\nIf that number is large (for example, `500`), choose a lower number as too many slices will hurt performance.\nSetting slices higher than the number of shards generally does not improve efficiency and adds overhead.\n\nIndexing performance scales linearly across available resources with the number of slices.\n\nWhether query or indexing performance dominates the runtime depends on the documents being reindexed and cluster resources.\n\n**Modify documents during reindexing**\n\nLike `_update_by_query`, reindex operations support a script that modifies the document.\nUnlike `_update_by_query`, the script is allowed to modify the document's metadata.\n\nJust as in `_update_by_query`, you can set `ctx.op` to change the operation that is run on the destination.\nFor example, set `ctx.op` to `noop` if your script decides that the document doesn’t have to be indexed in the destination. This \"no operation\" will be reported in the `noop` counter in the response body.\nSet `ctx.op` to `delete` if your script decides that the document must be deleted from the destination.\nThe deletion will be reported in the `deleted` counter in the response body.\nSetting `ctx.op` to anything else will return an error, as will setting any other field in `ctx`.\n\nThink of the possibilities! Just be careful; you are able to change:\n\n* `_id`\n* `_index`\n* `_version`\n* `_routing`\n\nSetting `_version` to `null` or clearing it from the `ctx` map is just like not sending the version in an indexing request.\nIt will cause the document to be overwritten in the destination regardless of the version on the target or the version type you use in the reindex API.\n\n**Reindex from remote**\n\nReindex supports reindexing from a remote Elasticsearch cluster.\nThe `host` parameter must contain a scheme, host, port, and optional path.\nThe `username` and `password` parameters are optional and when they are present the reindex operation will connect to the remote Elasticsearch node using basic authentication.\nBe sure to use HTTPS when using basic authentication or the password will be sent in plain text.\nThere are a range of settings available to configure the behavior of the HTTPS connection.\n\nWhen using Elastic Cloud, it is also possible to authenticate against the remote cluster through the use of a valid API key.\nRemote hosts must be explicitly allowed with the `reindex.remote.whitelist` setting.\nIt can be set to a comma delimited list of allowed remote host and port combinations.\nScheme is ignored; only the host and port are used.\nFor example:\n\n```\nreindex.remote.whitelist: [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*\"]\n```\n\nThe list of allowed hosts must be configured on any nodes that will coordinate the reindex.\nThis feature should work with remote clusters of any version of Elasticsearch.\nThis should enable you to upgrade from any version of Elasticsearch to the current version by reindexing from a cluster of the old version.\n\nWARNING: Elasticsearch does not support forward compatibility across major versions.\nFor example, you cannot reindex from a 7.x cluster into a 6.x cluster.\n\nTo enable queries sent to older versions of Elasticsearch, the `query` parameter is sent directly to the remote host without validation or modification.\n\nNOTE: Reindexing from remote clusters does not support manual or automatic slicing.\n\nReindexing from a remote server uses an on-heap buffer that defaults to a maximum size of 100mb.\nIf the remote index includes very large documents you'll need to use a smaller batch size.\nIt is also possible to set the socket read timeout on the remote connection with the `socket_timeout` field and the connection timeout with the `connect_timeout` field.\nBoth default to 30 seconds.\n\n**Configuring SSL parameters**\n\nReindex from remote supports configurable SSL settings.\nThese must be specified in the `elasticsearch.yml` file, with the exception of the secure settings, which you add in the Elasticsearch keystore.\nIt is not possible to configure SSL in the body of the reindex request.", "inherits": { "type": { "name": "RequestBase", @@ -32298,7 +32380,7 @@ } }, { - "description": "The throttle for this request in sub-requests per second.\nDefaults to no throttle.", + "description": "The throttle for this request in sub-requests per second.\nBy default, there is no throttle.", "name": "requests_per_second", "required": false, "serverDefault": -1, @@ -32311,7 +32393,7 @@ } }, { - "description": "Specifies how long a consistent view of the index should be maintained for scrolled search.", + "description": "The period of time that a consistent view of the index should be maintained for scrolled search.", "name": "scroll", "required": false, "type": { @@ -32323,7 +32405,9 @@ } }, { - "description": "The number of slices this task should be divided into.\nDefaults to 1 slice, meaning the task isn’t sliced into subtasks.", + "description": "The number of slices this task should be divided into.\nIt defaults to one slice, which means the task isn't sliced into subtasks.\n\nReindex supports sliced scroll to parallelize the reindexing process.\nThis parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts.\n\nNOTE: Reindexing from remote clusters does not support manual or automatic slicing.\n\nIf set to `auto`, Elasticsearch chooses the number of slices to use.\nThis setting will use one slice per shard, up to a certain limit.\nIf there are multiple sources, it will choose the number of slices based on the index or backing index with the smallest number of shards.", + "extDocId": "slice-scroll", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#slice-scroll", "name": "slices", "required": false, "serverDefault": "1", @@ -32336,7 +32420,7 @@ } }, { - "description": "Period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards.", + "description": "The period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards.\nBy default, Elasticsearch waits for at least one minute before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.", "name": "timeout", "required": false, "serverDefault": "1m", @@ -32349,7 +32433,7 @@ } }, { - "description": "The number of shard copies that must be active before proceeding with the operation.\nSet to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).", + "description": "The number of shard copies that must be active before proceeding with the operation.\nSet it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).\nThe default value is one, which means it waits for each primary shard to be active.", "name": "wait_for_active_shards", "required": false, "serverDefault": "1", @@ -32388,7 +32472,7 @@ } } ], - "specLocation": "_global/reindex/ReindexRequest.ts#L27-L104" + "specLocation": "_global/reindex/ReindexRequest.ts#L27-L303" }, { "kind": "response", @@ -32396,6 +32480,7 @@ "kind": "properties", "properties": [ { + "description": "The number of scroll responses that were pulled back by the reindex.", "name": "batches", "required": false, "type": { @@ -32407,6 +32492,7 @@ } }, { + "description": "The number of documents that were successfully created.", "name": "created", "required": false, "type": { @@ -32418,6 +32504,7 @@ } }, { + "description": "The number of documents that were successfully deleted.", "name": "deleted", "required": false, "type": { @@ -32429,6 +32516,7 @@ } }, { + "description": "If there were any unrecoverable errors during the process, it is an array of those failures.\nIf this array is not empty, the request ended because of those failures.\nReindex is implemented using batches and any failure causes the entire process to end but all failures in the current batch are collected into the array.\nYou can use the `conflicts` option to prevent the reindex from ending on version conflicts.", "name": "failures", "required": false, "type": { @@ -32443,6 +32531,7 @@ } }, { + "description": "The number of documents that were ignored because the script used for the reindex returned a `noop` value for `ctx.op`.", "name": "noops", "required": false, "type": { @@ -32454,6 +32543,7 @@ } }, { + "description": "The number of retries attempted by reindex.", "name": "retries", "required": false, "type": { @@ -32465,6 +32555,7 @@ } }, { + "description": "The number of requests per second effectively run during the reindex.", "name": "requests_per_second", "required": false, "type": { @@ -32498,6 +32589,7 @@ } }, { + "description": "The number of milliseconds the request slept to conform to `requests_per_second`.", "name": "throttled_millis", "required": false, "type": { @@ -32518,6 +32610,7 @@ } }, { + "description": "This field should always be equal to zero in a reindex response.\nIt has meaning only when using the task API, where it indicates the next time (in milliseconds since epoch) that a throttled request will be run again in order to conform to `requests_per_second`.", "name": "throttled_until_millis", "required": false, "type": { @@ -32538,6 +32631,7 @@ } }, { + "description": "If any of the requests that ran during the reindex timed out, it is `true`.", "name": "timed_out", "required": false, "type": { @@ -32549,6 +32643,7 @@ } }, { + "description": "The total milliseconds the entire operation took.", "name": "took", "required": false, "type": { @@ -32569,6 +32664,7 @@ } }, { + "description": "The number of documents that were successfully processed.", "name": "total", "required": false, "type": { @@ -32580,6 +32676,7 @@ } }, { + "description": "The number of documents that were successfully updated.\nThat is to say, a document with the same ID already existed before the reindex updated it.", "name": "updated", "required": false, "type": { @@ -32591,6 +32688,7 @@ } }, { + "description": "The number of version conflicts that occurred.", "name": "version_conflicts", "required": false, "type": { @@ -32607,7 +32705,7 @@ "name": "Response", "namespace": "_global.reindex" }, - "specLocation": "_global/reindex/ReindexResponse.ts#L26-L45" + "specLocation": "_global/reindex/ReindexResponse.ts#L26-L92" }, { "kind": "interface", @@ -32617,7 +32715,7 @@ }, "properties": [ { - "description": "The name of the data stream, index, or alias you are copying from.\nAccepts a comma-separated list to reindex from multiple sources.", + "description": "The name of the data stream, index, or alias you are copying from.\nIt accepts a comma-separated list to reindex from multiple sources.", "name": "index", "required": true, "type": { @@ -32629,7 +32727,7 @@ } }, { - "description": "Specifies the documents to reindex using the Query DSL.", + "description": "The documents to reindex, which is defined with Query DSL.", "name": "query", "required": false, "type": { @@ -32653,9 +32751,10 @@ } }, { - "description": "The number of documents to index per batch.\nUse when indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB.", + "description": "The number of documents to index per batch.\nUse it when you are indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB.", "name": "size", "required": false, + "serverDefault": 1000, "type": { "kind": "instance_of", "type": { @@ -32677,6 +32776,11 @@ } }, { + "deprecation": { + "description": "", + "version": "7.6.0" + }, + "description": "A comma-separated list of `:` pairs to sort by before indexing.\nUse it in conjunction with `max_docs` to control what documents are reindexed.\n\nWARNING: Sort in reindex is deprecated.\nSorting in reindex was never guaranteed to index documents in order and prevents further development of reindex such as resilience and performance improvements.\nIf used in combination with `max_docs`, consider using a query filter instead.", "name": "sort", "required": false, "type": { @@ -32689,7 +32793,7 @@ }, { "codegenName": "source_fields", - "description": "If `true` reindexes all source fields.\nSet to a list to reindex select fields.", + "description": "If `true`, reindex all source fields.\nSet it to a list to reindex select fields.", "name": "_source", "required": false, "serverDefault": "true", @@ -32713,7 +32817,7 @@ } } ], - "specLocation": "_global/reindex/types.ts#L66-L97" + "specLocation": "_global/reindex/types.ts#L69-L110" }, { "kind": "interface", @@ -33081,7 +33185,7 @@ "body": { "kind": "no_body" }, - "description": "Throttle a reindex operation.\n\nChange the number of requests per second for a particular reindex operation.", + "description": "Throttle a reindex operation.\n\nChange the number of requests per second for a particular reindex operation.\nFor example:\n\n```\nPOST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1\n```\n\nRethrottling that speeds up the query takes effect immediately.\nRethrottling that slows down the query will take effect after completing the current batch.\nThis behavior prevents scroll timeouts.", "inherits": { "type": { "name": "RequestBase", @@ -33094,7 +33198,7 @@ }, "path": [ { - "description": "Identifier for the task.", + "description": "The task identifier, which can be found by using the tasks API.", "name": "task_id", "required": true, "type": { @@ -33108,7 +33212,7 @@ ], "query": [ { - "description": "The throttle for this request in sub-requests per second.", + "description": "The throttle for this request in sub-requests per second.\nIt can be either `-1` to turn off throttling or any decimal number like `1.7` or `12` to throttle to that level.", "name": "requests_per_second", "required": false, "type": { @@ -33120,7 +33224,7 @@ } } ], - "specLocation": "_global/reindex_rethrottle/ReindexRethrottleRequest.ts#L24-L46" + "specLocation": "_global/reindex_rethrottle/ReindexRethrottleRequest.ts#L24-L57" }, { "kind": "response", @@ -42691,7 +42795,7 @@ "kind": "properties", "properties": [ { - "description": "Set to false to disable setting 'result' in the response\nto 'noop' if no change to the document occurred.", + "description": "If `true`, the `result` in the response is set to `noop` (no operation) when there are no changes to the document.", "name": "detect_noop", "required": false, "serverDefault": true, @@ -42704,7 +42808,7 @@ } }, { - "description": "A partial update to an existing document.", + "description": "A partial update to an existing document.\nIf both `doc` and `script` are specified, `doc` is ignored.", "name": "doc", "required": false, "type": { @@ -42716,7 +42820,7 @@ } }, { - "description": "Set to true to use the contents of 'doc' as the value of 'upsert'", + "description": "If `true`, use the contents of 'doc' as the value of 'upsert'.\nNOTE: Using ingest pipelines with `doc_as_upsert` is not supported.", "name": "doc_as_upsert", "required": false, "serverDefault": false, @@ -42729,7 +42833,7 @@ } }, { - "description": "Script to execute to update the document.", + "description": "The script to run to update the document.", "name": "script", "required": false, "type": { @@ -42741,7 +42845,7 @@ } }, { - "description": "Set to true to execute the script whether or not the document exists.", + "description": "If `true`, run the script whether or not the document exists.", "name": "scripted_upsert", "required": false, "serverDefault": false, @@ -42754,7 +42858,7 @@ } }, { - "description": "Set to false to disable source retrieval. You can also specify a comma-separated\nlist of the fields you want to retrieve.", + "description": "If `false`, turn off source retrieval.\nYou can also specify a comma-separated list of the fields you want to retrieve.", "name": "_source", "required": false, "serverDefault": "true", @@ -42767,7 +42871,7 @@ } }, { - "description": "If the document does not already exist, the contents of 'upsert' are inserted as a\nnew document. If the document exists, the 'script' is executed.", + "description": "If the document does not already exist, the contents of 'upsert' are inserted as a new document.\nIf the document exists, the 'script' is run.", "name": "upsert", "required": false, "type": { @@ -42780,7 +42884,7 @@ } ] }, - "description": "Update a document.\nUpdates a document by running a script or passing a partial document.", + "description": "Update a document.\n\nUpdate a document by running a script or passing a partial document.\n\nIf the Elasticsearch security features are enabled, you must have the `index` or `write` index privilege for the target index or index alias.\n\nThe script can update, delete, or skip modifying the document.\nThe API also supports passing a partial document, which is merged into the existing document.\nTo fully replace an existing document, use the index API.\nThis operation:\n\n* Gets the document (collocated with the shard) from the index.\n* Runs the specified script.\n* Indexes the result.\n\nThe document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.\n\nThe `_source` field must be enabled to use this API.\nIn addition to `_source`, you can access the following variables through the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`, and `_now` (the current timestamp).", "generics": [ { "name": "TDocument", @@ -42803,7 +42907,7 @@ }, "path": [ { - "description": "Document ID", + "description": "A unique identifier for the document to be updated.", "name": "id", "required": true, "type": { @@ -42815,7 +42919,7 @@ } }, { - "description": "The name of the index", + "description": "The name of the target index.\nBy default, the index is created automatically if it doesn't exist.", "name": "index", "required": true, "type": { @@ -42830,6 +42934,8 @@ "query": [ { "description": "Only perform the operation if the document has this primary term.", + "extDocId": "optimistic-concurrency", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/optimistic-concurrency-control.html", "name": "if_primary_term", "required": false, "type": { @@ -42842,6 +42948,8 @@ }, { "description": "Only perform the operation if the document has this sequence number.", + "extDocId": "optimistic-concurrency", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/optimistic-concurrency-control.html", "name": "if_seq_no", "required": false, "type": { @@ -42866,7 +42974,7 @@ } }, { - "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation\nvisible to search, if 'wait_for' then wait for a refresh to make this operation\nvisible to search, if 'false' do nothing with refreshes.", + "description": "If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search.\nIf 'wait_for', it waits for a refresh to make this operation visible to search.\nIf 'false', it does nothing with refreshes.", "name": "refresh", "required": false, "serverDefault": "false", @@ -42879,7 +42987,7 @@ } }, { - "description": "If true, the destination must be an index alias.", + "description": "If `true`, the destination must be an index alias.", "name": "require_alias", "required": false, "serverDefault": false, @@ -42892,7 +43000,7 @@ } }, { - "description": "Specify how many times should the operation be retried when a conflict occurs.", + "description": "The number of times the operation should be retried when a conflict occurs.", "name": "retry_on_conflict", "required": false, "serverDefault": 0, @@ -42905,7 +43013,7 @@ } }, { - "description": "Custom value used to route operations to a specific shard.", + "description": "A custom value used to route operations to a specific shard.", "name": "routing", "required": false, "type": { @@ -42917,7 +43025,7 @@ } }, { - "description": "Period to wait for dynamic mapping updates and active shards.\nThis guarantees Elasticsearch waits for at least the timeout before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.", + "description": "The period to wait for the following operations: dynamic mapping updates and waiting for active shards.\nElasticsearch waits for at least the timeout period before failing.\nThe actual wait time could be longer, particularly when multiple waits occur.", "name": "timeout", "required": false, "serverDefault": "1m", @@ -42930,7 +43038,7 @@ } }, { - "description": "The number of shard copies that must be active before proceeding with the operations.\nSet to 'all' or any positive integer up to the total number of shards in the index\n(number_of_replicas+1). Defaults to 1 meaning the primary shard.", + "description": "The number of copies of each shard that must be active before proceeding with the operation.\nSet to 'all' or any positive integer up to the total number of shards in the index (`number_of_replicas`+1).\nThe default value of `1` means it waits for each primary shard to be active.", "name": "wait_for_active_shards", "required": false, "serverDefault": "1", @@ -42943,7 +43051,7 @@ } }, { - "description": "Set to false to disable source retrieval. You can also specify a comma-separated\nlist of the fields you want to retrieve.", + "description": "If `false`, source retrieval is turned off.\nYou can also specify a comma-separated list of the fields you want to retrieve.", "name": "_source", "required": false, "serverDefault": "true", @@ -42956,7 +43064,7 @@ } }, { - "description": "Specify the source fields you want to exclude.", + "description": "The source fields you want to exclude.", "name": "_source_excludes", "required": false, "type": { @@ -42968,7 +43076,7 @@ } }, { - "description": "Specify the source fields you want to retrieve.", + "description": "The source fields you want to retrieve.", "name": "_source_includes", "required": false, "type": { @@ -42980,7 +43088,7 @@ } } ], - "specLocation": "_global/update/UpdateRequest.ts#L38-L154" + "specLocation": "_global/update/UpdateRequest.ts#L38-L183" }, { "kind": "response", @@ -44131,7 +44239,7 @@ } } ], - "specLocation": "_types/Base.ts#L47-L50" + "specLocation": "_types/Base.ts#L69-L72" }, { "kind": "type_alias", @@ -44140,7 +44248,7 @@ "name": "AggregateName", "namespace": "_types" }, - "specLocation": "_types/common.ts#L146-L150", + "specLocation": "_types/common.ts#L149-L153", "type": { "kind": "instance_of", "type": { @@ -44402,7 +44510,7 @@ "name": "Bytes", "namespace": "_types" }, - "specLocation": "_types/common.ts#L170-L182" + "specLocation": "_types/common.ts#L173-L185" }, { "kind": "type_alias", @@ -44545,7 +44653,7 @@ "name": "ClusterInfoTarget", "namespace": "_types" }, - "specLocation": "_types/common.ts#L382-L388" + "specLocation": "_types/common.ts#L385-L391" }, { "kind": "type_alias", @@ -44553,7 +44661,7 @@ "name": "ClusterInfoTargets", "namespace": "_types" }, - "specLocation": "_types/common.ts#L390-L390", + "specLocation": "_types/common.ts#L393-L393", "type": { "kind": "union_of", "items": [ @@ -44772,7 +44880,7 @@ "name": "Conflicts", "namespace": "_types" }, - "specLocation": "_types/common.ts#L184-L193" + "specLocation": "_types/common.ts#L187-L196" }, { "kind": "interface", @@ -45292,7 +45400,7 @@ } } ], - "specLocation": "_types/Base.ts#L54-L93" + "specLocation": "_types/Base.ts#L76-L115" }, { "kind": "interface", @@ -45347,7 +45455,7 @@ } } ], - "specLocation": "_types/Base.ts#L95-L103" + "specLocation": "_types/Base.ts#L117-L125" }, { "kind": "interface", @@ -45357,7 +45465,7 @@ "namespace": "_types" }, "properties": [], - "specLocation": "_types/common.ts#L161-L162" + "specLocation": "_types/common.ts#L164-L165" }, { "kind": "type_alias", @@ -45524,7 +45632,7 @@ } } ], - "specLocation": "_types/Base.ts#L105-L114" + "specLocation": "_types/Base.ts#L127-L136" }, { "kind": "type_alias", @@ -45569,7 +45677,7 @@ "name": "ExpandWildcard", "namespace": "_types" }, - "specLocation": "_types/common.ts#L202-L216" + "specLocation": "_types/common.ts#L205-L219" }, { "kind": "type_alias", @@ -45577,7 +45685,7 @@ "name": "ExpandWildcards", "namespace": "_types" }, - "specLocation": "_types/common.ts#L218-L218", + "specLocation": "_types/common.ts#L221-L221", "type": { "kind": "union_of", "items": [ @@ -45608,7 +45716,7 @@ "name": "Field", "namespace": "_types" }, - "specLocation": "_types/common.ts#L139-L140", + "specLocation": "_types/common.ts#L142-L143", "type": { "kind": "instance_of", "type": { @@ -45922,7 +46030,7 @@ "name": "Fields", "namespace": "_types" }, - "specLocation": "_types/common.ts#L141-L141", + "specLocation": "_types/common.ts#L144-L144", "type": { "kind": "union_of", "items": [ @@ -46017,7 +46125,7 @@ "name": "Fuzziness", "namespace": "_types" }, - "specLocation": "_types/common.ts#L134-L135", + "specLocation": "_types/common.ts#L137-L138", "type": { "kind": "union_of", "items": [ @@ -46662,7 +46770,7 @@ "name": "HealthStatus", "namespace": "_types" }, - "specLocation": "_types/common.ts#L220-L240" + "specLocation": "_types/common.ts#L223-L243" }, { "kind": "type_alias", @@ -46685,7 +46793,7 @@ "name": "HttpHeaders", "namespace": "_types" }, - "specLocation": "_types/common.ts#L159-L159", + "specLocation": "_types/common.ts#L162-L162", "type": { "kind": "dictionary_of", "key": { @@ -47162,7 +47270,7 @@ } } ], - "specLocation": "_types/common.ts#L336-L363" + "specLocation": "_types/common.ts#L339-L366" }, { "kind": "interface", @@ -47189,7 +47297,7 @@ } } ], - "specLocation": "_types/Base.ts#L116-L118" + "specLocation": "_types/Base.ts#L138-L140" }, { "kind": "interface", @@ -47305,7 +47413,7 @@ } } ], - "specLocation": "_types/common.ts#L321-L334" + "specLocation": "_types/common.ts#L324-L337" }, { "kind": "type_alias", @@ -47713,7 +47821,7 @@ "name": "Level", "namespace": "_types" }, - "specLocation": "_types/common.ts#L250-L254" + "specLocation": "_types/common.ts#L253-L257" }, { "kind": "enum", @@ -48023,7 +48131,7 @@ "name": "MinimumShouldMatch", "namespace": "_types" }, - "specLocation": "_types/common.ts#L164-L168", + "specLocation": "_types/common.ts#L167-L171", "type": { "kind": "union_of", "items": [ @@ -48052,7 +48160,7 @@ "name": "MultiTermQueryRewrite", "namespace": "_types" }, - "specLocation": "_types/common.ts#L136-L137", + "specLocation": "_types/common.ts#L139-L140", "type": { "kind": "instance_of", "type": { @@ -48645,7 +48753,7 @@ "name": "OpType", "namespace": "_types" }, - "specLocation": "_types/common.ts#L256-L265" + "specLocation": "_types/common.ts#L259-L268" }, { "kind": "type_alias", @@ -48653,7 +48761,7 @@ "name": "Password", "namespace": "_types" }, - "specLocation": "_types/common.ts#L196-L196", + "specLocation": "_types/common.ts#L199-L199", "type": { "kind": "instance_of", "type": { @@ -48822,7 +48930,7 @@ "name": "PropertyName", "namespace": "_types" }, - "specLocation": "_types/common.ts#L131-L131", + "specLocation": "_types/common.ts#L134-L134", "type": { "kind": "instance_of", "type": { @@ -49149,7 +49257,7 @@ "name": "Refresh", "namespace": "_types" }, - "specLocation": "_types/common.ts#L267-L274" + "specLocation": "_types/common.ts#L270-L277" }, { "kind": "interface", @@ -49251,7 +49359,7 @@ "name": "RelationName", "namespace": "_types" }, - "specLocation": "_types/common.ts#L132-L132", + "specLocation": "_types/common.ts#L135-L135", "type": { "kind": "instance_of", "type": { @@ -49400,6 +49508,7 @@ }, "properties": [ { + "description": "The number of bulk actions retried.", "name": "bulk", "required": true, "type": { @@ -49411,6 +49520,7 @@ } }, { + "description": "The number of search actions retried.", "name": "search", "required": true, "type": { @@ -49422,7 +49532,7 @@ } } ], - "specLocation": "_types/Retries.ts#L22-L25" + "specLocation": "_types/Retries.ts#L22-L31" }, { "kind": "interface", @@ -50383,7 +50493,7 @@ "name": "SearchType", "namespace": "_types" }, - "specLocation": "_types/common.ts#L276-L281" + "specLocation": "_types/common.ts#L279-L284" }, { "kind": "interface", @@ -50698,7 +50808,7 @@ "name": "SequenceNumber", "namespace": "_types" }, - "specLocation": "_types/common.ts#L129-L129", + "specLocation": "_types/common.ts#L132-L132", "type": { "kind": "instance_of", "type": { @@ -50877,7 +50987,7 @@ } } ], - "specLocation": "_types/Base.ts#L120-L123" + "specLocation": "_types/Base.ts#L142-L145" }, { "kind": "interface", @@ -50933,7 +51043,7 @@ "name": "Slices", "namespace": "_types" }, - "specLocation": "_types/common.ts#L365-L370", + "specLocation": "_types/common.ts#L368-L373", "type": { "kind": "union_of", "items": [ @@ -50966,7 +51076,7 @@ "name": "SlicesCalculation", "namespace": "_types" }, - "specLocation": "_types/common.ts#L372-L380" + "specLocation": "_types/common.ts#L375-L383" }, { "kind": "type_alias", @@ -51346,7 +51456,7 @@ }, "properties": [ { - "description": "Specifies the language the script is written in.", + "description": "The language the script is written in.", "name": "lang", "required": true, "type": { @@ -51429,7 +51539,7 @@ "name": "SuggestMode", "namespace": "_types" }, - "specLocation": "_types/common.ts#L283-L296" + "specLocation": "_types/common.ts#L286-L299" }, { "kind": "type_alias", @@ -51438,7 +51548,7 @@ "name": "SuggestionName", "namespace": "_types" }, - "specLocation": "_types/common.ts#L152-L156", + "specLocation": "_types/common.ts#L155-L159", "type": { "kind": "instance_of", "type": { @@ -51507,7 +51617,7 @@ "name": "TaskId", "namespace": "_types" }, - "specLocation": "_types/common.ts#L133-L133", + "specLocation": "_types/common.ts#L136-L136", "type": { "kind": "union_of", "items": [ @@ -51659,7 +51769,7 @@ "name": "ThreadType", "namespace": "_types" }, - "specLocation": "_types/common.ts#L298-L304" + "specLocation": "_types/common.ts#L301-L307" }, { "kind": "type_alias", @@ -52015,7 +52125,7 @@ "name": "Username", "namespace": "_types" }, - "specLocation": "_types/common.ts#L195-L195", + "specLocation": "_types/common.ts#L198-L198", "type": { "kind": "instance_of", "type": { @@ -52030,7 +52140,7 @@ "name": "Uuid", "namespace": "_types" }, - "specLocation": "_types/common.ts#L126-L126", + "specLocation": "_types/common.ts#L129-L129", "type": { "kind": "instance_of", "type": { @@ -52077,14 +52187,15 @@ "name": "internal" }, { - "description": "Only index the document if the given version is strictly higher than the version of the stored document or if there is no existing document.", + "description": "Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.", "name": "external" }, { - "description": "Only index the document if the given version is equal or higher than the version of the stored document or if there is no existing document.\nNote: the external_gte version type is meant for special use cases and should be used with care.\nIf used incorrectly, it can result in loss of data.", + "description": "Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.\nNOTE: The `external_gte` version type is meant for special use cases and should be used with care.\nIf used incorrectly, it can result in loss of data.", "name": "external_gte" }, { + "description": "This option is deprecated because it can cause primary and replica shards to diverge.", "name": "force" } ], @@ -52092,7 +52203,7 @@ "name": "VersionType", "namespace": "_types" }, - "specLocation": "_types/common.ts#L107-L123" + "specLocation": "_types/common.ts#L107-L126" }, { "kind": "enum", @@ -52108,7 +52219,7 @@ "name": "WaitForActiveShardOptions", "namespace": "_types" }, - "specLocation": "_types/common.ts#L306-L310" + "specLocation": "_types/common.ts#L309-L313" }, { "kind": "type_alias", @@ -52120,7 +52231,7 @@ "name": "WaitForActiveShards", "namespace": "_types" }, - "specLocation": "_types/common.ts#L143-L144", + "specLocation": "_types/common.ts#L146-L147", "type": { "kind": "union_of", "items": [ @@ -52167,7 +52278,7 @@ "name": "WaitForEvents", "namespace": "_types" }, - "specLocation": "_types/common.ts#L312-L319" + "specLocation": "_types/common.ts#L315-L322" }, { "kind": "interface", @@ -52261,6 +52372,7 @@ }, "properties": [ { + "description": "The unique identifier for the added document.", "name": "_id", "required": true, "type": { @@ -52272,6 +52384,7 @@ } }, { + "description": "The name of the index the document was added to.", "name": "_index", "required": true, "type": { @@ -52283,6 +52396,7 @@ } }, { + "description": "The primary term assigned to the document for the indexing operation.", "name": "_primary_term", "required": false, "type": { @@ -52294,6 +52408,7 @@ } }, { + "description": "The result of the indexing operation: `created` or `updated`.", "name": "result", "required": true, "type": { @@ -52305,6 +52420,7 @@ } }, { + "description": "The sequence number assigned to the document for the indexing operation.\nSequence numbers are used to ensure an older version of a document doesn't overwrite a newer version.", "name": "_seq_no", "required": false, "type": { @@ -52316,6 +52432,7 @@ } }, { + "description": "Information about the replication process of the operation.", "name": "_shards", "required": true, "type": { @@ -52327,6 +52444,7 @@ } }, { + "description": "The document version, which is incremented each time the document is updated.", "name": "_version", "required": true, "type": { @@ -52349,7 +52467,7 @@ } } ], - "specLocation": "_types/Base.ts#L36-L45" + "specLocation": "_types/Base.ts#L36-L67" }, { "kind": "type_alias", diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index eceb10e18a..f6da90f0ef 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -140,17 +140,14 @@ dissect-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branc distance-units,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/api-conventions.html#distance-units docs-bulk,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-bulk.html docs-delete-by-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-delete-by-query.html -docs-delete-by-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-delete-by-query.html docs-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-delete.html docs-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html -docs-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html -docs-index_,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-index_.html +docs-index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-index_.html docs-multi-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-multi-get.html docs-multi-termvectors,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-multi-termvectors.html docs-reindex,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-reindex.html docs-termvectors,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-termvectors.html docs-update-by-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-update-by-query.html -docs-update-by-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-update-by-query.html docs-update,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-update.html document-input-parameters,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-mlt-query.html#_document_input_parameters dot-expand-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/dot-expand-processor.html @@ -381,6 +378,7 @@ node-roles,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modu nodes-api-shutdown-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-shutdown.html nodes-api-shutdown-status,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-shutdown.html nodes-api-shutdown,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-shutdown.html +optimistic-concurrency,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/optimistic-concurrency-control.html paginate-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html painless-contexts,https://www.elastic.co/guide/en/elasticsearch/painless/{branch}/painless-contexts.html painless-execute-api,https://www.elastic.co/guide/en/elasticsearch/painless/{branch}/painless-execute-api.html @@ -674,6 +672,7 @@ set-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/s shape,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/shape.html simulate-ingest-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/simulate-ingest-api.html simulate-pipeline-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/simulate-pipeline-api.html +slice-scroll,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#slice-scroll slm-api-delete-policy,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-delete-policy.html slm-api-execute-lifecycle,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-execute-lifecycle.html slm-api-execute-retention,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/slm-api-execute-retention.html diff --git a/specification/_global/create/CreateRequest.ts b/specification/_global/create/CreateRequest.ts index 7ccb45e1ef..8df7c7f95e 100644 --- a/specification/_global/create/CreateRequest.ts +++ b/specification/_global/create/CreateRequest.ts @@ -30,67 +30,149 @@ import { import { Duration } from '@_types/Time' /** - * Index a document. - * Adds a JSON document to the specified data stream or index and makes it searchable. - * If the target is an index and the document already exists, the request updates the document and increments its version. + * Create a new document in the index. + * + * You can index a new JSON document with the `//_doc/` or `//_create/<_id>` APIs + * Using `_create` guarantees that the document is indexed only if it does not already exist. + * It returns a 409 response when a document with a same ID already exists in the index. + * To update an existing document, you must use the `//_doc/` API. + * + * If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias: + * + * * To add a document using the `PUT //_create/<_id>` or `POST //_create/<_id>` request formats, you must have the `create_doc`, `create`, `index`, or `write` index privilege. + * * To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege. + * + * Automatic data stream creation requires a matching index template with data stream enabled. + * + * **Automatically create data streams and indices** + * + * If the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream. + * + * If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates. + * + * NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation. + * + * If no mapping exists, the index operation creates a dynamic mapping. + * By default, new fields and objects are automatically added to the mapping if needed. + * + * Automatic index creation is controlled by the `action.auto_create_index` setting. + * If it is `true`, any index can be created automatically. + * You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely. + * Specify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked. + * When a list is specified, the default behaviour is to disallow. + * + * NOTE: The `action.auto_create_index` setting affects the automatic creation of indices only. + * It does not affect the creation of data streams. + * + * **Routing** + * + * By default, shard placement — or routing — is controlled by using a hash of the document's ID value. + * For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter. + * + * When setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself. + * This does come at the (very minimal) cost of an additional document parsing pass. + * If the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted. + * + * NOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template. + * + * ** Distributed** + * + * The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. + * After the primary shard completes the operation, if needed, the update is distributed to applicable replicas. + * + * **Active shards** + * + * To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. + * If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. + * By default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`). + * This default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`. + * To alter this behavior per operation, use the `wait_for_active_shards request` parameter. + * + * Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1). + * Specifying a negative value or a number greater than the number of shard copies will throw an error. + * + * For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). + * If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. + * This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. + * If `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. + * This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. + * However, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. + * The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard. + * + * It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. + * After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. + * The `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed. * @rest_spec_name create * @availability stack since=5.0.0 stability=stable * @availability serverless stability=stable visibility=public + * @index_privileges create * @doc_tag document + * @doc_id docs-index + * @ext_doc_id data-streams */ export interface Request extends RequestBase { path_parts: { /** - * Unique identifier for the document. + * A unique identifier for the document. + * To automatically generate a document ID, use the `POST //_doc/` request format. */ id: Id /** - * Name of the data stream or index to target. - * If the target doesn’t exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream. - * If the target doesn’t exist and doesn’t match a data stream template, this request creates the index. + * The name of the data stream or index to target. + * If the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream. + * If the target doesn't exist and doesn’t match a data stream template, this request creates the index. */ index: IndexName } query_parameters: { /** - * ID of the pipeline to use to preprocess incoming documents. - * If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. - * If a final pipeline is configured it will always run, regardless of the value of this parameter. + * The ID of the pipeline to use to preprocess incoming documents. + * If the index has a default ingest pipeline specified, setting the value to `_none` turns off the default ingest pipeline for this request. + * If a final pipeline is configured, it will always run regardless of the value of this parameter. */ pipeline?: string /** - * If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes. - * Valid values: `true`, `false`, `wait_for`. + * If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search. + * If `wait_for`, it waits for a refresh to make this operation visible to search. + * If `false`, it does nothing with refreshes. * @server_default false */ refresh?: Refresh /** - * Custom value used to route operations to a specific shard. + * A custom value that is used to route operations to a specific shard. */ routing?: Routing /** - * Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. + * The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. + * Elasticsearch waits for at least the specified timeout period before failing. + * The actual wait time could be longer, particularly when multiple waits occur. + * + * This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. + * Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. + * By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. + * The actual wait time could be longer, particularly when multiple waits occur. * @server_default 1m */ timeout?: Duration /** - * Explicit version number for concurrency control. - * The specified version must match the current version of the document for the request to succeed. + * The explicit version number for concurrency control. + * It must be a non-negative long number. */ version?: VersionNumber /** - * Specific version type: `external`, `external_gte`. + * The version type. */ version_type?: VersionType /** * The number of shard copies that must be active before proceeding with the operation. - * Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). + * You can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). + * The default value of `1` means it waits for each primary shard to be active. * @server_default 1 */ wait_for_active_shards?: WaitForActiveShards } /** - * Request body contains the JSON source for the document data. + * The request body contains the JSON source for the document data. * @codegen_name document */ body: TDocument } diff --git a/specification/_global/create/examples/request/CreateRequestExample1.yaml b/specification/_global/create/examples/request/CreateRequestExample1.yaml new file mode 100644 index 0000000000..aef98eafd0 --- /dev/null +++ b/specification/_global/create/examples/request/CreateRequestExample1.yaml @@ -0,0 +1,13 @@ +# summary: +# method_request: PUT my-index-000001/_create/1 +description: > + Run `PUT my-index-000001/_create/1` to index a document into the `my-index-000001` index if no document with that ID exists. +# type: request +value: |- + { + "@timestamp": "2099-11-15T13:12:00", + "message": "GET /search HTTP/1.1 200 1070000", + "user": { + "id": "kimchy" + } + } diff --git a/specification/_global/delete/DeleteRequest.ts b/specification/_global/delete/DeleteRequest.ts index bef0fdd14b..b0a795176b 100644 --- a/specification/_global/delete/DeleteRequest.ts +++ b/specification/_global/delete/DeleteRequest.ts @@ -33,59 +33,106 @@ import { Duration } from '@_types/Time' /** * Delete a document. - * Removes a JSON document from the specified index. + * + * Remove a JSON document from the specified index. + * + * NOTE: You cannot send deletion requests directly to a data stream. + * To delete a document in a data stream, you must target the backing index containing the document. + * + * **Optimistic concurrency control** + * + * Delete operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters. + * If a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`. + * + * **Versioning** + * + * Each document indexed is versioned. + * When deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime. + * Every write operation run on a document, deletes included, causes its version to be incremented. + * The version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations. + * The length of time for which a deleted document's version remains available is determined by the `index.gc_deletes` index setting. + * + * **Routing** + * + * If routing is used during indexing, the routing value also needs to be specified to delete a document. + * + * If the `_routing` mapping is set to `required` and no routing value is specified, the delete API throws a `RoutingMissingException` and rejects the request. + * + * For example: + * + * ``` + * DELETE /my-index-000001/_doc/1?routing=shard-1 + * ``` + * + * This request deletes the document with ID 1, but it is routed based on the user. + * The document is not deleted if the correct routing is not specified. + * + * **Distributed** + * + * The delete operation gets hashed into a specific shard ID. + * It then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group. * @rest_spec_name delete * @availability stack stability=stable * @availability serverless stability=stable visibility=public + * @index_privileges delete * @doc_tag document + * @doc_id docs-delete */ export interface Request extends RequestBase { path_parts: { /** - * Unique identifier for the document. + * A unique identifier for the document. */ id: Id /** - * Name of the target index. + * The name of the target index. */ index: IndexName } query_parameters: { /** * Only perform the operation if the document has this primary term. + * @ext_doc_id optimistic-concurrency */ if_primary_term?: long /** * Only perform the operation if the document has this sequence number. + * @ext_doc_id optimistic-concurrency */ if_seq_no?: SequenceNumber /** - * If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes. - * Valid values: `true`, `false`, `wait_for`. + * If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search. + * If `wait_for`, it waits for a refresh to make this operation visible to search. + * If `false`, it does nothing with refreshes. * @server_default false */ refresh?: Refresh /** - * Custom value used to route operations to a specific shard. + * A custom value used to route operations to a specific shard. */ routing?: Routing /** - * Period to wait for active shards. + * The period to wait for active shards. + * + * This parameter is useful for situations where the primary shard assigned to perform the delete operation might not be available when the delete operation runs. + * Some reasons for this might be that the primary shard is currently recovering from a store or undergoing relocation. + * By default, the delete operation will wait on the primary shard to become available for up to 1 minute before failing and responding with an error. * @server_default 1m */ timeout?: Duration /** - * Explicit version number for concurrency control. - * The specified version must match the current version of the document for the request to succeed. + * An explicit version number for concurrency control. + * It must match the current version of the document for the request to succeed. */ version?: VersionNumber /** - * Specific version type: `external`, `external_gte`. + * The version type. */ version_type?: VersionType /** - * The number of shard copies that must be active before proceeding with the operation. - * Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). + * The minimum number of shard copies that must be active before proceeding with the operation. + * You can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). + * The default value of `1` means it waits for each primary shard to be active. * @server_default 1 */ wait_for_active_shards?: WaitForActiveShards diff --git a/specification/_global/delete/examples/response/DeleteResponseExample1.yaml b/specification/_global/delete/examples/response/DeleteResponseExample1.yaml new file mode 100644 index 0000000000..4a258a25c7 --- /dev/null +++ b/specification/_global/delete/examples/response/DeleteResponseExample1.yaml @@ -0,0 +1,18 @@ +# summary: +description: A successful response from `DELETE /my-index-000001/_doc/1`, which deletes the JSON document 1 from the `my-index-000001` index. +# type: response +# response_code: '' +value: |- + { + "_shards": { + "total": 2, + "failed": 0, + "successful": 2 + }, + "_index": "my-index-000001", + "_id": "1", + "_version": 2, + "_primary_term": 1, + "_seq_no": 5, + "result": "deleted" + } diff --git a/specification/_global/exists/DocumentExistsRequest.ts b/specification/_global/exists/DocumentExistsRequest.ts index 836d75e961..8d7c74a854 100644 --- a/specification/_global/exists/DocumentExistsRequest.ts +++ b/specification/_global/exists/DocumentExistsRequest.ts @@ -30,28 +30,51 @@ import { /** * Check a document. - * Checks if a specified document exists. + * + * Verify that a document exists. + * For example, check to see if a document with the `_id` 0 exists: + * + * ``` + * HEAD my-index-000001/_doc/0 + * ``` + * + * If the document exists, the API returns a status code of `200 - OK`. + * If the document doesn’t exist, the API returns `404 - Not Found`. + * + * **Versioning support** + * + * You can use the `version` parameter to check the document only if its current version is equal to the specified one. + * + * Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. + * The old version of the document doesn't disappear immediately, although you won't be able to access it. + * Elasticsearch cleans up deleted documents in the background as you continue to index more data. * @rest_spec_name exists * @availability stack stability=stable * @availability serverless stability=stable visibility=public * @doc_tag document + * @doc_id docs-get */ export interface Request extends RequestBase { path_parts: { /** - * Identifier of the document. + * A unique document identifier. */ id: Id /** - * Comma-separated list of data streams, indices, and aliases. - * Supports wildcards (`*`). + * A comma-separated list of data streams, indices, and aliases. + * It supports wildcards (`*`). */ index: IndexName } query_parameters: { /** - * Specifies the node or shard the operation should be performed on. - * Random by default. + * The node or shard the operation should be performed on. + * By default, the operation is randomized between the shard replicas. + * + * If it is set to `_local`, the operation will prefer to be run on a local allocated shard when possible. + * If it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value. + * This can help with "jumping values" when hitting different shards in different refresh states. + * A sample value can be something like the web session ID or the user name. */ preference?: string /** @@ -61,31 +84,37 @@ export interface Request extends RequestBase { */ realtime?: boolean /** - * If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes. + * If `true`, the request refreshes the relevant shards before retrieving the document. + * Setting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing). * @server_default false */ refresh?: boolean /** - * Target the specified primary shard. - * @doc_id routing + * A custom value used to route operations to a specific shard. + * @ext_doc_id routing */ routing?: Routing /** - * `true` or `false` to return the `_source` field or not, or a list of fields to return. + * Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return. */ _source?: SourceConfigParam /** - * A comma-separated list of source fields to exclude in the response. + * A comma-separated list of source fields to exclude from the response. + * You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter. + * If the `_source` parameter is `false`, this parameter is ignored. */ _source_excludes?: Fields /** * A comma-separated list of source fields to include in the response. + * If this parameter is specified, only these source fields are returned. + * You can exclude fields from this subset using the `_source_excludes` query parameter. + * If the `_source` parameter is `false`, this parameter is ignored. */ _source_includes?: Fields /** - * List of stored fields to return as part of a hit. + * A comma-separated 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. + * If this field is specified, the `_source` parameter defaults to `false`. */ stored_fields?: Fields /** @@ -94,7 +123,7 @@ export interface Request extends RequestBase { */ version?: VersionNumber /** - * Specific version type: `external`, `external_gte`. + * The version type. */ version_type?: VersionType } diff --git a/specification/_global/exists_source/SourceExistsRequest.ts b/specification/_global/exists_source/SourceExistsRequest.ts index 304dc6a20e..488d50d95e 100644 --- a/specification/_global/exists_source/SourceExistsRequest.ts +++ b/specification/_global/exists_source/SourceExistsRequest.ts @@ -30,48 +30,60 @@ import { /** * Check for a document source. - * Checks if a document's `_source` is stored. + * + * Check whether a document source exists in an index. + * For example: + * + * ``` + * HEAD my-index-000001/_source/1 + * ``` + * + * A document's source is not available if it is disabled in the mapping. * @rest_spec_name exists_source * @availability stack since=5.4.0 stability=stable * @availability serverless stability=stable visibility=public * @doc_tag document + * @index_privileges read + * @doc_id docs-get + * @ext_doc_id mapping-source-field */ export interface Request extends RequestBase { path_parts: { /** - * Identifier of the document. + * A unique identifier for the document. */ id: Id /** - * Comma-separated list of data streams, indices, and aliases. - * Supports wildcards (`*`). + * A comma-separated list of data streams, indices, and aliases. + * It supports wildcards (`*`). */ index: IndexName } query_parameters: { /** - * Specifies the node or shard the operation should be performed on. - * Random by default. + * The node or shard the operation should be performed on. + * By default, the operation is randomized between the shard replicas. */ preference?: string /** - * If true, the request is real-time as opposed to near-real-time. + * If `true`, the request is real-time as opposed to near-real-time. * @server_default true - * @doc_id realtime + * @ext_doc_id realtime */ realtime?: boolean /** - * If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes. + * If `true`, the request refreshes the relevant shards before retrieving the document. + * Setting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing). * @server_default false */ refresh?: boolean /** - * Target the specified primary shard. - * @doc_id routing + * A custom value used to route operations to a specific shard. + * @ext_doc_id routing */ routing?: Routing /** - * `true` or `false` to return the `_source` field or not, or a list of fields to return. + * Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return. */ _source?: SourceConfigParam /** @@ -83,12 +95,12 @@ export interface Request extends RequestBase { */ _source_includes?: Fields /** - * Explicit version number for concurrency control. - * The specified version must match the current version of the document for the request to succeed. + * The version number for concurrency control. + * It must match the current version of the document for the request to succeed. */ version?: VersionNumber /** - * Specific version type: `external`, `external_gte`. + * The version type. */ version_type?: VersionType } diff --git a/specification/_global/get/GetRequest.ts b/specification/_global/get/GetRequest.ts index a54dec0b4a..7c47c1e4ed 100644 --- a/specification/_global/get/GetRequest.ts +++ b/specification/_global/get/GetRequest.ts @@ -30,29 +30,93 @@ import { /** * Get a document by its ID. - * Retrieves the document with the specified ID from an index. + * + * Get a document and its source or stored fields from an index. + * + * By default, this API is realtime and is not affected by the refresh rate of the index (when data will become visible for search). + * In the case where stored fields are requested with the `stored_fields` parameter and the document has been updated but is not yet refreshed, the API will have to parse and analyze the source to extract the stored fields. + * To turn off realtime behavior, set the `realtime` parameter to false. + * + * **Source filtering** + * + * By default, the API returns the contents of the `_source` field unless you have used the `stored_fields` parameter or the `_source` field is turned off. + * You can turn off `_source` retrieval by using the `_source` parameter: + * + * ``` + * GET my-index-000001/_doc/0?_source=false + * ``` + * + * If you only need one or two fields from the `_source`, use the `_source_includes` or `_source_excludes` parameters to include or filter out particular fields. + * This can be helpful with large documents where partial retrieval can save on network overhead + * Both parameters take a comma separated list of fields or wildcard expressions. + * For example: + * + * ``` + * GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities + * ``` + * + * If you only want to specify includes, you can use a shorter notation: + * + * ``` + * GET my-index-000001/_doc/0?_source=*.id + * ``` + * + * **Routing** + * + * If routing is used during indexing, the routing value also needs to be specified to retrieve a document. + * For example: + * + * ``` + * GET my-index-000001/_doc/2?routing=user1 + * ``` + * + * This request gets the document with ID 2, but it is routed based on the user. + * The document is not fetched if the correct routing is not specified. + * + * **Distributed** + * + * The GET operation is hashed into a specific shard ID. + * It is then redirected to one of the replicas within that shard ID and returns the result. + * The replicas are the primary shard and its replicas within that shard ID group. + * This means that the more replicas you have, the better your GET scaling will be. + * + * **Versioning support** + * + * You can use the `version` parameter to retrieve the document only if its current version is equal to the specified one. + * + * Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. + * The old version of the document doesn't disappear immediately, although you won't be able to access it. + * Elasticsearch cleans up deleted documents in the background as you continue to index more data. * @rest_spec_name get * @availability stack stability=stable * @availability serverless stability=stable visibility=public + * @index_privileges read * @doc_tag document + * @doc_id docs-get */ export interface Request extends RequestBase { path_parts: { - /** Unique identifier of the document. */ + /** A unique document identifier. */ id: Id - /** Name of the index that contains the document. */ + /** The name of the index that contains the document. */ index: IndexName } query_parameters: { /** - * Should this request force synthetic _source? - * Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. - * Fetches with this enabled will be slower the enabling synthetic source natively in the index. + * Indicates whether the request forces synthetic `_source`. + * Use this paramater to test if the mapping supports synthetic `_source` and to get a sense of the worst case performance. + * Fetches with this parameter enabled will be slower than enabling synthetic source natively in the index. * @availability stack since=8.4.0 visibility=feature_flag feature_flag=es.index_mode_feature_flag_registered */ force_synthetic_source?: boolean /** - * Specifies the node or shard the operation should be performed on. Random by default. + * The node or shard the operation should be performed on. + * By default, the operation is randomized between the shard replicas. + * + * If it is set to `_local`, the operation will prefer to be run on a local allocated shard when possible. + * If it is set to a custom value, the value is used to guarantee that the same shards will be used for the same custom value. + * This can help with "jumping values" when hitting different shards in different refresh states. + * A sample value can be something like the web session ID or the user name. */ preference?: string /** @@ -62,39 +126,48 @@ export interface Request extends RequestBase { */ realtime?: boolean /** - * If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes. + * If `true`, the request refreshes the relevant shards before retrieving the document. + * Setting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing). * @server_default false */ refresh?: boolean /** - * Target the specified primary shard. - * @doc_id routing + * A custom value used to route operations to a specific shard. + * @ext_doc_id routing */ routing?: Routing /** - * True or false to return the _source field or not, or a list of fields to return. + * Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return. */ _source?: SourceConfigParam /** - * A comma-separated list of source fields to exclude in the response. + * A comma-separated list of source fields to exclude from the response. + * You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter. + * If the `_source` parameter is `false`, this parameter is ignored. */ _source_excludes?: Fields /** * A comma-separated list of source fields to include in the response. + * If this parameter is specified, only these source fields are returned. + * You can exclude fields from this subset using the `_source_excludes` query parameter. + * If the `_source` parameter is `false`, this parameter is ignored. */ _source_includes?: Fields /** - * List of stored fields to return as part of a hit. + * A comma-separated 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. + * If this field is specified, the `_source` parameter defaults to `false`. + * Only leaf fields can be retrieved with the `stored_field` option. + * Object fields can't be returned;​if specified, the request fails. */ stored_fields?: Fields /** - * Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed. + * The version number for concurrency control. + * It must match the current version of the document for the request to succeed. */ version?: VersionNumber /** - * Specific version type: internal, external, external_gte. + * The version type. */ version_type?: VersionType } diff --git a/specification/_global/get/examples/response/GetResponseExample1.yaml b/specification/_global/get/examples/response/GetResponseExample1.yaml new file mode 100644 index 0000000000..5e848d59ba --- /dev/null +++ b/specification/_global/get/examples/response/GetResponseExample1.yaml @@ -0,0 +1,35 @@ +summary: Get a document +description: > + A successful response from `GET my-index-000001/_doc/0`. + It retrieves the JSON document with the `_id` 0 from the `my-index-000001` index. +# type: response +# response_code: '' +value: |- + { + "_index": "my-index-000001", + "_id": "0", + "_version": 1, + "_seq_no": 0, + "_primary_term": 1, + "found": true, + "_source": { + "@timestamp": "2099-11-15T14:12:12", + "http": { + "request": { + "method": "get" + }, + "response": { + "status_code": 200, + "bytes": 1070000 + }, + "version": "1.1" + }, + "source": { + "ip": "127.0.0.1" + }, + "message": "GET /search HTTP/1.1 200 1070000", + "user": { + "id": "kimchy" + } + } + } diff --git a/specification/_global/get/examples/response/GetResponseExample2.yaml b/specification/_global/get/examples/response/GetResponseExample2.yaml new file mode 100644 index 0000000000..89d788a873 --- /dev/null +++ b/specification/_global/get/examples/response/GetResponseExample2.yaml @@ -0,0 +1,21 @@ +summary: Get stored fields +description: > + A successful response from `GET my-index-000001/_doc/1?stored_fields=tags,counter`, which retrieves a set of stored fields. + Field values fetched from the document itself are always returned as an array. + Any requested fields that are not stored (such as the counter field in this example) are ignored. +# type: response +# response_code: '' +value: |- + { + "_index": "my-index-000001", + "_id": "1", + "_version": 1, + "_seq_no" : 22, + "_primary_term" : 1, + "found": true, + "fields": { + "tags": [ + "production" + ] + } + } diff --git a/specification/_global/get/examples/response/GetResponseExample3.yaml b/specification/_global/get/examples/response/GetResponseExample3.yaml new file mode 100644 index 0000000000..0736884b2d --- /dev/null +++ b/specification/_global/get/examples/response/GetResponseExample3.yaml @@ -0,0 +1,20 @@ +summary: Get metadata fields +description: > + A successful response from `GET my-index-000001/_doc/2?routing=user1&stored_fields=tags,counter`, which retrieves the `_routing` metadata field. +# type: response +# response_code: '' +value: |- + { + "_index": "my-index-000001", + "_id": "2", + "_version": 1, + "_seq_no" : 13, + "_primary_term" : 1, + "_routing": "user1", + "found": true, + "fields": { + "tags": [ + "env2" + ] + } + } diff --git a/specification/_global/get/types.ts b/specification/_global/get/types.ts index 46124f05c9..5e08de3698 100644 --- a/specification/_global/get/types.ts +++ b/specification/_global/get/types.ts @@ -23,14 +23,45 @@ import { Id, IndexName, SequenceNumber, VersionNumber } from '@_types/common' import { long } from '@_types/Numeric' export class GetResult { + /** + * The name of the index the document belongs to. + */ _index: IndexName + /** + * If the `stored_fields` parameter is set to `true` and `found` is `true`, it contains the document fields stored in the index. + */ fields?: Dictionary _ignored?: string[] + /** + * Indicates whether the document exists. + */ found: boolean + /** + * The unique identifier for the document. + */ _id: Id + /** + * The primary term assigned to the document for the indexing operation. + * @ext_doc_id optimistic_concurrency + */ _primary_term?: long + /** + * The explicit routing, if set. + */ _routing?: string + /** + * The sequence number assigned to the document for the indexing operation. + * Sequence numbers are used to ensure an older version of a document doesn't overwrite a newer version. + * @ext_doc_id optimistic_concurrency + */ _seq_no?: SequenceNumber + /** + * If `found` is `true`, it contains the document data formatted in JSON. + * If the `_source` parameter is set to `false` or the `stored_fields` parameter is set to `true`, it is excluded. + */ _source?: TDocument + /** + * The document version, which is ncremented each time the document is updated. + */ _version?: VersionNumber } diff --git a/specification/_global/get_source/SourceRequest.ts b/specification/_global/get_source/SourceRequest.ts index 9c2b305f6e..50f369cd2e 100644 --- a/specification/_global/get_source/SourceRequest.ts +++ b/specification/_global/get_source/SourceRequest.ts @@ -30,42 +30,59 @@ import { /** * Get a document's source. - * Returns the source of a document. + * + * Get the source of a document. + * For example: + * + * ``` + * GET my-index-000001/_source/1 + * ``` + * + * You can use the source filtering parameters to control which parts of the `_source` are returned: + * + * ``` + * GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities + * ``` * @rest_spec_name get_source * @availability stack stability=stable * @availability serverless stability=stable visibility=public + * @index_privileges read * @doc_tag document + * @doc_id docs-get + * @ext_doc_id mapping-source-field */ export interface Request extends RequestBase { path_parts: { - /** Unique identifier of the document. */ + /** A unique document identifier. */ id: Id - /** Name of the index that contains the document. */ + /** The name of the index that contains the document. */ index: IndexName } query_parameters: { /** - * Specifies the node or shard the operation should be performed on. Random by default. + * The node or shard the operation should be performed on. + * By default, the operation is randomized between the shard replicas. */ preference?: string /** - * Boolean) If true, the request is real-time as opposed to near-real-time. + * If `true`, the request is real-time as opposed to near-real-time. * @server_default true * @doc_id realtiime */ realtime?: boolean /** - * If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If false, do nothing with refreshes. + * If `true`, the request refreshes the relevant shards before retrieving the document. + * Setting it to `true` should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing). * @server_default false */ refresh?: boolean /** - * Target the specified primary shard. - * @doc_id routing + * A custom value used to route operations to a specific shard. + * @ext_doc_id routing */ routing?: Routing /** - * True or false to return the _source field or not, or a list of fields to return. + * Indicates whether to return the `_source` field (`true` or `false`) or lists the fields to return. */ _source?: SourceConfigParam /** @@ -76,13 +93,17 @@ export interface Request extends RequestBase { * A comma-separated list of source fields to include in the response. */ _source_includes?: Fields + /** + * A comma-separated list of stored fields to return as part of a hit. + */ stored_fields?: Fields /** - * Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed. + * The version number for concurrency control. + * It must match the current version of the document for the request to succeed. */ version?: VersionNumber /** - * Specific version type: internal, external, external_gte. + * The version type. */ version_type?: VersionType } diff --git a/specification/_global/index/IndexRequest.ts b/specification/_global/index/IndexRequest.ts index 1edb606b28..23d532c3bb 100644 --- a/specification/_global/index/IndexRequest.ts +++ b/specification/_global/index/IndexRequest.ts @@ -33,75 +33,209 @@ import { long } from '@_types/Numeric' import { Duration } from '@_types/Time' /** - * Index a document. - * Adds a JSON document to the specified data stream or index and makes it searchable. + * Create or update a document in an index. + * + * Add a JSON document to the specified data stream or index and make it searchable. * If the target is an index and the document already exists, the request updates the document and increments its version. + * + * NOTE: You cannot use this API to send update requests for existing documents in a data stream. + * + * If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias: + * + * * To add or overwrite a document using the `PUT //_doc/<_id>` request format, you must have the `create`, `index`, or `write` index privilege. + * * To add a document using the `POST //_doc/` request format, you must have the `create_doc`, `create`, `index`, or `write` index privilege. + * * To automatically create a data stream or index with this API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege. + * + * Automatic data stream creation requires a matching index template with data stream enabled. + * + * NOTE: Replica shards might not all be started when an indexing operation returns successfully. + * By default, only the primary is required. Set `wait_for_active_shards` to change this default behavior. + * + * **Automatically create data streams and indices** + * + * If the request's target doesn't exist and matches an index template with a `data_stream` definition, the index operation automatically creates the data stream. + * + * If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates. + * + * NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation. + * + * If no mapping exists, the index operation creates a dynamic mapping. + * By default, new fields and objects are automatically added to the mapping if needed. + * + * Automatic index creation is controlled by the `action.auto_create_index` setting. + * If it is `true`, any index can be created automatically. + * You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to `false` to turn off automatic index creation entirely. + * Specify a comma-separated list of patterns you want to allow or prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked. + * When a list is specified, the default behaviour is to disallow. + * + * NOTE: The `action.auto_create_index` setting affects the automatic creation of indices only. + * It does not affect the creation of data streams. + * + * **Optimistic concurrency control** + * + * Index operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the `if_seq_no` and `if_primary_term` parameters. + * If a mismatch is detected, the operation will result in a `VersionConflictException` and a status code of `409`. + * + * **Routing** + * + * By default, shard placement — or routing — is controlled by using a hash of the document's ID value. + * For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the `routing` parameter. + * + * When setting up explicit mapping, you can also use the `_routing` field to direct the index operation to extract the routing value from the document itself. + * This does come at the (very minimal) cost of an additional document parsing pass. + * If the `_routing` mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted. + * + * NOTE: Data streams do not support custom routing unless they were created with the `allow_custom_routing` setting enabled in the template. + * + * * ** Distributed** + * + * The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. + * After the primary shard completes the operation, if needed, the update is distributed to applicable replicas. + * + * **Active shards** + * + * To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. + * If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. + * By default, write operations only wait for the primary shards to be active before proceeding (that is to say `wait_for_active_shards` is `1`). + * This default can be overridden in the index settings dynamically by setting `index.write.wait_for_active_shards`. + * To alter this behavior per operation, use the `wait_for_active_shards request` parameter. + * + * Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is `number_of_replicas`+1). + * Specifying a negative value or a number greater than the number of shard copies will throw an error. + * + * For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). + * If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. + * This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. + * If `wait_for_active_shards` is set on the request to `3` (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. + * This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. + * However, if you set `wait_for_active_shards` to `all` (or to `4`, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. + * The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard. + * + * It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. + * After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. + * The `_shards` section of the API response reveals the number of shard copies on which replication succeeded and failed. + * + * **No operation (noop) updates** + * + * When updating a document by using this API, a new version of the document is always created even if the document hasn't changed. + * If this isn't acceptable use the `_update` API with `detect_noop` set to `true`. + * The `detect_noop` option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source. + * + * There isn't a definitive rule for when noop updates aren't acceptable. + * It's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates. + * + * **Versioning** + * + * Each indexed document is given a version number. + * By default, internal versioning is used that starts at 1 and increments with each update, deletes included. + * Optionally, the version number can be set to an external value (for example, if maintained in a database). + * To enable this functionality, `version_type` should be set to `external`. + * The value provided must be a numeric, long value greater than or equal to 0, and less than around `9.2e+18`. + * + * NOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations. + * If no version is provided, the operation runs without any version checks. + * + * When using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document. + * If true, the document will be indexed and the new version number used. + * If the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example: + * + * ``` + * PUT my-index-000001/_doc/1?version=2&version_type=external + * { + * "user": { + * "id": "elkbee" + * } + * } + * + * In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1. + * If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code). + * + * A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used. + * Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order. * @rest_spec_name index * @availability stack stability=stable * @availability serverless stability=stable visibility=public + * @index_privileges index * @doc_tag document + * @doc_id docs-index + * @ext_doc_id data-streams */ export interface Request extends RequestBase { path_parts: { /** - * Unique identifier for the document. + * A unique identifier for the document. + * To automatically generate a document ID, use the `POST //_doc/` request format and omit this parameter. */ id?: Id /** - * Name of the data stream or index to target. + * The name of the data stream or index to target. + * If the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream. + * If the target doesn't exist and doesn't match a data stream template, this request creates the index. + * You can check for existing targets with the resolve index API. */ index: IndexName } query_parameters: { /** * Only perform the operation if the document has this primary term. + * @ext_doc_id optimistic-concurrency */ if_primary_term?: long /** * Only perform the operation if the document has this sequence number. + * @ext_doc_id optimistic-concurrency */ if_seq_no?: SequenceNumber /** - * Set to create to only index the document if it does not already exist (put if absent). + * Set to `create` to only index the document if it does not already exist (put if absent). * If a document with the specified `_id` already exists, the indexing operation will fail. - * Same as using the `/_create` endpoint. - * Valid values: `index`, `create`. - * If document id is specified, it defaults to `index`. + * The behavior is the same as using the `/_create` endpoint. + * If a document ID is specified, this paramater defaults to `index`. * Otherwise, it defaults to `create`. + * If the request targets a data stream, an `op_type` of `create` is required. */ op_type?: OpType /** - * ID of the pipeline to use to preprocess incoming documents. + * The ID of the pipeline to use to preprocess incoming documents. * If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. * If a final pipeline is configured it will always run, regardless of the value of this parameter. */ pipeline?: string /** - * If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` do nothing with refreshes. - * Valid values: `true`, `false`, `wait_for`. + * If `true`, Elasticsearch refreshes the affected shards to make this operation visible to search. + * If `wait_for`, it waits for a refresh to make this operation visible to search. + * If `false`, it does nothing with refreshes. + * @server_default false */ refresh?: Refresh /** - * Custom value used to route operations to a specific shard. + * A custom value that is used to route operations to a specific shard. */ routing?: Routing /** - * Period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. + * The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards. + * + * This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. + * Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. + * By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. + * The actual wait time could be longer, particularly when multiple waits occur. * @server_default 1m */ timeout?: Duration /** - * Explicit version number for concurrency control. - * The specified version must match the current version of the document for the request to succeed. + * An explicit version number for concurrency control. + * It must be a non-negative long number. + * */ version?: VersionNumber /** - * Specific version type: `external`, `external_gte`. + * The version type. */ version_type?: VersionType /** * The number of shard copies that must be active before proceeding with the operation. - * Set to all or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). + * You can set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). + * The default value of `1` means it waits for each primary shard to be active. * @server_default 1 */ wait_for_active_shards?: WaitForActiveShards @@ -113,7 +247,7 @@ export interface Request extends RequestBase { } /** @codegen_name document */ /** - * Request body contains the JSON source for the document data. + * The request body contains the JSON source for the document data. */ body: TDocument } diff --git a/specification/_global/index/examples/request/IndexRequestExample1.yaml b/specification/_global/index/examples/request/IndexRequestExample1.yaml new file mode 100644 index 0000000000..7fe8c920d1 --- /dev/null +++ b/specification/_global/index/examples/request/IndexRequestExample1.yaml @@ -0,0 +1,14 @@ +summary: Automate document IDs +# method_request: POST my-index-000001/_doc/ +description: > + Run `POST my-index-000001/_doc/` to index a document. + When you use the `POST //_doc/` request format, the `op_type` is automatically set to `create` and the index operation generates a unique ID for the document. +# type: request +value: |- + { + "@timestamp": "2099-11-15T13:12:00", + "message": "GET /search HTTP/1.1 200 1070000", + "user": { + "id": "kimchy" + } + } diff --git a/specification/_global/index/examples/request/IndexRequestExample2.yaml b/specification/_global/index/examples/request/IndexRequestExample2.yaml new file mode 100644 index 0000000000..06f367fe7e --- /dev/null +++ b/specification/_global/index/examples/request/IndexRequestExample2.yaml @@ -0,0 +1,13 @@ +summary: Define document IDs +# method_request: PUT my-index-000001/_doc/1 +description: > + Run `PUT my-index-000001/_doc/1` to insert a JSON document into the `my-index-000001` index with an `_id` of 1. +# type: request +value: |- + { + "@timestamp": "2099-11-15T13:12:00", + "message": "GET /search HTTP/1.1 200 1070000", + "user": { + "id": "kimchy" + } + } diff --git a/specification/_global/index/examples/response/IndexResponseExample1.yaml b/specification/_global/index/examples/response/IndexResponseExample1.yaml new file mode 100644 index 0000000000..c1e63ecf03 --- /dev/null +++ b/specification/_global/index/examples/response/IndexResponseExample1.yaml @@ -0,0 +1,18 @@ +summary: Automate document IDs +description: A successful response from `POST my-index-000001/_doc/`, which contains an automated document ID. +# type: response +# response_code: 200 +value: |- + { + "_shards": { + "total": 2, + "failed": 0, + "successful": 2 + }, + "_index": "my-index-000001", + "_id": "W0tpsmIBdwcYyG50zbta", + "_version": 1, + "_seq_no": 0, + "_primary_term": 1, + "result": "created" + } diff --git a/specification/_global/index/examples/response/IndexResponseExample2.yaml b/specification/_global/index/examples/response/IndexResponseExample2.yaml new file mode 100644 index 0000000000..6fc1fc0b16 --- /dev/null +++ b/specification/_global/index/examples/response/IndexResponseExample2.yaml @@ -0,0 +1,18 @@ +summary: Define document IDs +description: A successful response from `PUT my-index-000001/_doc/1`. +# type: response +# response_code: 200 +value: |- + { + "_shards": { + "total": 2, + "failed": 0, + "successful": 2 + }, + "_index": "my-index-000001", + "_id": "1", + "_version": 1, + "_seq_no": 0, + "_primary_term": 1, + "result": "created" + } diff --git a/specification/_global/reindex/ReindexRequest.ts b/specification/_global/reindex/ReindexRequest.ts index 090942ad02..69581b4769 100644 --- a/specification/_global/reindex/ReindexRequest.ts +++ b/specification/_global/reindex/ReindexRequest.ts @@ -26,11 +26,193 @@ import { Destination, Source } from './types' /** * Reindex documents. - * Copies documents from a source to a destination. The source can be any existing index, alias, or data stream. The destination must differ from the source. For example, you cannot reindex a data stream into itself. + * + * Copy documents from a source to a destination. + * You can copy all documents to the destination index or reindex a subset of the documents. + * The source can be any existing index, alias, or data stream. + * The destination must differ from the source. + * For example, you cannot reindex a data stream into itself. + * + * IMPORTANT: Reindex requires `_source` to be enabled for all documents in the source. + * The destination should be configured as wanted before calling the reindex API. + * Reindex does not copy the settings from the source or its associated template. + * Mappings, shard counts, and replicas, for example, must be configured ahead of time. + * + * If the Elasticsearch security features are enabled, you must have the following security privileges: + * + * * The `read` index privilege for the source data stream, index, or alias. + * * The `write` index privilege for the destination data stream, index, or index alias. + * * To automatically create a data stream or index with a reindex API request, you must have the `auto_configure`, `create_index`, or `manage` index privilege for the destination data stream, index, or alias. + * * If reindexing from a remote cluster, the `source.remote.user` must have the `monitor` cluster privilege and the `read` index privilege for the source data stream, index, or alias. + * + * If reindexing from a remote cluster, you must explicitly allow the remote host in the `reindex.remote.whitelist` setting. + * Automatic data stream creation requires a matching index template with data stream enabled. + * + * The `dest` element can be configured like the index API to control optimistic concurrency control. + * Omitting `version_type` or setting it to `internal` causes Elasticsearch to blindly dump documents into the destination, overwriting any that happen to have the same ID. + * + * Setting `version_type` to `external` causes Elasticsearch to preserve the `version` from the source, create any documents that are missing, and update any documents that have an older version in the destination than they do in the source. + * + * Setting `op_type` to `create` causes the reindex API to create only missing documents in the destination. + * All existing documents will cause a version conflict. + * + * IMPORTANT: Because data streams are append-only, any reindex request to a destination data stream must have an `op_type` of `create`. + * A reindex can only add new documents to a destination data stream. + * It cannot update existing documents in a destination data stream. + * + * By default, version conflicts abort the reindex process. + * To continue reindexing if there are conflicts, set the `conflicts` request body property to `proceed`. + * In this case, the response includes a count of the version conflicts that were encountered. + * Note that the handling of other error types is unaffected by the `conflicts` property. + * Additionally, if you opt to count version conflicts, the operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query. + * + * NOTE: The reindex API makes no effort to handle ID collisions. + * The last document written will "win" but the order isn't usually predictable so it is not a good idea to rely on this behavior. + * Instead, make sure that IDs are unique by using a script. + * + * **Running reindex asynchronously** + * + * If the request contains `wait_for_completion=false`, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task. + * Elasticsearch creates a record of this task as a document at `_tasks/`. + * + * **Reindex from multiple sources** + * + * If you have many sources to reindex it is generally better to reindex them one at a time rather than using a glob pattern to pick up multiple sources. + * That way you can resume the process if there are any errors by removing the partially completed source and starting over. + * It also makes parallelizing the process fairly simple: split the list of sources to reindex and run each list in parallel. + * + * For example, you can use a bash script like this: + * + * ``` + * for index in i1 i2 i3 i4 i5; do + * curl -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{ + * "source": { + * "index": "'$index'" + * }, + * "dest": { + * "index": "'$index'-reindexed" + * } + * }' + * done + * ``` + * + * ** Throttling** + * + * Set `requests_per_second` to any positive decimal number (`1.4`, `6`, `1000`, for example) to throttle the rate at which reindex issues batches of index operations. + * Requests are throttled by padding each batch with a wait time. + * To turn off throttling, set `requests_per_second` to `-1`. + * + * The throttling is done by waiting between batches so that the scroll that reindex uses internally can be given a timeout that takes into account the padding. + * The padding time is the difference between the batch size divided by the `requests_per_second` and the time spent writing. + * By default the batch size is `1000`, so if `requests_per_second` is set to `500`: + * + * ``` + * target_time = 1000 / 500 per second = 2 seconds + * wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds + * ``` + * + * Since the batch is issued as a single bulk request, large batch sizes cause Elasticsearch to create many requests and then wait for a while before starting the next set. + * This is "bursty" instead of "smooth". + * + * **Slicing** + * + * Reindex supports sliced scroll to parallelize the reindexing process. + * This parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts. + * + * NOTE: Reindexing from remote clusters does not support manual or automatic slicing. + * + * You can slice a reindex request manually by providing a slice ID and total number of slices to each request. + * You can also let reindex automatically parallelize by using sliced scroll to slice on `_id`. + * The `slices` parameter specifies the number of slices to use. + * + * Adding `slices` to the reindex request just automates the manual process, creating sub-requests which means it has some quirks: + * + * * You can see these requests in the tasks API. These sub-requests are "child" tasks of the task for the request with slices. + * * Fetching the status of the task for the request with `slices` only contains the status of completed slices. + * * These sub-requests are individually addressable for things like cancellation and rethrottling. + * * Rethrottling the request with `slices` will rethrottle the unfinished sub-request proportionally. + * * Canceling the request with `slices` will cancel each sub-request. + * * Due to the nature of `slices`, each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution. + * * Parameters like `requests_per_second` and `max_docs` on a request with `slices` are distributed proportionally to each sub-request. Combine that with the previous point about distribution being uneven and you should conclude that using `max_docs` with `slices` might not result in exactly `max_docs` documents being reindexed. + * * Each sub-request gets a slightly different snapshot of the source, though these are all taken at approximately the same time. + * + * If slicing automatically, setting `slices` to `auto` will choose a reasonable number for most indices. + * If slicing manually or otherwise tuning automatic slicing, use the following guidelines. + * + * Query performance is most efficient when the number of slices is equal to the number of shards in the index. + * If that number is large (for example, `500`), choose a lower number as too many slices will hurt performance. + * Setting slices higher than the number of shards generally does not improve efficiency and adds overhead. + * + * Indexing performance scales linearly across available resources with the number of slices. + * + * Whether query or indexing performance dominates the runtime depends on the documents being reindexed and cluster resources. + * + * **Modify documents during reindexing** + * + * Like `_update_by_query`, reindex operations support a script that modifies the document. + * Unlike `_update_by_query`, the script is allowed to modify the document's metadata. + * + * Just as in `_update_by_query`, you can set `ctx.op` to change the operation that is run on the destination. + * For example, set `ctx.op` to `noop` if your script decides that the document doesn’t have to be indexed in the destination. This "no operation" will be reported in the `noop` counter in the response body. + * Set `ctx.op` to `delete` if your script decides that the document must be deleted from the destination. + * The deletion will be reported in the `deleted` counter in the response body. + * Setting `ctx.op` to anything else will return an error, as will setting any other field in `ctx`. + * + * Think of the possibilities! Just be careful; you are able to change: + * + * * `_id` + * * `_index` + * * `_version` + * * `_routing` + * + * Setting `_version` to `null` or clearing it from the `ctx` map is just like not sending the version in an indexing request. + * It will cause the document to be overwritten in the destination regardless of the version on the target or the version type you use in the reindex API. + * + * **Reindex from remote** + * + * Reindex supports reindexing from a remote Elasticsearch cluster. + * The `host` parameter must contain a scheme, host, port, and optional path. + * The `username` and `password` parameters are optional and when they are present the reindex operation will connect to the remote Elasticsearch node using basic authentication. + * Be sure to use HTTPS when using basic authentication or the password will be sent in plain text. + * There are a range of settings available to configure the behavior of the HTTPS connection. + * + * When using Elastic Cloud, it is also possible to authenticate against the remote cluster through the use of a valid API key. + * Remote hosts must be explicitly allowed with the `reindex.remote.whitelist` setting. + * It can be set to a comma delimited list of allowed remote host and port combinations. + * Scheme is ignored; only the host and port are used. + * For example: + * + * ``` + * reindex.remote.whitelist: [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*"] + * ``` + * + * The list of allowed hosts must be configured on any nodes that will coordinate the reindex. + * This feature should work with remote clusters of any version of Elasticsearch. + * This should enable you to upgrade from any version of Elasticsearch to the current version by reindexing from a cluster of the old version. + * + * WARNING: Elasticsearch does not support forward compatibility across major versions. + * For example, you cannot reindex from a 7.x cluster into a 6.x cluster. + * + * To enable queries sent to older versions of Elasticsearch, the `query` parameter is sent directly to the remote host without validation or modification. + * + * NOTE: Reindexing from remote clusters does not support manual or automatic slicing. + * + * Reindexing from a remote server uses an on-heap buffer that defaults to a maximum size of 100mb. + * If the remote index includes very large documents you'll need to use a smaller batch size. + * It is also possible to set the socket read timeout on the remote connection with the `socket_timeout` field and the connection timeout with the `connect_timeout` field. + * Both default to 30 seconds. + * + * **Configuring SSL parameters** + * + * Reindex from remote supports configurable SSL settings. + * These must be specified in the `elasticsearch.yml` file, with the exception of the secure settings, which you add in the Elasticsearch keystore. + * It is not possible to configure SSL in the body of the reindex request. * @rest_spec_name reindex * @availability stack since=2.3.0 stability=stable * @availability serverless stability=stable visibility=public + * @index_privileges read, write * @doc_tag document + * @doc_id docs-reindex */ export interface Request extends RequestBase { query_parameters: { @@ -41,28 +223,41 @@ export interface Request extends RequestBase { refresh?: boolean /** * The throttle for this request in sub-requests per second. - * Defaults to no throttle. + * By default, there is no throttle. * @server_default -1 */ requests_per_second?: float /** - * Specifies how long a consistent view of the index should be maintained for scrolled search. + * The period of time that a consistent view of the index should be maintained for scrolled search. */ scroll?: Duration /** * The number of slices this task should be divided into. - * Defaults to 1 slice, meaning the task isn’t sliced into subtasks. + * It defaults to one slice, which means the task isn't sliced into subtasks. + * + * Reindex supports sliced scroll to parallelize the reindexing process. + * This parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts. + * + * NOTE: Reindexing from remote clusters does not support manual or automatic slicing. + * + * If set to `auto`, Elasticsearch chooses the number of slices to use. + * This setting will use one slice per shard, up to a certain limit. + * If there are multiple sources, it will choose the number of slices based on the index or backing index with the smallest number of shards. * @server_default 1 + * @ext_doc_id slice-scroll */ slices?: Slices /** - * Period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards. + * The period each indexing waits for automatic index creation, dynamic mapping updates, and waiting for active shards. + * By default, Elasticsearch waits for at least one minute before failing. + * The actual wait time could be longer, particularly when multiple waits occur. * @server_default 1m */ timeout?: Duration /** * The number of shard copies that must be active before proceeding with the operation. - * Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). + * Set it to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`). + * The default value is one, which means it waits for each primary shard to be active. * @server_default 1 */ wait_for_active_shards?: WaitForActiveShards @@ -79,7 +274,7 @@ export interface Request extends RequestBase { } body: { /** - * Set to proceed to continue reindexing even if there are conflicts. + * Indicates whether to continue reindexing even when there are conflicts. * @server_default abort */ conflicts?: Conflicts @@ -89,6 +284,10 @@ export interface Request extends RequestBase { dest: Destination /** * The maximum number of documents to reindex. + * By default, all documents are reindexed. + * If it is a value less then or equal to `scroll_size`, a scroll will not be used to retrieve the results for the operation. + * + * If `conflicts` is set to `proceed`, the reindex operation could attempt to reindex more documents from the source than `max_docs` until it has successfully indexed `max_docs` documents into the target or it has gone through every document in the source query. */ max_docs?: long /** diff --git a/specification/_global/reindex/ReindexResponse.ts b/specification/_global/reindex/ReindexResponse.ts index 3c8e50452f..d48e68c6e2 100644 --- a/specification/_global/reindex/ReindexResponse.ts +++ b/specification/_global/reindex/ReindexResponse.ts @@ -25,21 +25,68 @@ import { DurationValue, EpochTime, UnitMillis } from '@_types/Time' export class Response { body: { + /** + * The number of scroll responses that were pulled back by the reindex. + */ batches?: long + /** + * The number of documents that were successfully created. + */ created?: long + /** + * The number of documents that were successfully deleted. + */ deleted?: long + /** + * If there were any unrecoverable errors during the process, it is an array of those failures. + * If this array is not empty, the request ended because of those failures. + * Reindex is implemented using batches and any failure causes the entire process to end but all failures in the current batch are collected into the array. + * You can use the `conflicts` option to prevent the reindex from ending on version conflicts. + */ failures?: BulkIndexByScrollFailure[] + /** + * The number of documents that were ignored because the script used for the reindex returned a `noop` value for `ctx.op`. + */ noops?: long + /** + * The number of retries attempted by reindex. + */ retries?: Retries + /** + * The number of requests per second effectively run during the reindex. + */ requests_per_second?: float slice_id?: integer task?: TaskId + /** + * The number of milliseconds the request slept to conform to `requests_per_second`. + */ throttled_millis?: EpochTime + /** + * This field should always be equal to zero in a reindex response. + * It has meaning only when using the task API, where it indicates the next time (in milliseconds since epoch) that a throttled request will be run again in order to conform to `requests_per_second`. + */ throttled_until_millis?: EpochTime + /** + * If any of the requests that ran during the reindex timed out, it is `true`. + */ timed_out?: boolean + /** + * The total milliseconds the entire operation took. + */ took?: DurationValue + /** + * The number of documents that were successfully processed. + */ total?: long + /** + * The number of documents that were successfully updated. + * That is to say, a document with the same ID already existed before the reindex updated it. + */ updated?: long + /** + * The number of version conflicts that occurred. + */ version_conflicts?: long } } diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample1.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample1.yaml new file mode 100644 index 0000000000..b30e00d9a6 --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample1.yaml @@ -0,0 +1,16 @@ +summary: Reindex multiple sources +# method_request: POST _reindex +description: > + Run `POST _reindex` to reindex from multiple sources. + The `index` attribute in source can be a list, which enables you to copy from lots of sources in one request. + This example copies documents from the `my-index-000001` and `my-index-000002` indices. +# type: request +value: |- + { + "source": { + "index": ["my-index-000001", "my-index-000002"] + }, + "dest": { + "index": "my-new-index-000002" + } + } diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample10.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample10.yaml new file mode 100644 index 0000000000..3b5f2cc9a5 --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample10.yaml @@ -0,0 +1,12 @@ +summary: Reindex with Painless +# method_request: POST _reindex +description: > + You can use Painless to reindex daily indices to apply a new template to the existing documents. + The script extracts the date from the index name and creates a new index with `-1` appended. + For example, all data from `metricbeat-2016.05.31` will be reindexed into `metricbeat-2016.05.31-1`. +# type: request +value: + "{\n \"source\": {\n \"index\": \"metricbeat-*\"\n },\n \"dest\": {\n\ + \ \"index\": \"metricbeat\"\n },\n \"script\": {\n \"lang\": \"painless\"\ + ,\n \"source\": \"ctx._index = 'metricbeat-' + (ctx._index.substring('metricbeat-'.length(),\ + \ ctx._index.length())) + '-1'\"\n }\n}" diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample11.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample11.yaml new file mode 100644 index 0000000000..352e94818d --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample11.yaml @@ -0,0 +1,11 @@ +summary: Reindex a random subset +# method_request: POST _reindex +description: > + Run `POST _reindex` to extract a random subset of the source for testing. + You might need to adjust the `min_score` value depending on the relative amount of data extracted from source. +# type: request +value: + "{\n \"max_docs\": 10,\n \"source\": {\n \"index\": \"my-index-000001\"\ + ,\n \"query\": {\n \"function_score\" : {\n \"random_score\" : {},\n\ + \ \"min_score\" : 0.9\n }\n }\n },\n \"dest\": {\n \"index\"\ + : \"my-new-index-000001\"\n }\n}" diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample12.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample12.yaml new file mode 100644 index 0000000000..0bc53d0337 --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample12.yaml @@ -0,0 +1,11 @@ +summary: Reindex modified documents +# method_request: POST _reindex +description: > + Run `POST _reindex` to modify documents during reindexing. + This example bumps the version of the source document. +# type: request +value: + "{\n \"source\": {\n \"index\": \"my-index-000001\"\n },\n \"dest\":\ + \ {\n \"index\": \"my-new-index-000001\",\n \"version_type\": \"external\"\ + \n },\n \"script\": {\n \"source\": \"if (ctx._source.foo == 'bar') {ctx._version++;\ + \ ctx._source.remove('foo')}\",\n \"lang\": \"painless\"\n }\n}" diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample13.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample13.yaml new file mode 100644 index 0000000000..16718e5733 --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample13.yaml @@ -0,0 +1,11 @@ +summary: Reindex from remote on Elastic Cloud +# method_request: POST _reindex +description: > + When using Elastic Cloud, you can run `POST _reindex` and authenticate against a remote cluster with an API key. +# type: request +value: + "{\n \"source\": {\n \"remote\": {\n \"host\": \"http://otherhost:9200\"\ + ,\n \"username\": \"user\",\n \"password\": \"pass\"\n },\n \"index\"\ + : \"my-index-000001\",\n \"query\": {\n \"match\": {\n \"test\":\ + \ \"data\"\n }\n }\n },\n \"dest\": {\n \"index\": \"my-new-index-000001\"\ + \n }\n}" diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample2.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample2.yaml new file mode 100644 index 0000000000..dd7c59be91 --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample2.yaml @@ -0,0 +1,19 @@ +summary: Manual slicing +# method_request: POST _reindex +description: > + Run `POST _reindex` to slice a reindex request manually. + Provide a slice ID and total number of slices to each request. +# type: request +value: |- + { + "source": { + "index": "my-index-000001", + "slice": { + "id": 0, + "max": 2 + } + }, + "dest": { + "index": "my-new-index-000001" + } + } diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample3.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample3.yaml new file mode 100644 index 0000000000..6739f7efcd --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample3.yaml @@ -0,0 +1,9 @@ +summary: Automatic slicing +# method_request: POST _reindex?slices=5&refresh +description: > + Run `POST _reindex?slices=5&refresh` to automatically parallelize using sliced scroll to slice on `_id`. + The `slices` parameter specifies the number of slices to use. +# type: request +value: + "{\n \"source\": {\n \"index\": \"my-index-000001\"\n },\n \"dest\":\ + \ {\n \"index\": \"my-new-index-000001\"\n }\n}" diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample4.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample4.yaml new file mode 100644 index 0000000000..62ef40fca3 --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample4.yaml @@ -0,0 +1,11 @@ +summary: Routing +# method_request: POST _reindex +description: > + By default if reindex sees a document with routing then the routing is preserved unless it's changed by the script. + You can set `routing` on the `dest` request to change this behavior. + In this example, run `POST _reindex` to copy all documents from the `source` with the company name `cat` into the `dest` with routing set to `cat`. +# type: request +value: + "{\n \"source\": {\n \"index\": \"source\",\n \"query\": {\n \"\ + match\": {\n \"company\": \"cat\"\n }\n }\n },\n \"dest\": {\n\ + \ \"index\": \"dest\",\n \"routing\": \"=cat\"\n }\n}" diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample5.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample5.yaml new file mode 100644 index 0000000000..9cc24461c2 --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample5.yaml @@ -0,0 +1,7 @@ +summary: Ingest pipelines +# method_request: POST _reindex +description: Run `POST _reindex` and use the ingest pipelines feature. +# type: request +value: + "{\n \"source\": {\n \"index\": \"source\"\n },\n \"dest\": {\n \"\ + index\": \"dest\",\n \"pipeline\": \"some_ingest_pipeline\"\n }\n}" diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample6.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample6.yaml new file mode 100644 index 0000000000..c87ff330e1 --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample6.yaml @@ -0,0 +1,10 @@ +summary: Reindex with a query +# method_request: POST _reindex +description: > + Run `POST _reindex` and add a query to the `source` to limit the documents to reindex. + For example, this request copies documents into `my-new-index-000001` only if they have a `user.id` of `kimchy`. +# type: request +value: + "{\n \"source\": {\n \"index\": \"my-index-000001\",\n \"query\": {\n\ + \ \"term\": {\n \"user.id\": \"kimchy\"\n }\n }\n },\n \"\ + dest\": {\n \"index\": \"my-new-index-000001\"\n }\n}" diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample7.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample7.yaml new file mode 100644 index 0000000000..ed868d28d5 --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample7.yaml @@ -0,0 +1,9 @@ +summary: Reindex with max_docs +# method_request: POST _reindex +description: > + You can limit the number of processed documents by setting `max_docs`. + For example, run `POST _reindex` to copy a single document from `my-index-000001` to `my-new-index-000001`. +# type: request +value: + "{\n \"max_docs\": 1,\n \"source\": {\n \"index\": \"my-index-000001\"\ + \n },\n \"dest\": {\n \"index\": \"my-new-index-000001\"\n }\n}" diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample8.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample8.yaml new file mode 100644 index 0000000000..b15f45ed5c --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample8.yaml @@ -0,0 +1,10 @@ +summary: Reindex selected fields +# method_request: POST _reindex +description: > + You can use source filtering to reindex a subset of the fields in the original documents. + For example, run `POST _reindex` the reindex only the `user.id` and `_doc` fields of each document. +# type: request +value: + "{\n \"source\": {\n \"index\": \"my-index-000001\",\n \"_source\":\ + \ [\"user.id\", \"_doc\"]\n },\n \"dest\": {\n \"index\": \"my-new-index-000001\"\ + \n }\n}" diff --git a/specification/_global/reindex/examples/request/ReindexRequestExample9.yaml b/specification/_global/reindex/examples/request/ReindexRequestExample9.yaml new file mode 100644 index 0000000000..4db7e1ad72 --- /dev/null +++ b/specification/_global/reindex/examples/request/ReindexRequestExample9.yaml @@ -0,0 +1,10 @@ +summary: Reindex new field names +# method_request: POST _reindex +description: > + A reindex operation can build a copy of an index with renamed fields. + If your index has documents with `text` and `flag` fields, you can change the latter field name to `tag` during the reindex. +# type: request +value: + "{\n \"source\": {\n \"index\": \"my-index-000001\"\n },\n \"dest\":\ + \ {\n \"index\": \"my-new-index-000001\"\n },\n \"script\": {\n \"source\"\ + : \"ctx._source.tag = ctx._source.remove(\\\"flag\\\")\"\n }\n}" diff --git a/specification/_global/reindex/types.ts b/specification/_global/reindex/types.ts index 678c40e338..395da4278c 100644 --- a/specification/_global/reindex/types.ts +++ b/specification/_global/reindex/types.ts @@ -42,8 +42,9 @@ export class Destination { */ index: IndexName /** - * Set to `create` to only index documents that do not already exist. - * Important: To reindex to a data stream destination, this argument must be `create`. + * If it is `create`, the operation will only index documents that do not already exist (also known as "put if absent"). + * + * IMPORTANT: To reindex to a data stream destination, this argument must be `create`. * @server_default index */ op_type?: OpType @@ -52,8 +53,10 @@ export class Destination { */ pipeline?: string /** - * By default, a document's routing is preserved unless it’s changed by the script. - * Set to `discard` to set routing to `null`, or `=value` to route using the specified `value`. + * By default, a document's routing is preserved unless it's changed by the script. + * If it is `keep`, the routing on the bulk request sent for each match is set to the routing on the match. + * If it is `discard`, the routing on the bulk request sent for each match is set to `null`. + * If it is `=value`, the routing on the bulk request sent for each match is set to all value specified after the equals sign (`=`). * @server_default keep */ routing?: Routing @@ -66,11 +69,11 @@ export class Destination { export class Source { /** * The name of the data stream, index, or alias you are copying from. - * Accepts a comma-separated list to reindex from multiple sources. + * It accepts a comma-separated list to reindex from multiple sources. */ index: Indices /** - * Specifies the documents to reindex using the Query DSL. + * The documents to reindex, which is defined with Query DSL. */ query?: QueryContainer /** @@ -79,17 +82,27 @@ export class Source { remote?: RemoteSource /** * The number of documents to index per batch. - * Use when indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB. + * Use it when you are indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB. + * @server_default 1000 */ size?: integer /** * Slice the reindex request manually using the provided slice ID and total number of slices. */ slice?: SlicedScroll + /** + * A comma-separated list of `:` pairs to sort by before indexing. + * Use it in conjunction with `max_docs` to control what documents are reindexed. + * + * WARNING: Sort in reindex is deprecated. + * Sorting in reindex was never guaranteed to index documents in order and prevents further development of reindex such as resilience and performance improvements. + * If used in combination with `max_docs`, consider using a query filter instead. + * @deprecated 7.6.0 + */ sort?: Sort /** - * If `true` reindexes all source fields. - * Set to a list to reindex select fields. + * If `true`, reindex all source fields. + * Set it to a list to reindex select fields. * @server_default true * @codegen_name source_fields */ _source?: Fields @@ -99,7 +112,7 @@ export class Source { export class RemoteSource { /** * The remote connection timeout. - * Defaults to 30 seconds. + * @server_default 30s */ connect_timeout?: Duration /** @@ -108,6 +121,7 @@ export class RemoteSource { headers?: Dictionary /** * The URL for the remote instance of Elasticsearch that you want to index from. + * This information is required when you're indexing from remote. */ host: Host /** @@ -119,7 +133,8 @@ export class RemoteSource { */ password?: Password /** - * The remote socket read timeout. Defaults to 30 seconds. + * The remote socket read timeout. + * @server_default 30s */ socket_timeout?: Duration } diff --git a/specification/_global/reindex_rethrottle/ReindexRethrottleRequest.ts b/specification/_global/reindex_rethrottle/ReindexRethrottleRequest.ts index 8a2841b40e..d6b6030590 100644 --- a/specification/_global/reindex_rethrottle/ReindexRethrottleRequest.ts +++ b/specification/_global/reindex_rethrottle/ReindexRethrottleRequest.ts @@ -25,21 +25,32 @@ import { float } from '@_types/Numeric' * Throttle a reindex operation. * * Change the number of requests per second for a particular reindex operation. + * For example: + * + * ``` + * POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1 + * ``` + * + * Rethrottling that speeds up the query takes effect immediately. + * Rethrottling that slows down the query will take effect after completing the current batch. + * This behavior prevents scroll timeouts. * @rest_spec_name reindex_rethrottle * @availability stack since=2.4.0 stability=stable * @availability serverless stability=stable visibility=private * @doc_tag document + * @doc_id docs-reindex */ export interface Request extends RequestBase { path_parts: { /** - * Identifier for the task. + * The task identifier, which can be found by using the tasks API. */ task_id: Id } query_parameters: { /** * The throttle for this request in sub-requests per second. + * It can be either `-1` to turn off throttling or any decimal number like `1.7` or `12` to throttle to that level. */ requests_per_second?: float } diff --git a/specification/_global/update/UpdateRequest.ts b/specification/_global/update/UpdateRequest.ts index 1f9ce904c8..edff2d17d5 100644 --- a/specification/_global/update/UpdateRequest.ts +++ b/specification/_global/update/UpdateRequest.ts @@ -37,24 +37,52 @@ import { Duration } from '@_types/Time' /** * Update a document. - * Updates a document by running a script or passing a partial document. + * + * Update a document by running a script or passing a partial document. + * + * If the Elasticsearch security features are enabled, you must have the `index` or `write` index privilege for the target index or index alias. + * + * The script can update, delete, or skip modifying the document. + * The API also supports passing a partial document, which is merged into the existing document. + * To fully replace an existing document, use the index API. + * This operation: + * + * * Gets the document (collocated with the shard) from the index. + * * Runs the specified script. + * * Indexes the result. + * + * The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation. + * + * The `_source` field must be enabled to use this API. + * In addition to `_source`, you can access the following variables through the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`, and `_now` (the current timestamp). * @rest_spec_name update * @availability stack stability=stable * @availability serverless stability=stable visibility=public + * @index_privileges write * @doc_tag document + * @doc_id docs-update */ export interface Request extends RequestBase { path_parts: { + /** + * A unique identifier for the document to be updated. + */ id: Id + /** + * The name of the target index. + * By default, the index is created automatically if it doesn't exist. + */ index: IndexName } query_parameters: { /** * Only perform the operation if the document has this primary term. + * @ext_doc_id optimistic-concurrency */ if_primary_term?: long /** * Only perform the operation if the document has this sequence number. + * @ext_doc_id optimistic-concurrency */ if_seq_no?: SequenceNumber /** @@ -63,90 +91,91 @@ export interface Request extends RequestBase { */ lang?: string /** - * If 'true', Elasticsearch refreshes the affected shards to make this operation - * visible to search, if 'wait_for' then wait for a refresh to make this operation - * visible to search, if 'false' do nothing with refreshes. + * If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. + * If 'wait_for', it waits for a refresh to make this operation visible to search. + * If 'false', it does nothing with refreshes. * @server_default false */ refresh?: Refresh /** - * If true, the destination must be an index alias. + * If `true`, the destination must be an index alias. * @server_default false */ require_alias?: boolean /** - * Specify how many times should the operation be retried when a conflict occurs. + * The number of times the operation should be retried when a conflict occurs. * @server_default 0 */ retry_on_conflict?: integer /** - * Custom value used to route operations to a specific shard. + * A custom value used to route operations to a specific shard. */ routing?: Routing /** - * Period to wait for dynamic mapping updates and active shards. - * This guarantees Elasticsearch waits for at least the timeout before failing. + * The period to wait for the following operations: dynamic mapping updates and waiting for active shards. + * Elasticsearch waits for at least the timeout period before failing. * The actual wait time could be longer, particularly when multiple waits occur. * @server_default 1m */ timeout?: Duration /** - * The number of shard copies that must be active before proceeding with the operations. - * Set to 'all' or any positive integer up to the total number of shards in the index - * (number_of_replicas+1). Defaults to 1 meaning the primary shard. + * The number of copies of each shard that must be active before proceeding with the operation. + * Set to 'all' or any positive integer up to the total number of shards in the index (`number_of_replicas`+1). + * The default value of `1` means it waits for each primary shard to be active. * @server_default 1 */ wait_for_active_shards?: WaitForActiveShards /** - * Set to false to disable source retrieval. You can also specify a comma-separated - * list of the fields you want to retrieve. + * If `false`, source retrieval is turned off. + * You can also specify a comma-separated list of the fields you want to retrieve. * @server_default true */ _source?: SourceConfigParam /** - * Specify the source fields you want to exclude. + * The source fields you want to exclude. */ _source_excludes?: Fields /** - * Specify the source fields you want to retrieve. + * The source fields you want to retrieve. */ _source_includes?: Fields } body: { /** - * Set to false to disable setting 'result' in the response - * to 'noop' if no change to the document occurred. + * If `true`, the `result` in the response is set to `noop` (no operation) when there are no changes to the document. * @server_default true */ detect_noop?: boolean /** * A partial update to an existing document. + * If both `doc` and `script` are specified, `doc` is ignored. * @prop_serializer SourceFormatter`1 */ doc?: TPartialDocument /** - * Set to true to use the contents of 'doc' as the value of 'upsert' + * If `true`, use the contents of 'doc' as the value of 'upsert'. + * NOTE: Using ingest pipelines with `doc_as_upsert` is not supported. * @server_default false */ doc_as_upsert?: boolean /** - * Script to execute to update the document. + * The script to run to update the document. */ script?: Script /** - * Set to true to execute the script whether or not the document exists. + * If `true`, run the script whether or not the document exists. * @server_default false */ scripted_upsert?: boolean /** - * Set to false to disable source retrieval. You can also specify a comma-separated - * list of the fields you want to retrieve. + * If `false`, turn off source retrieval. + * You can also specify a comma-separated list of the fields you want to retrieve. * @server_default true */ _source?: SourceConfig /** - * If the document does not already exist, the contents of 'upsert' are inserted as a - * new document. If the document exists, the 'script' is executed. + * If the document does not already exist, the contents of 'upsert' are inserted as a new document. + * If the document exists, the 'script' is run. * @prop_serializer SourceFormatter`1 */ upsert?: TDocument diff --git a/specification/_global/update/examples/request/UpdateRequestExample1.yaml b/specification/_global/update/examples/request/UpdateRequestExample1.yaml new file mode 100644 index 0000000000..f0268d534b --- /dev/null +++ b/specification/_global/update/examples/request/UpdateRequestExample1.yaml @@ -0,0 +1,8 @@ +summary: Update a counter with a script +# method_request: POST test/_update/1 +description: Run `POST test/_update/1` to increment a counter by using a script. +# type: request +value: + "{\n \"script\" : {\n \"source\": \"ctx._source.counter += params.count\"\ + ,\n \"lang\": \"painless\",\n \"params\" : {\n \"count\" : 4\n }\n\ + \ }\n}" diff --git a/specification/_global/update/examples/request/UpdateRequestExample10.yaml b/specification/_global/update/examples/request/UpdateRequestExample10.yaml new file mode 100644 index 0000000000..3a90656d9e --- /dev/null +++ b/specification/_global/update/examples/request/UpdateRequestExample10.yaml @@ -0,0 +1,11 @@ +summary: Scripted upsert +# method_request: POST test/_update/1 +description: > + Run `POST test/_update/1` to perform a scripted upsert. + When `scripted_upsert` is `true`, the script runs whether or not the document exists. +# type: request +value: + "{\n \"scripted_upsert\": true,\n \"script\": {\n \"source\": \"\"\"\n\ + \ if ( ctx.op == 'create' ) {\n ctx._source.counter = params.count\n\ + \ } else {\n ctx._source.counter += params.count\n }\n \"\"\"\ + ,\n \"params\": {\n \"count\": 4\n }\n },\n \"upsert\": {}\n}" diff --git a/specification/_global/update/examples/request/UpdateRequestExample11.yaml b/specification/_global/update/examples/request/UpdateRequestExample11.yaml new file mode 100644 index 0000000000..130e9f8b76 --- /dev/null +++ b/specification/_global/update/examples/request/UpdateRequestExample11.yaml @@ -0,0 +1,9 @@ +summary: Doc as upsert +# method_request: POST test/_update/1 +description: > + Run `POST test/_update/1` to perform a doc as upsert. + Instead of sending a partial `doc` plus an `upsert` doc, you can set `doc_as_upsert` to `true` to use the contents of `doc` as the `upsert` value. +# type: request +value: + "{\n \"doc\": {\n \"name\": \"new_name\"\n },\n \"doc_as_upsert\": true\n\ + }" diff --git a/specification/_global/update/examples/request/UpdateRequestExample2.yaml b/specification/_global/update/examples/request/UpdateRequestExample2.yaml new file mode 100644 index 0000000000..18d537b6f9 --- /dev/null +++ b/specification/_global/update/examples/request/UpdateRequestExample2.yaml @@ -0,0 +1,10 @@ +summary: Add a tag with a script +# method_request: POST test/_update/1 +description: > + Run `POST test/_update/1` to use a script to add a tag to a list of tags. + In this example, it is just a list, so the tag is added even it exists. +# type: request +value: + "{\n \"script\": {\n \"source\": \"ctx._source.tags.add(params.tag)\",\n\ + \ \"lang\": \"painless\",\n \"params\": {\n \"tag\": \"blue\"\n }\n\ + \ }\n}" diff --git a/specification/_global/update/examples/request/UpdateRequestExample3.yaml b/specification/_global/update/examples/request/UpdateRequestExample3.yaml new file mode 100644 index 0000000000..e7d10056fb --- /dev/null +++ b/specification/_global/update/examples/request/UpdateRequestExample3.yaml @@ -0,0 +1,12 @@ +summary: Remove a tag with a script +# method_request: POST test/_update/1 +description: > + Run `POST test/_update/1` to use a script to remove a tag from a list of tags. + The Painless function to remove a tag takes the array index of the element you want to remove. + To avoid a possible runtime error, you first need to make sure the tag exists. + If the list contains duplicates of the tag, this script just removes one occurrence. +# type: request +value: + "{\n \"script\": {\n \"source\": \"if (ctx._source.tags.contains(params.tag))\ + \ { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }\",\n \"lang\"\ + : \"painless\",\n \"params\": {\n \"tag\": \"blue\"\n }\n }\n}" diff --git a/specification/_global/update/examples/request/UpdateRequestExample4.yaml b/specification/_global/update/examples/request/UpdateRequestExample4.yaml new file mode 100644 index 0000000000..006d9f536c --- /dev/null +++ b/specification/_global/update/examples/request/UpdateRequestExample4.yaml @@ -0,0 +1,6 @@ +summary: Add fields with a script +# method_request: POST test/_update/1 +description: > + Run `POST test/_update/1` to use a script to add a field `new_field` to the document. +# type: request +value: "{\n \"script\" : \"ctx._source.new_field = 'value_of_new_field'\"\n}" diff --git a/specification/_global/update/examples/request/UpdateRequestExample5.yaml b/specification/_global/update/examples/request/UpdateRequestExample5.yaml new file mode 100644 index 0000000000..5f0a334f7e --- /dev/null +++ b/specification/_global/update/examples/request/UpdateRequestExample5.yaml @@ -0,0 +1,6 @@ +summary: Remove fields with a script +# method_request: POST test/_update/1 +description: > + Run `POST test/_update/1` to use a script to remove a field `new_field` from the document. +# type: request +value: "{\n \"script\" : \"ctx._source.remove('new_field')\"\n}" diff --git a/specification/_global/update/examples/request/UpdateRequestExample6.yaml b/specification/_global/update/examples/request/UpdateRequestExample6.yaml new file mode 100644 index 0000000000..074785f143 --- /dev/null +++ b/specification/_global/update/examples/request/UpdateRequestExample6.yaml @@ -0,0 +1,6 @@ +summary: Remove subfields with a script +# method_request: POST test/_update/1 +description: > + Run `POST test/_update/1` to use a script to remove a subfield from an object field. +# type: request +value: "{\n \"script\": \"ctx._source['my-object'].remove('my-subfield')\"\n}" diff --git a/specification/_global/update/examples/request/UpdateRequestExample7.yaml b/specification/_global/update/examples/request/UpdateRequestExample7.yaml new file mode 100644 index 0000000000..b0c7438984 --- /dev/null +++ b/specification/_global/update/examples/request/UpdateRequestExample7.yaml @@ -0,0 +1,10 @@ +summary: Change the operation with a script +# method_request: POST test/_update/1 +description: > + Run `POST test/_update/1` to change the operation that runs from within the script. + For example, this request deletes the document if the `tags` field contains `green`, otherwise it does nothing (`noop`). +# type: request +value: + "{\n \"script\": {\n \"source\": \"if (ctx._source.tags.contains(params.tag))\ + \ { ctx.op = 'delete' } else { ctx.op = 'noop' }\",\n \"lang\": \"painless\"\ + ,\n \"params\": {\n \"tag\": \"green\"\n }\n }\n}" diff --git a/specification/_global/update/examples/request/UpdateRequestExample8.yaml b/specification/_global/update/examples/request/UpdateRequestExample8.yaml new file mode 100644 index 0000000000..d46fe73164 --- /dev/null +++ b/specification/_global/update/examples/request/UpdateRequestExample8.yaml @@ -0,0 +1,6 @@ +summary: Update part of a document +# method_request: POST test/_update/1 +description: > + Run `POST test/_update/1` to do a partial update that adds a new field to the existing document. +# type: request +value: "{\n \"doc\": {\n \"name\": \"new_name\"\n }\n}" diff --git a/specification/_global/update/examples/request/UpdateRequestExample9.yaml b/specification/_global/update/examples/request/UpdateRequestExample9.yaml new file mode 100644 index 0000000000..bf2e4662d1 --- /dev/null +++ b/specification/_global/update/examples/request/UpdateRequestExample9.yaml @@ -0,0 +1,10 @@ +summary: Upsert +# method_request: POST test/_update/1 +description: > + Run `POST test/_update/1` to perfom an upsert. + If the document does not already exist, the contents of the upsert element are inserted as a new document. If the document exists, the script is run. +# type: request +value: + "{\n \"script\": {\n \"source\": \"ctx._source.counter += params.count\"\ + ,\n \"lang\": \"painless\",\n \"params\": {\n \"count\": 4\n }\n \ + \ },\n \"upsert\": {\n \"counter\": 1\n }\n}" diff --git a/specification/_global/update/examples/response/UpdateResponseExample1.yaml b/specification/_global/update/examples/response/UpdateResponseExample1.yaml new file mode 100644 index 0000000000..b8ed42a503 --- /dev/null +++ b/specification/_global/update/examples/response/UpdateResponseExample1.yaml @@ -0,0 +1,10 @@ +summary: Detect noop updates +description: > + By default updates that don't change anything detect that they don't change anything and return `"result": "noop"`. +# type: response +# response_code: '' +value: + "{\n \"_shards\": {\n \"total\": 0,\n \"successful\": 0,\n\ + \ \"failed\": 0\n },\n \"_index\": \"test\",\n \"_id\": \"1\",\n \ + \ \"_version\": 2,\n \"_primary_term\": 1,\n \"_seq_no\": 1,\n \"result\"\ + : \"noop\"\n}" diff --git a/specification/_types/Base.ts b/specification/_types/Base.ts index 621087765a..8bb72f17e4 100644 --- a/specification/_types/Base.ts +++ b/specification/_types/Base.ts @@ -34,12 +34,34 @@ import { DateTime } from './Time' export class RequestBase implements CommonQueryParameters {} export class WriteResponseBase { + /** + * The unique identifier for the added document. + */ _id: Id + /** + * The name of the index the document was added to. + */ _index: IndexName + /** + * The primary term assigned to the document for the indexing operation. + */ _primary_term?: long + /** + * The result of the indexing operation: `created` or `updated`. + */ result: Result + /** + * The sequence number assigned to the document for the indexing operation. + * Sequence numbers are used to ensure an older version of a document doesn't overwrite a newer version. + */ _seq_no?: SequenceNumber + /** + * Information about the replication process of the operation. + */ _shards: ShardStatistics + /** + * The document version, which is incremented each time the document is updated. + */ _version: VersionNumber forced_refresh?: boolean } diff --git a/specification/_types/Retries.ts b/specification/_types/Retries.ts index 0a744f85ae..03c767e67b 100644 --- a/specification/_types/Retries.ts +++ b/specification/_types/Retries.ts @@ -20,6 +20,12 @@ import { long } from './Numeric' export class Retries { + /** + * The number of bulk actions retried. + */ bulk: long + /** + * The number of search actions retried. + */ search: long } diff --git a/specification/_types/Scripting.ts b/specification/_types/Scripting.ts index 8532f867f4..685d4ee789 100644 --- a/specification/_types/Scripting.ts +++ b/specification/_types/Scripting.ts @@ -46,7 +46,7 @@ export enum ScriptLanguage { export class StoredScript { /** - * Specifies the language the script is written in. + * The language the script is written in. */ lang: ScriptLanguage options?: Dictionary diff --git a/specification/_types/common.ts b/specification/_types/common.ts index 33edc9911c..a29ec7f8ae 100644 --- a/specification/_types/common.ts +++ b/specification/_types/common.ts @@ -110,15 +110,18 @@ export enum VersionType { */ internal, /** - * Only index the document if the given version is strictly higher than the version of the stored document or if there is no existing document. + * Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document. */ external, /** - * Only index the document if the given version is equal or higher than the version of the stored document or if there is no existing document. - * Note: the external_gte version type is meant for special use cases and should be used with care. + * Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document. + * NOTE: The `external_gte` version type is meant for special use cases and should be used with care. * If used incorrectly, it can result in loss of data. */ external_gte, + /** + * This option is deprecated because it can cause primary and replica shards to diverge. + */ force } diff --git a/specification/cluster/put_settings/examples/request/ClusterPutSettingsRequestExample1.yaml b/specification/cluster/put_settings/examples/request/ClusterPutSettingsRequestExample1.yaml index 996b2597d9..4fad2a3a2d 100644 --- a/specification/cluster/put_settings/examples/request/ClusterPutSettingsRequestExample1.yaml +++ b/specification/cluster/put_settings/examples/request/ClusterPutSettingsRequestExample1.yaml @@ -1,4 +1,4 @@ -# summary: +summary: A simple setting # method_request: PUT /_cluster/settings description: An example of a persistent update. # type: request diff --git a/specification/cluster/put_settings/examples/request/ClusterPutSettingsRequestExample2.yaml b/specification/cluster/put_settings/examples/request/ClusterPutSettingsRequestExample2.yaml new file mode 100644 index 0000000000..5829be2f63 --- /dev/null +++ b/specification/cluster/put_settings/examples/request/ClusterPutSettingsRequestExample2.yaml @@ -0,0 +1,14 @@ +summary: A setting with multiple patterns +# method_request: PUT /_cluster/settings +description: > + PUT `/_cluster/settings` to update the `action.auto_create_index` setting. + The setting accepts a comma-separated list of patterns that you want to allow or you can prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked. + In this example, the auto-creation of indices called `my-index-000001` or `index10` is allowed, the creation of indices that match the pattern `index1*` is blocked, and the creation of any other indices that match the `ind*` pattern is allowed. + Patterns are matched in the order specified. +# type: request +value: |- + { + "persistent": { + "action.auto_create_index": "my-index-000001,index10,-index1*,+ind*" + } + }