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

clojure

174 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))

Result / 51 B

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

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

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

definition

clojure

14 B

[db kind path]

clojure

20 B

[db kind path as-of]

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.
`kind`	`Name`	Value	Required	The definition folder kind.
`path`	`Name`	Value	Required	The stored definition path.
`as-of`	`long`	Value	Absent	The committed snapshot to read. Zero selects the latest snapshot.

Errors

Status	When
`:not-found`	no definition is stored at the path
`:closed`	the database is closed
`:out-of-memory`	native memory is exhausted

Examples

Read a stored query definition

clojure

44 B

(sd/definition db :queries "people/by_role")

Result / 182 B

{:value {:find       [?name]
         :orderBy    [?name]
         :parameters {:?role "engineer"}
         :where      [
           [?e "role" ?role]
           [?e "name" ?name]]}}

C exports: stardust_db_definition_get, stardust_result_take_document, stardust_result_error, stardust_result_release

plan

clojure

21 B

[db kind path action]

clojure

50 B

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

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.
`kind`	`Name`	Value	Required	queries or mutations.
`path`	`Name`	Value	Required	The stored definition path.
`action`	`Name`	Value	Required	explain, 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.
`argument`	`Integer`	Value	Absent	For history or explain, the exclusive lower transaction bound, or zero to start. For revert, the exact historical plan transaction. Other actions require zero.
`page-size`	`Integer`	Value	Absent	For history or explain, the positive maximum revision count. Other actions require zero. History remains durable; this count only bounds one response.
`max-bytes`	`Integer`	Value	Absent	For 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

Status	When
`:invalid-argument`	the kind, action, revision or page limits are invalid, or the selected plan cannot run the current authored definition
`:not-found`	the definition or exact historical plan revision does not exist
`:conflict`	the authored definition or accepted plan changed before the explicit control committed
`:closed`	the database is closed
`:out-of-memory`	native memory is exhausted

Examples

Pin a plan and explain its revision history

clojure

144 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)

Result / 1.1 kB

{:value {:transaction 12
         :plan        {:format     2
                       :hash       {:1 0}
                       :order      [0 1]
                       :parameters ""
                       :pinned     true
                       :policy     "0000000000000000"
                       :reason     "explicit pin"
                       :revision   "7e7de32f33f508a5"
                       :settled    false
                       :source     "Planned"
                       :version    1}
         :history     [
           {:transaction 12
            :plan        {:format     2
                          :hash       {:1 0}
                          :order      [0 1]
                          :parameters ""
                          :pinned     true
                          :policy     "0000000000000000"
                          :reason     "explicit pin"
                          :revision   "7e7de32f33f508a5"
                          :settled    false
                          :source     "Planned"
                          :version    1}}]
         :next_after  0}}

C exports: stardust_db_plan, stardust_result_take_document, stardust_result_error, stardust_result_release

definitions

clojure

9 B

[db kind]

clojure

17 B

[db kind pattern]

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.
`kind`	`Name`	Value	Required	The definition folder kind.
`pattern`	`Name`	Value	Absent	The pattern for definition paths. An absent pattern selects all paths in the requested folder.

Errors

Status	When
`:invalid-argument`	the kind or the pattern is invalid
`:closed`	the database is closed
`:out-of-memory`	native memory is exhausted

Examples

database/definitions

clojure

40 B

(sd/definitions db :queries "people/.*")

Result / 27 B

{:value ["people/by_role"]}

database/definitions

clojure

40 B

(sd/definitions db :queries "people/.*")

Result / 11 B

{:value []}

database/definitions

clojure

40 B

(sd/definitions db :queries "people/.*")

Result / 27 B

{:value ["people/by_role"]}

database/definitions

clojure

40 B

(sd/definitions db :queries "people/.*")

Result / 11 B

{:value []}

C exports: stardust_db_definition_list, stardust_result_take_document, stardust_result_error, stardust_result_release

patch-definition

clojure

20 B

[db kind path patch]

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.
`kind`	`Name`	Value	Required	The definition folder kind.
`path`	`Name`	Value	Required	The stored definition path.
`patch`	`Document`	Borrowed for the call	Required	An object merges or creates the definition. Null deletes it.

Errors

Status	When
`:invalid-definition`	the patched definition is invalid
`:closed`	the database is closed
`:out-of-memory`	native memory is exhausted

Examples

database/patch_definition

definition-text holds this document:

edn

133 B

{:parameters {:?role "engineer"}
 :find       [?name]
 :where      [
   [?e "role" ?role]
   [?e "name" ?name]]
 :orderBy    [?name]}

clojure

120 B

(with-open [definition (sd/parse definition-text :edn)]
  (sd/patch-definition db :queries "people/by_role" definition))

Result / 153 B

{:value {:status       "committed"
         :transaction  3
         :facts        0
         :committed_at 17923367750507039
         :ids          {}}}

C exports: stardust_db_definition_patch, stardust_db_result_commit_info, stardust_result_error, stardust_result_release