Definitions

The example stores a query definition and executes it with different variables. It then changes the query ordering and updates the people that the query selects.

Example

Run stored definitions by path

clojure174 B
(with-open [promote (sd/mutation db "people/promote")]
  (sd/run promote))
(with-open [query (sd/query db "people/by_role")
            rows (sd/run query)]
  (sd/next rows))
TRON89 B
0054 52 4F 4Emagic TRON
044C 6E616D65txt "name"
093C 416461txt "Ada"
0D0F 0A 04000000 0900 0000map leaf, size 10: @4 → @9
174C 6E616D65txt "name"
1C3C 426F62txt "Bob"
200F 0A 17000000 1C00 0000map leaf, size 10: @17 → @1C
2A4C 6E616D65txt "name"
2F2C 4379txt "Cy"
320F 0A 2A000000 2F00 0000map leaf, size 10: @2A → @2F
3C0E 15 00 0700 030000 00 0D000000 200000 00 32000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32

Definition versions

A transaction records each committed change to a stored definition.

  • An open definition handle identifies its stored path, so later calls can select the applicable version.
  • To read a specific historical version, use the as_of rules below.

Stored query and mutation plans

The plan operation below reads and controls the accepted plan for a stored query or mutation. It works without a planner plugin. Mutation selections use the query planner and report selection feedback. Background trials of a mutation execute its selection only. They do not apply its patch.

The adaptive planner can retain separate plans for exact parameter values. Values without a retained plan use the shared fallback plan. Measured repeated-use savings must justify the lookup, trial and storage costs within the database memory budget. Optional anchor probes can improve estimates when their measured cost justifies the work. An incomplete probe supplies a lower bound and cannot prove that a query is empty.

Use explain for the current accepted state and its paged revision history. Use status for the current state alone, or history for a history page. Each history entry includes the plan version, source and reason for the change. Trial reasons report the candidates and their measured outcomes.

The pin action prevents automatic replacement for every parameter value. The unpin action permits learning again. The replan action rebuilds the fallback plan and clears specialized parameter plans. It preserves the global pin. The revert action restores a complete historical state, including its pin and parameter plans. Revert requires the exact plan transaction and the same authored definition revision.

Explicit changes compare both authored and accepted plan revisions inside the commit. A concurrent definition or plan change reports conflict. Every returned plan document owns its buffers and remains readable after the database closes.

Operations

OperationReturnsSummary
definitiondocumentdatabase.definition(kind, path, as_of) returns an owned authored definition document.
plandocumentdatabase.plan(kind, path, action, argument, page_size, max_bytes) reads or explicitly controls a stored query or mutation plan.
definitionsdocumentdatabase.definitions(kind, pattern) returns an owned array document of sorted matching definition paths.
patch-definitioncommitdatabase.patch_definition(kind, path, patch) validates and stores a definition merge patch and returns commit information.

definition

clojure14 B
[db kind path]
clojure20 B
[db kind path as-of]

Parameters

ParameterTypeOwnershipDefaultMeaning
dbDatabaseBorrowed for the callRequiredThe database owner for this operation. Keep it alive during the call.
kindNameValueRequiredThe definition folder kind.
pathNameValueRequiredThe stored definition path.
as-oflongValueAbsentThe committed snapshot to read. Zero selects the latest snapshot.

Errors

StatusWhen
:not-foundno definition is stored at the path
:closedthe database is closed
:out-of-memorynative memory is exhausted

Examples

Read a stored query definition

clojure44 B
(sd/definition db :queries "people/by_role")
TRON264 B
00054 52 4F 4Emagic TRON
0045C 3F6E616D65txt "?name"
00A0E 0D 00 0100 010000 00 04000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
0175C 3F6E616D65txt "?name"
01D0E 0D 00 0100 010000 00 17000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @17
02A5C 3F726F6C65txt "?role"
0308C 656E67696E6565 72txt "engineer"
0390F 0A 2A000000 3000 0000map leaf, size 10: @2A → @30
0432C 3F65txt "?e"
0464C 726F6C65txt "role"
04B5C 3F726F6C65txt "?role"
0510E 15 00 0700 030000 00 43000000 460000 00 4B000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @43 → @46 → @4B
0662C 3F65txt "?e"
0694C 6E616D65txt "name"
06E5C 3F6E616D65txt "?name"
0740E 15 00 0700 030000 00 66000000 690000 00 6E000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @66 → @69 → @6E
0890E 11 00 0300 020000 00 51000000 740000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @51 → @74
09A5C 7768657265txt "where"
0A00F 0A 9A000000 8900 0000map leaf, size 10: @9A → @89
0AA4C 66696E64txt "find"
0AF0F 0A AA000000 0A00 0000map leaf, size 10: @AA → @A
0B9AC 706172616D6574 657273txt "parameters"
0C40F 0A B9000000 3900 0000map leaf, size 10: @B9 → @39
0CE7C 6F726465724279txt "orderBy"
0D60F 0A CE000000 1D00 0000map leaf, size 10: @CE → @1D
0E007 0E 20080000 C400 0000 D6000000map branch, size 14, depth 1, slots 5, 11: @C4 → @D6
0EE07 12 2A000000 A000 0000 AF000000 E000 0000map branch, size 18, depth 0 (root), slots 1, 3, 5: @A0 → @AF → @E0

C exports: stardust_db_definition_get, stardust_result_take_document, stardust_result_error, stardust_result_release

plan

clojure21 B
[db kind path action]
clojure50 B
[db kind path action argument page-size max-bytes]

Parameters

ParameterTypeOwnershipDefaultMeaning
dbDatabaseBorrowed for the callRequiredThe database owner for this operation. Keep it alive during the call.
kindNameValueRequiredqueries or mutations.
pathNameValueRequiredThe stored definition path.
actionNameValueRequiredexplain, status, history, pin, unpin, replan or revert. Pin prevents every automatic replacement. Replan chooses a statistics plan and preserves a pin. Unpin permits learning. Revert restores an exact earlier plan transaction only if its authored revision still matches; it preserves that revision's pin.
argumentIntegerValueAbsentFor history or explain, the exclusive lower transaction bound, or zero to start. For revert, the exact historical plan transaction. Other actions require zero.
page-sizeIntegerValueAbsentFor history or explain, the positive maximum revision count. Other actions require zero. History remains durable; this count only bounds one response.
max-bytesIntegerValueAbsentFor history or explain, the positive diagnostic buffer capacity in bytes. The database may grant less. Exhaustion reports out_of_memory with no partial response. Other actions require zero. Returned documents own independent buffers after the call.

Errors

StatusWhen
:invalid-argumentthe kind, action, revision or page limits are invalid, or the selected plan cannot run the current authored definition
:not-foundthe definition or exact historical plan revision does not exist
:conflictthe authored definition or accepted plan changed before the explicit control committed
:closedthe database is closed
:out-of-memorynative memory is exhausted

Examples

Pin a plan and explain its revision history

clojure144 B
(with-open [pinned (sd/plan db :queries "people/by_role" :pin)]
  (sd/root pinned))
(sd/plan db :queries "people/by_role" :explain 0 16 1048576)
TRON1 kB
00054 52 4F 4Emagic TRON
0041C 31txt "1"
00602 00000000000000 00i64 0
00F0F 0A 04000000 0600 0000map leaf, size 10: @4 → @6
01902 00000000000000 00i64 0
02202 01000000000000 00i64 1
02B0E 11 00 0300 020000 00 19000000 220000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @19 → @22
03C4C 68617368txt "hash"
0410F 0A 3C000000 0F00 0000map leaf, size 10: @3C → @F
04B7C 76657273696F6Etxt "version"
05302 01000000000000 00i64 1
05C0F 0A 4B000000 5300 0000map leaf, size 10: @4B → @53
066AC 706172616D6574 657273txt "parameters"
0710Ctxt ""
0720F 0A 66000000 7100 0000map leaf, size 10: @66 → @71
07C6C 666F726D6174txt "format"
08302 02000000000000 00i64 2
08C0F 0A 7C000000 8300 0000map leaf, size 10: @7C → @83
09607 0E 20200000 7200 0000 8C000000map branch, size 14, depth 1, slots 5, 13: @72 → @8C
0A46C 70696E6E6564txt "pinned"
0AB09bit true
0AC0F 0A A4000000 AB00 0000map leaf, size 10: @A4 → @AB
0B65C 6F72646572txt "order"
0BC0F 0A B6000000 2B00 0000map leaf, size 10: @B6 → @2B
0C607 0E 82000000 AC00 0000 BC000000map branch, size 14, depth 1, slots 1, 7: @AC → @BC
0D46C 736F75726365txt "source"
0DB7C 506C616E6E6564txt "Planned"
0E30F 0A D4000000 DB00 0000map leaf, size 10: @D4 → @DB
0ED7C 736574746C6564txt "settled"
0F501bit false
0F60F 0A ED000000 F500 0000map leaf, size 10: @ED → @F5
10007 0E 01200000 E300 0000 F6000000map branch, size 14, depth 1, slots 0, 13: @E3 → @F6
Show all 100 nodes
10E8C 7265766973696F 6Etxt "revision"
11714 10 376537646533 3266333366353038 6135txt "7e7de32f33f508a5"
1290F 0A 0E010000 1701 0000map leaf, size 10: @10E → @117
1336C 706F6C696379txt "policy"
13A14 10 303030303030 3030303030303030 3030txt "0000000000000000"
14C0F 0A 33010000 3A01 0000map leaf, size 10: @133 → @13A
1566C 726561736F6Etxt "reason"
15DCC 6578706C696369 742070696Etxt "explicit pin"
16A0F 0A 56010000 5D01 0000map leaf, size 10: @156 → @15D
17407 26 EA0D0000 4100 0000 5C000000 9600 0000 C6000000 0001 0000 29010000 4C01 0000 6A010000map branch, size 38, depth 0 (root), slots 1, 3, 5, 6, 7, 8, 10, 11: @41 → @5C → @96 → @C6 → @100 → @129 → @14C → @16A
19A1C 31txt "1"
19C02 00000000000000 00i64 0
1A50F 0A 9A010000 9C01 0000map leaf, size 10: @19A → @19C
1AF02 00000000000000 00i64 0
1B802 01000000000000 00i64 1
1C10E 11 00 0300 020000 00 AF010000 B80100 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @1AF → @1B8
1D24C 68617368txt "hash"
1D70F 0A D2010000 A501 0000map leaf, size 10: @1D2 → @1A5
1E17C 76657273696F6Etxt "version"
1E902 01000000000000 00i64 1
1F20F 0A E1010000 E901 0000map leaf, size 10: @1E1 → @1E9
1FCAC 706172616D6574 657273txt "parameters"
2070Ctxt ""
2080F 0A FC010000 0702 0000map leaf, size 10: @1FC → @207
2126C 666F726D6174txt "format"
21902 02000000000000 00i64 2
2220F 0A 12020000 1902 0000map leaf, size 10: @212 → @219
22C07 0E 20200000 0802 0000 22020000map branch, size 14, depth 1, slots 5, 13: @208 → @222
23A6C 70696E6E6564txt "pinned"
24109bit true
2420F 0A 3A020000 4102 0000map leaf, size 10: @23A → @241
24C5C 6F72646572txt "order"
2520F 0A 4C020000 C101 0000map leaf, size 10: @24C → @1C1
25C07 0E 82000000 4202 0000 52020000map branch, size 14, depth 1, slots 1, 7: @242 → @252
26A6C 736F75726365txt "source"
2717C 506C616E6E6564txt "Planned"
2790F 0A 6A020000 7102 0000map leaf, size 10: @26A → @271
2837C 736574746C6564txt "settled"
28B01bit false
28C0F 0A 83020000 8B02 0000map leaf, size 10: @283 → @28B
29607 0E 01200000 7902 0000 8C020000map branch, size 14, depth 1, slots 0, 13: @279 → @28C
2A48C 7265766973696F 6Etxt "revision"
2AD14 10 376537646533 3266333366353038 6135txt "7e7de32f33f508a5"
2BF0F 0A A4020000 AD02 0000map leaf, size 10: @2A4 → @2AD
2C96C 706F6C696379txt "policy"
2D014 10 303030303030 3030303030303030 3030txt "0000000000000000"
2E20F 0A C9020000 D002 0000map leaf, size 10: @2C9 → @2D0
2EC6C 726561736F6Etxt "reason"
2F3CC 6578706C696369 742070696Etxt "explicit pin"
3000F 0A EC020000 F302 0000map leaf, size 10: @2EC → @2F3
30A07 26 EA0D0000 D701 0000 F2010000 2C02 0000 5C020000 9602 0000 BF020000 E202 0000 00030000map branch, size 38, depth 0 (root), slots 1, 3, 5, 6, 7, 8, 10, 11: @1D7 → @1F2 → @22C → @25C → @296 → @2BF → @2E2 → @300
3304C 706C616Etxt "plan"
3350F 0A 30030000 0A03 0000map leaf, size 10: @330 → @30A
33FBC 7472616E736163 74696F6Etxt "transaction"
34B02 0C000000000000 00i64 12
3540F 0A 3F030000 4B03 0000map leaf, size 10: @33F → @34B
35E07 0E 02020000 3503 0000 54030000map branch, size 14, depth 0 (root), slots 1, 9: @335 → @354
36C0E 0D 00 0100 010000 00 5E030000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @35E
3794C 706C616Etxt "plan"
37E0F 0A 79030000 7401 0000map leaf, size 10: @379 → @174
388BC 7472616E736163 74696F6Etxt "transaction"
39402 0C000000000000 00i64 12
39D0F 0A 88030000 9403 0000map leaf, size 10: @388 → @394
3A77C 686973746F7279txt "history"
3AF0F 0A A7030000 6C03 0000map leaf, size 10: @3A7 → @36C
3B9AC 6E6578745F6166 746572txt "next_after"
3C402 00000000000000 00i64 0
3CD0F 0A B9030000 C403 0000map leaf, size 10: @3B9 → @3C4
3D707 16 024A0000 7E03 0000 9D030000 AF03 0000 CD030000map branch, size 22, depth 0 (root), slots 1, 9, 11, 14: @37E → @39D → @3AF → @3CD

C exports: stardust_db_plan, stardust_result_take_document, stardust_result_error, stardust_result_release

definitions

clojure9 B
[db kind]
clojure17 B
[db kind pattern]

Parameters

ParameterTypeOwnershipDefaultMeaning
dbDatabaseBorrowed for the callRequiredThe database owner for this operation. Keep it alive during the call.
kindNameValueRequiredThe definition folder kind.
patternNameValueAbsentThe pattern for definition paths. An absent pattern selects all paths in the requested folder.

Errors

StatusWhen
:invalid-argumentthe kind or the pattern is invalid
:closedthe database is closed
:out-of-memorynative memory is exhausted

Examples

database/definitions

clojure40 B
(sd/definitions db :queries "people/.*")
TRON40 B
0054 52 4F 4Emagic TRON
04EC 70656F706C652F 62795F726F6C65txt "people/by_role"
130E 0D 00 0100 010000 00 04000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4

database/definitions

clojure40 B
(sd/definitions db :queries "people/.*")
TRON21 B
0054 52 4F 4Emagic TRON
040E 09 00 0000 000000 00array leaf, size 9, shift 0, bitmap 0000, count 0 (root)

database/definitions

clojure40 B
(sd/definitions db :queries "people/.*")
TRON40 B
0054 52 4F 4Emagic TRON
04EC 70656F706C652F 62795F726F6C65txt "people/by_role"
130E 0D 00 0100 010000 00 04000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4

database/definitions

clojure40 B
(sd/definitions db :queries "people/.*")
TRON21 B
0054 52 4F 4Emagic TRON
040E 09 00 0000 000000 00array leaf, size 9, shift 0, bitmap 0000, count 0 (root)

C exports: stardust_db_definition_list, stardust_result_take_document, stardust_result_error, stardust_result_release

patch-definition

clojure20 B
[db kind path patch]

Parameters

ParameterTypeOwnershipDefaultMeaning
dbDatabaseBorrowed for the callRequiredThe database owner for this operation. Keep it alive during the call.
kindNameValueRequiredThe definition folder kind.
pathNameValueRequiredThe stored definition path.
patchDocumentBorrowed for the callRequiredAn object merges or creates the definition. Null deletes it.

Errors

StatusWhen
:invalid-definitionthe patched definition is invalid
:closedthe database is closed
:out-of-memorynative memory is exhausted

Examples

database/patch_definition

definition-text holds this document:

TRON264 B
00054 52 4F 4Emagic TRON
0045C 3F726F6C65txt "?role"
00A8C 656E67696E6565 72txt "engineer"
0130F 0A 04000000 0A00 0000map leaf, size 10: @4 → @A
01D5C 3F6E616D65txt "?name"
0230E 0D 00 0100 010000 00 1D000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @1D
0302C 3F65txt "?e"
0334C 726F6C65txt "role"
0385C 3F726F6C65txt "?role"
03E0E 15 00 0700 030000 00 30000000 330000 00 38000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @30 → @33 → @38
0532C 3F65txt "?e"
0564C 6E616D65txt "name"
05B5C 3F6E616D65txt "?name"
0610E 15 00 0700 030000 00 53000000 560000 00 5B000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @53 → @56 → @5B
0760E 11 00 0300 020000 00 3E000000 610000 00array leaf, size 17, shift 0, bitmap 0003, count 2 (root): @3E → @61
0875C 3F6E616D65txt "?name"
08D0E 0D 00 0100 010000 00 87000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @87
09A5C 7768657265txt "where"
0A00F 0A 9A000000 7600 0000map leaf, size 10: @9A → @76
0AA4C 66696E64txt "find"
0AF0F 0A AA000000 2300 0000map leaf, size 10: @AA → @23
0B9AC 706172616D6574 657273txt "parameters"
0C40F 0A B9000000 1300 0000map leaf, size 10: @B9 → @13
0CE7C 6F726465724279txt "orderBy"
0D60F 0A CE000000 8D00 0000map leaf, size 10: @CE → @8D
0E007 0E 20080000 C400 0000 D6000000map branch, size 14, depth 1, slots 5, 11: @C4 → @D6
0EE07 12 2A000000 A000 0000 AF000000 E000 0000map branch, size 18, depth 0 (root), slots 1, 3, 5: @A0 → @AF → @E0
clojure121 B
(with-open [definition (sd/parse definition-text :tron)]
  (sd/patch-definition db :queries "people/by_role" definition))
TRON179 B
0054 52 4F 4Emagic TRON
040F 02map leaf, size 2
063C 696473txt "ids"
0A0F 0A 06000000 0400 0000map leaf, size 10: @6 → @4
146C 737461747573txt "status"
1B9C 636F6D6D697474 6564txt "committed"
250F 0A 14000000 1B00 0000map leaf, size 10: @14 → @1B
2F07 0E 02040000 0A00 0000 25000000map branch, size 14, depth 1, slots 1, 10: @A → @25
3DBC 7472616E736163 74696F6Etxt "transaction"
4902 03000000000000 00i64 3
520F 0A 3D000000 4900 0000map leaf, size 10: @3D → @49
5CCC 636F6D6D697474 65645F6174txt "committed_at"
6902 798CF53F35AD3F 00i64 17923367750700153
720F 0A 5C000000 6900 0000map leaf, size 10: @5C → @69
7C5C 6661637473txt "facts"
8202 00000000000000 00i64 0
8B0F 0A 7C000000 8200 0000map leaf, size 10: @7C → @82
9507 16 01460000 2F00 0000 52000000 7200 0000 8B000000map branch, size 22, depth 0 (root), slots 0, 9, 10, 14: @2F → @52 → @72 → @8B

C exports: stardust_db_definition_patch, stardust_db_result_commit_info, stardust_result_error, stardust_result_release