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:

TRON

221 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	2C 3F65	txt "?e"
07	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
14	2C 3F65	txt "?e"
17	4C 6E616D65	txt "name"
1C	3C 416461	txt "Ada"
20	0E 15 00 0700 030000 00 14000000 170000 00 1C000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C
35	0E 0D 00 0100 010000 00 20000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @20
42	5C 7768657265	txt "where"
48	0F 0A 42000000 3500 0000	map leaf, size 10: @42 → @35
52	4C 66696E64	txt "find"
57	0F 0A 52000000 0700 0000	map leaf, size 10: @52 → @7
61	07 0E 0A000000 4800 0000 57000000	map branch, size 14, depth 0 (root), slots 1, 3: @48 → @57
6F	3C 616765	txt "age"
73	02 25000000000000 00	i64 37
7C	0F 0A 6F000000 7300 0000	map leaf, size 10: @6F → @73
86	2C 3F65	txt "?e"
89	0F 0A 86000000 7C00 0000	map leaf, size 10: @86 → @7C
93	5C 7175657279	txt "query"
99	0F 0A 93000000 6100 0000	map leaf, size 10: @93 → @61
A3	5C 7061746368	txt "patch"
A9	0F 0A A3000000 8900 0000	map leaf, size 10: @A3 → @89
B3	07 0E 40020000 9900 0000 A9000000	map branch, size 14, depth 2, slots 6, 9: @99 → @A9
C1	07 0A 01000000 B300 0000	map branch, size 10, depth 1, slots 0: @B3
CB	07 0A 80000000 C100 0000	map branch, size 10, depth 0 (root), slots 7: @C1
D5	CB000000 00000000	root → @CB; previous: none

query_text holds this document:

TRON

158 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 3F616765	txt "?age"
09	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
16	2C 3F65	txt "?e"
19	4C 6E616D65	txt "name"
1E	3C 416461	txt "Ada"
22	0E 15 00 0700 030000 00 16000000 190000 00 1E000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @16 → @19 → @1E
37	2C 3F65	txt "?e"
3A	3C 616765	txt "age"
3E	4C 3F616765	txt "?age"
43	0E 15 00 0700 030000 00 37000000 3A0000 00 3E000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @37 → @3A → @3E
58	0E 11 00 0300 020000 00 22000000 430000 00	array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @22 → @43
69	5C 7768657265	txt "where"
6F	0F 0A 69000000 5800 0000	map leaf, size 10: @69 → @58
79	4C 66696E64	txt "find"
7E	0F 0A 79000000 0900 0000	map leaf, size 10: @79 → @9
88	07 0E 0A000000 6F00 0000 7E000000	map branch, size 14, depth 0 (root), slots 1, 3: @6F → @7E
96	88000000 00000000	root → @88; previous: none

1.5 kB

stardust_document *birthday = NULL;
stardust_document *definition = NULL;
stardust_db_mutation *mutation = NULL;
stardust_result *committed = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_result *page = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_parse(birthday_text, STARDUST_TRON, &birthday);
if (status == STARDUST_OK) status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source change = {.kind = STARDUST_SOURCE_DOCUMENT, .document = birthday};
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_mutation_open(db, &change, &mutation);
if (status == STARDUST_OK) status = stardust_db_mutation_run(mutation, NULL, NULL, NULL, &committed);
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, NULL, NULL, &rows);
if (status == STARDUST_OK) status = stardust_db_rows_next(rows, &page);
if (status == STARDUST_OK) status = stardust_result_take_document(page, &result);
stardust_result_release(page);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_result_release(committed);
stardust_db_mutation_release(mutation);
stardust_document_release(definition);
stardust_document_release(birthday);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

TRON

48 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	3C 616765	txt "age"
08	02 25000000000000 00	i64 37
11	0F 0A 04000000 0800 0000	map leaf, size 10: @4 → @8
1B	0E 0D 00 0100 010000 00 11000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @11
28	1B000000 00000000	root → @1B; previous: none

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
stardust_db_read_entity	Status. document through output	database.read_entity(entity, max_depth, max_entities) atomically returns an owned {document links revisions truncated} document, expanding links up to max_depth hops.
stardust_db_query_open	Status. query through output	Open an owned query from a path or an inline definition.
stardust_db_mutation_open	Status. mutation through output	Open an owned mutation from a path or an inline definition.
stardust_db_query_run	Status. rows through output	Run the query and return an owned row cursor.
stardust_db_query_release	`void`	Release the query handle.
stardust_db_rows_next	Status. document through output	Read the next page as an owned document.
pages	Unavailable	rows.pages() iterates the non-empty pages of the cursor.
all_pages	Unavailable	rows.all_pages() reads every remaining page into one owned array document.
stardust_db_rows_release	`void`	Release the rows handle.
stardust_db_query_subscribe	Status. subscription through output	query.subscribe(parameters, options) opens an owned live subscription.
stardust_db_subscription_next	Status. event through output	Wait for the next live event.
events	Unavailable	subscription.events() delivers events in order until the subscription is cancelled, closes or fails.
stardust_db_subscription_cancel	`void`	subscription.cancel() ends the subscription.
stardust_db_subscription_release	`void`	Release the subscription handle.
stardust_db_mutation_run	Status. commit through output	Run the mutation and return commit information.
stardust_db_mutation_release	`void`	Release the mutation handle.
stardust_db_merge_patch	Status. commit through output	database.merge_patch(patch) applies an entity-keyed patch document in one transaction and returns commit information.
stardust_db_indexes_sync	Status. none through output	database.indexes_sync(max_wait) waits until the database built every exact index that earlier definition commits and inline runs ask for.
stardust_db_bulk_begin	Status. none through output	database.bulk_begin() starts a bulk build of data merge patches held by the database.
stardust_db_bulk_add	Status. none through output	database.bulk_add(patch) copies and queues one merge-patch document in the bulk build.
stardust_db_bulk_finish	Status. document through output	database.bulk_finish() publishes the bulk build with one commit, ends it and returns an owned summary document.
stardust_db_bulk_abort	`void`	database.bulk_abort() drops the bulk build in progress without writing it.
stardust_db_subscription_set_notify	status	Wake a host scheduler when a subscription may be ready.

stardust_db_read_entity

133 B

uint32_t stardust_db_read_entity(stardust_db *db, int64_t entity, int64_t max_depth, int64_t max_entities, stardust_result **output);

92 B

uint32_t stardust_result_take_document(stardust_result *result, stardust_document **output);

96 B

uint32_t stardust_result_error(const stardust_result *result, stardust_diagnostic_view *output);

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_db_read_entity

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`entity`	`int64_t`	Value	Required	The decimal user entity ID.
`max_depth`	`int64_t`	Value	Required	Link hops to expand along each path, 0 through 32. 0, the default, leaves every link a {#link id} reference.
`max_entities`	`int64_t`	Value	Required	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.
`output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_take_document

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_document **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_error

Parameter	Type	Ownership	Default	Meaning
`result`	`const stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_result_release

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	the entity ID is outside the user entity range, `max_depth` is negative or above 32, or `max_entities` is negative
`STARDUST_CLOSED`	the database is closed
`STARDUST_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

330 B

stardust_document *result = NULL;
stardust_result *outcome = NULL;
uint32_t status = stardust_db_read_entity(db, 2, 1, 0, &outcome);
if (status == STARDUST_OK) status = stardust_result_take_document(outcome, &result);
stardust_result_release(outcome);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

TRON

408 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	3C 616765	txt "age"
008	02 24000000000000 00	i64 36
011	0F 0A 04000000 0800 0000	map leaf, size 10: @4 → @8
01B	4C 726F6C65	txt "role"
020	8C 656E67696E6565 72	txt "engineer"
029	0F 0A 1B000000 2000 0000	map leaf, size 10: @1B → @20
033	4C 6E616D65	txt "name"
038	3C 416461	txt "Ada"
03C	0F 0A 33000000 3800 0000	map leaf, size 10: @33 → @38
046	07 12 00910000 1100 0000 29000000 3C00 0000	map branch, size 18, depth 0 (root), slots 8, 12, 15: @11 → @29 → @3C
058	3C 616765	txt "age"
05C	02 29000000000000 00	i64 41
065	0F 0A 58000000 5C00 0000	map leaf, size 10: @58 → @5C
06F	6C 6D656E746F72	txt "mentor"
076	0F 0A 6F000000 4600 0000	map leaf, size 10: @6F → @46
080	4C 726F6C65	txt "role"
085	8C 656E67696E6565 72	txt "engineer"
08E	0F 0A 80000000 8500 0000	map leaf, size 10: @80 → @85
098	4C 6E616D65	txt "name"
09D	3C 426F62	txt "Bob"
0A1	0F 0A 98000000 9D00 0000	map leaf, size 10: @98 → @9D
0AB	07 16 00990000 6500 0000 76000000 8E00 0000 A1000000	map branch, size 22, depth 0 (root), slots 8, 11, 12, 15: @65 → @76 → @8E → @A1
0C1	5C 236C696E6B	txt "#link"
0C7	02 01000000000000 00	i64 1
0D0	0F 0A C1000000 C700 0000	map leaf, size 10: @C1 → @C7
0DA	7C 2F6D656E746F72	txt "/mentor"
0E2	0F 0A DA000000 D000 0000	map leaf, size 10: @DA → @D0
0EC	1C 31	txt "1"
0EE	02 04000000000000 00	i64 4
0F7	0F 0A EC000000 EE00 0000	map leaf, size 10: @EC → @EE
101	1C 32	txt "2"
103	02 04000000000000 00	i64 4
10C	0F 0A 01010000 0301 0000	map leaf, size 10: @101 → @103
116	07 0E 14000000 F700 0000 0C010000	map branch, size 14, depth 0 (root), slots 2, 4: @F7 → @10C
124	9C 7472756E636174 6564	txt "truncated"
12E	01	bit false
12F	0F 0A 24010000 2E01 0000	map leaf, size 10: @124 → @12E
139	8C 646F63756D656E 74	txt "document"
142	0F 0A 39010000 AB00 0000	map leaf, size 10: @139 → @AB
14C	5C 6C696E6B73	txt "links"
152	0F 0A 4C010000 E200 0000	map leaf, size 10: @14C → @E2
15C	07 0E 20100000 4201 0000 52010000	map branch, size 14, depth 1, slots 5, 12: @142 → @152
16A	9C 7265766973696F 6E73	txt "revisions"
174	0F 0A 6A010000 1601 0000	map leaf, size 10: @16A → @116
17E	07 12 82200000 2F01 0000 5C010000 7401 0000	map branch, size 18, depth 0 (root), slots 1, 7, 13: @12F → @15C → @174
190	7E010000 00000000	root → @17E; previous: none

Also calls: stardust_result_take_document, stardust_result_error, stardust_result_release

stardust_db_query_open

111 B

uint32_t stardust_db_query_open(stardust_db *db, const stardust_db_source *source, stardust_db_query **output);

100 B

uint32_t stardust_db_query_error(const stardust_db_query *handle, stardust_diagnostic_view *output);

Parameters

stardust_db_query_open

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`source`	`const stardust_db_source *`	Borrowed input	Required	An inline native definition or a stored definition path.
`output`	`stardust_db_query **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_db_query_error

Parameter	Type	Ownership	Default	Meaning
`handle`	`const stardust_db_query *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_NOT_FOUND`	no definition is stored at the path
`STARDUST_INVALID_DEFINITION`	the definition is invalid
`STARDUST_CLOSED`	the database is closed
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

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:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

868 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_result *page = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, NULL, NULL, &rows);
if (status == STARDUST_OK) status = stardust_db_rows_next(rows, &page);
if (status == STARDUST_OK) status = stardust_result_take_document(page, &result);
stardust_result_release(page);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

TRON

89 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	3C000000 00000000	root → @3C; previous: none

Refuse an invalid query definition

definition_text holds this document:

TRON

43 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	2C 3F78	txt "?x"
07	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
14	4C 66696E64	txt "find"
19	0F 0A 14000000 0700 0000	map leaf, size 10: @14 → @7
23	19000000 00000000	root → @19; previous: none

496 B

stardust_document *definition = NULL;
uint32_t status = stardust_parse(definition_text, STARDUST_TRON, &definition);
if (status != STARDUST_OK) {stardust_document_release(definition); return status;}
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
stardust_db_query *failed = NULL;
status = stardust_db_query_open(db, &source, &failed);
stardust_document_release(definition);
stardust_diagnostic_view result = {0};
stardust_db_query_error(failed, &result);

TRON

231 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	14 12 696E76616C69 645F646566696E69 74696F6E	txt "invalid_definition"
1F	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
29	6C 656E74697479	txt "entity"
30	00	nil
31	0F 0A 29000000 3000 0000	map leaf, size 10: @29 → @30
3B	7C 6D657373616765	txt "message"
43	14 10 556E626F756E 645F566172696162 6C65	txt "Unbound_Variable"
55	0F 0A 3B000000 4300 0000	map leaf, size 10: @3B → @43
5F	07 0E 08020000 3100 0000 55000000	map branch, size 14, depth 1, slots 3, 9: @31 → @55
6D	4C 70617468	txt "path"
72	00	nil
73	0F 0A 6D000000 7200 0000	map leaf, size 10: @6D → @72
7D	5C 6669656C64	txt "field"
83	00	nil
84	0F 0A 7D000000 8300 0000	map leaf, size 10: @7D → @83
8E	4C 636F6465	txt "code"
93	14 10 756E626F756E 645F766172696162 6C65	txt "unbound_variable"
A5	0F 0A 8E000000 9300 0000	map leaf, size 10: @8E → @93
AF	6C 6F6666736574	txt "offset"
B6	00	nil
B7	0F 0A AF000000 B600 0000	map leaf, size 10: @AF → @B6
C1	07 1E 51620000 1F00 0000 5F000000 7300 0000 84000000 A500 0000 B7000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @1F → @5F → @73 → @84 → @A5 → @B7
DF	C1000000 00000000	root → @C1; previous: none

Report a missing stored query

287 B

stardust_db_source source = {.kind = STARDUST_SOURCE_PATH, .path = {(const uint8_t *)"people/missing", 14}};
stardust_db_query *failed = NULL;
uint32_t status = stardust_db_query_open(db, &source, &failed);
stardust_diagnostic_view result = {0};
stardust_db_query_error(failed, &result);

TRON

237 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	9C 6E6F745F666F75 6E64	txt "not_found"
15	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
1F	6C 656E74697479	txt "entity"
26	00	nil
27	0F 0A 1F000000 2600 0000	map leaf, size 10: @1F → @26
31	7C 6D657373616765	txt "message"
39	14 1A 6E6F20646566 696E6974696F6E20 6174207468697320 70617468	txt "no definition at this pa…"
55	0F 0A 31000000 3900 0000	map leaf, size 10: @31 → @39
5F	07 0E 08020000 2700 0000 55000000	map branch, size 14, depth 1, slots 3, 9: @27 → @55
6D	4C 70617468	txt "path"
72	EC 70656F706C652F 6D697373696E67	txt "people/missing"
81	0F 0A 6D000000 7200 0000	map leaf, size 10: @6D → @72
8B	5C 6669656C64	txt "field"
91	00	nil
92	0F 0A 8B000000 9100 0000	map leaf, size 10: @8B → @91
9C	4C 636F6465	txt "code"
A1	9C 6E6F745F666F75 6E64	txt "not_found"
AB	0F 0A 9C000000 A100 0000	map leaf, size 10: @9C → @A1
B5	6C 6F6666736574	txt "offset"
BC	00	nil
BD	0F 0A B5000000 BC00 0000	map leaf, size 10: @B5 → @BC
C7	07 1E 51620000 1500 0000 5F000000 8100 0000 92000000 AB00 0000 BD000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @15 → @5F → @81 → @92 → @AB → @BD
E5	C7000000 00000000	root → @C7; previous: none

Also calls: stardust_db_query_error

stardust_db_mutation_open

117 B

uint32_t stardust_db_mutation_open(stardust_db *db, const stardust_db_source *source, stardust_db_mutation **output);

106 B

uint32_t stardust_db_mutation_error(const stardust_db_mutation *handle, stardust_diagnostic_view *output);

Parameters

stardust_db_mutation_open

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`source`	`const stardust_db_source *`	Borrowed input	Required	An inline native definition or a stored definition path.
`output`	`stardust_db_mutation **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_db_mutation_error

Parameter	Type	Ownership	Default	Meaning
`handle`	`const stardust_db_mutation *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_NOT_FOUND`	no definition is stored at the path
`STARDUST_INVALID_DEFINITION`	the definition is invalid
`STARDUST_CLOSED`	the database is closed
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

Notes

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

Mutation documents.

Examples

database/mutation

birthday_text holds this document:

TRON

221 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	2C 3F65	txt "?e"
07	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
14	2C 3F65	txt "?e"
17	4C 6E616D65	txt "name"
1C	3C 416461	txt "Ada"
20	0E 15 00 0700 030000 00 14000000 170000 00 1C000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C
35	0E 0D 00 0100 010000 00 20000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @20
42	5C 7768657265	txt "where"
48	0F 0A 42000000 3500 0000	map leaf, size 10: @42 → @35
52	4C 66696E64	txt "find"
57	0F 0A 52000000 0700 0000	map leaf, size 10: @52 → @7
61	07 0E 0A000000 4800 0000 57000000	map branch, size 14, depth 0 (root), slots 1, 3: @48 → @57
6F	3C 616765	txt "age"
73	02 25000000000000 00	i64 37
7C	0F 0A 6F000000 7300 0000	map leaf, size 10: @6F → @73
86	2C 3F65	txt "?e"
89	0F 0A 86000000 7C00 0000	map leaf, size 10: @86 → @7C
93	5C 7175657279	txt "query"
99	0F 0A 93000000 6100 0000	map leaf, size 10: @93 → @61
A3	5C 7061746368	txt "patch"
A9	0F 0A A3000000 8900 0000	map leaf, size 10: @A3 → @89
B3	07 0E 40020000 9900 0000 A9000000	map branch, size 14, depth 2, slots 6, 9: @99 → @A9
C1	07 0A 01000000 B300 0000	map branch, size 10, depth 1, slots 0: @B3
CB	07 0A 80000000 C100 0000	map branch, size 10, depth 0 (root), slots 7: @C1
D5	CB000000 00000000	root → @CB; previous: none

615 B

stardust_document *definition = NULL;
stardust_db_mutation *mutation = NULL;
stardust_result *result = NULL;
uint32_t status = stardust_parse(birthday_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_mutation_open(db, &source, &mutation);
if (status == STARDUST_OK) status = stardust_db_mutation_run(mutation, NULL, NULL, NULL, &result);
stardust_db_mutation_release(mutation);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_result_release(result); return status;}

TRON

179 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	0F 02	map leaf, size 2
06	3C 696473	txt "ids"
0A	0F 0A 06000000 0400 0000	map leaf, size 10: @6 → @4
14	6C 737461747573	txt "status"
1B	9C 636F6D6D697474 6564	txt "committed"
25	0F 0A 14000000 1B00 0000	map leaf, size 10: @14 → @1B
2F	07 0E 02040000 0A00 0000 25000000	map branch, size 14, depth 1, slots 1, 10: @A → @25
3D	BC 7472616E736163 74696F6E	txt "transaction"
49	02 05000000000000 00	i64 5
52	0F 0A 3D000000 4900 0000	map leaf, size 10: @3D → @49
5C	CC 636F6D6D697474 65645F6174	txt "committed_at"
69	02 3F9FB74A35AD3F 00	i64 17923367931191103
72	0F 0A 5C000000 6900 0000	map leaf, size 10: @5C → @69
7C	5C 6661637473	txt "facts"
82	02 01000000000000 00	i64 1
8B	0F 0A 7C000000 8200 0000	map leaf, size 10: @7C → @82
95	07 16 01460000 2F00 0000 52000000 7200 0000 8B000000	map branch, size 22, depth 0 (root), slots 0, 9, 10, 14: @2F → @52 → @72 → @8B
AB	95000000 00000000	root → @95; previous: none

Also calls: stardust_db_mutation_error

stardust_db_query_run

206 B

uint32_t stardust_db_query_run(stardust_db_query *query_handle, const stardust_document *parameters, const stardust_db_query_options *options, stardust_db_query_explain *explain, stardust_db_rows **output);

96 B

uint32_t stardust_db_rows_error(const stardust_db_rows *rows, stardust_diagnostic_view *output);

Parameters

stardust_db_query_run

Parameter	Type	Ownership	Default	Meaning
`query_handle`	`stardust_db_query *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`parameters`	`const stardust_document *`	Borrowed handle	NULL	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`	`const stardust_db_query_options *`	Borrowed input	NULL	The operation's options record. See its field defaults.
`explain`	`stardust_db_query_explain *`	Caller-owned output	NULL	Receives a record. Its pointer fields follow the record's ownership contract.
`output`	`stardust_db_rows **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_db_rows_error

Parameter	Type	Ownership	Default	Meaning
`rows`	`const stardust_db_rows *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_NOT_FOUND`	the stored query definition was deleted
`STARDUST_INVALID_DEFINITION`	the loaded query definition is invalid
`STARDUST_INVALID_ARGUMENT`	the parameters or run options are invalid
`STARDUST_EVALUATION_FAILED`	the query fails or exceeds `max_cost`
`STARDUST_CLOSED`	the parent database is closed
`STARDUST_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:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

868 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_result *page = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, NULL, NULL, &rows);
if (status == STARDUST_OK) status = stardust_db_rows_next(rows, &page);
if (status == STARDUST_OK) status = stardust_result_take_document(page, &result);
stardust_result_release(page);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

TRON

89 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	3C000000 00000000	root → @3C; previous: none

Capture the host duration boundary

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

boundary_text holds this document:

TRON

21 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	02 FFFFFFFFFFFFFF 7F	i64 9223372036854775807
0D	04000000 00000000	root → @4; previous: none

1.1 kB

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_document *boundary = NULL;
uint32_t boundary_root = 0;
int64_t ticks = 0;
uint32_t status = stardust_parse(boundary_text, STARDUST_TRON, &boundary);
if (status == STARDUST_OK) status = stardust_document_root(boundary, &boundary_root);
if (status == STARDUST_OK) status = stardust_document_i64(boundary, boundary_root, &ticks);
stardust_document_release(boundary);
if (status == STARDUST_OK) status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
stardust_db_query_options result = {.size=sizeof(result), .version=1, .page_size=2, .max_cost_ticks=ticks};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, &result, NULL, &rows);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) return status;

TRON

112 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	8C 6D61785F636F73 74	txt "max_cost"
0D	02 FFFFFFFFFFFFFF 7F	i64 9223372036854775807
16	0F 0A 04000000 0D00 0000	map leaf, size 10: @4 → @D
20	5C 61735F6F66	txt "as_of"
26	02 00000000000000 00	i64 0
2F	0F 0A 20000000 2600 0000	map leaf, size 10: @20 → @26
39	9C 706167655F7369 7A65	txt "page_size"
43	02 02000000000000 00	i64 2
4C	0F 0A 39000000 4300 0000	map leaf, size 10: @39 → @43
56	07 12 28200000 1600 0000 2F000000 4C00 0000	map branch, size 18, depth 0 (root), slots 3, 5, 13: @16 → @2F → @4C
68	56000000 00000000	root → @56; previous: none

The C ABI takes complete 100-ns ticks

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

532 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
stardust_db_query_options result = {.size=sizeof(result), .version=1, .page_size=2, .max_cost_ticks=1};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) return status;

TRON

112 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	8C 6D61785F636F73 74	txt "max_cost"
0D	02 01000000000000 00	i64 1
16	0F 0A 04000000 0D00 0000	map leaf, size 10: @4 → @D
20	5C 61735F6F66	txt "as_of"
26	02 00000000000000 00	i64 0
2F	0F 0A 20000000 2600 0000	map leaf, size 10: @20 → @26
39	9C 706167655F7369 7A65	txt "page_size"
43	02 02000000000000 00	i64 2
4C	0F 0A 39000000 4300 0000	map leaf, size 10: @39 → @43
56	07 12 28200000 1600 0000 2F000000 4C00 0000	map branch, size 18, depth 0 (root), slots 3, 5, 13: @16 → @2F → @4C
68	56000000 00000000	root → @56; previous: none

Explain query execution

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

671 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_db_query_explain explain = {0};
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, NULL, &explain, &rows);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) return status;
stardust_db_query_explain result = explain;

TRON

1.1 kB

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	BC 6172656E615F62 79746573	txt "arena_bytes"
010	02 90060000000000 00	i64 1680
019	0F 0A 04000000 1000 0000	map leaf, size 10: @4 → @10
023	3C 637075	txt "cpu"
027	02 AB020000000000 00	i64 683
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 B8020000000000 00	i64 696
048	0F 0A 3A000000 3F00 0000	map leaf, size 10: @3A → @3F
052	07 12 21800000 1900 0000 30000000 4800 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @19 → @30 → @48
064	BC 6172656E615F62 79746573	txt "arena_bytes"
070	02 00000000000000 00	i64 0
079	0F 0A 64000000 7000 0000	map leaf, size 10: @64 → @70
083	3C 637075	txt "cpu"
087	02 08000000000000 00	i64 8
090	0F 0A 83000000 8700 0000	map leaf, size 10: @83 → @87
09A	4C 77616C6C	txt "wall"
09F	02 0A000000000000 00	i64 10
0A8	0F 0A 9A000000 9F00 0000	map leaf, size 10: @9A → @9F
0B2	07 12 21800000 7900 0000 90000000 A800 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @79 → @90 → @A8
0C4	BC 6172656E615F62 79746573	txt "arena_bytes"
0D0	02 001D0000000000 00	i64 7424
0D9	0F 0A C4000000 D000 0000	map leaf, size 10: @C4 → @D0
0E3	3C 637075	txt "cpu"
0E7	02 8D1F0000000000 00	i64 8077
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 D81F0000000000 00	i64 8152
108	0F 0A FA000000 FF00 0000	map leaf, size 10: @FA → @FF
112	07 12 21800000 D900 0000 F0000000 0801 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @D9 → @F0 → @108
124	BC 6172656E615F62 79746573	txt "arena_bytes"

Show all 106 nodes

Offset (hex)	Bytes (hex)	Meaning
130	02 90230000000000 00	i64 9104
139	0F 0A 24010000 3001 0000	map leaf, size 10: @124 → @130
143	3C 637075	txt "cpu"
147	02 5B220000000000 00	i64 8795
150	0F 0A 43010000 4701 0000	map leaf, size 10: @143 → @147
15A	4C 77616C6C	txt "wall"
15F	02 B4220000000000 00	i64 8884
168	0F 0A 5A010000 5F01 0000	map leaf, size 10: @15A → @15F
172	07 12 21800000 3901 0000 50010000 6801 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @139 → @150 → @168
184	7C 65786563757465	txt "execute"
18C	02 00000000000000 00	i64 0
195	0F 0A 84010000 8C01 0000	map leaf, size 10: @184 → @18C
19F	4C 726F7773	txt "rows"
1A4	02 03000000000000 00	i64 3
1AD	0F 0A 9F010000 A401 0000	map leaf, size 10: @19F → @1A4
1B7	4C 706C616E	txt "plan"
1BC	02 B3010000000000 00	i64 435
1C5	0F 0A B7010000 BC01 0000	map leaf, size 10: @1B7 → @1BC
1CF	3C 72756E	txt "run"
1D3	0F 0A CF010000 1201 0000	map leaf, size 10: @1CF → @112
1DD	07 12 01840000 AD01 0000 C5010000 D301 0000	map branch, size 18, depth 1, slots 0, 10, 15: @1AD → @1C5 → @1D3
1EF	5C 67726F7570	txt "group"
1F5	02 00000000000000 00	i64 0
1FE	0F 0A EF010000 F501 0000	map leaf, size 10: @1EF → @1F5
208	7C 636F6D70696C65	txt "compile"
210	02 FE000000000000 00	i64 254
219	0F 0A 08020000 1002 0000	map leaf, size 10: @208 → @210
223	AC 706172616D6574 657273	txt "parameters"
22E	0F 0A 23020000 B200 0000	map leaf, size 10: @223 → @B2
238	14 10 737461676573 5F636F6D706C6574 6564	txt "stages_completed"
24A	02 03000000000000 00	i64 3
253	0F 0A 38020000 4A02 0000	map leaf, size 10: @238 → @24A
25D	5C 6F72646572	txt "order"
263	02 00000000000000 00	i64 0
26C	0F 0A 5D020000 6302 0000	map leaf, size 10: @25D → @263
276	07 0E C0000000 5302 0000 6C020000	map branch, size 14, depth 1, slots 6, 7: @253 → @26C
284	EC 6172656E615F63 61706163697479	txt "arena_capacity"
293	02 00004000000000 00	i64 4194304
29C	0F 0A 84020000 9302 0000	map leaf, size 10: @284 → @293
2A6	14 11 627564676574 5F757365645F6279 746573	txt "budget_used_bytes"
2B9	02 D2270000000000 00	i64 10194
2C2	0F 0A A6020000 B902 0000	map leaf, size 10: @2A6 → @2B9
2CC	07 0E 24000000 9C02 0000 C2020000	map branch, size 14, depth 1, slots 2, 5: @29C → @2C2
2DA	FC 6275646765745F 7265667573616C73	txt "budget_refusals"
2EA	02 00000000000000 00	i64 0
2F3	0F 0A DA020000 EA02 0000	map leaf, size 10: @2DA → @2EA
2FD	4C 776F726B	txt "work"
302	02 32140000000000 00	i64 5170
30B	0F 0A FD020000 0203 0000	map leaf, size 10: @2FD → @302
315	07 0E 88000000 F302 0000 0B030000	map branch, size 14, depth 1, slots 3, 7: @2F3 → @30B
323	FC 6D656D6F72795F 7265667573616C73	txt "memory_refusals"
333	02 00000000000000 00	i64 0
33C	0F 0A 23030000 3303 0000	map leaf, size 10: @323 → @333
346	CC 6275646765745F 6279746573	txt "budget_bytes"
353	02 00823E71020000 00	i64 10489856512
35C	0F 0A 46030000 5303 0000	map leaf, size 10: @346 → @353
366	5C 746F74616C	txt "total"
36C	0F 0A 66030000 7201 0000	map leaf, size 10: @366 → @172
376	14 11 627564676574 5F7065616B5F6279 746573	txt "budget_peak_bytes"
389	02 BB370000000000 00	i64 14267
392	0F 0A 76030000 8903 0000	map leaf, size 10: @376 → @389
39C	07 16 13040000 3C03 0000 5C030000 6C03 0000 92030000	map branch, size 22, depth 1, slots 0, 1, 4, 10: @33C → @35C → @36C → @392
3B2	5C 7265747279	txt "retry"
3B8	02 00000000000000 00	i64 0
3C1	0F 0A B2030000 B803 0000	map leaf, size 10: @3B2 → @3B8
3CB	7C 72657472696573	txt "retries"
3D3	02 00000000000000 00	i64 0
3DC	0F 0A CB030000 D303 0000	map leaf, size 10: @3CB → @3D3
3E6	CC 6D656D6F72795F 6279746573	txt "memory_bytes"
3F3	02 6B170000000000 00	i64 5995
3FC	0F 0A E6030000 F303 0000	map leaf, size 10: @3E6 → @3F3
406	FC 6C6F61645F6465 66696E6974696F6E	txt "load_definition"
416	0F 0A 06040000 5200 0000	map leaf, size 10: @406 → @52
420	07 0E 01100000 FC03 0000 16040000	map branch, size 14, depth 1, slots 0, 12: @3FC → @416
42E	07 36 FBDA0000 9501 0000 DD010000 FE01 0000 19020000 2E02 0000 76020000 CC02 0000 15030000 9C03 0000 C1030000 DC03 0000 20040000	map branch, size 54, depth 0 (root), slots 0, 1, 3, 4, 5, 6, 7, 9, 11, 12, 14, 15: @195 → @1DD → @1FE → @219 → @22E → @276 → @2CC → @315 → @39C → @3C1 → @3DC → @420

Offset (hex)	Bytes (hex)	Meaning
464	2E040000 00000000	root → @42E; previous: none

A negative configured duration is not an absent field

90 B

stardust_db_query_options result = {.size=sizeof(result), .version=1, .max_cost_ticks=-1};

TRON

112 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	8C 6D61785F636F73 74	txt "max_cost"
0D	02 FFFFFFFFFFFFFF FF	i64 -1
16	0F 0A 04000000 0D00 0000	map leaf, size 10: @4 → @D
20	5C 61735F6F66	txt "as_of"
26	02 00000000000000 00	i64 0
2F	0F 0A 20000000 2600 0000	map leaf, size 10: @20 → @26
39	9C 706167655F7369 7A65	txt "page_size"
43	02 00000000000000 00	i64 0
4C	0F 0A 39000000 4300 0000	map leaf, size 10: @39 → @43
56	07 12 28200000 1600 0000 2F000000 4C00 0000	map branch, size 18, depth 0 (root), slots 3, 5, 13: @16 → @2F → @4C
68	56000000 00000000	root → @56; previous: none

Run with typed query options

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

713 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
stardust_db_query_options result = {.size=sizeof(result), .version=1, .page_size=2, .max_cost_ticks=STARDUST_TICKS_PER_SECOND};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, &result, NULL, &rows);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) return status;

TRON

112 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	8C 6D61785F636F73 74	txt "max_cost"
0D	02 80969800000000 00	i64 10000000
16	0F 0A 04000000 0D00 0000	map leaf, size 10: @4 → @D
20	5C 61735F6F66	txt "as_of"
26	02 00000000000000 00	i64 0
2F	0F 0A 20000000 2600 0000	map leaf, size 10: @20 → @26
39	9C 706167655F7369 7A65	txt "page_size"
43	02 02000000000000 00	i64 2
4C	0F 0A 39000000 4300 0000	map leaf, size 10: @39 → @43
56	07 12 28200000 1600 0000 2F000000 4C00 0000	map branch, size 18, depth 0 (root), slots 3, 5, 13: @16 → @2F → @4C
68	56000000 00000000	root → @56; previous: none

Also calls: stardust_db_rows_error

stardust_db_query_release

64 B

void stardust_db_query_release(stardust_db_query *query_handle);

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`query_handle`	`stardust_db_query *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Examples

Open an inline query and read its first page

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

868 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_result *page = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, NULL, NULL, &rows);
if (status == STARDUST_OK) status = stardust_db_rows_next(rows, &page);
if (status == STARDUST_OK) status = stardust_result_take_document(page, &result);
stardust_result_release(page);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

TRON

89 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	3C000000 00000000	root → @3C; previous: none

stardust_db_rows_next

79 B

uint32_t stardust_db_rows_next(stardust_db_rows *rows, stardust_result **page);

92 B

uint32_t stardust_result_take_document(stardust_result *result, stardust_document **output);

96 B

uint32_t stardust_result_error(const stardust_result *result, stardust_diagnostic_view *output);

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_db_rows_next

Parameter	Type	Ownership	Default	Meaning
`rows`	`stardust_db_rows *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`page`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_take_document

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_document **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_error

Parameter	Type	Ownership	Default	Meaning
`result`	`const stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_result_release

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Errors

Status	When
`STARDUST_EVALUATION_FAILED`	the page does not render
`STARDUST_CLOSED`	the parent database is closed
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

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:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

868 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_result *page = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, NULL, NULL, &rows);
if (status == STARDUST_OK) status = stardust_db_rows_next(rows, &page);
if (status == STARDUST_OK) status = stardust_result_take_document(page, &result);
stardust_result_release(page);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

TRON

89 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	3C000000 00000000	root → @3C; previous: none

Also calls: stardust_result_take_document, stardust_result_error, stardust_result_release

pages

Call stardust_db_rows_next until a page root has no first child.

Also calls: 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

Copy each page's rows into one stardust_document_builder_add_many array.

Also calls: 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

stardust_db_rows_release

54 B

void stardust_db_rows_release(stardust_db_rows *rows);

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`rows`	`stardust_db_rows *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Examples

Open an inline query and read its first page

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

868 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_result *page = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, NULL, NULL, &rows);
if (status == STARDUST_OK) status = stardust_db_rows_next(rows, &page);
if (status == STARDUST_OK) status = stardust_result_take_document(page, &result);
stardust_result_release(page);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

TRON

89 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	3C000000 00000000	root → @3C; previous: none

184 B

uint32_t stardust_db_query_subscribe(stardust_db_query *query_handle, const stardust_document *parameters, const stardust_db_query_options *options, stardust_db_subscription **output);

111 B

uint32_t stardust_db_subscription_error(const stardust_db_subscription *sub, stardust_diagnostic_view *output);

Parameters

Parameter	Type	Ownership	Default	Meaning
`query_handle`	`stardust_db_query *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`parameters`	`const stardust_document *`	Borrowed handle	NULL	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`	`const stardust_db_query_options *`	Borrowed input	NULL	The operation's options record. See its field defaults.
`output`	`stardust_db_subscription **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_db_subscription_error

Parameter	Type	Ownership	Default	Meaning
`sub`	`const stardust_db_subscription *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

Errors

Status	When
`STARDUST_INVALID_DEFINITION`	the query or its callable definitions are invalid
`STARDUST_INVALID_ARGUMENT`	the parameters or subscription options are invalid
`STARDUST_CLOSED`	the parent database is closed
`STARDUST_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.

Blocking next works without registration. To wake your scheduler, see Readiness callbacks for registration, waiting and context lifetime.

Query documents.

Examples

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

835 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_subscription *subscription = NULL;
stardust_db_live_event event = {0};
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_subscribe(query, NULL, NULL, &subscription);
if (status == STARDUST_OK) status = stardust_db_subscription_next(subscription, 0, &event);
stardust_db_subscription_release(subscription);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_document_release(event.result); return status;}
stardust_document *result = event.result;

TRON

89 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	3C000000 00000000	root → @3C; previous: none

Read the complete initial subscription event

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

832 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_subscription *subscription = NULL;
stardust_db_live_event event = {0};
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_subscribe(query, NULL, NULL, &subscription);
if (status == STARDUST_OK) status = stardust_db_subscription_next(subscription, 0, &event);
stardust_db_subscription_release(subscription);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_document_release(event.result); return status;}
stardust_db_live_event result = event;

TRON

217 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	AC 73757065727365 646564	txt "superseded"
5C	02 00000000000000 00	i64 0
65	0F 0A 51000000 5C00 0000	map leaf, size 10: @51 → @5C
6F	BC 7472616E736163 74696F6E	txt "transaction"
7B	02 04000000000000 00	i64 4
84	0F 0A 6F000000 7B00 0000	map leaf, size 10: @6F → @7B
8E	6C 726573756C74	txt "result"
95	0F 0A 8E000000 3C00 0000	map leaf, size 10: @8E → @3C
9F	8C 73657175656E63 65	txt "sequence"
A8	02 01000000000000 00	i64 1
B1	0F 0A 9F000000 A800 0000	map leaf, size 10: @9F → @A8
BB	07 16 00330000 6500 0000 84000000 9500 0000 B1000000	map branch, size 22, depth 0 (root), slots 8, 9, 12, 13: @65 → @84 → @95 → @B1
D1	BB000000 00000000	root → @BB; previous: none

Also calls: stardust_db_subscription_error

stardust_db_subscription_next

125 B

uint32_t stardust_db_subscription_next(stardust_db_subscription *sub, int64_t max_wait_ticks, stardust_db_live_event *event);

111 B

uint32_t stardust_db_subscription_error(const stardust_db_subscription *sub, stardust_diagnostic_view *output);

55 B

void stardust_document_release(stardust_document *doc);

Parameters

stardust_db_subscription_next

Parameter	Type	Ownership	Default	Meaning
`sub`	`stardust_db_subscription *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`max_wait_ticks`	`int64_t`	Value	Required	Value passed to the call.
`event`	`stardust_db_live_event *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_db_subscription_error

Parameter	Type	Ownership	Default	Meaning
`sub`	`const stardust_db_subscription *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_document_release

Parameter	Type	Ownership	Default	Meaning
`doc`	`stardust_document *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	`max_wait` is negative
`STARDUST_CANCELLED`	the subscription is cancelled or closed
`STARDUST_EVALUATION_FAILED`	a rerun of the query failed. Every later call reports this failure
`STARDUST_CLOSED`	the parent database is closed
`STARDUST_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:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

835 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_subscription *subscription = NULL;
stardust_db_live_event event = {0};
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_subscribe(query, NULL, NULL, &subscription);
if (status == STARDUST_OK) status = stardust_db_subscription_next(subscription, 0, &event);
stardust_db_subscription_release(subscription);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_document_release(event.result); return status;}
stardust_document *result = event.result;

TRON

89 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	3C000000 00000000	root → @3C; previous: none

Also calls: stardust_db_subscription_error, stardust_document_release

events

Call stardust_db_subscription_next repeatedly.

Also calls: stardust_db_subscription_next, stardust_db_subscription_error

stardust_db_subscription_cancel

68 B

void stardust_db_subscription_cancel(stardust_db_subscription *sub);

Parameters

Parameter	Type	Ownership	Default	Meaning
`sub`	`stardust_db_subscription *`	Borrowed handle	NULL	Keep the handle alive until the call returns.

Notes

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

Examples

subscription/cancel

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

882 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_subscription *subscription = NULL;
stardust_db_live_event event = {0};
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_subscribe(query, NULL, NULL, &subscription);
if (status == STARDUST_OK) status = stardust_db_subscription_next(subscription, 0, &event);
stardust_db_subscription_cancel(subscription);
stardust_db_subscription_release(subscription);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_document_release(event.result); return status;}
stardust_document *result = event.result;

TRON

89 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	3C000000 00000000	root → @3C; previous: none

stardust_db_subscription_release

69 B

void stardust_db_subscription_release(stardust_db_subscription *sub);

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`sub`	`stardust_db_subscription *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Examples

subscription/close

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

835 B

stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_subscription *subscription = NULL;
stardust_db_live_event event = {0};
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_subscribe(query, NULL, NULL, &subscription);
if (status == STARDUST_OK) status = stardust_db_subscription_next(subscription, 0, &event);
stardust_db_subscription_release(subscription);
stardust_db_query_release(query);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_document_release(event.result); return status;}
stardust_document *result = event.result;

TRON

89 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	3C000000 00000000	root → @3C; previous: none

stardust_db_mutation_run

210 B

uint32_t stardust_db_mutation_run(stardust_db_mutation *mutation, const stardust_document *parameters, const stardust_db_write_options *options, stardust_db_mutation_explain *explain, stardust_result **output);

102 B

uint32_t stardust_db_result_commit_info(const stardust_result *result, stardust_db_commit_info *info);

96 B

uint32_t stardust_result_error(const stardust_result *result, stardust_diagnostic_view *output);

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_db_mutation_run

Parameter	Type	Ownership	Default	Meaning
`mutation`	`stardust_db_mutation *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`parameters`	`const stardust_document *`	Borrowed handle	NULL	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`	`const stardust_db_write_options *`	Borrowed input	NULL	The operation's options record. See its field defaults.
`explain`	`stardust_db_mutation_explain *`	Caller-owned output	NULL	Receives a record. Its pointer fields follow the record's ownership contract.
`output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_db_result_commit_info

Parameter	Type	Ownership	Default	Meaning
`result`	`const stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`info`	`stardust_db_commit_info *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_result_error

Parameter	Type	Ownership	Default	Meaning
`result`	`const stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_result_release

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Errors

Status	When
`STARDUST_INVALID_DEFINITION`	the mutation selection or definition is invalid
`STARDUST_INVALID_ARGUMENT`	the parameters or run options are invalid
`STARDUST_SCHEMA_VIOLATION`	the write breaks a schema
`STARDUST_CONFLICT`	concurrent writes prevent the commit
`STARDUST_REJECTED`	a mutation target or write guard refuses the write
`STARDUST_UNAVAILABLE`	the patch sets stardust/history and no enabled plugin purges history
`STARDUST_EVALUATION_FAILED`	the mutation fails
`STARDUST_CLOSED`	the parent database is closed
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted

Notes

Mutation documents.

Examples

mutation/run

birthday_text holds this document:

TRON

221 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	2C 3F65	txt "?e"
07	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
14	2C 3F65	txt "?e"
17	4C 6E616D65	txt "name"
1C	3C 416461	txt "Ada"
20	0E 15 00 0700 030000 00 14000000 170000 00 1C000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C
35	0E 0D 00 0100 010000 00 20000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @20
42	5C 7768657265	txt "where"
48	0F 0A 42000000 3500 0000	map leaf, size 10: @42 → @35
52	4C 66696E64	txt "find"
57	0F 0A 52000000 0700 0000	map leaf, size 10: @52 → @7
61	07 0E 0A000000 4800 0000 57000000	map branch, size 14, depth 0 (root), slots 1, 3: @48 → @57
6F	3C 616765	txt "age"
73	02 25000000000000 00	i64 37
7C	0F 0A 6F000000 7300 0000	map leaf, size 10: @6F → @73
86	2C 3F65	txt "?e"
89	0F 0A 86000000 7C00 0000	map leaf, size 10: @86 → @7C
93	5C 7175657279	txt "query"
99	0F 0A 93000000 6100 0000	map leaf, size 10: @93 → @61
A3	5C 7061746368	txt "patch"
A9	0F 0A A3000000 8900 0000	map leaf, size 10: @A3 → @89
B3	07 0E 40020000 9900 0000 A9000000	map branch, size 14, depth 2, slots 6, 9: @99 → @A9
C1	07 0A 01000000 B300 0000	map branch, size 10, depth 1, slots 0: @B3
CB	07 0A 80000000 C100 0000	map branch, size 10, depth 0 (root), slots 7: @C1
D5	CB000000 00000000	root → @CB; previous: none

615 B

stardust_document *definition = NULL;
stardust_db_mutation *mutation = NULL;
stardust_result *result = NULL;
uint32_t status = stardust_parse(birthday_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_mutation_open(db, &source, &mutation);
if (status == STARDUST_OK) status = stardust_db_mutation_run(mutation, NULL, NULL, NULL, &result);
stardust_db_mutation_release(mutation);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_result_release(result); return status;}

TRON

179 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	0F 02	map leaf, size 2
06	3C 696473	txt "ids"
0A	0F 0A 06000000 0400 0000	map leaf, size 10: @6 → @4
14	6C 737461747573	txt "status"
1B	9C 636F6D6D697474 6564	txt "committed"
25	0F 0A 14000000 1B00 0000	map leaf, size 10: @14 → @1B
2F	07 0E 02040000 0A00 0000 25000000	map branch, size 14, depth 1, slots 1, 10: @A → @25
3D	BC 7472616E736163 74696F6E	txt "transaction"
49	02 05000000000000 00	i64 5
52	0F 0A 3D000000 4900 0000	map leaf, size 10: @3D → @49
5C	CC 636F6D6D697474 65645F6174	txt "committed_at"
69	02 3D9BFF4A35AD3F 00	i64 17923367935908669
72	0F 0A 5C000000 6900 0000	map leaf, size 10: @5C → @69
7C	5C 6661637473	txt "facts"
82	02 01000000000000 00	i64 1
8B	0F 0A 7C000000 8200 0000	map leaf, size 10: @7C → @82
95	07 16 01460000 2F00 0000 52000000 7200 0000 8B000000	map branch, size 22, depth 0 (root), slots 0, 9, 10, 14: @2F → @52 → @72 → @8B
AB	95000000 00000000	root → @95; previous: none

Explain mutation execution

birthday_text holds this document:

TRON

221 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	2C 3F65	txt "?e"
07	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
14	2C 3F65	txt "?e"
17	4C 6E616D65	txt "name"
1C	3C 416461	txt "Ada"
20	0E 15 00 0700 030000 00 14000000 170000 00 1C000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C
35	0E 0D 00 0100 010000 00 20000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @20
42	5C 7768657265	txt "where"
48	0F 0A 42000000 3500 0000	map leaf, size 10: @42 → @35
52	4C 66696E64	txt "find"
57	0F 0A 52000000 0700 0000	map leaf, size 10: @52 → @7
61	07 0E 0A000000 4800 0000 57000000	map branch, size 14, depth 0 (root), slots 1, 3: @48 → @57
6F	3C 616765	txt "age"
73	02 25000000000000 00	i64 37
7C	0F 0A 6F000000 7300 0000	map leaf, size 10: @6F → @73
86	2C 3F65	txt "?e"
89	0F 0A 86000000 7C00 0000	map leaf, size 10: @86 → @7C
93	5C 7175657279	txt "query"
99	0F 0A 93000000 6100 0000	map leaf, size 10: @93 → @61
A3	5C 7061746368	txt "patch"
A9	0F 0A A3000000 8900 0000	map leaf, size 10: @A3 → @89
B3	07 0E 40020000 9900 0000 A9000000	map branch, size 14, depth 2, slots 6, 9: @99 → @A9
C1	07 0A 01000000 B300 0000	map branch, size 10, depth 1, slots 0: @B3
CB	07 0A 80000000 C100 0000	map branch, size 10, depth 0 (root), slots 7: @C1
D5	CB000000 00000000	root → @CB; previous: none

711 B

stardust_document *definition = NULL;
stardust_db_mutation *mutation = NULL;
stardust_result *written = NULL;
stardust_db_mutation_explain explain = {0};
uint32_t status = stardust_parse(birthday_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_mutation_open(db, &source, &mutation);
if (status == STARDUST_OK) status = stardust_db_mutation_run(mutation, NULL, NULL, &explain, &written);
stardust_result_release(written);
stardust_db_mutation_release(mutation);
stardust_document_release(definition);
if (status != STARDUST_OK) return status;
stardust_db_mutation_explain result = explain;

TRON

606 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	BC 6172656E615F62 79746573	txt "arena_bytes"
010	02 10090000000000 00	i64 2320
019	0F 0A 04000000 1000 0000	map leaf, size 10: @4 → @10
023	3C 637075	txt "cpu"
027	02 C7030000000000 00	i64 967
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 CE030000000000 00	i64 974
048	0F 0A 3A000000 3F00 0000	map leaf, size 10: @3A → @3F
052	07 12 21800000 1900 0000 30000000 4800 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @19 → @30 → @48
064	BC 6172656E615F62 79746573	txt "arena_bytes"
070	02 00000000000000 00	i64 0
079	0F 0A 64000000 7000 0000	map leaf, size 10: @64 → @70
083	3C 637075	txt "cpu"
087	02 08000000000000 00	i64 8
090	0F 0A 83000000 8700 0000	map leaf, size 10: @83 → @87
09A	4C 77616C6C	txt "wall"
09F	02 0A000000000000 00	i64 10
0A8	0F 0A 9A000000 9F00 0000	map leaf, size 10: @9A → @9F
0B2	07 12 21800000 7900 0000 90000000 A800 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @79 → @90 → @A8
0C4	BC 6172656E615F62 79746573	txt "arena_bytes"
0D0	02 50AB0000000000 00	i64 43856
0D9	0F 0A C4000000 D000 0000	map leaf, size 10: @C4 → @D0
0E3	3C 637075	txt "cpu"
0E7	02 671B0000000000 00	i64 7015
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 71850000000000 00	i64 34161
108	0F 0A FA000000 FF00 0000	map leaf, size 10: @FA → @FF
112	07 12 21800000 D900 0000 F0000000 0801 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @D9 → @F0 → @108
124	BC 6172656E615F62 79746573	txt "arena_bytes"

Show all 58 nodes

Offset (hex)	Bytes (hex)	Meaning
130	02 60B40000000000 00	i64 46176
139	0F 0A 24010000 3001 0000	map leaf, size 10: @124 → @130
143	3C 637075	txt "cpu"
147	02 9B1F0000000000 00	i64 8091
150	0F 0A 43010000 4701 0000	map leaf, size 10: @143 → @147
15A	4C 77616C6C	txt "wall"
15F	02 B6890000000000 00	i64 35254
168	0F 0A 5A010000 5F01 0000	map leaf, size 10: @15A → @15F
172	07 12 21800000 3901 0000 50010000 6801 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @139 → @150 → @168
184	3C 72756E	txt "run"
188	0F 0A 84010000 1201 0000	map leaf, size 10: @184 → @112
192	AC 706172616D6574 657273	txt "parameters"
19D	0F 0A 92010000 B200 0000	map leaf, size 10: @192 → @B2
1A7	14 10 737461676573 5F636F6D706C6574 6564	txt "stages_completed"
1B9	02 03000000000000 00	i64 3
1C2	0F 0A A7010000 B901 0000	map leaf, size 10: @1A7 → @1B9
1CC	EC 6172656E615F63 61706163697479	txt "arena_capacity"
1DB	02 00004000000000 00	i64 4194304
1E4	0F 0A CC010000 DB01 0000	map leaf, size 10: @1CC → @1DB
1EE	5C 746F74616C	txt "total"
1F4	0F 0A EE010000 7201 0000	map leaf, size 10: @1EE → @172
1FE	8C 617474656D7074 73	txt "attempts"
207	02 01000000000000 00	i64 1
210	0F 0A FE010000 0702 0000	map leaf, size 10: @1FE → @207
21A	FC 6C6F61645F6465 66696E6974696F6E	txt "load_definition"
22A	0F 0A 1A020000 5200 0000	map leaf, size 10: @21A → @52
234	07 22 E2A80000 8801 0000 9D010000 C201 0000 E4010000 F401 0000 10020000 2A02 0000	map branch, size 34, depth 0 (root), slots 1, 5, 6, 7, 11, 13, 15: @188 → @19D → @1C2 → @1E4 → @1F4 → @210 → @22A

Offset (hex)	Bytes (hex)	Meaning
256	34020000 00000000	root → @234; previous: none

Also calls: stardust_db_result_commit_info, stardust_result_error, stardust_result_release

stardust_db_mutation_release

66 B

void stardust_db_mutation_release(stardust_db_mutation *mutation);

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`mutation`	`stardust_db_mutation *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Examples

mutation/close

birthday_text holds this document:

TRON

221 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	2C 3F65	txt "?e"
07	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
14	2C 3F65	txt "?e"
17	4C 6E616D65	txt "name"
1C	3C 416461	txt "Ada"
20	0E 15 00 0700 030000 00 14000000 170000 00 1C000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @14 → @17 → @1C
35	0E 0D 00 0100 010000 00 20000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @20
42	5C 7768657265	txt "where"
48	0F 0A 42000000 3500 0000	map leaf, size 10: @42 → @35
52	4C 66696E64	txt "find"
57	0F 0A 52000000 0700 0000	map leaf, size 10: @52 → @7
61	07 0E 0A000000 4800 0000 57000000	map branch, size 14, depth 0 (root), slots 1, 3: @48 → @57
6F	3C 616765	txt "age"
73	02 25000000000000 00	i64 37
7C	0F 0A 6F000000 7300 0000	map leaf, size 10: @6F → @73
86	2C 3F65	txt "?e"
89	0F 0A 86000000 7C00 0000	map leaf, size 10: @86 → @7C
93	5C 7175657279	txt "query"
99	0F 0A 93000000 6100 0000	map leaf, size 10: @93 → @61
A3	5C 7061746368	txt "patch"
A9	0F 0A A3000000 8900 0000	map leaf, size 10: @A3 → @89
B3	07 0E 40020000 9900 0000 A9000000	map branch, size 14, depth 2, slots 6, 9: @99 → @A9
C1	07 0A 01000000 B300 0000	map branch, size 10, depth 1, slots 0: @B3
CB	07 0A 80000000 C100 0000	map branch, size 10, depth 0 (root), slots 7: @C1
D5	CB000000 00000000	root → @CB; previous: none

615 B

stardust_document *definition = NULL;
stardust_db_mutation *mutation = NULL;
stardust_result *result = NULL;
uint32_t status = stardust_parse(birthday_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_mutation_open(db, &source, &mutation);
if (status == STARDUST_OK) status = stardust_db_mutation_run(mutation, NULL, NULL, NULL, &result);
stardust_db_mutation_release(mutation);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_result_release(result); return status;}

TRON

179 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	0F 02	map leaf, size 2
06	3C 696473	txt "ids"
0A	0F 0A 06000000 0400 0000	map leaf, size 10: @6 → @4
14	6C 737461747573	txt "status"
1B	9C 636F6D6D697474 6564	txt "committed"
25	0F 0A 14000000 1B00 0000	map leaf, size 10: @14 → @1B
2F	07 0E 02040000 0A00 0000 25000000	map branch, size 14, depth 1, slots 1, 10: @A → @25
3D	BC 7472616E736163 74696F6E	txt "transaction"
49	02 05000000000000 00	i64 5
52	0F 0A 3D000000 4900 0000	map leaf, size 10: @3D → @49
5C	CC 636F6D6D697474 65645F6174	txt "committed_at"
69	02 6E83F34A35AD3F 00	i64 17923367935116142
72	0F 0A 5C000000 6900 0000	map leaf, size 10: @5C → @69
7C	5C 6661637473	txt "facts"
82	02 01000000000000 00	i64 1
8B	0F 0A 7C000000 8200 0000	map leaf, size 10: @7C → @82
95	07 16 01460000 2F00 0000 52000000 7200 0000 8B000000	map branch, size 22, depth 0 (root), slots 0, 9, 10, 14: @2F → @52 → @72 → @8B
AB	95000000 00000000	root → @95; previous: none

stardust_db_merge_patch

186 B

uint32_t stardust_db_merge_patch(stardust_db *db, const stardust_document *patch, const stardust_db_write_options *options, stardust_db_patch_explain *explain, stardust_result **output);

102 B

uint32_t stardust_db_result_commit_info(const stardust_result *result, stardust_db_commit_info *info);

96 B

uint32_t stardust_result_error(const stardust_result *result, stardust_diagnostic_view *output);

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_db_merge_patch

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`patch`	`const stardust_document *`	Borrowed handle	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`	`const stardust_db_write_options *`	Borrowed input	NULL	Caller-owned record read during the call.
`explain`	`stardust_db_patch_explain *`	Caller-owned output	NULL	Receives a record. Its pointer fields follow the record's ownership contract.
`output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_db_result_commit_info

Parameter	Type	Ownership	Default	Meaning
`result`	`const stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`info`	`stardust_db_commit_info *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_result_error

Parameter	Type	Ownership	Default	Meaning
`result`	`const stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_result_release

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Errors

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

Notes

Patch documents.

Examples

database/merge_patch

seed_text holds this document:

TRON

449 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	3C 616765	txt "age"
008	02 24000000000000 00	i64 36
011	0F 0A 04000000 0800 0000	map leaf, size 10: @4 → @8
01B	4C 726F6C65	txt "role"
020	8C 656E67696E6565 72	txt "engineer"
029	0F 0A 1B000000 2000 0000	map leaf, size 10: @1B → @20
033	4C 6E616D65	txt "name"
038	3C 416461	txt "Ada"
03C	0F 0A 33000000 3800 0000	map leaf, size 10: @33 → @38
046	07 12 00910000 1100 0000 29000000 3C00 0000	map branch, size 18, depth 0 (root), slots 8, 12, 15: @11 → @29 → @3C
058	5C 236C696E6B	txt "#link"
05E	5C 235F616461	txt "#_ada"
064	0F 0A 58000000 5E00 0000	map leaf, size 10: @58 → @5E
06E	3C 616765	txt "age"
072	02 29000000000000 00	i64 41
07B	0F 0A 6E000000 7200 0000	map leaf, size 10: @6E → @72
085	6C 6D656E746F72	txt "mentor"
08C	0F 0A 85000000 6400 0000	map leaf, size 10: @85 → @64
096	4C 726F6C65	txt "role"
09B	8C 656E67696E6565 72	txt "engineer"
0A4	0F 0A 96000000 9B00 0000	map leaf, size 10: @96 → @9B
0AE	4C 6E616D65	txt "name"
0B3	3C 426F62	txt "Bob"
0B7	0F 0A AE000000 B300 0000	map leaf, size 10: @AE → @B3
0C1	07 16 00990000 7B00 0000 8C000000 A400 0000 B7000000	map branch, size 22, depth 0 (root), slots 8, 11, 12, 15: @7B → @8C → @A4 → @B7
0D7	3C 616765	txt "age"
0DB	02 1D000000000000 00	i64 29
0E4	0F 0A D7000000 DB00 0000	map leaf, size 10: @D7 → @DB
0EE	4C 726F6C65	txt "role"
0F3	8C 64657369676E65 72	txt "designer"
0FC	0F 0A EE000000 F300 0000	map leaf, size 10: @EE → @F3
106	4C 6E616D65	txt "name"
10B	2C 4379	txt "Cy"
10E	0F 0A 06010000 0B01 0000	map leaf, size 10: @106 → @10B
118	07 12 00910000 E400 0000 FC000000 0E01 0000	map branch, size 18, depth 0 (root), slots 8, 12, 15: @E4 → @FC → @10E
12A	6C 617574686F72	txt "author"
131	5C 736D6F6B65	txt "smoke"
137	0F 0A 2A010000 3101 0000	map leaf, size 10: @12A → @131
141	6C 726561736F6E	txt "reason"
148	4C 73656564	txt "seed"
14D	0F 0A 41010000 4801 0000	map leaf, size 10: @141 → @148
157	07 0E 40080000 3701 0000 4D010000	map branch, size 14, depth 0 (root), slots 6, 11: @137 → @14D
165	4C 235F7478	txt "#_tx"
16A	0F 0A 65010000 5701 0000	map leaf, size 10: @165 → @157
174	4C 235F6379	txt "#_cy"
179	0F 0A 74010000 1801 0000	map leaf, size 10: @174 → @118
183	5C 235F626F62	txt "#_bob"
189	0F 0A 83010000 C100 0000	map leaf, size 10: @183 → @C1
193	5C 235F616461	txt "#_ada"
199	0F 0A 93010000 4600 0000	map leaf, size 10: @193 → @46
1A3	07 16 88210000 6A01 0000 79010000 8901 0000 99010000	map branch, size 22, depth 0 (root), slots 3, 7, 8, 13: @16A → @179 → @189 → @199
1B9	A3010000 00000000	root → @1A3; previous: none

336 B

stardust_document *patch = NULL;
stardust_result *result = NULL;
uint32_t status = stardust_parse(seed_text, STARDUST_TRON, &patch);
if (status == STARDUST_OK) status = stardust_db_merge_patch(db, patch, NULL, NULL, &result);
stardust_document_release(patch);
if (status != STARDUST_OK) {stardust_result_release(result); return status;}

TRON

269 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	4C 235F6379	txt "#_cy"
009	02 01000000000000 00	i64 1
012	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
01C	5C 235F626F62	txt "#_bob"
022	02 02000000000000 00	i64 2
02B	0F 0A 1C000000 2200 0000	map leaf, size 10: @1C → @22
035	5C 235F616461	txt "#_ada"
03B	02 03000000000000 00	i64 3
044	0F 0A 35000000 3B00 0000	map leaf, size 10: @35 → @3B
04E	07 12 80210000 1200 0000 2B000000 4400 0000	map branch, size 18, depth 0 (root), slots 7, 8, 13: @12 → @2B → @44
060	3C 696473	txt "ids"
064	0F 0A 60000000 4E00 0000	map leaf, size 10: @60 → @4E
06E	6C 737461747573	txt "status"
075	9C 636F6D6D697474 6564	txt "committed"
07F	0F 0A 6E000000 7500 0000	map leaf, size 10: @6E → @75
089	07 0E 02040000 6400 0000 7F000000	map branch, size 14, depth 1, slots 1, 10: @64 → @7F
097	BC 7472616E736163 74696F6E	txt "transaction"
0A3	02 04000000000000 00	i64 4
0AC	0F 0A 97000000 A300 0000	map leaf, size 10: @97 → @A3
0B6	CC 636F6D6D697474 65645F6174	txt "committed_at"
0C3	02 84AC8E4A35AD3F 00	i64 17923367928507524
0CC	0F 0A B6000000 C300 0000	map leaf, size 10: @B6 → @C3
0D6	5C 6661637473	txt "facts"
0DC	02 0C000000000000 00	i64 12
0E5	0F 0A D6000000 DC00 0000	map leaf, size 10: @D6 → @DC
0EF	07 16 01460000 8900 0000 AC000000 CC00 0000 E5000000	map branch, size 22, depth 0 (root), slots 0, 9, 10, 14: @89 → @AC → @CC → @E5
105	EF000000 00000000	root → @EF; previous: none

Explain patch validation and commit

seed_text holds this document:

TRON

449 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	3C 616765	txt "age"
008	02 24000000000000 00	i64 36
011	0F 0A 04000000 0800 0000	map leaf, size 10: @4 → @8
01B	4C 726F6C65	txt "role"
020	8C 656E67696E6565 72	txt "engineer"
029	0F 0A 1B000000 2000 0000	map leaf, size 10: @1B → @20
033	4C 6E616D65	txt "name"
038	3C 416461	txt "Ada"
03C	0F 0A 33000000 3800 0000	map leaf, size 10: @33 → @38
046	07 12 00910000 1100 0000 29000000 3C00 0000	map branch, size 18, depth 0 (root), slots 8, 12, 15: @11 → @29 → @3C
058	5C 236C696E6B	txt "#link"
05E	5C 235F616461	txt "#_ada"
064	0F 0A 58000000 5E00 0000	map leaf, size 10: @58 → @5E
06E	3C 616765	txt "age"
072	02 29000000000000 00	i64 41
07B	0F 0A 6E000000 7200 0000	map leaf, size 10: @6E → @72
085	6C 6D656E746F72	txt "mentor"
08C	0F 0A 85000000 6400 0000	map leaf, size 10: @85 → @64
096	4C 726F6C65	txt "role"
09B	8C 656E67696E6565 72	txt "engineer"
0A4	0F 0A 96000000 9B00 0000	map leaf, size 10: @96 → @9B
0AE	4C 6E616D65	txt "name"
0B3	3C 426F62	txt "Bob"
0B7	0F 0A AE000000 B300 0000	map leaf, size 10: @AE → @B3
0C1	07 16 00990000 7B00 0000 8C000000 A400 0000 B7000000	map branch, size 22, depth 0 (root), slots 8, 11, 12, 15: @7B → @8C → @A4 → @B7
0D7	3C 616765	txt "age"
0DB	02 1D000000000000 00	i64 29
0E4	0F 0A D7000000 DB00 0000	map leaf, size 10: @D7 → @DB
0EE	4C 726F6C65	txt "role"
0F3	8C 64657369676E65 72	txt "designer"
0FC	0F 0A EE000000 F300 0000	map leaf, size 10: @EE → @F3
106	4C 6E616D65	txt "name"
10B	2C 4379	txt "Cy"
10E	0F 0A 06010000 0B01 0000	map leaf, size 10: @106 → @10B
118	07 12 00910000 E400 0000 FC000000 0E01 0000	map branch, size 18, depth 0 (root), slots 8, 12, 15: @E4 → @FC → @10E
12A	6C 617574686F72	txt "author"
131	5C 736D6F6B65	txt "smoke"
137	0F 0A 2A010000 3101 0000	map leaf, size 10: @12A → @131
141	6C 726561736F6E	txt "reason"
148	4C 73656564	txt "seed"
14D	0F 0A 41010000 4801 0000	map leaf, size 10: @141 → @148
157	07 0E 40080000 3701 0000 4D010000	map branch, size 14, depth 0 (root), slots 6, 11: @137 → @14D
165	4C 235F7478	txt "#_tx"
16A	0F 0A 65010000 5701 0000	map leaf, size 10: @165 → @157
174	4C 235F6379	txt "#_cy"
179	0F 0A 74010000 1801 0000	map leaf, size 10: @174 → @118
183	5C 235F626F62	txt "#_bob"
189	0F 0A 83010000 C100 0000	map leaf, size 10: @183 → @C1
193	5C 235F616461	txt "#_ada"
199	0F 0A 93010000 4600 0000	map leaf, size 10: @193 → @46
1A3	07 16 88210000 6A01 0000 79010000 8901 0000 99010000	map branch, size 22, depth 0 (root), slots 3, 7, 8, 13: @16A → @179 → @189 → @199
1B9	A3010000 00000000	root → @1A3; previous: none

426 B

stardust_document *patch = NULL;
stardust_db_patch_explain explain = {0};
stardust_result *written = NULL;
uint32_t status = stardust_parse(seed_text, STARDUST_TRON, &patch);
if (status == STARDUST_OK) status = stardust_db_merge_patch(db, patch, NULL, &explain, &written);
stardust_result_release(written);
stardust_document_release(patch);
if (status != STARDUST_OK) return status;
stardust_db_patch_explain result = explain;

TRON

461 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	BC 6172656E615F62 79746573	txt "arena_bytes"
010	02 180C0000000000 00	i64 3096
019	0F 0A 04000000 1000 0000	map leaf, size 10: @4 → @10
023	3C 637075	txt "cpu"
027	02 47050000000000 00	i64 1351
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 4A050000000000 00	i64 1354
048	0F 0A 3A000000 3F00 0000	map leaf, size 10: @3A → @3F
052	07 12 21800000 1900 0000 30000000 4800 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @19 → @30 → @48
064	BC 6172656E615F62 79746573	txt "arena_bytes"
070	02 481F0000000000 00	i64 8008
079	0F 0A 64000000 7000 0000	map leaf, size 10: @64 → @70
083	3C 637075	txt "cpu"
087	02 46010000000000 00	i64 326
090	0F 0A 83000000 8700 0000	map leaf, size 10: @83 → @87
09A	4C 77616C6C	txt "wall"
09F	02 01C60000000000 00	i64 50689
0A8	0F 0A 9A000000 9F00 0000	map leaf, size 10: @9A → @9F
0B2	07 12 21800000 7900 0000 90000000 A800 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @79 → @90 → @A8
0C4	BC 6172656E615F62 79746573	txt "arena_bytes"
0D0	02 6E2B0000000000 00	i64 11118
0D9	0F 0A C4000000 D000 0000	map leaf, size 10: @C4 → @D0
0E3	3C 637075	txt "cpu"
0E7	02 F5060000000000 00	i64 1781
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 B5CB0000000000 00	i64 52149
108	0F 0A FA000000 FF00 0000	map leaf, size 10: @FA → @FF
112	07 12 21800000 D900 0000 F0000000 0801 0000	map branch, size 18, depth 0 (root), slots 0, 5, 15: @D9 → @F0 → @108
124	14 10 737461676573 5F636F6D706C6574 6564	txt "stages_completed"
136	02 02000000000000 00	i64 2
13F	0F 0A 24010000 3601 0000	map leaf, size 10: @124 → @136
149	EC 6172656E615F63 61706163697479	txt "arena_capacity"
158	02 00004000000000 00	i64 4194304
161	0F 0A 49010000 5801 0000	map leaf, size 10: @149 → @158
16B	5C 746F74616C	txt "total"
171	0F 0A 6B010000 1201 0000	map leaf, size 10: @16B → @112
17B	6C 636F6D6D6974	txt "commit"
182	0F 0A 7B010000 B200 0000	map leaf, size 10: @17B → @B2
18C	AC 636F70795F7061 746368	txt "copy_patch"
197	0F 0A 8C010000 5200 0000	map leaf, size 10: @18C → @52
1A1	07 0E 08100000 8201 0000 97010000	map branch, size 14, depth 1, slots 3, 12: @182 → @197
1AF	07 16 C0880000 3F01 0000 61010000 7101 0000 A1010000	map branch, size 22, depth 0 (root), slots 6, 7, 11, 15: @13F → @161 → @171 → @1A1
1C5	AF010000 00000000	root → @1AF; previous: none

Refuse a metadata-only transaction

patch_text holds this document:

TRON

46 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 617574686F72	txt "author"
0B	1C 78	txt "x"
0D	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
17	4C 235F7478	txt "#_tx"
1C	0F 0A 17000000 0D00 0000	map leaf, size 10: @17 → @D
26	1C000000 00000000	root → @1C; previous: none

390 B

stardust_document *patch = NULL;
stardust_result *failed = NULL;
uint32_t status = stardust_parse(patch_text, STARDUST_TRON, &patch);
if (status != STARDUST_OK) {stardust_document_release(patch); return status;}
status = stardust_db_merge_patch(db, patch, NULL, NULL, &failed);
stardust_document_release(patch);
stardust_diagnostic_view result = {0};
stardust_result_error(failed, &result);

TRON

263 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	6C 737461747573	txt "status"
00B	8C 72656A65637465 64	txt "rejected"
014	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
01E	6C 656E74697479	txt "entity"
025	00	nil
026	0F 0A 1E000000 2500 0000	map leaf, size 10: @1E → @25
030	7C 6D657373616765	txt "message"
038	14 37 612070617463 68206F66206F6E6C 7920235F74782069 7320726566757365 643A20235F747820 616E6E6F74617465 7320612077726974 65	txt "a patch of only #_tx is …"
071	0F 0A 30000000 3800 0000	map leaf, size 10: @30 → @38
07B	07 0E 08020000 2600 0000 71000000	map branch, size 14, depth 1, slots 3, 9: @26 → @71
089	4C 70617468	txt "path"
08E	4C 235F7478	txt "#_tx"
093	0F 0A 89000000 8E00 0000	map leaf, size 10: @89 → @8E
09D	5C 6669656C64	txt "field"
0A3	00	nil
0A4	0F 0A 9D000000 A300 0000	map leaf, size 10: @9D → @A3
0AE	4C 636F6465	txt "code"
0B3	14 10 7472616E7361 6374696F6E5F6F6E 6C79	txt "transaction_only"
0C5	0F 0A AE000000 B300 0000	map leaf, size 10: @AE → @B3
0CF	6C 6F6666736574	txt "offset"
0D6	00	nil
0D7	0F 0A CF000000 D600 0000	map leaf, size 10: @CF → @D6
0E1	07 1E 51620000 1400 0000 7B000000 9300 0000 A4000000 C500 0000 D7000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @14 → @7B → @93 → @A4 → @C5 → @D7
0FF	E1000000 00000000	root → @E1; previous: none

Refuse a repeated commit time

future_text holds this document:

TRON

145 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 78	txt "x"
06	02 01000000000000 00	i64 1
0F	0F 0A 04000000 0600 0000	map leaf, size 10: @4 → @6
19	4C 23757463	txt "#utc"
1E	14 14 323230302D30 312D30315430303A 30303A30305A	txt "2200-01-01T00:00:00Z"
34	0F 0A 19000000 1E00 0000	map leaf, size 10: @19 → @1E
3E	14 14 737461726475 73742F636F6D6D69 747465644174	txt "stardust/committedAt"
54	0F 0A 3E000000 3400 0000	map leaf, size 10: @3E → @34
5E	4C 235F7478	txt "#_tx"
63	0F 0A 5E000000 5400 0000	map leaf, size 10: @5E → @54
6D	3C 235F64	txt "#_d"
71	0F 0A 6D000000 0F00 0000	map leaf, size 10: @6D → @F
7B	07 0E 08010000 6300 0000 71000000	map branch, size 14, depth 0 (root), slots 3, 8: @63 → @71
89	7B000000 00000000	root → @7B; previous: none

patch_text holds this document:

TRON

145 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 78	txt "x"
06	02 02000000000000 00	i64 2
0F	0F 0A 04000000 0600 0000	map leaf, size 10: @4 → @6
19	4C 23757463	txt "#utc"
1E	14 14 323230302D30 312D30315430303A 30303A30305A	txt "2200-01-01T00:00:00Z"
34	0F 0A 19000000 1E00 0000	map leaf, size 10: @19 → @1E
3E	14 14 737461726475 73742F636F6D6D69 747465644174	txt "stardust/committedAt"
54	0F 0A 3E000000 3400 0000	map leaf, size 10: @3E → @34
5E	4C 235F7478	txt "#_tx"
63	0F 0A 5E000000 5400 0000	map leaf, size 10: @5E → @54
6D	3C 235F65	txt "#_e"
71	0F 0A 6D000000 0F00 0000	map leaf, size 10: @6D → @F
7B	07 0E 08010000 6300 0000 71000000	map branch, size 14, depth 0 (root), slots 3, 8: @63 → @71
89	7B000000 00000000	root → @7B; previous: none

716 B

stardust_document *future = NULL;
stardust_document *patch = NULL;
stardust_result *committed = NULL;
uint32_t status = stardust_parse(future_text, STARDUST_TRON, &future);
if (status == STARDUST_OK) status = stardust_parse(patch_text, STARDUST_TRON, &patch);
if (status == STARDUST_OK) status = stardust_db_merge_patch(db, future, NULL, NULL, &committed);
stardust_result_release(committed);
stardust_document_release(future);
if (status != STARDUST_OK) {stardust_document_release(patch); return status;}
stardust_result *failed = NULL;
status = stardust_db_merge_patch(db, patch, NULL, NULL, &failed);
stardust_document_release(patch);
stardust_diagnostic_view result = {0};
stardust_result_error(failed, &result);

TRON

290 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	6C 737461747573	txt "status"
00B	14 13 696E76616C69 645F636F6D6D6974 5F74696D65	txt "invalid_commit_time"
020	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
02A	6C 656E74697479	txt "entity"
031	00	nil
032	0F 0A 2A000000 3100 0000	map leaf, size 10: @2A → @31
03C	7C 6D657373616765	txt "message"
044	14 47 737461726475 73742F636F6D6D69 747465644174206D 7573742062652073 74726963746C7920 6E65776572207468 616E20746865206C 617465737420636F 6D6D69742074696D 65	txt "stardust/committedAt mus…"
08D	0F 0A 3C000000 4400 0000	map leaf, size 10: @3C → @44
097	07 0E 08020000 3200 0000 8D000000	map branch, size 14, depth 1, slots 3, 9: @32 → @8D
0A5	4C 70617468	txt "path"
0AA	00	nil
0AB	0F 0A A5000000 AA00 0000	map leaf, size 10: @A5 → @AA
0B5	5C 6669656C64	txt "field"
0BB	00	nil
0BC	0F 0A B5000000 BB00 0000	map leaf, size 10: @B5 → @BB
0C6	4C 636F6465	txt "code"
0CB	14 13 696E76616C69 645F636F6D6D6974 5F74696D65	txt "invalid_commit_time"
0E0	0F 0A C6000000 CB00 0000	map leaf, size 10: @C6 → @CB
0EA	6C 6F6666736574	txt "offset"
0F1	00	nil
0F2	0F 0A EA000000 F100 0000	map leaf, size 10: @EA → @F1
0FC	07 1E 51620000 2000 0000 97000000 AB00 0000 BC000000 E000 0000 F2000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @20 → @97 → @AB → @BC → @E0 → @F2
11A	FC000000 00000000	root → @FC; previous: none

Also calls: stardust_db_result_commit_info, stardust_result_error, stardust_result_release

stardust_db_indexes_sync

75 B

uint32_t stardust_db_indexes_sync(stardust_db *db, int64_t max_wait_ticks);

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`max_wait_ticks`	`int64_t`	Value	Required	Value passed to the call.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	`max_wait` is negative
`STARDUST_TIMEOUT`	`max_wait` passed first
`STARDUST_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

542 B

stardust_result *listed = NULL;
stardust_bytes kind = {(const uint8_t *)"queries", 7};
stardust_bytes pattern = {(const uint8_t *)"people/.*", 9};
uint32_t status = stardust_db_indexes_sync(db, 50000000);
if (status == STARDUST_OK) status = stardust_db_definition_list(db, kind, pattern, &listed);
if (status != STARDUST_OK) { stardust_result_release(listed); return status; }
stardust_document *result = NULL;
status = stardust_result_take_document(listed, &result);
stardust_result_release(listed);
if (status != STARDUST_OK) return status;

TRON

40 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	EC 70656F706C652F 62795F726F6C65	txt "people/by_role"
13	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
20	13000000 00000000	root → @13; previous: none

stardust_db_bulk_begin

49 B

uint32_t stardust_db_bulk_begin(stardust_db *db);

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	a bulk build is already in progress on the database
`STARDUST_CLOSED`	the database is closed
`STARDUST_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

282 B

uint32_t status = stardust_db_bulk_begin(db);
if (status != STARDUST_OK) return status;
// A second build on the same database is refused while this one runs.
if (stardust_db_bulk_begin(db) != STARDUST_INVALID_ARGUMENT) return STARDUST_EVALUATION_FAILED;
stardust_db_bulk_abort(db);

stardust_db_bulk_add

79 B

uint32_t stardust_db_bulk_add(stardust_db *db, const stardust_document *patch);

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`patch`	`const stardust_document *`	Borrowed handle	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
`STARDUST_INVALID_ARGUMENT`	no bulk build is in progress
`STARDUST_REJECTED`	the database refuses the patch; the build has failed and later adds report the same status
`STARDUST_CLOSED`	the database is closed
`STARDUST_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

826 B

// The first entity of an empty database is 1, so the second patch updates it.
const char *patches[] = {"{\"#_ada\":{\"name\":\"Ada\"}}", "{\"1\":{\"title\":\"Countess\"}}"};
stardust_result *finished = NULL;
uint32_t status = stardust_db_bulk_begin(db);
for (size_t index = 0; status == STARDUST_OK && index < 2; index++) {
    stardust_bytes patch = {(const uint8_t *)patches[index], (int64_t)strlen(patches[index])};
    stardust_document *document = NULL;
    status = stardust_parse(patch, STARDUST_JSON, &document);
    if (status == STARDUST_OK) status = stardust_db_bulk_add(db, document);
    stardust_document_release(document);
}
if (status == STARDUST_OK) status = stardust_db_bulk_finish(db, &finished);
else stardust_db_bulk_abort(db);
stardust_result_release(finished);
if (status != STARDUST_OK) return status;

stardust_db_bulk_finish

76 B

uint32_t stardust_db_bulk_finish(stardust_db *db, stardust_result **output);

92 B

uint32_t stardust_result_take_document(stardust_result *result, stardust_document **output);

96 B

uint32_t stardust_result_error(const stardust_result *result, stardust_diagnostic_view *output);

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_db_bulk_finish

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_take_document

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_document **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_error

Parameter	Type	Ownership	Default	Meaning
`result`	`const stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_result_release

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	no bulk build is in progress
`STARDUST_REJECTED`	the database refuses a patch; an initial build publishes nothing and fallback keeps earlier commits
`STARDUST_CONFLICT`	another write committed to the database during the build
`STARDUST_CLOSED`	the database is closed
`STARDUST_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

928 B

const char *text = "{\"#_ada\":{\"name\":\"Ada\",\"title\":\"Countess\"}}";
stardust_bytes patch = {(const uint8_t *)text, (int64_t)strlen(text)};
stardust_result *finished = NULL;
stardust_document *summary = NULL;
uint32_t status = stardust_db_bulk_begin(db);
stardust_document *document = NULL;
if (status == STARDUST_OK) status = stardust_parse(patch, STARDUST_JSON, &document);
if (status == STARDUST_OK) status = stardust_db_bulk_add(db, document);
stardust_document_release(document);
// finish ends the build also when it fails.
if (status == STARDUST_OK) status = stardust_db_bulk_finish(db, &finished);
else stardust_db_bulk_abort(db);
if (status == STARDUST_OK) status = stardust_result_take_document(finished, &summary);
stardust_result_release(finished);
// summary holds status, patches, transactions, facts, entities and phase timings.
stardust_document_release(summary);
if (status != STARDUST_OK) return status;

Also calls: stardust_result_take_document, stardust_result_error, stardust_result_release

stardust_db_bulk_abort

45 B

void stardust_db_bulk_abort(stardust_db *db);

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	NULL	Keep the handle alive until the call returns.

Notes

Abort preserves patches already committed in fallback mode. It is safe without a build or after database closure.

Examples

Drop a bulk build without writing it

527 B

const char *text = "{\"#_ada\":{\"name\":\"Ada\"}}";
stardust_bytes patch = {(const uint8_t *)text, (int64_t)strlen(text)};
uint32_t status = stardust_db_bulk_begin(db);
stardust_document *document = NULL;
if (status == STARDUST_OK) status = stardust_parse(patch, STARDUST_JSON, &document);
if (status == STARDUST_OK) status = stardust_db_bulk_add(db, document);
stardust_document_release(document);
// Abort writes nothing; without a build it does nothing.
stardust_db_bulk_abort(db);
if (status != STARDUST_OK) return status;

stardust_db_subscription_set_notify

59 B

typedef void (*stardust_db_subscription_notify)(void *ctx);

127 B

uint32_t stardust_db_subscription_set_notify(stardust_db_subscription *sub, stardust_db_subscription_notify notify, void *ctx);

Parameters

Parameter	Requirement	Meaning
`sub`	Required	Subscription receiving the callback. Use the handle exclusively during registration.
`notify`	Required	Readiness callback.
`ctx`	NULL is valid	Caller-owned state, passed unchanged to the callback. Stardust does not read or free it.

Notes

Use this optional callback to wake a host scheduler without polling or a dedicated waiting thread. Blocking next works without registration.

Register a borrowed signal-only C callback once, before any next call. NULL context is valid. Native registration allocates nothing. Install the application waiter before next with zero wait; TIMEOUT arms a coalesced readiness hint. The callback may run on any thread, must return promptly, and must not call Stardust or run application work. Keep callback code and context valid until subscription release returns; no callback is running or can run afterward. Concurrent next calls race for events. A null subscription or callback, duplicate registration, or registration after next reports invalid_argument. A failed subscription preserves its saved failure. A rejected registration retains nothing.

The example requires a C implementation with C11 threads (<threads.h>) and timed condition waits.

Examples

Wait through a readiness callback

query_text holds this document:

TRON

165 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	5C 3F6E616D65	txt "?name"
0A	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
17	2C 3F65	txt "?e"
1A	4C 6E616D65	txt "name"
1F	5C 3F6E616D65	txt "?name"
25	0E 15 00 0700 030000 00 17000000 1A0000 00 1F000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A	0E 0D 00 0100 010000 00 25000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
47	5C 3F6E616D65	txt "?name"
4D	0E 0D 00 0100 010000 00 47000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A	5C 7768657265	txt "where"
60	0F 0A 5A000000 3A00 0000	map leaf, size 10: @5A → @3A
6A	4C 66696E64	txt "find"
6F	0F 0A 6A000000 0A00 0000	map leaf, size 10: @6A → @A
79	7C 6F726465724279	txt "orderBy"
81	0F 0A 79000000 4D00 0000	map leaf, size 10: @79 → @4D
8B	07 12 2A000000 6000 0000 6F000000 8100 0000	map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
9D	8B000000 00000000	root → @8B; previous: none

2.6 kB

#include <threads.h>
#include <time.h>
#include <stdlib.h>

struct subscription_waiter {
    mtx_t mutex;
    cnd_t changed;
    uint64_t generation;
};

static void notify_sync_check(int status) {
    if (status != thrd_success) abort();
}

static void subscription_ready(void *ctx) {
    struct subscription_waiter *waiter = ctx;
    notify_sync_check(mtx_lock(&waiter->mutex));
    waiter->generation++;
    notify_sync_check(cnd_broadcast(&waiter->changed));
    notify_sync_check(mtx_unlock(&waiter->mutex));
}

struct subscription_waiter waiter = {0};
if (mtx_init(&waiter.mutex, mtx_plain) != thrd_success) return STARDUST_OUT_OF_MEMORY;
if (cnd_init(&waiter.changed) != thrd_success) {
    mtx_destroy(&waiter.mutex);
    return STARDUST_OUT_OF_MEMORY;
}
stardust_document *definition = NULL;
stardust_db_query *query = NULL;
stardust_db_subscription *subscription = NULL;
stardust_db_live_event event = {0};
uint32_t status = stardust_parse(query_text, STARDUST_TRON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(db, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_subscribe(query, NULL, NULL, &subscription);
if (status == STARDUST_OK) status = stardust_db_subscription_set_notify(subscription, subscription_ready, &waiter);
struct timespec deadline = {0};
if (timespec_get(&deadline, TIME_UTC) != TIME_UTC) status = STARDUST_INVALID_ARGUMENT;
deadline.tv_sec += 5;
while (status == STARDUST_OK) {
    notify_sync_check(mtx_lock(&waiter.mutex));
    uint64_t observed = waiter.generation;
    notify_sync_check(mtx_unlock(&waiter.mutex));
    status = stardust_db_subscription_next(subscription, 0, &event);
    if (status != STARDUST_TIMEOUT) break;
    notify_sync_check(mtx_lock(&waiter.mutex));
    int waited = thrd_success;
    while (waiter.generation == observed && waited == thrd_success)
        waited = cnd_timedwait(&waiter.changed, &waiter.mutex, &deadline);
    notify_sync_check(mtx_unlock(&waiter.mutex));
    if (waited == thrd_success) status = STARDUST_OK;
    else if (waited != thrd_timedout) status = STARDUST_INVALID_ARGUMENT;
}
// Release joins callbacks before the stack context or its mutex is destroyed.
stardust_db_subscription_release(subscription);
stardust_db_query_release(query);
stardust_document_release(definition);
cnd_destroy(&waiter.changed);
mtx_destroy(&waiter.mutex);
if (status != STARDUST_OK) {stardust_document_release(event.result); return status;}
stardust_document *result = event.result;

TRON

89 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	4C 6E616D65	txt "name"
09	3C 416461	txt "Ada"
0D	0F 0A 04000000 0900 0000	map leaf, size 10: @4 → @9
17	4C 6E616D65	txt "name"
1C	3C 426F62	txt "Bob"
20	0F 0A 17000000 1C00 0000	map leaf, size 10: @17 → @1C
2A	4C 6E616D65	txt "name"
2F	2C 4379	txt "Cy"
32	0F 0A 2A000000 2F00 0000	map leaf, size 10: @2A → @2F
3C	0E 15 00 0700 030000 00 0D000000 200000 00 32000000	array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32
51	3C000000 00000000	root → @3C; previous: none

stardust_db_query_options

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

Note

Supply size and version with each record. NULL options select the defaults of the call.

Field	C type	Unit	Range	Default	Meaning
`size`	`uint32_t`	Bytes	Unsigned u32	Required: sizeof(stardust_db_query_options)	—
`version`	`uint32_t`	None	Unsigned u32	Required: 1	—
`page_size`	`uint32_t`	Count	Unsigned u32	0 selects the default page size	Rows per page. 0 selects the default page size. Queries only.
`reserved`	`uint32_t`	None	Unsigned u32	0	Must be zero.
`max_cost_ticks`	`int64_t`	100 ns ticks	Signed i64	0 selects the dynamic CPU budget	Thread CPU duration limit. 0 selects the engine’s dynamic budget.
`as_of`	`int64_t`	None	Signed i64	Zero	A positive transaction runs a stored definition as of that transaction.

stardust_db_write_options

Note

Supply size and version with each record. NULL options select the defaults of the call.

Field	C type	Unit	Range	Default	Meaning
`size`	`uint32_t`	Bytes	Unsigned u32	Required: sizeof(stardust_db_write_options)	—
`version`	`uint32_t`	None	Unsigned u32	Required: 1	—
`max_cost_ticks`	`int64_t`	100 ns ticks	Signed i64	0 selects the dynamic CPU budget	Thread CPU duration limit. 0 selects the engine’s dynamic budget.
`as_of`	`int64_t`	None	Signed i64	Zero	A positive transaction runs a stored definition as of that transaction.

stardust_db_commit_info

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

Field	C type	Unit	Range	Default	Meaning
`status`	`uint32_t`	None	Unsigned u32	The call sets it	—
`reserved`	`uint32_t`	None	Unsigned u32	0	Must be zero.
`transaction`	`int64_t`	None	Signed i64	The call sets it	Zero when nothing was written.
`facts`	`int64_t`	Count	Signed i64	The call sets it	—
`committed_at_ticks`	`int64_t`	100 ns ticks since the Unix epoch (UTC)	Signed i64	The call sets it	Recorded commit time as a UTC instant. The call measures this value. Independent calls can differ.

stardust_db_live_event

This record contains the result of subscription next.

Field	C type	Unit	Range	Meaning
`sequence`	`int64_t`	Count	Signed i64	Event number. Event 1 is the initial result.
`superseded`	`int64_t`	Count	Signed i64	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`	`int64_t`	None	Signed i64	Transaction the result was computed at.
`result`	`stardust_document *`	None	C type range	The full query result. The event owns it and the consumer closes it.