Data Mutations

INSERT, UPDATE, UPSERT, and REMOVE operations for modifying documents in your collections.

Data Modification Operations

SDBQL supports data modification operations for inserting and updating documents directly within queries.

INSERT Insert Documents

Insert new documents into a collection.

INSERT document INTO collection

Simple Insert

LET nums = [1, 2, 3]
FOR i IN nums
  INSERT { value: i } INTO items
  RETURN i

With Computed Fields

FOR i IN 1..5
  INSERT {
    name: CONCAT("User", i),
    index: i
  } INTO users
  RETURN i

UPDATE Update Documents

Update existing documents in a collection by merging changes into existing fields.

UPDATE document WITH { changes } IN collection

Merge Behavior

UPDATE merges the changes into the existing document. Fields not specified in the changes object are preserved.

Update Single Document

FOR doc IN users
  FILTER doc.name == "Alice"
  UPDATE doc WITH {
    status: "premium"
  } IN users
  RETURN doc.name

Update Multiple Fields

FOR doc IN users
  FILTER doc.age >= 30
  UPDATE doc WITH {
    status: "vip",
    level: 5,
    verified: true
  } IN users
  RETURN doc._key

With Computed Values

FOR doc IN users
  FILTER doc.city == "Paris"
  UPDATE doc WITH {
    fullName: CONCAT(doc.name, " from ", doc.city),
    region: "Europe"
  } IN users
  RETURN doc.name

With Bind Variables

FOR doc IN users
  FILTER doc.name == @name
  UPDATE doc WITH { points: @points } IN users
  RETURN doc.name

{
  "name": "Alice",
  "points": 100
}

Return Modified Document

Use RETURN NEW to get the version of the document after the update.

FOR doc IN users
  FILTER doc._key == "alice"
  UPDATE doc WITH { status: "active" } IN users
  RETURN NEW

UPSERT Update or Insert

Atomically updates a document if it exists, or inserts it if it doesn't.

UPSERT { search } INSERT { insert } UPDATE { update } IN collection

Atomicity

In a transaction, UPSERT ensures that no other process inserts the document between the check and the insertion. The search condition should uniquely identify a single document (usually by _key).

Example

UPSERT { _key: "user123" }
INSERT { _key: "user123", name: "Alice", visits: 1 }
UPDATE { visits: 1 } --Merges if exists
IN users
RETURN NEW

REMOVE Delete Documents

Remove documents from a collection.

REMOVE document IN collection

Caution

REMOVE permanently deletes documents. Always use FILTER to target specific documents, or you'll delete all documents in the collection.

Remove by Key (Single)

FOR doc IN users
  FILTER doc._key == "alice"
  REMOVE doc IN users
  RETURN doc._key

Remove by Condition (Multiple)

FOR doc IN users
  FILTER doc.city == "Paris"
  REMOVE doc IN users
  RETURN doc.name

Remove All (Use with Caution!)

FOR doc IN users
  REMOVE doc IN users
  RETURN doc._key

Operators Graph Queries