See Document Model for more information on documents in Ditto.

There are two ways to modify documents in DQL:

​

Updating

To optimize performance and reduce unnecessary overhead, apply most updates in your app through the UPDATE method instead.

Here is an example of a basic UPDATE operation on the cars collection:

try await ditto.store.execute("""
  UPDATE cars
  SET color = 'blue'
  WHERE _id = '123'
  """);

​

Attachment Token

Once an ATTACHMENT object is created and linked to a document, it becomes immutable, meaning its contents cannot be changed.

However, you can indirectly update attachments by performing an UPDATE operation on the document to replace the existing attachment token with a different one. The attachment token is the reference pointer linking the document to the attachment’s binary data stored separately.

// Updating a Ditto Document with an attachment
// Update the document "123" with a new attachment
try await ditto.store.execute(
    query: """
    UPDATE COLLECTION cars (my_attachment ATTACHMENT)
    SET my_attachment = :newAttachment
    WHERE _id = "123"
    """,
    arguments: ["newAttachment": newAttachment]
)

​

MAP Data Type

To add a MAP to a document, use the operator syntax -> (...), allowing you to edit multiple child fields within a single MAP:

UPDATE COLLECTION cars (properties MAP)
SET
  properties -> (
    color = 'red',
    mileage = 3001
  )
WHERE
  _id = '123'

​

Multiple Documents

Modify multiple documents simultaneously based on a specified condition.

For example, here is a snippet demonstrating the UPDATE operation modifying all documents in the cars collection that are currently red, and changing their color to blue.

After the update, you can reference the documents modified by the mutatedDocumentIDs method on the result of the update.

let result = try await ditto.store.execute(
  "UPDATE cars SET color = 'blue' WHERE _id = '123'");

result.mutatedDocumentIDs.forEach() { print($0) }

​

Inserting with Update

The INSERT operation provides conflict policy options to override default behavior if a document with the same ID already exists.

By using the ON ID CONFLICT DO UPDATE policy, inserted documents automatically apply updates for all provided fields.

var document = [
  "_id": "123",
  "color": "red",
];

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

​

MAP in a MAP

If you need to represent and organize highly complex data in a hierarchical structure, consider embedding a MAP within another MAP to establish a parent-child relationship within a document as follows:

let arguments: [String: Any] = [
  "newDocument": [
    "_id": "123",
    "top_map": [
      "nested_map": [
        "color": "blue"
      ]
    ]
  ]
];

await ditto.store.execute(
  query: """
  INSERT INTO COLLECTION your_collection_name (top_map MAP(nested_map MAP))
  DOCUMENTS (:newDocument)
  """,
  arguments: arguments);