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"
    ]
  ]
}

python

314 B

async with (await stardust.parse(birthday_text, "json")) as birthday, (await db.mutation(birthday)) as mutation:
    (await mutation.run())
async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, (await query.run()) as rows:
    result = (await rows.all_pages())

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
Database.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.
Database.query	query	Open an owned query from a path or an inline definition.
Database.mutation	mutation	Open an owned mutation from a path or an inline definition.
Query.run	rows	Run the query and return an owned row cursor.
Query.close	none	Release the query handle.
Rows.next	document	Read the next page as an owned document.
Rows.pages	pages	rows.pages() iterates the non-empty pages of the cursor.
Rows.all_pages	document	rows.all_pages() reads every remaining page into one owned array document.
Rows.close	none	Release the rows handle.
Query.subscribe	subscription	query.subscribe(parameters, options) opens an owned live subscription.
Subscription.next	event	Wait for the next live event.
Subscription.events	events	subscription.events() delivers events in order until the subscription is cancelled, closes or fails.
Subscription.cancel	none	subscription.cancel() ends the subscription.
Subscription.close	none	Release the subscription handle.
Mutation.run	commit	Run the mutation and return commit information.
Mutation.close	none	Release the mutation handle.
Database.merge_patch	commit	database.merge_patch(patch) applies an entity-keyed patch document in one transaction and returns commit information.
Database.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.
Database.bulk_begin	none	database.bulk_begin() starts a bulk build of data merge patches held by the database.
Database.bulk_add	none	database.bulk_add(patch) copies and queues one merge-patch document in the bulk build.
Database.bulk_finish	document	database.bulk_finish() publishes the bulk build with one commit, ends it and returns an owned summary document.
Database.bulk_abort	none	database.bulk_abort() drops the bulk build in progress without writing it.

Database.read_entity

python

89 B

def read_entity(self, entity: int, max_depth: int = 0, max_entities: int = 0) -> Document

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`entity`	`int`	Value	Required	The decimal user entity ID.
`max_depth`	`int`	Value	0	Link hops to expand along each path, 0 through 32. 0, the default, leaves every link a {#link id} reference.
`max_entities`	`int`	Value	0	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

python

35 B

result = await db.read_entity(2, 1)

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

Database.query

python

48 B

def query(self, source: str | Document) -> Query

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`source`	`str \| Document`	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"
  ]
}

python

169 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, (await query.run()) as rows:
    result = (await rows.next())

Result / 82 B

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

Refuse an invalid query definition

query_text holds this document:

json

29 B

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

python

210 B

async with (await stardust.parse(query_text, "json")) as definition:
    try:
        async with (await db.query(definition)):
            pass
    except stardust.StardustError as error:
        result = error

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

python

127 B

try:
    async with (await db.query("people/missing")):
        pass
except stardust.StardustError as error:
    result = error

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

Database.mutation

python

54 B

def mutation(self, source: str | Document) -> Mutation

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`source`	`str \| Document`	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
    }
  }
}

python

148 B

async with (await stardust.parse(birthday_text, "json")) as birthday, (await db.mutation(birthday)) as mutation:
    result = (await mutation.run())

Result / 111 B

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

C exports: stardust_db_mutation_open, stardust_db_mutation_error

Query.run

python

251 B

def run(
        self,
        parameters: Document | None = None,
        *,
        page_size: int | None = None,
        max_cost: timedelta | None = None,
        as_of: int | None = None,
        explain: QueryExplain | None = None,
    ) -> Rows

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Query`	Borrowed for the call	Required	The query owner for this operation. Keep it alive during the call.
`parameters`	`Document \| None`	Borrowed for the call	None	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.
`page_size`	`int \| None`	Value	None	—
`max_cost`	`timedelta \| None`	Value	None	—
`as_of`	`int \| None`	Value	None	—
`explain`	`QueryExplain \| None`	Caller-owned output	None	Optional explain output. This record contains explain output for query `run`. The `compile`, `plan`, `execute`, `group` and `order` fields divide the wall time of `run` into stages.

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"
  ]
}

python

169 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, (await query.run()) as rows:
    result = (await rows.next())

Result / 82 B

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

Capture the host duration boundary

boundary_text holds this document:

json

10 B

999999999

query_text holds this document:

json

134 B

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

python

367 B

async with (await stardust.parse(boundary_text, "json")) as boundary:
    days = (await boundary.i64((await boundary.root())))
options = dict(page_size=2, max_cost=timedelta(days=days))
async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, (await query.run(**options)):
    result = stardust.RunOptions(**options)

Result / 69 B

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

Python durations have microsecond resolution

python

77 B

result = stardust.RunOptions(page_size=2, max_cost=timedelta(microseconds=1))

Result / 52 B

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

Explain query execution

query_text holds this document:

json

134 B

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

python

198 B

explain = stardust.QueryExplain()
async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, (await query.run(explain=explain)):
    result = explain

Result / 669 B

{
  "load_definition": {
    "cpu": 1310,
    "wall": 1330,
    "arena_bytes": 1680
  },
  "parameters": {
    "cpu": 0,
    "wall": 0,
    "arena_bytes": 0
  },
  "run": {
    "cpu": 8660,
    "wall": 8680,
    "arena_bytes": 7424
  },
  "total": {
    "cpu": 10020,
    "wall": 10050,
    "arena_bytes": 9104
  },
  "arena_capacity": 4194304,
  "work": 6240,
  "rows": 3,
  "compile": 230,
  "plan": 420,
  "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
}

Python negative durations retain their microsecond precision

python

65 B

result = stardust.RunOptions(max_cost=timedelta(microseconds=-1))

Result / 53 B

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

Run with typed query options

query_text holds this document:

json

134 B

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

python

240 B

options = dict(page_size=2, max_cost=timedelta(seconds=1))
async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, (await query.run(**options)):
    result = stardust.RunOptions(**options)

Result / 58 B

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

C exports: stardust_db_query_run, stardust_db_rows_error

Query.close

python

23 B

def close(self) -> None

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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"
  ]
}

python

169 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, (await query.run()) as rows:
    result = (await rows.next())

Result / 82 B

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

C exports: stardust_db_query_release

Rows.next

python

26 B

def next(self) -> Document

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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"
  ]
}

python

169 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, (await query.run()) as rows:
    result = (await rows.next())

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

Rows.pages

python

37 B

def pages(self) -> Iterator[Document]

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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"
  ]
}

python

216 B

result = 0
async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, \
        (await query.run(page_size=1)) as rows:
    async for page in rows:
        result += 1

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

Rows.all_pages

python

31 B

def all_pages(self) -> Document

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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"
  ]
}

python

174 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, (await query.run()) as rows:
    result = (await rows.all_pages())

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

Rows.close

python

23 B

def close(self) -> None

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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"
  ]
}

python

169 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, (await query.run()) as rows:
    result = (await rows.next())

Result / 82 B

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

C exports: stardust_db_rows_release

python

220 B

def subscribe(
        self,
        parameters: Document | None = None,
        *,
        page_size: int | None = None,
        max_cost: timedelta | None = None,
        as_of: int | None = None,
    ) -> Subscription

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Query`	Borrowed for the call	Required	The query owner for this operation. Keep it alive during the call.
`parameters`	`Document \| None`	Borrowed for the call	None	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.
`page_size`	`int \| None`	Value	None	—
`max_cost`	`timedelta \| None`	Value	None	—
`as_of`	`int \| None`	Value	None	—

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"
  ]
}

python

293 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, \
        (await query.subscribe()) as subscription:
    event = await subscription.next(timedelta(seconds=5))
    if event is None:
        raise TimeoutError
    result = event.result

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"
  ]
}

python

269 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, \
        (await query.subscribe()) as subscription:
    result = await subscription.next(timedelta(seconds=5))
    if result is None:
        raise TimeoutError

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

Subscription.next

python

51 B

def next(self, max_wait: timedelta) -> Event | None

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Subscription`	Borrowed for the call	Required	The subscription owner for this operation. Keep it alive during the call.
`max_wait`	`timedelta`	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"
  ]
}

python

293 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, \
        (await query.subscribe()) as subscription:
    event = await subscription.next(timedelta(seconds=5))
    if event is None:
        raise TimeoutError
    result = event.result

Result / 82 B

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

C exports: stardust_db_subscription_next, stardust_db_subscription_error, stardust_document_release

Subscription.events

python

35 B

def events(self) -> Iterator[Event]

Parameters

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

Errors

Cancellation and closure end iteration. The iteration reports other terminal failures.

Status	When
`"evaluation_failed"`	a rerun of the query failed
`"out_of_memory"`	native memory is exhausted

Notes

The consumer owns each result. Leaving iteration early cancels the subscription. Close the subscription separately.

Examples

subscription/events

query_text holds this document:

json

134 B

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

python

217 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, \
        (await query.subscribe()) as subscription:
    result = (await anext(subscription.events())).result

Result / 82 B

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

C exports: stardust_db_subscription_next, stardust_db_subscription_error

Subscription.cancel

python

24 B

def cancel(self) -> None

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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"
  ]
}

python

327 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, \
        (await query.subscribe()) as subscription:
    event = await subscription.next(timedelta(seconds=5))
    if event is None:
        raise TimeoutError
    (await subscription.cancel())
    result = event.result

Result / 82 B

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

C exports: stardust_db_subscription_cancel

Subscription.close

python

23 B

def close(self) -> None

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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"
  ]
}

python

293 B

async with (await stardust.parse(query_text, "json")) as definition, (await db.query(definition)) as query, \
        (await query.subscribe()) as subscription:
    event = await subscription.next(timedelta(seconds=5))
    if event is None:
        raise TimeoutError
    result = event.result

Result / 82 B

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

C exports: stardust_db_subscription_release

Mutation.run

python

256 B

def run(
        self,
        parameters: Document | None = None,
        *,
        page_size: int | None = None,
        max_cost: timedelta | None = None,
        as_of: int | None = None,
        explain: MutationExplain | None = None,
    ) -> Commit

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Mutation`	Borrowed for the call	Required	The mutation owner for this operation. Keep it alive during the call.
`parameters`	`Document \| None`	Borrowed for the call	None	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.
`page_size`	`int \| None`	Value	None	—
`max_cost`	`timedelta \| None`	Value	None	—
`as_of`	`int \| None`	Value	None	—
`explain`	`MutationExplain \| None`	Caller-owned output	None	Optional explain output. This record contains explain output for mutation `run`.

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
    }
  }
}

python

148 B

async with (await stardust.parse(birthday_text, "json")) as birthday, (await db.mutation(birthday)) as mutation:
    result = (await mutation.run())

Result / 111 B

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

Explain mutation execution

birthday_text holds this document:

json

186 B

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

python

208 B

explain = stardust.MutationExplain()
async with (await stardust.parse(birthday_text, "json")) as birthday, (await db.mutation(birthday)) as mutation:
    (await mutation.run(explain=explain))
result = explain

Result / 392 B

{
  "load_definition": {
    "cpu": 1640,
    "wall": 1650,
    "arena_bytes": 2320
  },
  "parameters": {
    "cpu": 10,
    "wall": 10,
    "arena_bytes": 0
  },
  "run": {
    "cpu": 9920,
    "wall": 34990,
    "arena_bytes": 43856
  },
  "total": {
    "cpu": 11700,
    "wall": 36790,
    "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

Mutation.close

python

23 B

def close(self) -> None

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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
    }
  }
}

python

148 B

async with (await stardust.parse(birthday_text, "json")) as birthday, (await db.mutation(birthday)) as mutation:
    result = (await mutation.run())

Result / 111 B

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

C exports: stardust_db_mutation_release

Database.merge_patch

python

85 B

def merge_patch(self, patch: Document, explain: PatchExplain | None = None) -> Commit

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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.
`explain`	`PatchExplain \| None`	Caller-owned output	None	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"
  }
}

python

103 B

async with (await stardust.parse(seed_text, "json")) as seed:
    result = (await db.merge_patch(seed))

Result / 161 B

{
  "status": "committed",
  "transaction": 4,
  "facts": 12,
  "committed_at": 17923367793334820,
  "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"
  }
}

python

154 B

explain = stardust.PatchExplain()
async with (await stardust.parse(seed_text, "json")) as seed:
    (await db.merge_patch(seed, explain))
result = explain

Result / 295 B

{
  "copy_patch": {
    "cpu": 2030,
    "wall": 2030,
    "arena_bytes": 3096
  },
  "commit": {
    "cpu": 770,
    "wall": 56360,
    "arena_bytes": 8008
  },
  "total": {
    "cpu": 2970,
    "wall": 58560,
    "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"
  }
}

python

177 B

async with (await stardust.parse(patch_text, "json")) as patch:
    try:
        (await db.merge_patch(patch))
    except stardust.StardustError as error:
        result = error

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"
    }
  }
}

patch_text holds this document:

json

120 B

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

python

267 B

async with (await stardust.parse(future_text, "json")) as future, (await stardust.parse(patch_text, "json")) as patch:
    (await db.merge_patch(future))
    try:
        (await db.merge_patch(patch))
    except stardust.StardustError as error:
        result = error

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

Database.indexes_sync

python

51 B

def indexes_sync(self, max_wait: timedelta) -> None

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`max_wait`	`timedelta`	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

python

97 B

await db.indexes_sync(timedelta(seconds=5))
result = await db.definitions("queries", "people/.*")

Result / 22 B

[
  "people/by_role"
]

C exports: stardust_db_indexes_sync

Database.bulk_begin

python

28 B

def bulk_begin(self) -> None

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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

python

43 B

await db.bulk_begin()
await db.bulk_abort()

C exports: stardust_db_bulk_begin

Database.bulk_add

python

43 B

def bulk_add(self, patch: Document) -> None

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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

python

437 B

await db.bulk_begin()
try:
    # The first entity of an empty database is 1, so the second patch updates it.
    async with await stardust.parse('{"#_ada":{"name":"Ada"}}', "json") as patch:
        await db.bulk_add(patch)
    async with await stardust.parse('{"1":{"title":"Countess"}}', "json") as patch:
        await db.bulk_add(patch)
except BaseException:
    await db.bulk_abort()
    raise
await (await db.bulk_finish()).close()

C exports: stardust_db_bulk_add

Database.bulk_finish

python

33 B

def bulk_finish(self) -> Document

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`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

python

441 B

await db.bulk_begin()
try:
    async with await stardust.parse('{"#_ada":{"name":"Ada","title":"Countess"}}', "json") as patch:
        await db.bulk_add(patch)
except BaseException:
    await db.bulk_abort()
    raise
# Finish ends the build also when it fails.
async with await db.bulk_finish() as summary:
    # status, patches, transactions, facts, entities and phase timings
    transactions = (await summary.to_value())["transactions"]

C exports: stardust_db_bulk_finish, stardust_result_take_document, stardust_result_error, stardust_result_release

Database.bulk_abort

python

28 B

def bulk_abort(self) -> None

Parameters

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

await db.bulk_begin()
try:
    async with await stardust.parse('{"#_ada":{"name":"Ada"}}', "json") as patch:
        await db.bulk_add(patch)
finally:
    # Abort writes nothing; without a build it does nothing.
    await db.bulk_abort()

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`	`int`	Count	Host type range	Rows per page. 0 selects the default page size. Queries only.
`max_cost`	`timedelta`	Host duration (100 ns ticks at the ABI)	Tick range	Thread CPU duration limit. 0 selects the engine’s dynamic budget.
`as_of`	`int`	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`	`str`	None	Host type range	—	—
`transaction`	`int`	None	Host type range	—	Zero when nothing was written.
`facts`	`int`	Count	Host type range	—	—
`committed_at`	`datetime \| None`	UTC instant (100 ns ticks since the Unix epoch at the ABI)	Tick range	None	Recorded commit time as a UTC instant. The call measures this value. Independent calls can differ.
`ids`	`dict[str, int] \| None`	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`	`int`	Count	Event number. Event 1 is the initial result.
`superseded`	`int`	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`	`int`	None	Transaction the result was computed at.
`result`	`Document \| None`	None	The full query result. The event owns it and the consumer closes it.