INSERT

When using DQL’s INSERT command, you can add new documents using JSON objects:

INSERT INTO your_collection_name
VALUES ([document1]),([document2]), ([document3]), ...
[ON ID CONFLICT [FAIL | DO NOTHING | DO MERGE]]

• INSERT INTO is the name of the collection from which you want to retrieve the data.
• VALUES ([document1]), ([document2]), ([document3]), ... represent the documents being inserted.
• [ ON ID CONFLICT [DO FAIL | DO NOTHING | DO MERGE ([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).

​

INSERT Document

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

​

INSERT with Multiple Documents

await ditto.store.execute(
  query: "INSERT INTO cars VALUES (: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
    VALUES (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 MERGE) when a conflict occurs during an INSERT operation:

ON ID CONFLICT [DO FAIL | DO NOTHING | DO MERGE]

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 MERGE 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 MERGE conflict resolution policy:

let newCar = [
  "_id": "123",
  "color": "blue"
]

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

​

INSERT with INITIAL Documents

INSERT allows you to set specific documents as default data using the INITIAL VALUES action.

Initial values 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.

INSERT INTO your_collection_name
INITIAL VALUES ([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 VALUES (:newCar)
    """,
  arguments: [ "newCar": newCar ])

​

INSERT Document with MAP Type

let arguments: [String: Any] = [
  "newCar": [
    "_id": "123",
    "properties": [
      "color": "blue",
      "mileage": 3000
    ]
  }
];

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