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

odin

588 B

birthday_source := stardust.parse(birthday_text, .TRON) or_return
defer stardust.close(&birthday_source)

birthday := stardust.mutation(db, birthday_source) or_return
defer stardust.close(&birthday)

commit := stardust.run(birthday) or_return
defer stardust.close(&commit)

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

rows := stardust.run(query) or_return
defer stardust.close(&rows)

result := stardust.all_pages(rows) or_return
defer stardust.close(&result)

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

read_entity

odin

174 B

read_entity :: proc(
	db: Database,
	entity: builtin.i64,
	max_depth: builtin.i64 = 0,
	max_entities: builtin.i64 = 0,
	allocator := context.allocator,
) -> (Document, Error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`entity`	`builtin.i64`	Value	Required	The decimal user entity ID.
`max_depth`	`builtin.i64`	Value	0	Link hops to expand along each path, 0 through 32. 0, the default, leaves every link a {#link id} reference.
`max_entities`	`builtin.i64`	Value	0	The most entity documents the result holds, counting the root and every expanded or absent target each time it is placed. 0 selects the default of 1000.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Invalid_Argument`	the entity ID is outside the user entity range, `max_depth` is negative or above 32, or `max_entities` is negative
`.Closed`	the database is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

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

Examples

Read Bob with his mentor expanded

odin

80 B

result := stardust.read_entity(db, 2, 1) or_return
defer stardust.close(&result)

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

C exports: stardust_db_read_entity, stardust_result_take_document, stardust_result_error, stardust_result_release

query

odin

91 B

query :: proc(db: Database, path: string, allocator := context.allocator) -> (Query, Error)

odin

110 B

query :: proc(
	db: Database,
	definition: Document,
	allocator := context.allocator,
) -> (
	Query,
	Error,
)

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`path`	`string`	Value	Required	The stored definition path selected at run time.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.
`definition`	`Document`	Borrowed for the call	Required	The inline native definition copied into the opened handle.

Errors

Status	When
`.Not_Found`	no definition is stored at the path
`.Invalid_Definition`	the definition is invalid
`.Closed`	the database is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

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

Query documents.

Examples

Open an inline query and read its first page

query_text holds this document:

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

odin

309 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

rows := stardust.run(query) or_return
defer stardust.close(&rows)

result := stardust.next(rows) or_return
defer stardust.close(&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

Refuse an invalid query definition

query_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

odin

199 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query, result := stardust.query(db, definition)
defer stardust.close(&query)
defer stardust.close(&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

odin

112 B

query, result := stardust.query(db, "people/missing")
defer stardust.close(&query)
defer stardust.close(&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

C exports: stardust_db_query_open, stardust_db_query_error

mutation

odin

97 B

mutation :: proc(db: Database, path: string, allocator := context.allocator) -> (Mutation, Error)

odin

116 B

mutation :: proc(
	db: Database,
	definition: Document,
	allocator := context.allocator,
) -> (
	Mutation,
	Error,
)

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`path`	`string`	Value	Required	The stored definition path selected at run time.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.
`definition`	`Document`	Borrowed for the call	Required	The inline native definition copied into the opened handle.

Errors

Status	When
`.Not_Found`	no definition is stored at the path
`.Invalid_Definition`	the definition is invalid
`.Closed`	the database is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

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

Mutation documents.

Examples

database/mutation

birthday_text holds this document:

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

odin

263 B

source := stardust.parse(birthday_text, .TRON) or_return
defer stardust.close(&source)

mutation := stardust.mutation(db, source) or_return
defer stardust.close(&mutation)

commit := stardust.run(mutation) or_return
defer stardust.close(&commit)

result := commit

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 6AE47F4735AD3F 00	i64 17923367877207146
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

C exports: stardust_db_mutation_open, stardust_db_mutation_error

run

odin

172 B

run :: proc(
	query: Query,
	parameters: Document = {},
	options: Run_Options = {},
	explain: ^Query_Explain = nil,
	allocator := context.allocator,
) -> (
	Rows,
	Error,
)

Parameters

Parameter	Type	Ownership	Default	Meaning
`query`	`Query`	Borrowed for the call	Required	The query owner for this operation. Keep it alive during the call.
`parameters`	`Document`	Borrowed for the call	{}	An optional object of parameter values that merge-patches the definition's declared parameters. A parameter matched in the entity position of a fact clause takes an entity reference {#link id}, never the bare ID number: a commit returns IDs as numbers, so wrap one as {#link id}, or as the typed Link value where the binding has one, before passing it. A query run fails with `entity_reference_expected` when a bare number reaches that position. Projected and found entities also read back as {#link id}, so a typed field that receives one uses Link rather than a plain integer.
`options`	`Run_Options`	Value	{}	The operation's options record. See its field defaults.
`explain`	`^Query_Explain`	Caller-owned output	nil	Optional explain output. This record contains explain output for query `run`. The `compile`, `plan`, `execute`, `group` and `order` fields divide the wall time of `run` into stages.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Not_Found`	the stored query definition was deleted
`.Invalid_Definition`	the loaded query definition is invalid
`.Invalid_Argument`	the parameters or run options are invalid
`.Evaluation_Failed`	the query fails or exceeds `max_cost`
`.Closed`	the query is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

Query documents.

Examples

Open an inline query and read its first page

query_text holds this document:

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

odin

309 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

rows := stardust.run(query) or_return
defer stardust.close(&rows)

result := stardust.next(rows) or_return
defer stardust.close(&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

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

odin

537 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

boundary := stardust.parse(boundary_text, .TRON) or_return
defer stardust.close(&boundary)

nanoseconds := stardust.i64(boundary, stardust.root(boundary) or_return) or_return
options := stardust.Run_Options{page_size = 2, max_cost = time.Duration(nanoseconds)}
rows := stardust.run(query, options = options) or_return
defer stardust.close(&rows)

result := options

TRON

112 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	8C 6D61785F636F73 74	txt "max_cost"
0D	02 AE47E17A14AE47 01	i64 92233720368547758
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

Truncate a positive sub-tick duration

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 63000000000000 00	i64 99
0D	04000000 00000000	root → @4; previous: none

odin

537 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

boundary := stardust.parse(boundary_text, .TRON) or_return
defer stardust.close(&boundary)

nanoseconds := stardust.i64(boundary, stardust.root(boundary) or_return) or_return
options := stardust.Run_Options{page_size = 2, max_cost = time.Duration(nanoseconds)}
rows := stardust.run(query, options = options) or_return
defer stardust.close(&rows)

result := options

TRON

112 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	8C 6D61785F636F73 74	txt "max_cost"
0D	02 00000000000000 00	i64 0
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

odin

309 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

explain: stardust.Query_Explain
rows := stardust.run(query, explain = &explain) or_return
defer stardust.close(&rows)

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 36020000000000 00	i64 566
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 3E020000000000 00	i64 574
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 07000000000000 00	i64 7
090	0F 0A 83000000 8700 0000	map leaf, size 10: @83 → @87
09A	4C 77616C6C	txt "wall"
09F	02 09000000000000 00	i64 9
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 E4230000000000 00	i64 9188
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 2B240000000000 00	i64 9259
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 3E260000000000 00	i64 9790
150	0F 0A 43010000 4701 0000	map leaf, size 10: @143 → @147
15A	4C 77616C6C	txt "wall"
15F	02 8F260000000000 00	i64 9871
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 BC010000000000 00	i64 444
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 C5000000000000 00	i64 197
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 F6170000000000 00	i64 6134
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 Odin duration keeps its sign at the ABI boundary

odin

59 B

result := stardust.Run_Options{max_cost = -time.Nanosecond}

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

odin

347 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

options := stardust.Run_Options{page_size = 2, max_cost = time.Second}
rows := stardust.run(query, options = options) or_return
defer stardust.close(&rows)

result := options

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

C exports: stardust_db_query_run, stardust_db_rows_error

close

odin

28 B

close :: proc(query: ^Query)

Consumes the receiver handle.

Parameters

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

Examples

Open an inline query and read its first page

query_text holds this document:

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

odin

333 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

rows := stardust.run(query) or_return
defer stardust.close(&rows)

result := stardust.next(rows) or_return
defer stardust.close(&result)

stardust.close(&query)

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

C exports: stardust_db_query_release

odin

77 B

next :: proc(rows: Rows, allocator := context.allocator) -> (Document, Error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`rows`	`Rows`	Borrowed for the call	Required	The rows owner for this operation. Keep it alive during the call.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Evaluation_Failed`	the page does not render
`.Closed`	the rows is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

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

Examples

Open an inline query and read its first page

query_text holds this document:

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

odin

309 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

rows := stardust.run(query) or_return
defer stardust.close(&rows)

result := stardust.next(rows) or_return
defer stardust.close(&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

C exports: stardust_db_rows_next, stardust_result_take_document, stardust_result_error, stardust_result_release

page_iterator

odin

82 B

page_iterator :: proc(rows: Rows, allocator := context.allocator) -> Page_Iterator

Parameters

Parameter	Type	Ownership	Default	Meaning
`rows`	`Rows`	Borrowed for the call	Required	The rows owner for this operation. Keep it alive during the call.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Evaluation_Failed`	a page does not render
`.Closed`	the rows is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

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

Examples

Iterate the pages of a query run

query_text holds this document:

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

odin

466 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

rows := stardust.run(query, options = stardust.Run_Options{page_size = 1}) or_return
defer stardust.close(&rows)

it := stardust.page_iterator(rows)
defer stardust.page_iterator_destroy(&it)
result: i64 = 0
for _ in stardust.iterate_pages(&it) {
	result += 1
}
if it.err != nil {return it.err}

TRON

21 B

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

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

all_pages

odin

97 B

all_pages :: proc(rows: Rows, allocator := context.allocator) -> (result: Document, error: Error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`rows`	`Rows`	Borrowed for the call	Required	The rows owner for this operation. Keep it alive during the call.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Evaluation_Failed`	a page does not render
`.Closed`	the rows is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

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

Examples

Read all remaining rows into one document

query_text holds this document:

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

odin

361 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

rows := stardust.run(query, options = stardust.Run_Options{page_size = 1}) or_return
defer stardust.close(&rows)

result := stardust.all_pages(rows) or_return
defer stardust.close(&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

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

close

odin

26 B

close :: proc(rows: ^Rows)

Consumes the receiver handle.

Parameters

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

Examples

Open an inline query and read its first page

query_text holds this document:

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

odin

332 B

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

rows := stardust.run(query) or_return
defer stardust.close(&rows)

result := stardust.next(rows) or_return
defer stardust.close(&result)

stardust.close(&rows)

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

C exports: stardust_db_rows_release

odin

154 B

subscribe :: proc(
	query: Query,
	parameters: Document = {},
	options: Run_Options = {},
	allocator := context.allocator,
) -> (
	Subscription,
	Error,
)

Parameters

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

Errors

Status	When
`.Invalid_Definition`	the query or its callable definitions are invalid
`.Invalid_Argument`	the parameters or subscription options are invalid
`.Closed`	the query is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

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

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

odin

352 B

source := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&source)

query := stardust.query(db, source) or_return
defer stardust.close(&query)

subscription := stardust.subscribe(query) or_return
defer stardust.close(&subscription)

event := stardust.next(subscription, 0) or_return
result := event.result
defer stardust.close(&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

odin

330 B

source := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&source)

query := stardust.query(db, source) or_return
defer stardust.close(&query)

subscription := stardust.subscribe(query) or_return
defer stardust.close(&subscription)

result := stardust.next(subscription, 0) or_return
defer stardust.close(&result)

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

C exports: stardust_db_query_subscribe, stardust_db_subscription_set_notify, stardust_db_subscription_error

odin

126 B

next :: proc(
	subscription: Subscription,
	max_wait: time.Duration,
	allocator := context.allocator,
) -> (
	Event,
	Error,
)

Parameters

Parameter	Type	Ownership	Default	Meaning
`subscription`	`Subscription`	Borrowed for the call	Required	The subscription owner for this operation. Keep it alive during the call.
`max_wait`	`time.Duration`	Value	Required	The maximum wait. Zero checks once.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Invalid_Argument`	`max_wait` is negative
`.Cancelled`	the subscription is cancelled or closed
`.Evaluation_Failed`	a rerun of the query failed. Every later call reports this failure
`.Closed`	the subscription is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

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

Examples

subscription/next

query_text holds this document:

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

odin

352 B

source := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&source)

query := stardust.query(db, source) or_return
defer stardust.close(&query)

subscription := stardust.subscribe(query) or_return
defer stardust.close(&subscription)

event := stardust.next(subscription, 0) or_return
result := event.result
defer stardust.close(&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

C exports: stardust_db_subscription_next, stardust_db_subscription_error, stardust_document_release

events

Odin callers loop over next directly

C exports: stardust_db_subscription_next, stardust_db_subscription_error

cancel

odin

55 B

subscription_cancel :: proc(subscription: Subscription)

Parameters

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

Notes

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

Examples

subscription/cancel

query_text holds this document:

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

odin

382 B

source := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&source)

query := stardust.query(db, source) or_return
defer stardust.close(&query)

subscription := stardust.subscribe(query) or_return
defer stardust.close(&subscription)

event := stardust.next(subscription, 0) or_return
stardust.cancel(subscription)
result := event.result
defer stardust.close(&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

C exports: stardust_db_subscription_cancel

close

odin

42 B

close :: proc(subscription: ^Subscription)

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`subscription`	`^Subscription`	Consumed owner	Required	The subscription owner to release. Do not use it 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

odin

383 B

source := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&source)

query := stardust.query(db, source) or_return
defer stardust.close(&query)

subscription := stardust.subscribe(query) or_return
defer stardust.close(&subscription)

event := stardust.next(subscription, 0) or_return
result := event.result
defer stardust.close(&result)

stardust.close(&subscription)

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

C exports: stardust_db_subscription_release

run

odin

183 B

run :: proc(
	mutation: Mutation,
	parameters: Document = {},
	options: Run_Options = {},
	explain: ^Mutation_Explain = nil,
	allocator := context.allocator,
) -> (
	Commit,
	Error,
)

Parameters

Parameter	Type	Ownership	Default	Meaning
`mutation`	`Mutation`	Borrowed for the call	Required	The mutation owner for this operation. Keep it alive during the call.
`parameters`	`Document`	Borrowed for the call	{}	An optional object of parameter values that merge-patches the definition's declared parameters. A parameter matched in the entity position of a fact clause takes an entity reference {#link id}, never the bare ID number: a commit returns IDs as numbers, so wrap one as {#link id}, or as the typed Link value where the binding has one, before passing it. A query run fails with `entity_reference_expected` when a bare number reaches that position. Projected and found entities also read back as {#link id}, so a typed field that receives one uses Link rather than a plain integer.
`options`	`Run_Options`	Value	{}	The operation's options record. See its field defaults.
`explain`	`^Mutation_Explain`	Caller-owned output	nil	Optional explain output. This record contains explain output for mutation `run`.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Invalid_Definition`	the mutation selection or definition is invalid
`.Invalid_Argument`	the parameters or run options are invalid
`.Schema_Violation`	the write breaks a schema
`.Conflict`	concurrent writes prevent the commit
`.Rejected`	a mutation target or write guard refuses the write
`.Unavailable`	the patch sets stardust/history and no enabled plugin purges history
`.Evaluation_Failed`	the mutation fails
`.Closed`	the mutation is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

Mutation documents.

Examples

mutation/run

birthday_text holds this document:

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

odin

263 B

source := stardust.parse(birthday_text, .TRON) or_return
defer stardust.close(&source)

mutation := stardust.mutation(db, source) or_return
defer stardust.close(&mutation)

commit := stardust.run(mutation) or_return
defer stardust.close(&commit)

result := commit

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 0DBBC04735AD3F 00	i64 17923367881456397
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

odin

319 B

source := stardust.parse(birthday_text, .TRON) or_return
defer stardust.close(&source)

mutation := stardust.mutation(db, source) or_return
defer stardust.close(&mutation)

explain: stardust.Mutation_Explain
commit := stardust.run(mutation, explain = &explain) or_return
defer stardust.close(&commit)

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 8C040000000000 00	i64 1164
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 A7040000000000 00	i64 1191
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 09000000000000 00	i64 9
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 62220000000000 00	i64 8802
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 57DC0000000000 00	i64 56407
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 56270000000000 00	i64 10070
150	0F 0A 43010000 4701 0000	map leaf, size 10: @143 → @147
15A	4C 77616C6C	txt "wall"
15F	02 6CE10000000000 00	i64 57708
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

C exports: stardust_db_mutation_run, stardust_db_result_commit_info, stardust_result_error, stardust_result_release

close

odin

34 B

close :: proc(mutation: ^Mutation)

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`mutation`	`^Mutation`	Consumed owner	Required	The mutation owner to release. Do not use it 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

odin

290 B

source := stardust.parse(birthday_text, .TRON) or_return
defer stardust.close(&source)

mutation := stardust.mutation(db, source) or_return
defer stardust.close(&mutation)

commit := stardust.run(mutation) or_return
defer stardust.close(&commit)

result := commit

stardust.close(&mutation)

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 102BB24735AD3F 00	i64 17923367880502032
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

C exports: stardust_db_mutation_release

merge_patch

odin

144 B

merge_patch :: proc(
	db: Database,
	patch: Document,
	explain: ^Patch_Explain = nil,
	allocator := context.allocator,
) -> (
	Commit,
	Error,
)

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`patch`	`Document`	Borrowed for the call	Required	An entity-keyed native patch. Temporary names use `#_name`. `#_tx` holds metadata and an optional stardust/checkAndSet map from entity IDs to expected transactions. Positive expectations match exact last-touch transactions; zero requires no current facts. Conditions are consumed and checked atomically, including for no-ops.
`explain`	`^Patch_Explain`	Caller-owned output	nil	Optional explain output. This record contains explain output for `merge_patch`.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

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

Notes

Patch documents.

Examples

database/merge_patch

seed_text holds this document:

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

odin

181 B

patch := stardust.parse(seed_text, .TRON) or_return
defer stardust.close(&patch)

commit := stardust.merge_patch(db, patch) or_return
defer stardust.close(&commit)

result := commit

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 A4B25F4735AD3F 00	i64 17923367875097252
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

odin

224 B

patch := stardust.parse(seed_text, .TRON) or_return
defer stardust.close(&patch)

explain: stardust.Patch_Explain
commit := stardust.merge_patch(db, patch, &explain) or_return
defer stardust.close(&commit)

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 91040000000000 00	i64 1169
030	0F 0A 23000000 2700 0000	map leaf, size 10: @23 → @27
03A	4C 77616C6C	txt "wall"
03F	02 94040000000000 00	i64 1172
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 9A010000000000 00	i64 410
090	0F 0A 83000000 8700 0000	map leaf, size 10: @83 → @87
09A	4C 77616C6C	txt "wall"
09F	02 DA850000000000 00	i64 34266
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 B3060000000000 00	i64 1715
0F0	0F 0A E3000000 E700 0000	map leaf, size 10: @E3 → @E7
0FA	4C 77616C6C	txt "wall"
0FF	02 FC8A0000000000 00	i64 35580
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

odin

192 B

patch := stardust.parse(patch_text, .TRON) or_return
defer stardust.close(&patch)

commit, result := stardust.merge_patch(db, patch)
defer stardust.close(&commit)
defer stardust.close(&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

older_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

odin

368 B

future := stardust.parse(future_text, .TRON) or_return
defer stardust.close(&future)

committed := stardust.merge_patch(db, future) or_return
defer stardust.close(&committed)

patch := stardust.parse(older_text, .TRON) or_return
defer stardust.close(&patch)

commit, result := stardust.merge_patch(db, patch)
defer stardust.close(&commit)
defer stardust.close(&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

C exports: stardust_db_merge_patch, stardust_db_result_commit_info, stardust_result_error, stardust_result_release

indexes_sync

odin

100 B

indexes_sync :: proc(db: Database, max_wait: time.Duration, allocator := context.allocator) -> Error

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`max_wait`	`time.Duration`	Value	Required	The maximum wait. Zero checks once.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Invalid_Argument`	`max_wait` is negative
`.Timeout`	`max_wait` passed first
`.Closed`	the database is closed

Notes

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

Examples

Wait for the exact indexes of the stored queries

odin

151 B

stardust.indexes_sync(db, 5 * time.Second) or_return
result := stardust.definitions(db, "queries", "people/.*") or_return
defer stardust.close(&result)

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

C exports: stardust_db_indexes_sync

bulk_begin

odin

73 B

bulk_begin :: proc(db: Database, allocator := context.allocator) -> Error

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Invalid_Argument`	a bulk build is already in progress on the database
`.Closed`	the database is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

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

Examples

Start a bulk build and drop it

odin

57 B

stardust.bulk_begin(db) or_return
stardust.bulk_abort(db)

C exports: stardust_db_bulk_begin

bulk_add

odin

88 B

bulk_add :: proc(db: Database, patch: Document, allocator := context.allocator) -> Error

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`patch`	`Document`	Borrowed for the call	Required	One borrowed entity-keyed merge-patch document, as `merge_patch` takes it. Temporary names use `#_name` and are scoped to this patch. Transaction metadata uses `#_tx`. The document is borrowed only until the call returns.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Invalid_Argument`	no bulk build is in progress
`.Rejected`	the database refuses the patch; the build has failed and later adds report the same status
`.Closed`	the database is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

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

Patch documents.

Examples

Queue patches in commit order

odin

495 B

stardust.bulk_begin(db) or_return
defer stardust.bulk_abort(db)
// The first entity of an empty database is 1, so the second patch updates it.
patch1 := stardust.parse(`{"#_ada":{"name":"Ada"}}`, .JSON) or_return
defer stardust.close(&patch1)
stardust.bulk_add(db, patch1) or_return
patch2 := stardust.parse(`{"1":{"title":"Countess"}}`, .JSON) or_return
defer stardust.close(&patch2)
stardust.bulk_add(db, patch2) or_return
summary := stardust.bulk_finish(db) or_return
stardust.close(&summary)

C exports: stardust_db_bulk_add

bulk_finish

odin

86 B

bulk_finish :: proc(db: Database, allocator := context.allocator) -> (Document, Error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`db`	`Database`	Borrowed for the call	Required	The database owner for this operation. Keep it alive during the call.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Invalid_Argument`	no bulk build is in progress
`.Rejected`	the database refuses a patch; an initial build publishes nothing and fallback keeps earlier commits
`.Conflict`	another write committed to the database during the build
`.Closed`	the database is closed
`.Out_Of_Memory`	native memory is exhausted

Notes

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

The summary contains:

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

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

Examples

Load patches with one commit and read the summary

odin

424 B

stardust.bulk_begin(db) or_return
defer stardust.bulk_abort(db)
patch := stardust.parse(`{"#_ada":{"name":"Ada","title":"Countess"}}`, .JSON) or_return
defer stardust.close(&patch)
stardust.bulk_add(db, patch) or_return
// Finish ends the build also when it fails.
summary := stardust.bulk_finish(db) or_return
defer stardust.close(&summary)
// summary holds status, patches, transactions, facts, entities and phase timings.

C exports: stardust_db_bulk_finish, stardust_result_take_document, stardust_result_error, stardust_result_release

bulk_abort

odin

32 B

bulk_abort :: proc(db: Database)

Parameters

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

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

odin

258 B

stardust.bulk_begin(db) or_return
// Abort writes nothing; without a build it does nothing.
defer stardust.bulk_abort(db)
patch := stardust.parse(`{"#_ada":{"name":"Ada"}}`, .JSON) or_return
defer stardust.close(&patch)
stardust.bulk_add(db, patch) or_return

C exports: stardust_db_bulk_abort

subscription_set_notify

odin

37 B

Notify :: #type proc "c"(ctx: rawptr)

odin

136 B

subscription_set_notify :: proc(
	subscription: Subscription,
	notify: Notify,
	ctx: rawptr,
	allocator := context.allocator,
) -> Error

Parameters

Parameter	Requirement	Meaning
`subscription`	Required	Subscription receiving the callback. Use the handle exclusively during registration.
`notify`	Required	Readiness callback.
`ctx`	nil is valid	Caller-owned state, passed unchanged to the callback. Stardust does not read or free it.
`allocator`	context.allocator	Allocator for copied error diagnostics.

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 close 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.

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

odin

1.4 kB

definition := stardust.parse(query_text, .TRON) or_return
defer stardust.close(&definition)
query := stardust.query(db, definition) or_return
defer stardust.close(&query)

Waiter :: struct {
	mutex: sync.Mutex,
	changed: sync.Cond,
	generation: i64,
}
waiter: Waiter
notify :: proc "c" (ctx: rawptr) {
	state := (^Waiter)(ctx)
	sync.mutex_lock(&state.mutex)
	state.generation += 1
	sync.cond_broadcast(&state.changed)
	sync.mutex_unlock(&state.mutex)
}
subscription := stardust.subscribe(query) or_return
// Deferred close joins callbacks before this stack context leaves scope.
defer stardust.close(&subscription)
stardust.subscription_set_notify(subscription, notify, &waiter) or_return

started := time.tick_now()
result: stardust.Document
for {
	sync.mutex_lock(&waiter.mutex)
	observed := waiter.generation
	sync.mutex_unlock(&waiter.mutex)
	event, error := stardust.next(subscription, 0)
	if error == nil {result = event.result; break}
	failure := error.(stardust.Failure)
	if failure.status != .Timeout {return error}
	sync.mutex_lock(&waiter.mutex)
	for waiter.generation == observed {
		remaining := 5*time.Second-time.tick_since(started)
		if remaining <= 0 {break}
		_ = sync.cond_wait_with_timeout(&waiter.changed, &waiter.mutex, remaining)
	}
	timed_out := waiter.generation == observed
	sync.mutex_unlock(&waiter.mutex)
	if timed_out {return error}
	stardust.close(&error)
}
defer stardust.close(&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

run_options

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

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

commit

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

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

event

This record contains the result of subscription next.

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