Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ditto.live/llms.txt

Use this file to discover all available pages before exploring further.

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 Syntax Diagram
  • 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.
    • Alternative: You can use VALUES instead of DOCUMENTS - they are functionally equivalent
  • [ 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).

​
VALUES vs DOCUMENTS

Both VALUES and DOCUMENTS keywords work identically in INSERT statements. You can use either based on your preference:
DQL
-- Using DOCUMENTS
INSERT INTO cars DOCUMENTS (:car1), (:car2)

-- Using VALUES (equivalent)
INSERT INTO cars VALUES (:car1), (:car2)
Both syntaxes support:
  • Single or multiple documents
  • Parameters or literal objects
  • Arrays of documents
  • ON ID CONFLICT clauses
  • INITIAL keyword for default data
Mixing single documents and arrays in one statement (v5+): Any parameter in the VALUES or DOCUMENTS list can be either a single document object or an array of document objects. When a parameter resolves to an array, each element is inserted as a separate document.
DQL
INSERT INTO collection VALUES(:single),(:array)
With parameters {"single": {"a": 1}, "array": [{"a": 2}, {"a": 3}]}, this results in 3 documents being inserted.
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 UNSET that field. (See UPDATE)

​
INSERT Document

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

​
INSERT with Multiple Documents

You can insert multiple documents in a single INSERT statement by providing multiple parameters or by passing an array of documents.

​
Using Multiple Parameters

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

​
Using Array Parameters

You can also insert multiple documents by passing an array of objects as a parameter. This is particularly useful when you have a dynamic list of documents to insert. 
let cars = [
  ["color": "blue", "year": 2020],
  ["color": "red", "year": 2021],
  ["color": "green", "year": 2022]
]

await ditto.store.execute(
  query: "INSERT INTO cars VALUES (:cars)",
  arguments: ["cars": cars]
)
When using array parameters, each object in the array will be inserted as a separate document. You can combine array parameters with literal document parameters in the same INSERT statement.

​
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.
deserialize_json() also works in UPDATE statements to set fields from JSON strings. See UPDATE with deserialize_json for examples.
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);