Writing
Ditto provides a robust query engine that allows you to perform various filter operations to carry out traditional create, read, update, and delete (CRUD) operations. For an overview, see Ditto Basics > CRUD Fundamentals.
Use the write command to upsert, update, and remove documents from the Big Peer.
Do not include a find query within a write command in a single operation. Instead, perform each as separate API calls. For instructions, see Performing Find and Write Operations.
Once changes are made to the Big Peer, those changes then propagate to all Small Peers connected to the mesh network.
To access Ditto's HTTP API, direct your write requests to the following URL endpoint, making sure to replace {app_id} with the ID Ditto generated when you created your app in the portal.
For instructions on how to get your app ID, see Onboarding.
You can insert documents using the upsert method and make changes to documents using either the upsert or update methods.
Upsert combines "update" and "insert" operations by either creating a new document if the document does not exist or modifying all fields in an existing document. For an example HTTP request, see Example Upsert, as follows.
For more information about create, read, update, and delete (CRUD) operations in Ditto, see Platform Manual > Upserting and Updating.
For both Upsert and Update operations, you can replace an entire map structure with a new set of values
and update operations, If you want to use maps as registers because you want to update a document's field using a payload while deleting old values and rewriting the whole value in the map.
The following snippet demonstrates how to use the curl command to perform a complete upsert operation to explicitly create or replace a document.
In this example, a friends key contains a register of the array type, alongside orderCount which functions as a counter.
For more information about registers and counters, see the Platform Manual > Data Types.

When invoking upsert to create a new document, if desired, include an attachment in your upsert operation by calling TypeOverride::Attachment method as follows:

An update operation targets specific fields for modification within an already existing document. For an overview of the subcommands you can use in your update operation to perform specific actions, see Update Subcommands.
When using update to make changes in the Big Peer, you can include any of the following subcommands within your update command to perform specific actions:
Subcommand | Description |
set | Sets a specific value for a given field property. |
increment | Increments the value of a counter. |
replaceWithCounter | Replaces the current value with the counter. |
In addition to including an attachment when upserting a new document, you can include an attachment when updating documents, as follows:
For more information about working with attachments using the HTTP API, see Managing Attachments.
Simplify your code's handling of attachment-related data obtained from the endpoint by simplifying the overall format or specific field types.
To modify the overall presentation of attachments within the response from read endpoints, set formatAttachment to true.
Once set, read endpoints will return attachment response details in a human-readable format, making it easier to work with.
For example, the following snippet demonstrates including formatAttachment: true in the request payload:
Resulting in the following response that displays attachment details, such as id, len, and metadata:
To control response serialization by specific fields retrieved from the read endpoints, use serializedAs: 'latestValuesAndTypes'.
The following snippet provides an example response to serializedAs: 'latestValuesAndTypes':
Unless explicitly specified during an upsert operation, Ditto defaults to using a register.
However, if you want to use a mutable type instead, such as a map or a counter, or add an attachment, call the valueTypeOverrides payload in your request to either upsert or update.
For example, you want the flexibility to replace everything that was there before and put in a completely new set of values all at once, instead of using the default register type, explicitly specify to use a map.
The following snippet demonstrates explicitly specifying a counter instead of using the default register type in an upsert operation:
In Ditto, an array behaves as a register by default. This means you do not need to explicitly specify an array as a register in your request.
For more information, see the Platform Manual > Register.
Use the remove command to delete documents from the Big Peer and all Small Peers connected in the mesh network.
Once deleted, Ditto indicates its removal by creating a tombstone document. A tombstone is a placeholder that contains metadata indicating that the associated data has been removed.
Ditto creates a single tombstone for each document ID that matches the specified query.
To ensure that all Small Peers connected in the mesh network are aware that the document has been deleted, the tombstone, once created, triggers a change event that propagates across the mesh network as a record of its removal.
For example, the following snippet demonstrates how to remove a document from the people collection where the name field is set to the value of John:

