This article provides an overview of creating documents using the INSERT DQL operation.
When writing updates by way of the execute API method with INSERT operation:
- If the document does not exist locally, Ditto creates it.
- If the document already exists in the local store, Ditto throws an error.
- If the document is inserted by two or more peers at the same time, the documents that were inserted after the first document will be treated as having performed an UPDATE operation for all fields.
For complete DQL syntax, see Ditto Query Language (DQL) > INSERT
Multiple documents can be created at the same time using the INSERT operation.
When creating a document, unless manually supplied, Ditto automatically generates and assigns the new document a 128‑bit Universally Unique Identifier (UUID).
The document identifier is represented as _id and is the primary key for the document.
If an identifier isn't provided Ditto will automatically generate one. This identifier can be accessed on the result object using the mutatedDocumentIDs field.
A custom document identifier can be either a string or a JSON-object. JSON-object keys are referred to as composite identifiers because multiple sub-fields together represent the identifier.
Document identifiers are immutable and you can only configure it 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.
For more information about document IDs, see Platform Manual > Document Model.
For example, the following snippet demonstrates a new document assigned the custom ID "123".
Following is the new 123 document that results:
The following snippet demonstrates combining the vin and make fields to form the composite key: