9.6 Writes

Every write query runs in one transaction: all its changes commit, or none do. Write stages are terminal. The response holds the written documents (for insert and set) and the counters inserted, replaced, deleted.

A write streams its rows into the transaction and charges what it holds to the query memory budget. Past it, a Glacier transaction moves its pending writes to disk and commits them as one at the end; the memory backend fails the write instead.

In a Place or App instance, written rows get the scope fields (_place, _app_instance), and a write reads only that scope’s rows.

insert

Definition. Inserts one document, or an array of documents.

Syntax

insert { <key>: <value>, … }
insert [ { … }, { … }, … ]

Behavior

• Keys may be bare identifiers or JSON strings; values are JSON (nested objects and arrays included).
• One object: inserted and returned with its generated _id.
• An array: every object in one transaction, as a streaming load in merge mode. Rows without _id get one; a row with the _id of an existing document is merged into it (not in a Place scope, where a row may not merge into a stored document).
• insert is the only stage of its pipeline.

Examples

on users | insert {name: "Frank", age: 52, tags: ["new"], profile: {country: "IT"}, active: true}
-- {"_id":"01a0d795-…","active":true,"age":52,"name":"Frank","profile":{"country":"IT"},"tags":["new"]}
on users | insert [{name: "Gus", age: 20}, {name: "Hal", age: 33}]

set

Definition. Updates fields of every document reaching it.

Syntax

set <field.path> = <expression> [, <field.path> = <expression>]*

Behavior

• Paths may be nested and are created when missing. = null stores null (it does not remove the field).
• As in an SQL UPDATE, every value is computed from the document as it was before the set: set a = b, b = a swaps two fields.
• It acts on exactly the documents that reach it, so sort, skip and limit may come before it.
• Returns the updated documents.

Examples

on users | where name == "Bob" | set active = true, profile.level = "gold", age = 18
on users | where name == "Bob" | set age = age + 1, nickname = lower(name), grade = if(profile.score >= 7, "B", "C")
on users | sort name | limit 1 | set top = true
on counters | where name == "visits" | set value = value + 1

delete

Definition. Deletes every document reaching it.

Syntax

delete

Examples

on orders | where status == "cancelled" | delete
on staging | delete                    -- empties the collection

into

Alias: out

Definition. Inserts every row reaching it into another collection.

Syntax

into <collection>

Behavior

• Returns no rows; the counters report inserted.
• Each stored row gets a fresh _id, even when the pipeline kept the source _id. The source is never modified.
• The target must differ from the source and cannot be a system collection (_…).
• Authorization: write on the target, read on the source.
• It is the only write allowed after as of or history (a restore).

Examples

on users | where active | into archive
on orders | group | by region | sum qty as units | end | into region_totals
on orders as of "2026-09-01" | into orders_restored

load

Definition. Imports or upserts batches of documents.

Syntax

load
| with replace | update | merge
| chunk [ {…}, {…}, … ]
| chunk [ … ]
| end

Behavior

• with sets the mode, exactly once; at least one chunk, each a JSON array of objects.
• Rows without _id get a fresh one; rows with an _id match stored documents:

• Atomic: an invalid _id, a duplicate _id in one request, or an update miss rolls back every chunk.
• load is the first stage.
• The compact form load <target> is a runtime hook (in ogd it rewrites the documents unchanged); use the streaming form for imports.

Examples

on customers | load | with merge | chunk [{"_id":"01900000-0000-7000-8000-00000000c001","name":"ACME","tier":"gold"}] | end
on customers | load | with update | chunk [{"_id":"01900000-0000-7000-8000-00000000c001","tier":"platinum"}] | end
on tmp | load | with merge | chunk [{"n":1},{"n":2}] | chunk [{"n":3}] | end      -- 3 inserts