Document Model

Identifiers

Every document has an identifier field _id. The identifier field serves as the primary key for the document and can be either auto-generated or custom-assigned.
Following are the main features and qualities associated with the _id field: 
Document Identification
The document _id field serves as the primary key identifying the document in Ditto.
Customizable Identifier:
If preferred, you can customize the _id as a string or JSON‑object. (See Custom Document Identifier﻿)
Retrieval by _id
You can fetch a document by its identifier. For more information, see Fetching a Document by _id.
Auto-Generated Document Identifier
When inserting a document, unless manually supplied, Ditto automatically generates and assigns the new document a 128‑bit Universally Unique Identifier (UUID) to the _id field.
﻿
﻿
Custom Document Identifier
﻿
Following are a few key principles for handling IDs in Ditto:
Do not include personally identifiable information (PII) in IDs
IDs should be immutable; that is, unchangeable once assigned and permanent
If an ID is formed by multiple fields, referred to as a composite key, those fields are not individually indexed
Supplying a Custom String Identifier
The following snippet demonstrates creating a new document assigned the string value 123.
﻿
Forming a Composite Key Identifier
The decision to opt for a composite key depends on your specific use case. Following are typical use cases for forming a composite key:
To implement additional logic to handle (or prevent) duplicate writes.

To simplify queries and enhance efficiency in the querying process.
To form a composite key, set the _id to a JSON object when inserting a new document.
The following snippet demonstrates combining the vin and make fields to form a composite key:
Swift
Kotlin
JS
Java
C#
C++
Rust
Dart (beta)
final newCar = {
  "_id": {
    "vin": "123",
    "make": "Toyota"
  },  
  "color": "blue"
};

final result = await ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: { "newCar": newCar },
);

// "{vin: "123", make: "Toyota"}"
print(result.mutatedDocumentIDs.first);
final newCar = {
  "_id": {
    "vin": "123",
    "make": "Toyota"
  },  
  "color": "blue"
};

final result = await ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: { "newCar": newCar },
);

// "{vin: "123", make: "Toyota"}"
print(result.mutatedDocumentIDs.first);
﻿
﻿
Fetching a Document by _id
Retrieve a document by its identifier (_id):
DQL
SELECT *
FROM cars
WHERE _id = '123'
SELECT *
FROM cars
WHERE _id = '123'
﻿
If querying a composite key identifier, use dot (.) notation:
DQL
SELECT *
FROM cars
WHERE _id.model = 'Toyota'
SELECT *
FROM cars
WHERE _id.model = 'Toyota'
﻿
For more information, see IDs, Paths, Strings, and Keywords﻿ and Operator Expressions﻿ in Ditto Query Language.

Document Identification	The document _id field serves as the primary key identifying the document in Ditto.
Customizable Identifier:	If preferred, you can customize the _id as a string or JSON‑object. (See Custom Document Identifier)
Retrieval by _id	You can fetch a document by its identifier. For more information, see Fetching a Document by _id.

Updated 10 Oct 2024

Did this page help you?

Collections

Relationships