INSERT

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﻿)
INSERT Document
﻿
INSERT with Multiple Documents
﻿
INSERT Document with MAP Type
For full MAP syntax, see MAP﻿.
﻿
INSERT JSON-serialized Document
Since SDK 4.8, you can insert JSON-serialized Documents into Ditto directly using the deserialize_json() function.
Swift
Kotlin
JS
Java
C#
C++
Rust
Dart
final newCar = '{"_id": "123", "color": "blue"}';

await ditto.execute("""
  INSERT INTO cars
  DOCUMENTS (json_deserialize(:newCar))""",
  queryArgs: {"newCar": newCar},
);
final newCar = '{"_id": "123", "color": "blue"}';

await ditto.execute("""
  INSERT INTO cars
  DOCUMENTS (json_deserialize(:newCar))""",
  queryArgs: {"newCar": newCar},
);
﻿
﻿
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 [DO FAIL | DO NOTHING | DO UPDATE]
ON ID CONFLICT [DO FAIL | DO NOTHING | DO UPDATE]
﻿
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:
Swift
Kotlin
JS
Java
C#
C++
Rust
Dart
final newCar = {
  "_id": "123",
  "color": "blue",
};

await ditto.execute("""
  INSERT INTO cars
  DOCUMENTS (:newCar)
  ON ID CONFLICT DO UPDATE""",
  queryArgs: {"newCar": newCar},
);
final newCar = {
  "_id": "123",
  "color": "blue",
};

await ditto.execute("""
  INSERT INTO cars
  DOCUMENTS (:newCar)
  ON ID CONFLICT DO UPDATE""",
  queryArgs: {"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])
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:
Swift
Kotlin
JS
Java
C#
C++
Rust
Dart
const newCar = {
  "_id": "123"
  "color": "blue",
};

await ditto.execute("""
  INSERT INTO cars
  INITIAL DOCUMENTS (:newCar)""",
  {"newCar": newCar},
);
const newCar = {
  "_id": "123"
  "color": "blue",
};

await ditto.execute("""
  INSERT INTO cars
  INITIAL DOCUMENTS (:newCar)""",
  {"newCar": newCar},
);
﻿
﻿
Updated 16 Oct 2024
Did this page help you?
SELECT
UPDATE