From 9e4618111c9f1b053def85f9d16f610007b6f439 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 15 Jul 2021 10:52:37 -0700 Subject: [PATCH] Added delete document to API reference --- .../rest-api/document-apis/delete-document.md | 72 +++++++++++++++++++ .../rest-api/document-apis/get-documents.md | 23 +++--- 2 files changed, 83 insertions(+), 12 deletions(-) create mode 100644 _opensearch/rest-api/document-apis/delete-document.md diff --git a/_opensearch/rest-api/document-apis/delete-document.md b/_opensearch/rest-api/document-apis/delete-document.md new file mode 100644 index 00000000..7f167ac4 --- /dev/null +++ b/_opensearch/rest-api/document-apis/delete-document.md @@ -0,0 +1,72 @@ +--- +layout: default +title: Delete document +parent: Document APIs +nav_order: 10 +--- + +# Get document + +If you no longer need a document in your index, you can use the delete document API operation to delete it. + +## Example + +``` +DELETE /sample-index1/_doc/1 +``` + +## Path and HTTP methods + +``` +DELETE //_doc/<_id> +``` + +## URL parameters + +Parameter | Type | Description | Required +:--- | :--- | :--- | :--- +<index-name> | String | The index to delete from. | Yes +<_id> | String | The ID of the document to delete. | Yes +if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No +if_primary_term | Integer | Only perform the delete operation if the document has the specified primary term. | No +refresh | Enum | If true, OpenSearch refreshes shards to make the operation visible to searching. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is false. | No +routing | String | Value used to route the operation to a specific shard. | No +timeout | Time | How long to wait for a response from the cluster. | No +version | Integer | The version of the document to delete, which must match the last updated version of the document. | No +version_type | Enum | Retrieves a specifically typed document. Available options are `external` (retrieve the document if the specified version number is greater than the document's current version) and `external_gte` (retrieve the document if the specified version number is greater than or equal to the document's current version). For example, to delete version 3 of a document, use `/_doc/1?version=3&version_type=external`. | No +wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the delete request. Default is 1 (only the primary shard). Set to `all` or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the operation to succeed. | No + + +## Response +```json +{ + "_index": "sample-index1", + "_type": "_doc", + "_id": "1", + "_version": 2, + "result": "deleted", + "_shards": { + "total": 2, + "successful": 2, + "failed": 0 + }, + "_seq_no": 1, + "_primary_term": 15 +} +``` + +## Response body fields + +Field | Description +:--- | :--- +_index | The name of the index. +_type | The document's type. OpenSearch only supports one type, which is `_doc`. +_id | The document's ID. +_version | The document's version. +_result | The result of the delete operation. +_shards | Detailed information about the cluster's shards. +total | The total number of shards. +successful | The number of shards OpenSearch succssfully deleted the document from. +failed | The number of shards OpenSearch failed to delete the document from. +_seq_no | The sequence number assigned when the document was indexed. +_primary_term | The primary term assigned when the document was indexed. diff --git a/_opensearch/rest-api/document-apis/get-documents.md b/_opensearch/rest-api/document-apis/get-documents.md index 3c521672..a7231b39 100644 --- a/_opensearch/rest-api/document-apis/get-documents.md +++ b/_opensearch/rest-api/document-apis/get-documents.md @@ -2,7 +2,6 @@ layout: default title: Get document parent: Document APIs -grand_parent: REST API reference nav_order: 5 --- @@ -33,16 +32,16 @@ All get document URL parameters are optional. Parameter | Type | Description :--- | :--- | :--- -preference | string | Specifies a preference of which shard to retrieve results from. Available options are `_local`, which tells the operation to retrieve results from a locally allocated shard replica, and a custom string value assigned to a specific shard replica. By default, OpenSearch executes get document operations on random shards. -realtime | boolean | Specifies whether the operation should run in realtime. If false, the operation waits for the index to refresh to analyze the source to retrieve data, which makes the operation near-realtime. Default is true. -refresh | boolean | If true, OpenSearch refreshes shards to make the operation visible to searching. Default is false. -routing | string | A value used to route the operation to a specific shard. -stored_fields | boolean | If true, the operation retrieves document fields stored in the index rather than the document's `_source`. Default is false. -_source | string | Whether to include the `_source` field in the response body. Default is true. -_source_excludes | string | A comma-separated list of source fields to exclude in the query response. -_source_includes | string | A comma-separated list of source fields to include in the query response. -version | integer | The version of the document to return, which must match the current version of the document. -version_type | enum | Retrieves a specifically typed document. Available options are `external` (retrieve the document if the specified version number is greater than the document's current version) and `external_gte` (retrieve the document if the specified version number is greater than or equal to the document's current verison). For example, to retrieve version 3 of a document, use `/_doc/1?version=3&version_type=external`. +preference | String | Specifies a preference of which shard to retrieve results from. Available options are `_local`, which tells the operation to retrieve results from a locally allocated shard replica, and a custom string value assigned to a specific shard replica. By default, OpenSearch executes get document operations on random shards. +realtime | Boolean | Specifies whether the operation should run in realtime. If false, the operation waits for the index to refresh to analyze the source to retrieve data, which makes the operation near-realtime. Default is true. +refresh | Boolean | If true, OpenSearch refreshes shards to make the operation visible to searching. Default is false. +routing | String | A value used to route the operation to a specific shard. +stored_fields | Boolean | If true, the operation retrieves document fields stored in the index rather than the document's `_source`. Default is false. +_source | String | Whether to include the `_source` field in the response body. Default is true. +_source_excludes | String | A comma-separated list of source fields to exclude in the query response. +_source_includes | String | A comma-separated list of source fields to include in the query response. +version | Integer | The version of the document to return, which must match the current version of the document. +version_type | Enum | Retrieves a specifically typed document. Available options are `external` (retrieve the document if the specified version number is greater than the document's current version) and `external_gte` (retrieve the document if the specified version number is greater than or equal to the document's current version). For example, to retrieve version 3 of a document, use `/_doc/1?version=3&version_type=external`. ## Response @@ -67,7 +66,7 @@ Field | Description :--- | :--- _index | The name of the index. _type | The document's type. OpenSearch only supports one type, which is `_doc`. -_id | The document's id. +_id | The document's ID. _version | The document's version number. Updated whenever the document changes. _seq_no | The sequnce number assigned when the document is indexed. primary_term | The primary term assigned when the document is indexed.