Primary Key: Document ID
The Ditto query engine supports various filter operations for optimal data retrieval. As the basis of data organization and access in Ditto, the query engine indexes the document ID so you can quickly and precisely access your data. When invoking the Upsert method to create a new document, unless manually supplied, Ditto automatically generates and assigns the new document a 128‑bit Universally Unique Identifier (UUID).When referencing the document ID in your queries for the HTTP API, pass
id
instead of the reserved _id
parameter. However, if not making API calls, pass the reserved _id
instead.Custom Document ID
If supplying your own document ID, you can encode your value in astring
or, if forming a composite key, a JSON-object.
You can configure a custom document ID only at the time of document creation.Once a document is created, to ensure consistency and uniqueness throughout the platform, the unique identifier that either Ditto automatically generated and assigned or you manually assigned becomes permanent and cannot be changed at a later time.
- To implement additional logic to handle (or prevent) duplicate writes.
- To simplify queries and enhance efficiency in the querying process.
Supplying a String ID
To provide a custom document ID, when invokingupsert
to create a new document, include the id
parameter with a string
set to the value you want to use as the document’s ID.
For example, the following snippet demonstrates creating a new document in the people
collection with the custom ID set to abc123
, along with the specified name
and age
values:
cURL
Forming a Composite Key
To form a composite key, when callingupsert
to create a new document, pass the fields you want to combine to form the new primary key in an embedded map
structure under the id
field.
For example, the following snippet shows an upsert
operation on the people
collection forming a composite key made up of two parts:
string
integer
Ditto compares document IDs based on the combination of keys and their corresponding values, not by literal order in which the key-value pairs are defined.Therefore, if two document IDs have the same key-value pairs, they will be considered equal. For example:
{a: "foo", b: 1} == { b: 1, a: "foo" }
cURL