Skip to main content
When using DQL’s INSERT command, you can add new documents using JSON objects:
DQL
INSERT INTO your_collection_name
DOCUMENTS ([document1]),([document2]), ([document3]), ...
[ON ID CONFLICT [FAIL | DO NOTHING | DO UPDATE | DO UPDATE_LOCAL_DIFF]]
  • 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 [FAIL | DO NOTHING | DO UPDATE | DO UPDATE_LOCAL_DIFF]] 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)

​
INSERT Document

await ditto.store.execute(
  query: "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: ["newCar": ["color": "blue"]]);

​
INSERT with Multiple Documents

await ditto.store.execute(
  query: "INSERT INTO cars DOCUMENTS (:car1), (:car2)",
  arguments: [
    "car1": ["color": "blue"],
    "car2": ["color": "red"]
  ]);

​
INSERT JSON-serialized Document

Starting with SDK 4.8, Ditto provides a convenient way to insert JSON-serialized documents using the deserialize_json() function. This allows you to directly insert string-encoded JSON data into your collections without manually parsing it first. 
await ditto.store.execute(
  query: """
    INSERT INTO cars
    DOCUMENTS (deserialize_json(:jsonData))
    ON ID CONFLICT DO UPDATE
    """,
  arguments: [ "jsonData": "{\"_id\": \"123\",\"color\": \"blue\"}" ])

​
INSERT with ID Conflict Handling

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:
DQL
ON ID CONFLICT [FAIL | DO NOTHING | DO UPDATE | DO UPDATE_LOCAL_DIFF]
In this syntax:
  • 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 means all fields provided will be replicated to other peers regardless of whether the values actually changed.
  • DO UPDATE_LOCAL_DIFF (SDK 4.12+) will only update fields whose values differ from the existing document. This is more efficient than DO UPDATE when you want to avoid unnecessary replication of unchanged values.

​
DO UPDATE

Use DO UPDATE when you want to update all fields in the document regardless of whether the values have changed. This is useful when you want to ensure all fields are replicated to other peers, even if the values are the same as the existing document. For example, inserting or updating a car — if there is a conflict (ON ID CONFLICT), execute the DO UPDATE conflict resolution policy: 
let newCar = [
  "_id": "123",
  "color": "blue"
]

await ditto.store.execute(
  query: """
    INSERT INTO cars
    DOCUMENTS (:newCar)
    ON ID CONFLICT DO UPDATE
    """,
  arguments: [ "newCar": newCar ])

​
DO UPDATE_LOCAL_DIFF

Use DO UPDATE_LOCAL_DIFF when you want to update only the fields that have actually changed. Unlike DO UPDATE, which updates every field regardless of whether the value changed, DO UPDATE_LOCAL_DIFF compares the incoming document against the existing local document and only updates fields with different values. This is useful when:
  • You want to minimize unnecessary replication traffic
  • You’re frequently re-inserting documents where most fields remain unchanged
  • You want to avoid triggering sync for unchanged data
let newCar = [
  "_id": "123",
  "color": "blue",
  "mileage": 5000
]

await ditto.store.execute(
  query: """
    INSERT INTO cars
    DOCUMENTS (:newCar)
    ON ID CONFLICT DO UPDATE_LOCAL_DIFF
    """,
  arguments: [ "newCar": newCar ])

​
INSERT with INITIAL Documents

INSERT allows you to set specific documents as default data using the INITIAL DOCUMENTS action. Initial documents are the documents 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.
When inserting, the initial documents DO NOTHING if the document ID already exists in the local Ditto store. The ON ID CONFLICT policy cannot change this behavior.
DQL
INSERT INTO your_collection_name
INITIAL DOCUMENTS ([document])
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: 
let newCar = [
  "_id": "123",
  "color": "blue"
]

await ditto.store.execute(
  query: """
    INSERT INTO cars
    INITIAL DOCUMENTS (:newCar)
    """,
  arguments: [ "newCar": newCar ])

​
INSERT Document with MAP Type

​
Disable Strict Mode

In 4.11+ and DQL_STRICT_MODE=false, collection definitions are no longer required.Read more
let arguments: [String: Any] = [
  "newCar": [
    "_id": "123",
    "properties": [
      "color": "blue",
      "mileage": 3000
    ]
  }
];

await ditto.store.execute(
  query: "INSERT INTO COLLECTION cars (properties MAP)  DOCUMENTS (:newCar)",
  arguments: arguments);