Queries and mutations

The example stores the people in a database and queries their names. It collects query pages, updates Ada's age, and reads the changed age.

The optional adaptive query planner learns from runs and compares alternative plans for stored queries. Enable it through the database's plugins open option.

Example

The example compares these results:

a committed mutation
a repeated mutation
a query that matches no entity

Give Ada her birthday and read her age

birthday-text holds this document:

json

186 B

{
  "query": {
    "find": [
      "?e"
    ],
    "where": [
      [
        "?e",
        "name",
        "Ada"
      ]
    ]
  },
  "patch": {
    "?e": {
      "age": 37
    }
  }
}

query-text holds this document:

json

150 B

{
  "find": [
    "?age"
  ],
  "where": [
    [
      "?e",
      "name",
      "Ada"
    ],
    [
      "?e",
      "age",
      "?age"
    ]
  ]
}

clojure

266 B

(with-open [source (sd/parse birthday-text :json)
            birthday (sd/mutation db source)]
  (sd/run birthday))
(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            rows (sd/run query)]
  (sd/all-pages rows))

Result / 25 B

[
  {
    "age": 37
  }
]

Query pages

Each query page is an owned document.

You can keep a page after you release the rows handle, query, or database that produced it.
Release each page when you finish with its values. The document ownership rule applies.

The database can keep completed native fact joins as owned binding rows before aggregation. When you run the same query and plan again, the cache can supply those rows at the same database snapshot. Aggregates and output expressions still run for each call.

The cache uses the database working-memory budget and gives memory back when queries need it. The cache discards rows from joins that do not complete. After a write, new queries use a new snapshot. An active reader keeps the rows from its original snapshot.

Parameterized, temporal and overlay queries use their normal execution paths. Queries with predicates, derivations, member clauses or transaction terms also use those paths. Background planner trials and sampled foreground measurements execute joins directly.

Exact indexes

A query or mutation definition that compares a field with a value makes the database build that field's exact index. The comparison is a fact clause with a constant or a parameter value, or a =, <, <=, >, >= or hasPrefix predicate on a fact clause's value. With the index, a hasPrefix predicate reads only the texts that start with the prefix, and no value of another type.

Storing the definition starts the build. An inline query or mutation that compares a field the same way also starts one.
The database builds the index in the background, including the values committed before the definition. The call that started it does not wait.
Queries scan the field until its index is ready. The results are the same; only the time differs.
Use indexes_sync to wait until every index that earlier definitions and inline runs ask for is ready, for example before you measure a query.
An index that no definition uses any more stays until the database next opens.

Operations

Operation	Returns	Summary
read-entity	document	database.read_entity(entity, max_depth, max_entities) atomically returns an owned {document links revisions truncated} document, expanding links up to max_depth hops.
query	query	Open an owned query from a path or an inline definition.
mutation	mutation	Open an owned mutation from a path or an inline definition.
run	rows	Run the query and return an owned row cursor.
close	none	Release the query handle.
next	document	Read the next page as an owned document.
pages	pages	rows.pages() iterates the non-empty pages of the cursor.
all-pages	document	rows.all_pages() reads every remaining page into one owned array document.
close	none	Release the rows handle.
subscribe	subscription	query.subscribe(parameters, options) opens an owned live subscription.
next	event	Wait for the next live event.
events	Unavailable	subscription.events() delivers events in order until the subscription is cancelled, closes or fails.
cancel	none	subscription.cancel() ends the subscription.
close	none	Release the subscription handle.
run	commit	Run the mutation and return commit information.
close	none	Release the mutation handle.
merge-patch	commit	database.merge_patch(patch) applies an entity-keyed patch document in one transaction and returns commit information.
indexes-sync	none	database.indexes_sync(max_wait) waits until the database built every exact index that earlier definition commits and inline runs ask for.
bulk-begin	none	database.bulk_begin() starts a bulk build of data merge patches held by the database.
bulk-add	none	database.bulk_add(patch) copies and queues one merge-patch document in the bulk build.
bulk-finish	document	database.bulk_finish() publishes the bulk build with one commit, ends it and returns an owned summary document.
bulk-abort	none	database.bulk_abort() drops the bulk build in progress without writing it.

read-entity

clojure

11 B

[db entity]

clojure

34 B

[db entity max-depth max-entities]

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`entity`	`Integer`	Value	Required	The decimal user entity ID.
`max-depth`	`Integer`	Value	Absent	Link hops to expand along each path, 0 through 32. 0, the default, leaves every link a {#link id} reference.
`max-entities`	`Integer`	Value	Absent	The most entity documents the result holds, counting the root and every expanded or absent target each time it is placed. 0 selects the default of 1000.

Errors

Status	When
`:invalid-argument`	the entity ID is outside the user entity range, `max_depth` is negative or above 32, or `max_entities` is negative
`:closed`	the database is closed
`:out-of-memory`	native memory is exhausted

Notes

revisions maps each placed entity's decimal ID to its last-touch transaction for #_tx.stardust/checkAndSet. Empty object and array fields are omitted recursively. See entity reads for result fields, JSON Pointer links and expansion rules.

Examples

Read Bob with his mentor expanded

clojure

25 B

(sd/read-entity db 2 1 0)

Result / 291 B

{
  "document": {
    "age": 41,
    "mentor": {
      "age": 36,
      "name": "Ada",
      "role": "engineer"
    },
    "name": "Bob",
    "role": "engineer"
  },
  "links": {
    "/mentor": {
      "#link": 1
    }
  },
  "revisions": {
    "1": 4,
    "2": 4
  },
  "truncated": false
}

C exports: stardust_db_read_entity, stardust_result_take_document, stardust_result_error, stardust_result_release

query

clojure

11 B

[db source]

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`source`	`Source`	Value	Required	An inline native definition or a stored definition path.

Errors

Status	When
`:not-found`	no definition is stored at the path
`:invalid-definition`	the definition is invalid
`:closed`	the database is closed
`:out-of-memory`	native memory is exhausted

Notes

Inline definitions are copied. Stored paths select their definition at run time.

Query documents.

Examples

Open an inline query and read its first page

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

144 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            rows (sd/run query)]
  (sd/next rows))

Result / 82 B

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

Refuse an invalid query definition

definition-text holds this document:

json

29 B

{
  "find": [
    "?x"
  ]
}

clojure

84 B

(with-open [definition (sd/parse definition-text :json)]
  (sd/query db definition))

Result / 168 B

{
  "code": "unbound_variable",
  "message": "Unbound_Variable",
  "path": null,
  "field": null,
  "entity": null,
  "offset": null,
  "status": "invalid_definition"
}

Report a missing stored query

clojure

30 B

(sd/query db "people/missing")

Result / 174 B

{
  "code": "not_found",
  "message": "no definition at this path",
  "path": "people/missing",
  "field": null,
  "entity": null,
  "offset": null,
  "status": "not_found"
}

C exports: stardust_db_query_open, stardust_db_query_error

mutation

clojure

11 B

[db source]

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`source`	`Source`	Value	Required	An inline native definition or a stored definition path.

Errors

Status	When
`:not-found`	no definition is stored at the path
`:invalid-definition`	the definition is invalid
`:closed`	the database is closed
`:out-of-memory`	native memory is exhausted

Notes

Inline definitions are copied. Stored paths select their definition at run time.

Mutation documents.

Examples

database/mutation

birthday-text holds this document:

json

186 B

{
  "query": {
    "find": [
      "?e"
    ],
    "where": [
      [
        "?e",
        "name",
        "Ada"
      ]
    ]
  },
  "patch": {
    "?e": {
      "age": 37
    }
  }
}

clojure

116 B

(with-open [source (sd/parse birthday-text :json)
            mutation (sd/mutation db source)]
  (sd/run mutation))

Result / 111 B

{
  "status": "committed",
  "transaction": 5,
  "facts": 1,
  "committed_at": 17923367749351308,
  "ids": {}
}

C exports: stardust_db_mutation_open, stardust_db_mutation_error

run

clojure

8 B

[handle]

clojure

19 B

[handle parameters]

clojure

50 B

[handle parameters {:keys [max-cost] :as options}]

Parameters

Parameter	Type	Ownership	Default	Meaning
`handle`	`Query`	Borrowed for the call	Required	The query owner for this operation. Keep it alive during the call.
`parameters`	`Document`	Borrowed for the call	Absent means no supplied parameters	An optional object of parameter values that merge-patches the definition's declared parameters. A parameter matched in the entity position of a fact clause takes an entity reference {#link id}, never the bare ID number: a commit returns IDs as numbers, so wrap one as {#link id}, or as the typed Link value where the binding has one, before passing it. A query run fails with `entity_reference_expected` when a bare number reaches that position. Projected and found entities also read back as {#link id}, so a typed field that receives one uses Link rather than a plain integer.
`options`	`run-options`	Value	Absent selects operation defaults	The operation's options record. See its field defaults.

Errors

Status	When
`:not-found`	the stored query definition was deleted
`:invalid-definition`	the loaded query definition is invalid
`:invalid-argument`	the parameters or run options are invalid
`:evaluation-failed`	the query fails or exceeds `max_cost`
`:closed`	the query is closed
`:out-of-memory`	native memory is exhausted

Notes

Query documents.

Examples

Open an inline query and read its first page

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

144 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            rows (sd/run query)]
  (sd/next rows))

Result / 82 B

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

Capture the host duration boundary

boundary-text holds this document:

json

20 B

9223372036854775807

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

357 B

(with-open [boundary (sd/parse boundary-text :json)
            definition (sd/parse query-text :json)
            query (sd/query db definition)]
  (let [max-cost (java.time.Duration/ofSeconds (sd/i64 boundary (sd/root boundary)))
        options {:page-size 2 :max-cost max-cost :as-of 0}]
    (with-open [rows (sd/run query nil options)]
      options)))

Result / 69 B

{
  "page_size": 2,
  "max_cost": 9223372036854775807,
  "as_of": 0
}

Truncate a positive sub-tick duration

boundary-text holds this document:

json

3 B

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

355 B

(with-open [boundary (sd/parse boundary-text :json)
            definition (sd/parse query-text :json)
            query (sd/query db definition)]
  (let [max-cost (java.time.Duration/ofNanos (sd/i64 boundary (sd/root boundary)))
        options {:page-size 2 :max-cost max-cost :as-of 0}]
    (with-open [rows (sd/run query nil options)]
      options)))

Result / 51 B

{
  "page_size": 2,
  "max_cost": 0,
  "as_of": 0
}

Explain query execution

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

187 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            ^java.io.Closeable rows (sd/run query nil {:explain? true})]
  (sd/explain rows))

Result / 670 B

{
  "load_definition": {
    "cpu": 836,
    "wall": 892,
    "arena_bytes": 1680
  },
  "parameters": {
    "cpu": 7,
    "wall": 12,
    "arena_bytes": 0
  },
  "run": {
    "cpu": 12141,
    "wall": 12239,
    "arena_bytes": 7424
  },
  "total": {
    "cpu": 13019,
    "wall": 13177,
    "arena_bytes": 9104
  },
  "arena_capacity": 4194304,
  "work": 8593,
  "rows": 3,
  "compile": 413,
  "plan": 697,
  "execute": 0,
  "group": 0,
  "order": 0,
  "memory_bytes": 5995,
  "memory_refusals": 0,
  "budget_bytes": 10489856512,
  "budget_used_bytes": 10194,
  "budget_peak_bytes": 14267,
  "budget_refusals": 0,
  "retry": 0,
  "stages_completed": 3,
  "retries": 0
}

A negative sub-tick Java duration rounds toward negative infinity

clojure

65 B

{:page-size 0 :max-cost (java.time.Duration/ofNanos -1) :as-of 0}

Result / 52 B

{
  "page_size": 0,
  "max_cost": -1,
  "as_of": 0
}

Run with typed query options

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

240 B

(let [options {:page-size 2 :max-cost (java.time.Duration/ofSeconds 1) :as-of 0}]
  (with-open [definition (sd/parse query-text :json)
              query (sd/query db definition)
              rows (sd/run query nil options)]
    options))

Result / 58 B

{
  "page_size": 2,
  "max_cost": 10000000,
  "as_of": 0
}

C exports: stardust_db_query_run, stardust_db_rows_error

close

clojure

8 B

[handle]

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`handle`	`Query`	Consumed owner	Required	The query owner to release. Do not use it after this call.

Examples

Open an inline query and read its first page

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

144 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            rows (sd/run query)]
  (sd/next rows))

Result / 82 B

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

C exports: stardust_db_query_release

clojure

8 B

[handle]

Parameters

Parameter	Type	Ownership	Default	Meaning
`handle`	`Rows`	Borrowed for the call	Required	The rows owner for this operation. Keep it alive during the call.

Errors

Status	When
`:evaluation-failed`	the page does not render
`:closed`	the rows is closed
`:out-of-memory`	native memory is exhausted

Notes

An empty array ends the cursor. Every page reads the snapshot selected by the run. Returned pages survive cursor and database closure.

Examples

Open an inline query and read its first page

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

144 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            rows (sd/run query)]
  (sd/next rows))

Result / 82 B

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

C exports: stardust_db_rows_next, stardust_result_take_document, stardust_result_error, stardust_result_release

pages

clojure

6 B

[rows]

Parameters

Parameter	Type	Ownership	Default	Meaning
`rows`	`Rows`	Borrowed for the call	Required	The rows owner for this operation. Keep it alive during the call.

Errors

Status	When
`:evaluation-failed`	a page does not render
`:closed`	the rows is closed
`:out-of-memory`	native memory is exhausted

Notes

Pages are read lazily from the run's snapshot. Rust callers own each page. In other bindings, a page closes when iteration advances. Use next to retain an owned page. Close the cursor separately.

Examples

Iterate the pages of a query run

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

187 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            rows (sd/run query nil {:page-size 1})]
  (reduce (fn [n _page] (inc n)) 0 rows))

Result / 1 B

C exports: stardust_db_rows_next, stardust_result_take_document, stardust_result_error, stardust_result_release, stardust_document_root, stardust_document_read_many, stardust_document_release

all-pages

clojure

6 B

[rows]

Parameters

Parameter	Type	Ownership	Default	Meaning
`rows`	`Rows`	Borrowed for the call	Required	The rows owner for this operation. Keep it alive during the call.

Errors

Status	When
`:evaluation-failed`	a page does not render
`:closed`	the rows is closed
`:out-of-memory`	native memory is exhausted

Notes

The array contains rows, not page documents. Previously read pages are excluded. Memory grows with the remaining result. Use pages for bounded page-by-page processing. Close the cursor separately.

Examples

Read all remaining rows into one document

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

149 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            rows (sd/run query)]
  (sd/all-pages rows))

Result / 82 B

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

C exports: stardust_db_rows_next, stardust_result_take_document, stardust_result_error, stardust_result_release, stardust_document_count, stardust_document_read_many, stardust_document_i64, stardust_document_f64, stardust_document_release, stardust_document_builder_create, stardust_document_builder_add_many, stardust_document_builder_seal, stardust_document_builder_release

close

clojure

8 B

[handle]

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`handle`	`Rows`	Consumed owner	Required	The rows owner to release. Do not use it after this call.

Examples

Open an inline query and read its first page

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

144 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            rows (sd/run query)]
  (sd/next rows))

Result / 82 B

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

C exports: stardust_db_rows_release

clojure

7 B

[query]

clojure

18 B

[query parameters]

clojure

49 B

[query parameters {:keys [max-cost] :as options}]

Parameters

Parameter	Type	Ownership	Default	Meaning
`query`	`Query`	Borrowed for the call	Required	The query owner for this operation. Keep it alive during the call.
`parameters`	`Document`	Borrowed for the call	Absent means no supplied parameters	An optional object of parameter values that merge-patches the definition's declared parameters. A parameter matched in the entity position of a fact clause takes an entity reference {#link id}, never the bare ID number: a commit returns IDs as numbers, so wrap one as {#link id}, or as the typed Link value where the binding has one, before passing it. A query run fails with `entity_reference_expected` when a bare number reaches that position. Projected and found entities also read back as {#link id}, so a typed field that receives one uses Link rather than a plain integer.
`options`	`run-options`	Value	Absent selects operation defaults	The operation's options record. See its field defaults.

Errors

Status	When
`:invalid-definition`	the query or its callable definitions are invalid
`:invalid-argument`	the parameters or subscription options are invalid
`:closed`	the query is closed
`:out-of-memory`	native memory is exhausted

Notes

The subscription copies its definition and parameters. Later definition edits do not change it. The page_size option is ignored.

Subscriptions register readiness callbacks automatically. Event waits use runtime notifications instead of blocking in the C ABI.

Query documents.

Examples

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

305 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            subscription (sd/subscribe query)]
  (let [event (or (sd/next subscription (java.time.Duration/ofSeconds 5))
                  (throw (java.util.concurrent.TimeoutException.)))]
    (:result event)))

Result / 82 B

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

Read the complete initial subscription event

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

259 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            subscription (sd/subscribe query)]
  (or (sd/next subscription (java.time.Duration/ofSeconds 5))
      (throw (java.util.concurrent.TimeoutException.))))

Result / 174 B

{
  "sequence": 1,
  "superseded": 0,
  "transaction": 4,
  "result": [
    {
      "name": "Ada"
    },
    {
      "name": "Bob"
    },
    {
      "name": "Cy"
    }
  ]
}

C exports: stardust_db_query_subscribe, stardust_db_subscription_set_notify, stardust_db_subscription_error

clojure

23 B

[subscription max-wait]

Parameters

Parameter	Type	Ownership	Default	Meaning
`subscription`	`Subscription`	Borrowed for the call	Required	The subscription owner for this operation. Keep it alive during the call.
`max-wait`	`java.time.Duration`	Value	Required	The maximum wait. Zero checks once.

Errors

Status	When
`:invalid-argument`	`max_wait` is negative
`:cancelled`	the subscription is cancelled or closed
`:evaluation-failed`	a rerun of the query failed. Every later call reports this failure
`:closed`	the subscription is closed
`:out-of-memory`	native memory is exhausted

Notes

Each event replaces the entire result. superseded counts skipped computed results, not commits. Cancel, close and database close wake blocked waits. Windows rounds deadlines to milliseconds.

Examples

subscription/next

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

305 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            subscription (sd/subscribe query)]
  (let [event (or (sd/next subscription (java.time.Duration/ofSeconds 5))
                  (throw (java.util.concurrent.TimeoutException.)))]
    (:result event)))

Result / 82 B

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

C exports: stardust_db_subscription_next, stardust_db_subscription_error, stardust_document_release

events

A subscription is reducible. Use reduce or into to consume events.

C exports: stardust_db_subscription_next, stardust_db_subscription_error

cancel

clojure

14 B

[subscription]

Parameters

Parameter	Type	Ownership	Default	Meaning
`subscription`	`Subscription`	Borrowed for the call	Required	The subscription owner for this operation. Keep it alive during the call.

Notes

Repeated cancellation is safe. Close the subscription separately to release its handle.

Examples

subscription/cancel

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

334 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            subscription (sd/subscribe query)]
  (let [event (or (sd/next subscription (java.time.Duration/ofSeconds 5))
                  (throw (java.util.concurrent.TimeoutException.)))]
    (sd/cancel subscription)
    (:result event)))

Result / 82 B

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

C exports: stardust_db_subscription_cancel

close

clojure

8 B

[handle]

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`handle`	`Subscription`	Consumed owner	Required	The subscription owner to release. Do not use it after this call.

Examples

subscription/close

query-text holds this document:

json

134 B

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?e",
      "name",
      "?name"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

clojure

305 B

(with-open [definition (sd/parse query-text :json)
            query (sd/query db definition)
            subscription (sd/subscribe query)]
  (let [event (or (sd/next subscription (java.time.Duration/ofSeconds 5))
                  (throw (java.util.concurrent.TimeoutException.)))]
    (:result event)))

Result / 82 B

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

C exports: stardust_db_subscription_release

run

clojure

8 B

[handle]

clojure

19 B

[handle parameters]

clojure

50 B

[handle parameters {:keys [max-cost] :as options}]

Parameters

Parameter	Type	Ownership	Default	Meaning
`handle`	`Mutation`	Borrowed for the call	Required	The mutation owner for this operation. Keep it alive during the call.
`parameters`	`Document`	Borrowed for the call	Absent means no supplied parameters	An optional object of parameter values that merge-patches the definition's declared parameters. A parameter matched in the entity position of a fact clause takes an entity reference {#link id}, never the bare ID number: a commit returns IDs as numbers, so wrap one as {#link id}, or as the typed Link value where the binding has one, before passing it. A query run fails with `entity_reference_expected` when a bare number reaches that position. Projected and found entities also read back as {#link id}, so a typed field that receives one uses Link rather than a plain integer.
`options`	`run-options`	Value	Absent selects operation defaults	The operation's options record. See its field defaults.

Errors

Status	When
`:invalid-definition`	the mutation selection or definition is invalid
`:invalid-argument`	the parameters or run options are invalid
`:schema-violation`	the write breaks a schema
`:conflict`	concurrent writes prevent the commit
`:rejected`	a mutation target or write guard refuses the write
`:unavailable`	the patch sets stardust/history and no enabled plugin purges history
`:evaluation-failed`	the mutation fails
`:closed`	the mutation is closed
`:out-of-memory`	native memory is exhausted

Notes

Mutation documents.

Examples

mutation/run

birthday-text holds this document:

json

186 B

{
  "query": {
    "find": [
      "?e"
    ],
    "where": [
      [
        "?e",
        "name",
        "Ada"
      ]
    ]
  },
  "patch": {
    "?e": {
      "age": 37
    }
  }
}

clojure

116 B

(with-open [source (sd/parse birthday-text :json)
            mutation (sd/mutation db source)]
  (sd/run mutation))

Result / 111 B

{
  "status": "committed",
  "transaction": 5,
  "facts": 1,
  "committed_at": 17923367756028911,
  "ids": {}
}

Explain mutation execution

birthday-text holds this document:

json

186 B

{
  "query": {
    "find": [
      "?e"
    ],
    "where": [
      [
        "?e",
        "name",
        "Ada"
      ]
    ]
  },
  "patch": {
    "?e": {
      "age": 37
    }
  }
}

clojure

150 B

(with-open [source (sd/parse birthday-text :json)
            mutation (sd/mutation db source)]
  (sd/explain (sd/run mutation nil {:explain? true})))

Result / 389 B

{
  "load_definition": {
    "cpu": 785,
    "wall": 790,
    "arena_bytes": 2320
  },
  "parameters": {
    "cpu": 10,
    "wall": 12,
    "arena_bytes": 0
  },
  "run": {
    "cpu": 9039,
    "wall": 40514,
    "arena_bytes": 43856
  },
  "total": {
    "cpu": 9937,
    "wall": 41433,
    "arena_bytes": 46176
  },
  "arena_capacity": 4194304,
  "stages_completed": 3,
  "attempts": 1
}

C exports: stardust_db_mutation_run, stardust_db_result_commit_info, stardust_result_error, stardust_result_release

close

clojure

8 B

[handle]

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`handle`	`Mutation`	Consumed owner	Required	The mutation owner to release. Do not use it after this call.

Examples

mutation/close

birthday-text holds this document:

json

186 B

{
  "query": {
    "find": [
      "?e"
    ],
    "where": [
      [
        "?e",
        "name",
        "Ada"
      ]
    ]
  },
  "patch": {
    "?e": {
      "age": 37
    }
  }
}

clojure

116 B

(with-open [source (sd/parse birthday-text :json)
            mutation (sd/mutation db source)]
  (sd/run mutation))

Result / 111 B

{
  "status": "committed",
  "transaction": 5,
  "facts": 1,
  "committed_at": 17923367755020813,
  "ids": {}
}

C exports: stardust_db_mutation_release

merge-patch

clojure

10 B

[db patch]

clojure

18 B

[db patch options]

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`patch`	`Document`	Borrowed for the call	Required	An entity-keyed native patch. Temporary names use `#_name`. `#_tx` holds metadata and an optional stardust/checkAndSet map from entity IDs to expected transactions. Positive expectations match exact last-touch transactions; zero requires no current facts. Conditions are consumed and checked atomically, including for no-ops.
`options`	`map`	Value	{}	Binding options map. The :library key selects the loaded native library. Omission uses the binding's default library. Optional explain output. This record contains explain output for `merge_patch`.

Errors

Status	When
`:invalid-commit-time`	the `#_tx` commit time is not later than the last commit
`:conflict`	an entity revision check fails or a concurrent writer prevents the commit; a revision mismatch reports the entity and expected and actual revisions
`:rejected`	the database refuses the patch; the code and diagnostic path name the reason and key
`:unavailable`	the patch sets stardust/history and no enabled plugin purges history
`:invalid-argument`	the patch is not an entity-keyed object, or a link names an ID outside the user entity range
`:closed`	the database is closed
`:out-of-memory`	native memory is exhausted

Notes

Patch documents.

Examples

database/merge_patch

seed-text holds this document:

json

333 B

{
  "#_ada": {
    "name": "Ada",
    "role": "engineer",
    "age": 36
  },
  "#_bob": {
    "name": "Bob",
    "role": "engineer",
    "age": 41,
    "mentor": {
      "#link": "#_ada"
    }
  },
  "#_cy": {
    "name": "Cy",
    "role": "designer",
    "age": 29
  },
  "#_tx": {
    "author": "smoke",
    "reason": "seed"
  }
}

clojure

74 B

(with-open [patch (sd/parse seed-text :json)]
  (sd/merge-patch db patch))

Result / 161 B

{
  "status": "committed",
  "transaction": 4,
  "facts": 12,
  "committed_at": 17923367746573834,
  "ids": {
    "#_ada": 1,
    "#_bob": 2,
    "#_cy": 3
  }
}

Explain patch validation and commit

seed-text holds this document:

json

333 B

{
  "#_ada": {
    "name": "Ada",
    "role": "engineer",
    "age": 36
  },
  "#_bob": {
    "name": "Bob",
    "role": "engineer",
    "age": 41,
    "mentor": {
      "#link": "#_ada"
    }
  },
  "#_cy": {
    "name": "Cy",
    "role": "designer",
    "age": 29
  },
  "#_tx": {
    "author": "smoke",
    "reason": "seed"
  }
}

clojure

104 B

(with-open [patch (sd/parse seed-text :json)]
  (sd/explain (sd/merge-patch db patch {:explain? true})))

Result / 298 B

{
  "copy_patch": {
    "cpu": 12321,
    "wall": 12502,
    "arena_bytes": 3096
  },
  "commit": {
    "cpu": 766,
    "wall": 33672,
    "arena_bytes": 8008
  },
  "total": {
    "cpu": 13252,
    "wall": 46346,
    "arena_bytes": 11118
  },
  "arena_capacity": 4194304,
  "stages_completed": 2
}

Refuse a metadata-only transaction

patch-text holds this document:

json

38 B

{
  "#_tx": {
    "author": "x"
  }
}

clojure

75 B

(with-open [patch (sd/parse patch-text :json)]
  (sd/merge-patch db patch))

Result / 199 B

{
  "code": "transaction_only",
  "message": "a patch of only #_tx is refused: #_tx annotates a write",
  "path": "#_tx",
  "field": null,
  "entity": null,
  "offset": null,
  "status": "rejected"
}

Refuse a repeated commit time

future-text holds this document:

json

120 B

{
  "#_d": {
    "x": 1
  },
  "#_tx": {
    "stardust/committedAt": {
      "#utc": "2200-01-01T00:00:00Z"
    }
  }
}

older-text holds this document:

json

120 B

{
  "#_e": {
    "x": 2
  },
  "#_tx": {
    "stardust/committedAt": {
      "#utc": "2200-01-01T00:00:00Z"
    }
  }
}

clojure

152 B

(with-open [future (sd/parse future-text :json)
            older (sd/parse older-text :json)]
  (sd/merge-patch db future)
  (sd/merge-patch db older))

Result / 227 B

{
  "code": "invalid_commit_time",
  "message": "stardust/committedAt must be strictly newer than the latest commit time",
  "path": null,
  "field": null,
  "entity": null,
  "offset": null,
  "status": "invalid_commit_time"
}

C exports: stardust_db_merge_patch, stardust_db_result_commit_info, stardust_result_error, stardust_result_release

indexes-sync

clojure

13 B

[db max-wait]

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`max-wait`	`java.time.Duration`	Value	Required	The maximum wait. Zero checks once.

Errors

Status	When
`:invalid-argument`	`max_wait` is negative
`:timeout`	`max_wait` passed first
`:closed`	the database is closed

Notes

An index that cannot be built does not hold this wait.

Examples

Wait for the exact indexes of the stored queries

clojure

94 B

(sd/indexes-sync db (java.time.Duration/ofSeconds 5))
(sd/definitions db :queries "people/.*")

Result / 22 B

[
  "people/by_role"
]

C exports: stardust_db_indexes_sync

bulk-begin

clojure

4 B

[db]

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.

Errors

Status	When
`:invalid-argument`	a bulk build is already in progress on the database
`:closed`	the database is closed
`:out-of-memory`	native memory is exhausted

Notes

On a database with existing facts, each added patch commits immediately and the summary reports fallback true. Closing the database drops an unfinished build.

Examples

Start a bulk build and drop it

clojure

37 B

(sd/bulk-begin db)
(sd/bulk-abort db)

C exports: stardust_db_bulk_begin

bulk-add

clojure

10 B

[db patch]

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`patch`	`Document`	Borrowed for the call	Required	One borrowed entity-keyed merge-patch document, as `merge_patch` takes it. Temporary names use `#_name` and are scoped to this patch. Transaction metadata uses `#_tx`. The document is borrowed only until the call returns.

Errors

Status	When
`:invalid-argument`	no bulk build is in progress
`:rejected`	the database refuses the patch; the build has failed and later adds report the same status
`:closed`	the database is closed
`:out-of-memory`	native memory is exhausted

Notes

Patches retain add order. Entity and field order within a patch does not matter. Temporary names resolve within one patch. The call waits for space within the build's memory budget. After failure, use finish for its diagnostic or abort for cleanup.

Patch documents.

Examples

Queue patches in commit order

clojure

325 B

;; The first entity of an empty database is 1, so the second patch updates it.
(sd/bulk-begin db)
(with-open [patch (sd/parse "{\"#_ada\":{\"name\":\"Ada\"}}" :json)]
  (sd/bulk-add db patch))
(with-open [patch (sd/parse "{\"1\":{\"title\":\"Countess\"}}" :json)]
  (sd/bulk-add db patch))
(with-open [_ (sd/bulk-finish db)])

C exports: stardust_db_bulk_add

bulk-finish

clojure

4 B

[db]

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.

Errors

Status	When
`:invalid-argument`	no bulk build is in progress
`:rejected`	the database refuses a patch; an initial build publishes nothing and fallback keeps earlier commits
`:conflict`	another write committed to the database during the build
`:closed`	the database is closed
`:out-of-memory`	native memory is exhausted

Notes

Finish ends the build even on failure. An initial build publishes all patches or none. Fallback keeps patches already committed.

The summary contains:

Field	Meaning
status	committed, or `no_change` when nothing was written
patches, transactions, facts, entities	Load counts
firstTransaction, lastTransaction	Assigned transaction range
fallback	Whether patches committed individually
threads	Worker count
tempBytes	Temporary run bytes
memoryBytes, memoryPeakBytes	Reserved memory share and its peak use
phases	parse, assign, rows, updates, spill, build and commit timings, each with wallNs and cpuNs

The memory budget covers build allocations. It excludes operating-system file cache and the process baseline.

Examples

Load patches with one commit and read the summary

clojure

408 B

;; bulk-load does the same for a sequence of patches, aborting on failure.
(sd/bulk-begin db)
(with-open [patch (sd/parse "{\"#_ada\":{\"name\":\"Ada\",\"title\":\"Countess\"}}" :json)]
  (sd/bulk-add db patch))
;; Finish ends the build also when it fails.
(with-open [summary (sd/bulk-finish db)]
  ;; status, patches, transactions, facts, entities and phase timings
  (:transactions (sd/to-value summary)))

C exports: stardust_db_bulk_finish, stardust_result_take_document, stardust_result_error, stardust_result_release

bulk-abort

clojure

4 B

[db]

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.

(sd/bulk-begin db)
(with-open [patch (sd/parse "{\"#_ada\":{\"name\":\"Ada\"}}" :json)]
  (sd/bulk-add db patch))
;; Abort writes nothing; without a build it does nothing.
(sd/bulk-abort db)

C exports: stardust_db_bulk_abort

run_options

This record supplies options for query and mutation run. Zero selects each default. Mutations use DB_Write_Options, whose fields are a subset.

Field	Type	Unit	Range	Meaning
`page_size`	`Count`	Count	Host type range	Rows per page. 0 selects the default page size. Queries only.
`max_cost`	`Duration`	Host duration (100 ns ticks at the ABI)	Tick range	Thread CPU duration limit. 0 selects the engine’s dynamic budget.
`as_of`	`Integer`	None	Host type range	A positive transaction runs a stored definition as of that transaction.

commit

This record contains the result of mutation run, merge_patch and patch_definition.

Field	Type	Unit	Range	Absent	Meaning
`status`	`Commit-Status`	None	Host type range	—	—
`transaction`	`Integer`	None	Host type range	—	Zero when nothing was written.
`facts`	`Integer`	Count	Host type range	—	—
`committed_at`	`Instant`	UTC instant (100 ns ticks since the Unix epoch at the ABI)	Tick range	nil	Recorded commit time as a UTC instant. The call measures this value. Independent calls can differ.
`ids`	`Id-Map`	None	Host type range	—	Maps each `#_name` of a merge patch to its entity ID number. Wrap an ID as {#link id}, or as the typed Link value where the binding has one, to pass it as an entity reference.

event

This record contains the result of subscription next.

Field	Type	Unit	Meaning
`sequence`	`Integer`	Count	Event number. Event 1 is the initial result.
`superseded`	`Integer`	Count	Intermediate computed results skipped by this subscription since its previous event. Zero for its first event. The delivered result replaces them in full. This value counts neither commits nor changed rows.
`transaction`	`Integer`	None	Transaction the result was computed at.
`result`	`Document`	None	The full query result. The event owns it and the consumer closes it.