Identifiers: Default and Custom

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) pseudocode const docid = await ditto store collection('people') upsert({ name 'susan', age 31, }) console log(docid) // auto generated uuid is "507f191e810c19729de860ea" 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 for more information, see /#primary key , as follows customizable primary key if preferred, you can customize the primary key as a string or json blob object for more information, see /#custom configurations retrieval by id using the find by id method, you can fetch a document by its primary key for more information, see /#fetching a document by id primary key the first set of fields within each document uniquely identifies the data that its document object encodes when grouped in a collection, this id serves as the primary key identifying the document in the collection in addition, you can improve organization, enhance querying capabilities, and establish specific relationships, using a combination of two or more fields to form a more specific and meaningful composite key it is important to note there are distinct tradeoffs that you must closely consider before choosing to create a composite key for more information, see /#custom configurations , as follows custom configurations 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 supplying a string id the following snippet demonstrates creating a new document assigned the string value 123abc pseudocode const docid = await ditto store collection('cars') upsert({ id '123abc', name 'susan', age 31, }) console log(docid) // "123abc"curl x post 'https //\<cloud endpoint>/api/v4/store/write' \\ \ header 'content type application/json' \\ \ data raw '{ "commands" \[{ "method" "upsert", "collection" "cars", "id" "abc123", "value" { "name" "susan", "age" 31 } }] }' forming a composite key 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, when calling upsert to create a new document, pass the fields you want to combine to form the new primary key in an embedded map structure the following snippet demonstrates combining the user id and work id fields to form the 123abc780 composite key pseudocode const docid = await ditto store collection('cars') upsert({ id { user id "123abc", work id 789 } }) console log(docid) // "123abc789"curl x post 'https //\<cloud endpoint>/api/v4/store/write' \\ \ header 'content type application/json' \\ \ data raw '{ \[{ "method" "upsert", "collection" "people", "id" { "user id" "456abc", "work id" 789 }, "value" { "name" "susan", "age" 31 } }] }' fetching a document by id fetch a single document by its primary key the document id field by invoking the find by id method pseudocode const document = await ditto store collection("cars") findbyid("123456")