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.

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


// "507f191e810c19729de860ea"
print(result.mutatedDocumentIDs.first);

Custom Document Identifier

If supplying your own document ID, you can encode your value in a string 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.

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.

final newCar = {
  "_id": "123",
  "color": "blue"
};

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

// "123"
print(result.mutatedDocumentIDs.first);

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:

final newCar = {
  "_id": {
    "vin": "123",
    "make": "Toyota"
  },  
  "color": "blue"
};

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

// "{vin: "123", make: "Toyota"}"
print(result.mutatedDocumentIDs.first);

Fetching a Document by _id

Retrieve a document by its identifier (_id):

SELECT *
FROM cars
WHERE _id = '123'

If querying a composite key identifier, use dot (.) notation:

SELECT *
FROM cars
WHERE _id.model = 'Toyota'

For more information, see IDs, Paths, Strings, and Keywords and Operator Expressions in Ditto Query Language.