When using DQL's INSERT command, you can add new documents using JSON objects:
- INSERT INTO is the name of the collection from which you want to retrieve the data.
- DOCUMENTS ([document1], [document2], [document3], ...) represent the documents being inserted.
- [ ON ID CONFLICT [DO FAIL | DO NOTHING | DO UPDATE ([policy])]] is an optional clause that allows for defining a policy if the ID already exists in the local data store. The default is to throw an error (FAIL).
In Ditto, excluding fields from your payload doesn't remove the existing data from the system.
To remove a specific field from a document, use an explicit UPDATE statement and tombstone that field. (See UPDATE)
For full MAP syntax, see MAP.
By default, the INSERT operation throws an error if an existing document with the same ID exists in the local Ditto store.
However, Ditto allows some flexibility by allowing you to choose between ignoring the conflict (DO NOTHING) or updating existing documents (DO UPDATE) when a conflict occurs during an INSERT operation:
In this syntax:
- DO FAIL (default) will cause an error to be thrown if a document with the same _id currently exists in the local data store.
- DO NOTHING will make the statement succeed with no action taken
- DO UPDATE will perform a value update on every field in the provided document, even if the value is the same. (This will result in all fields provided being replicated).
For example, inserting or updating a car — if there is a conflict (ON ID CONFLICT), execute the DO UPDATE conflict resolution policy:
INSERT allows you to set specific documents as default data using the INITIAL DOCUMENTS action.
Initial documents are documents that are inserted at the beginning of time and are viewed by all peers as the same INSERT operation. This allows multiple peers to independently initialize the same default data safely, so regardless of the individual peer's starting point.
Initial documents will always DO NOTHING if the document ID already exists in the local Ditto store on INSERT. This behavior cannot be overwritten by the ON ID CONFLICT policy.
In this syntax:
- your_collection_name is the name of the collection from which you want to retrieve the data.
- [document] represents the document.
For example, setting up default data by inserting the given car details as an initial document: