This article provides how-to instructions for creating and organizing documents, linking them to associated files, called attachments, and creating MAP structures for additional document hierarchies.

Attachments in Ditto are represented using the ATTACHMENT data type, which you can use to store binary data, such as images, alongside queryable descriptive information, such as file name and description.

Syncing data across the mesh is an entirely separate process from CRUD, involving replicating documents across different databases rather than interacting with a single datastore.

To create a document, call the EXECUTE API method against the ditto.store object and include an INSERT INTO query that specifies the document to be inserted.

For example, the following snippet demonstrates how to insert a new document with a single field "color" set to "blue":

To create multiple documents efficiently, batch your CREATE operations in a single operation.

If desired, supply a document ID in your creation request; otherwise, Ditto automatically generates and assigns one.

To create multiple documents in a single operation, use the INSERT INTO operation as follows:

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 serves as the primary key for the document.

To access the IDs of the documents affected by the INSERTION INTO operation, call the mutatedDocumentIDs method on the result object after the insertion like this:

When creating a document, you can assign it a custom ID. This custom ID can be generated using a single string value or a combination of two or more string values.

This flexibility in structuring document identifiers allows you to customize document IDs to your specific requirements, use cases, or standard naming conventions.

The following snippet demonstrates a new document assigned the custom ID "123".

Following is the new 123 document that results:

The following demonstrates combining the vin and make fields to form the composite key:

There are two separate steps in the process of creating an attachment:

To create the ATTACHMENT object that encodes your attachment data, call the newAttachment method on thestorenamespace.

If desired, enclose extra information about the attachment, such as name and description. This metadata is useful for attachment fetching operations.

If you want to include information about the attachment, such as name, description, and other relevant details, enclose it in a metadata object as key-value pairs.

For example, in the following snippet, the metadata property encapsulates the name of the attachment, as well as its description:

After creating and storing a new attachment object in Ditto, you receive an attachment token as part of the response.

The following snippet demonstrates how to create a new document object containing a new attachment, and then insert it into the cars collection:

There are two ways to create a MAP structure within a document:

To represent a highly complex data structure in a MAP, consider embedding it with an additional MAP. Embedding a MAP within a MAP establishes an additional hierarchy.

The decision to use deeply embedded MAPS in a single document or opt for a flat model depends on your requirements, relationships between data, and tolerance for certain tradeoffs.

When inserting a new document in Ditto, you can define a field as a MAP and include the structure of key-value pairs nested within it — a two-in-one approach. For example:

Another method to creating a MAP within a document is to perform an UPDATE operation.

In the UPDATE approach, you set the structure of key-value pairs and specify the document ID for storage.

For example, this statement creates the MAP structure — unless it already exists — setting a single key-value pair of color is red within the properties MAP for the document with the ID 123 in the cars collection:

When writing your insert query, include a completion handler to respond to the result of the query execution.

Once defined, you can reuse this handler throughout your codebase, resulting in greater consistency throughout your app. For example: