A document ID identifies one Elasticsearch document so it can be addressed directly. Like a relational database primary key, it stays associated with the document for its lifetime unless deliberately changed. IDs may be supplied by the client or generated by Elasticsearch. section 5.1.1
Index a movie with a chosen ID
Use PUT when the client chooses the identifier. In this example, 1 is part of the URL, so it identifies the movie document stored in the movies index. PUT movies/_doc/1 { "title": "The Godfather", "synopsis": "The aging patriarch of an organized crime dynasty transfers control of his clandestine empire to his reluctant son" } The path has four useful parts: PUT requests indexing at a resource URL; movies names the index; _doc is the document endpoint; and 1 is the document ID. section 5.1.1
When an application has no meaningful identifier to assign—such as an automatic car sending many alerts or heartbeats—it can index with POST and omit the ID. Elasticsearch then creates a random unique UUID and returns it after indexing. Keep that returned ID if the document must later be addressed directly. section 5.1.1
Let Elasticsearch generate the ID
POST myindex/_doc { "title": "Elasticsearch in Action" } With no identifier after _doc, the server assigns the document an ID. This differs from PUT movies/_doc/1, where the client controls the identifier in the request path. section 5.1.1
Document IDs make direct retrieval straightforward. Request one document with GET <index>/_doc/<id>; the response includes the original document under _source plus metadata such as index, id, found, and version. Use the _source endpoint when only the original document is needed. section 2.2.2
This request is the smallest direct lookup: index books, document endpoint _doc, and ID 1. section 2.2.2
Retrieve several known documents
For a set of known IDs, use an ids query through the _search endpoint rather than issuing separate document API calls. GET books/_search { "query": { "ids": { "values": [1, 2, 3] } } } The values array contains document IDs. By contrast, retrieving every document uses _search without IDs or search criteria. section 2.2.2
Choose client-provided IDs when the application needs a stable, meaningful way to address a document. Choose generated IDs when messages do not need a client-managed sequence. For creation that must fail if an ID already exists, the _create endpoint provides an alternative to the ordinary document indexing endpoint. section 5.1.1
