Errors

A call can fail because a definition is missing, a document is invalid, or the database refuses a change. The examples use the people data to show these results. Use the status and diagnostic fields to identify the failure.

Binding errors

Language	Failure
C	Returns a status. The owner that its operation names holds the diagnostic.
Go	Returns `*Error`.
Rust	Returns `Result<_, Error>`.
Clojure	Throws `clojure.lang.ExceptionInfo` with diagnostic data.
Python	Raises `StardustError`.
Odin	Returns an `Error` beside its result.

The error record gives the fields in your language. Statuses gives the failure conditions of each operation.

error

This record describes a failure with its status and diagnostic. The binding copies the diagnostic before it releases the native owner.

Field	Type	Unit	Absent
`code`	`string`	None	—
`message`	`string`	None	—
`path`	`Maybe(string)`	None	nil
`field`	`Maybe(string)`	None	nil
`entity`	`Maybe(builtin.i64)`	None	nil
`offset`	`Maybe(builtin.i64)`	Bytes	nil
`status`	`Status`	None	—

Statuses

Each status names a class of failure. The table lists codes from the binding. Native diagnostic codes can differ.

.Invalid_Argument

Codes: time_out_of_range, invalid_argument, out_of_range, non_finite_number, cycle, unsupported_type, too_large, native_failure, live_children, wrong_kind, not_integral, inexact_number, missing_field, unknown_field, duplicate_field, too_deep, length_mismatch, malformed_tag, ambiguous_field, ambiguous_variant, invalid_value, hook_failed.

When	Operations
the entity ID is outside the user entity range, `max_depth` is negative or above 32, or `max_entities` is negative	`read_entity`
the text is malformed, the format is unknown or a number is outside `i64` or finite `f64`	`parse`
the format is unknown or the width is negative	`serialize`
the text is malformed, a format is unknown or the width is negative	`convert`
the node breaks the preorder rules or has an invalid kind or number	`add`
a node breaks the preorder rules or has an invalid kind or number	`add_many`
the builder has no root or a container is still open	`seal`
id is not a node of the document	`read`, `child_iterator`
start is past the last node or capacity is negative	`read_many`
id is not an object node of the document	`member`
the node is not an integer number	`i64`
the node is not a number or its value overflows `f64`	`f64`
the arguments include an undeclared macro parameter	`build_macro`, `expand_macro`
the file is not a database, an option is invalid or selected plugins are incompatible	`open`
the parameters or run options are invalid	`run`, `run`
the parameters or subscription options are invalid	`subscribe`
`max_wait` is negative	`next`, `indexes_sync`
the patch is not an entity-keyed object, or a link names an ID outside the user entity range	`merge_patch`
the kind, action, revision or page limits are invalid, or the selected plan cannot run the current authored definition	`plan`
the kind or the pattern is invalid	`definitions`
a bulk build is already in progress on the database	`bulk_begin`
no bulk build is in progress	`bulk_add`, `bulk_finish`
a name is empty, the plugin has no call operation with the name, or the plugin refuses the request	`plugin_call`
a name is empty, the plugin has no stream operation with the name, or the plugin refuses the request	`plugin_stream`
the stream has finished or does not accept writes	`write`
the stream does not support reads, or length is negative	`read`
the stream does not support seeks, whence is unknown, or the position is negative or past the `i64` range	`seek`
the stream has finished or has no finish step	`finish`
the token is empty or longer than 4096 bytes	`activate`
entity is not a user entity	`objects_get`, `objects_path`
the parent or the name is invalid, or the parent is a file	`objects_lookup`
the parent is invalid or is a file	`objects_children`
the digest is not 64 hexadecimal digits	`objects_files`, `objects_manifest`, `objects_open`
the array is empty or malformed, a name is invalid, or a parent is a file	`objects_create`
the entity is a directory or invalid, the digest is malformed, or `expected_revision` is negative	`objects_update`
the request is malformed, the destination is a file or inside the node, the kinds differ, or a replaced directory is not empty	`objects_move`
the entity is invalid, the directory is not empty, or `expected_revision` is negative	`objects_remove`
options is not an object, or an option is invalid, duplicated or unsupported	`reactors_sync`, `backups_sync`, `sdk_sync`

.Invalid_JSON

When	Operations
JSON text is malformed	`parse`, `convert`

.Compile_Failed

When	Operations
the expression does not compile	`build`
the expansion does not compile	`build_macro`
the expanded expression does not compile	`expression`

.Evaluation_Failed

When	Operations
the expression fails on the input	`evaluate`
the query fails or exceeds `max_cost`	`run`
the page does not render	`next`
a page does not render	`page_iterator`, `all_pages`
a rerun of the query failed. Every later call reports this failure	`next`
the mutation fails	`run`
the plugin cannot read its stored state	`plugin_call`, `plugin_stream`
stored bytes do not match their digest	`read`
stored tree metadata or the manifest of a named payload is corrupted	`objects_get`, `objects_lookup`, `objects_children`, `objects_path`
the stored manifest is corrupted	`objects_manifest`, `objects_open`

.Out_Of_Memory

Codes: out_of_memory.

When Operations

native memory is exhausted read_entity, parse, serialize, convert, builder, add, add_many, seal, build, build_macro, expand_macro, evaluate, open, query, mutation, expression, run, next, page_iterator, all_pages, subscribe, next, run, merge_patch, definition, plan, definitions, patch_definition, bulk_begin, bulk_add, bulk_finish, plugin_call, plugin_stream, finish, plugins, objects_get, objects_lookup, objects_children, objects_path, objects_files, objects_manifest, objects_create, objects_update, objects_move, objects_remove, objects_upload, objects_open, reactors_status, backups_status, sdk_status

When	Operations
native memory is exhausted	`read_entity`, `parse`, `serialize`, `convert`, `builder`, `add`, `add_many`, `seal`, `build`, `build_macro`, `expand_macro`, `evaluate`, `open`, `query`, `mutation`, `expression`, `run`, `next`, `page_iterator`, `all_pages`, `subscribe`, `next`, `run`, `merge_patch`, `definition`, `plan`, `definitions`, `patch_definition`, `bulk_begin`, `bulk_add`, `bulk_finish`, `plugin_call`, `plugin_stream`, `finish`, `plugins`, `objects_get`, `objects_lookup`, `objects_children`, `objects_path`, `objects_files`, `objects_manifest`, `objects_create`, `objects_update`, `objects_move`, `objects_remove`, `objects_upload`, `objects_open`, `reactors_status`, `backups_status`, `sdk_status`

.Not_Found

Codes: not_found.

When	Operations
the object has no member with the key	`member`
the macro refers to an unknown macro	`build_macro`, `expand_macro`
the parent directory is missing, or the file is missing and create is false	`open`
no definition is stored at the path	`query`, `mutation`, `definition`
no expression is stored at the path	`expression`
the stored query definition was deleted	`run`
the definition or exact historical plan revision does not exist	`plan`
the plugin reports that the request names nothing it holds	`plugin_call`, `plugin_stream`
no object node has the entity	`objects_get`
the parent has no child with the name, or the parent does not exist	`objects_lookup`
the parent does not exist	`objects_children`
the node or one of its ancestors does not exist	`objects_path`
no payload with the digest is published	`objects_manifest`, `objects_open`
a parent does not exist or a digest is not published	`objects_create`
the file does not exist or the digest is not published	`objects_update`
the node or the destination does not exist	`objects_move`
the node does not exist	`objects_remove`

.Locked

When	Operations
another process holds the lock after `lock_timeout`	`open`

.Conflict

When	Operations
an enabled plugin finds the database inconsistent with its copies: backups refuse diverging copies with code `backup_history_divergent`, naming them	`open`
concurrent writes prevent the commit	`run`
an entity revision check fails or a concurrent writer prevents the commit; a revision mismatch reports the entity and expected and actual revisions	`merge_patch`
the authored definition or accepted plan changed before the explicit control committed	`plan`
another write committed to the database during the build	`bulk_finish`
the plugin's write lost to a concurrent change, or the database holds writes	`plugin_call`
the database holds writes	`plugin_stream`, `finish`, `objects_upload`
the database holds writes while the plugin stores the bytes	`write`
a name is already taken in its parent or appears twice, or the database holds writes	`objects_create`
`expected_revision` is stale, or the database holds writes	`objects_update`, `objects_remove`
the name is occupied without replace, `expected_revision` is stale, or the database holds writes	`objects_move`

.Invalid_Definition

When	Operations
the macro is invalid or expands recursively	`build_macro`, `expand_macro`
the definition is invalid	`query`, `mutation`
a macro it calls is invalid or expands recursively	`expression`
the loaded query definition is invalid	`run`
the query or its callable definitions are invalid	`subscribe`
the mutation selection or definition is invalid	`run`
the patched definition is invalid	`patch_definition`

.Schema_Violation

When	Operations
the write breaks a schema	`run`

.Invalid_Commit_Time

When	Operations
the `#_tx` commit time is not later than the last commit	`merge_patch`

.Closed

Codes: closed.

When	Operations
the database is closed	`read_entity`, `query`, `mutation`, `expression`, `merge_patch`, `definition`, `plan`, `definitions`, `patch_definition`, `indexes_sync`, `bulk_begin`, `bulk_add`, `bulk_finish`, `plugin_call`, `plugin_stream`, `objects_get`, `objects_lookup`, `objects_children`, `objects_path`, `objects_files`, `objects_manifest`, `objects_create`, `objects_update`, `objects_move`, `objects_remove`, `objects_upload`, `objects_open`, `reactors_status`, `reactors_sync`, `backups_status`, `backups_sync`, `sdk_status`, `sdk_sync`
the document is closed	`serialize`, `root`, `count`, `read`, `read_many`, `member`, `child_iterator`, `i64`, `f64`
the builder is closed	`add`, `add_many`, `seal`
the program is closed	`evaluate`
the query is closed	`run`, `subscribe`
the rows is closed	`next`, `page_iterator`, `all_pages`
the subscription is closed	`next`
the mutation is closed	`run`
the `plugin_stream` is closed	`write`, `read`, `seek`, `finish`

.Rejected

When	Operations
a mutation target or write guard refuses the write	`run`
the database refuses the patch; the code and diagnostic path name the reason and key	`merge_patch`
the database refuses the patch; the build has failed and later adds report the same status	`bulk_add`
the database refuses a patch; an initial build publishes nothing and fallback keeps earlier commits	`bulk_finish`

.Unsupported

Codes: abi_version, core_digest.

When	Operations
found differs from the ABI version of the binding	`check_version`

.Cancelled

Codes: cancelled.

When	Operations
the subscription is cancelled or closed	`next`

.Timeout

When	Operations
`max_wait` passed first	`indexes_sync`
the plugin's wait passed its limit	`plugin_call`
maxWait passed before the work finished	`reactors_sync`, `sdk_sync`
maxWait passed before every target confirmed	`backups_sync`

.Unavailable

When	Operations
an enabled plugin cannot reach what the open needs: backups refuse with `backup_targets_unreachable`, `backup_target_unreadable` or `backup_objects_required`	`open`
the patch sets stardust/history and no enabled plugin purges history	`run`, `merge_patch`
the plugin is unknown or the database does not enable it	`plugin_call`, `plugin_stream`
the database does not enable the objects plugin	`objects_get`, `objects_lookup`, `objects_children`, `objects_path`, `objects_files`, `objects_manifest`, `objects_create`, `objects_update`, `objects_move`, `objects_remove`, `objects_upload`, `objects_open`
the database does not enable the reactors plugin	`reactors_status`, `reactors_sync`
the database does not enable the backups plugin	`backups_status`, `backups_sync`
the database does not enable the sdk plugin	`sdk_status`, `sdk_sync`

.Failed

When	Operations
the plugin's work failed	`plugin_call`
the plugin's work failed; status describes the failure	`reactors_sync`, `backups_sync`, `sdk_sync`

.Unlicensed

Codes: unlicensed.

When	Operations
the token is refused; the error names the reason	`activate`

Refusal examples

The generator captured each result from the native library.

Describe the backup runtime

odin

105 B

failed, result := stardust.backups_status(db)
defer stardust.close(&failed)
defer stardust.close(&result)

TRON

226 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	BC 756E617661696C 61626C65	txt "unavailable"
17	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
21	6C 656E74697479	txt "entity"
28	00	nil
29	0F 0A 21000000 2800 0000	map leaf, size 10: @21 → @28
33	7C 6D657373616765	txt "message"
3B	14 19 74686520706C 7567696E20697320 6E6F7420656E6162 6C6564	txt "the plugin is not enable…"
56	0F 0A 33000000 3B00 0000	map leaf, size 10: @33 → @3B
60	07 0E 08020000 2900 0000 56000000	map branch, size 14, depth 1, slots 3, 9: @29 → @56
6E	4C 70617468	txt "path"
73	00	nil
74	0F 0A 6E000000 7300 0000	map leaf, size 10: @6E → @73
7E	5C 6669656C64	txt "field"
84	00	nil
85	0F 0A 7E000000 8400 0000	map leaf, size 10: @7E → @84
8F	4C 636F6465	txt "code"
94	BC 756E617661696C 61626C65	txt "unavailable"
A0	0F 0A 8F000000 9400 0000	map leaf, size 10: @8F → @94
AA	6C 6F6666736574	txt "offset"
B1	00	nil
B2	0F 0A AA000000 B100 0000	map leaf, size 10: @AA → @B1
BC	07 1E 51620000 1700 0000 60000000 7400 0000 85000000 A000 0000 B2000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @17 → @60 → @74 → @85 → @A0 → @B2
DA	BC000000 00000000	root → @BC; previous: none

Wait until every target stored the history

odin

188 B

sync_options := stardust.parse(`{maxWait {#dur PT5S}}`, .DUST) or_return
defer stardust.close(&sync_options)
result := stardust.backups_sync(db, sync_options)
defer stardust.close(&result)

TRON

226 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	BC 756E617661696C 61626C65	txt "unavailable"
17	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
21	6C 656E74697479	txt "entity"
28	00	nil
29	0F 0A 21000000 2800 0000	map leaf, size 10: @21 → @28
33	7C 6D657373616765	txt "message"
3B	14 19 74686520706C 7567696E20697320 6E6F7420656E6162 6C6564	txt "the plugin is not enable…"
56	0F 0A 33000000 3B00 0000	map leaf, size 10: @33 → @3B
60	07 0E 08020000 2900 0000 56000000	map branch, size 14, depth 1, slots 3, 9: @29 → @56
6E	4C 70617468	txt "path"
73	00	nil
74	0F 0A 6E000000 7300 0000	map leaf, size 10: @6E → @73
7E	5C 6669656C64	txt "field"
84	00	nil
85	0F 0A 7E000000 8400 0000	map leaf, size 10: @7E → @84
8F	4C 636F6465	txt "code"
94	BC 756E617661696C 61626C65	txt "unavailable"
A0	0F 0A 8F000000 9400 0000	map leaf, size 10: @8F → @94
AA	6C 6F6666736574	txt "offset"
B1	00	nil
B2	0F 0A AA000000 B100 0000	map leaf, size 10: @AA → @B1
BC	07 1E 51620000 1700 0000 60000000 7400 0000 85000000 A000 0000 B2000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @17 → @60 → @74 → @85 → @A0 → @B2
DA	BC000000 00000000	root → @BC; previous: none

convert

duplicate_text holds this document:

TRON

24 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	BC 7B3A612031203A 6120327D	txt "{:a 1 :a 2}"
10	04000000 00000000	root → @4; previous: none

odin

271 B

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

view := stardust.read(source, stardust.root(source) or_return) or_return
failed, result := stardust.parse(view.text, .EDN)
defer stardust.close(&failed)
defer stardust.close(&result)

TRON

254 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	14 10 696E76616C69 645F617267756D65 6E74	txt "invalid_argument"
1D	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
27	6C 656E74697479	txt "entity"
2E	00	nil
2F	0F 0A 27000000 2E00 0000	map leaf, size 10: @27 → @2E
39	7C 6D657373616765	txt "message"
41	14 27 696E76616C69 642045444E202844 75706C6963617465 5F4B657929206174 206F666673657420 36	txt "invalid EDN (Duplicate_K…"
6A	0F 0A 39000000 4100 0000	map leaf, size 10: @39 → @41
74	07 0E 08020000 2F00 0000 6A000000	map branch, size 14, depth 1, slots 3, 9: @2F → @6A
82	4C 70617468	txt "path"
87	00	nil
88	0F 0A 82000000 8700 0000	map leaf, size 10: @82 → @87
92	5C 6669656C64	txt "field"
98	00	nil
99	0F 0A 92000000 9800 0000	map leaf, size 10: @92 → @98
A3	4C 636F6465	txt "code"
A8	BC 696E76616C6964 5F65646E	txt "invalid_edn"
B4	0F 0A A3000000 A800 0000	map leaf, size 10: @A3 → @A8
BE	6C 6F6666736574	txt "offset"
C5	02 06000000000000 00	i64 6
CE	0F 0A BE000000 C500 0000	map leaf, size 10: @BE → @C5
D8	07 1E 51620000 1D00 0000 74000000 8800 0000 99000000 B400 0000 CE000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @1D → @74 → @88 → @99 → @B4 → @CE
F6	D8000000 00000000	root → @D8; 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

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

Report a malformed byte at offset zero

malformed holds these bytes:

text

1 B

odin

110 B

failed, result := stardust.parse(malformed, .DUST)
defer stardust.close(&failed)
defer stardust.close(&result)

TRON

242 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	14 10 696E76616C69 645F617267756D65 6E74	txt "invalid_argument"
1D	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
27	6C 656E74697479	txt "entity"
2E	00	nil
2F	0F 0A 27000000 2E00 0000	map leaf, size 10: @27 → @2E
39	7C 6D657373616765	txt "message"
41	14 1A 496E76616C69 645F53796E746178 206174206F666673 65742030	txt "Invalid_Syntax at offset…"
5D	0F 0A 39000000 4100 0000	map leaf, size 10: @39 → @41
67	07 0E 08020000 2F00 0000 5D000000	map branch, size 14, depth 1, slots 3, 9: @2F → @5D
75	4C 70617468	txt "path"
7A	00	nil
7B	0F 0A 75000000 7A00 0000	map leaf, size 10: @75 → @7A
85	5C 6669656C64	txt "field"
8B	00	nil
8C	0F 0A 85000000 8B00 0000	map leaf, size 10: @85 → @8B
96	4C 636F6465	txt "code"
9B	CC 696E76616C6964 5F64757374	txt "invalid_dust"
A8	0F 0A 96000000 9B00 0000	map leaf, size 10: @96 → @9B
B2	6C 6F6666736574	txt "offset"
B9	02 00000000000000 00	i64 0
C2	0F 0A B2000000 B900 0000	map leaf, size 10: @B2 → @B9
CC	07 1E 51620000 1D00 0000 67000000 7B00 0000 8C000000 A800 0000 C2000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @1D → @67 → @7B → @8C → @A8 → @C2
EA	CC000000 00000000	root → @CC; previous: none

Report malformed DUST

malformed holds these bytes:

text

1 B

odin

110 B

failed, result := stardust.parse(malformed, .DUST)
defer stardust.close(&failed)
defer stardust.close(&result)

TRON

242 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	14 10 696E76616C69 645F617267756D65 6E74	txt "invalid_argument"
1D	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
27	6C 656E74697479	txt "entity"
2E	00	nil
2F	0F 0A 27000000 2E00 0000	map leaf, size 10: @27 → @2E
39	7C 6D657373616765	txt "message"
41	14 1A 556E65787065 637465645F456E64 206174206F666673 65742032	txt "Unexpected_End at offset…"
5D	0F 0A 39000000 4100 0000	map leaf, size 10: @39 → @41
67	07 0E 08020000 2F00 0000 5D000000	map branch, size 14, depth 1, slots 3, 9: @2F → @5D
75	4C 70617468	txt "path"
7A	00	nil
7B	0F 0A 75000000 7A00 0000	map leaf, size 10: @75 → @7A
85	5C 6669656C64	txt "field"
8B	00	nil
8C	0F 0A 85000000 8B00 0000	map leaf, size 10: @85 → @8B
96	4C 636F6465	txt "code"
9B	CC 696E76616C6964 5F64757374	txt "invalid_dust"
A8	0F 0A 96000000 9B00 0000	map leaf, size 10: @96 → @9B
B2	6C 6F6666736574	txt "offset"
B9	02 02000000000000 00	i64 2
C2	0F 0A B2000000 B900 0000	map leaf, size 10: @B2 → @B9
CC	07 1E 51620000 1D00 0000 67000000 7B00 0000 8C000000 A800 0000 C2000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @1D → @67 → @7B → @8C → @A8 → @C2
EA	CC000000 00000000	root → @CC; previous: none