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

1.2 kB

stardust_db_source promote = {.kind = STARDUST_SOURCE_PATH, .path = {(const uint8_t *)"people/promote", 14}};
stardust_db_source by_role = {.kind = STARDUST_SOURCE_PATH, .path = {(const uint8_t *)"people/by_role", 14}};
stardust_db_mutation *mutation = NULL;
stardust_result *committed = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_result *page = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_db_mutation_open(db, &promote, &mutation);
if (status == STARDUST_OK) status = stardust_db_mutation_run(mutation, NULL, NULL, NULL, &committed);
if (status == STARDUST_OK) status = stardust_db_query_open(db, &by_role, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, NULL, NULL, &rows);
if (status == STARDUST_OK) status = stardust_db_rows_next(rows, &page);
if (status == STARDUST_OK) status = stardust_result_take_document(page, &result);
stardust_result_release(page);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_result_release(committed);
stardust_db_mutation_release(mutation);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

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
stardust_db_definition_get	Status. document through output	database.definition(kind, path, as_of) returns an owned authored definition document.
stardust_db_plan	Status. document through output	database.plan(kind, path, action, argument, page_size, max_bytes) reads or explicitly controls a stored query or mutation plan.
stardust_db_definition_list	Status. document through output	database.definitions(kind, pattern) returns an owned array document of sorted matching definition paths.
stardust_db_definition_patch	Status. commit through output	database.patch_definition(kind, path, patch) validates and stores a definition merge patch and returns commit information.

stardust_db_definition_get

142 B

uint32_t stardust_db_definition_get(stardust_db *db, stardust_bytes kind, stardust_bytes path, int64_t transaction, stardust_result **output);

92 B

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

96 B

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

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_db_definition_get

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`kind`	`stardust_bytes`	Value	Required	The definition folder kind.
`path`	`stardust_bytes`	Value	Required	The stored definition path.
`transaction`	`int64_t`	Value	Required	Value passed to the call.
`output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_take_document

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

stardust_result_error

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

stardust_result_release

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

Errors

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

Examples

Read a stored query definition

445 B

stardust_bytes kind = {(const uint8_t *)"queries", 7};
stardust_bytes path = {(const uint8_t *)"people/by_role", 14};
stardust_result *read = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_db_definition_get(db, kind, path, 0, &read);
if (status == STARDUST_OK) status = stardust_result_take_document(read, &result);
stardust_result_release(read);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

Result / 182 B

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

Also calls: stardust_result_take_document, stardust_result_error, stardust_result_release

stardust_db_plan

190 B

uint32_t stardust_db_plan(stardust_db *db, stardust_bytes kind, stardust_bytes path, stardust_bytes action, int64_t argument, int64_t page_size, int64_t max_bytes, stardust_result **output);

92 B

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

96 B

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

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_db_plan

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`kind`	`stardust_bytes`	Value	Required	queries or mutations.
`path`	`stardust_bytes`	Value	Required	The stored definition path.
`action`	`stardust_bytes`	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`	`int64_t`	Value	Required	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`	`int64_t`	Value	Required	For history or explain, the positive maximum revision count. Other actions require zero. History remains durable; this count only bounds one response.
`max_bytes`	`int64_t`	Value	Required	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.
`output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_take_document

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

stardust_result_error

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

stardust_result_release

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

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	the kind, action, revision or page limits are invalid, or the selected plan cannot run the current authored definition
`STARDUST_NOT_FOUND`	the definition or exact historical plan revision does not exist
`STARDUST_CONFLICT`	the authored definition or accepted plan changed before the explicit control committed
`STARDUST_CLOSED`	the database is closed
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted

Examples

Pin a plan and explain its revision history

736 B

stardust_bytes kind = {(const uint8_t *)"queries", 7};
stardust_bytes path = {(const uint8_t *)"people/by_role", 14};
stardust_bytes pin = {(const uint8_t *)"pin", 3};
stardust_bytes history = {(const uint8_t *)"explain", 7};
stardust_result *outcome = NULL;
uint32_t status = stardust_db_plan(db, kind, path, pin, 0, 0, 0, &outcome);
stardust_result_release(outcome);
if (status != STARDUST_OK) return status;
outcome = NULL;
stardust_document *result = NULL;
status = stardust_db_plan(db, kind, path, history, 0, 16, 1 << 20, &outcome);
if (status == STARDUST_OK) status = stardust_result_take_document(outcome, &result);
stardust_result_release(outcome);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

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}}

Also calls: stardust_result_take_document, stardust_result_error, stardust_result_release

stardust_db_definition_list

125 B

uint32_t stardust_db_definition_list(stardust_db *db, stardust_bytes kind, stardust_bytes pattern, stardust_result **output);

92 B

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

96 B

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

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_db_definition_list

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`kind`	`stardust_bytes`	Value	Required	The definition folder kind.
`pattern`	`stardust_bytes`	Value	Required	The pattern for definition paths. An absent pattern selects all paths in the requested folder.
`output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_take_document

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

stardust_result_error

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

stardust_result_release

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

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	the kind or the pattern is invalid
`STARDUST_CLOSED`	the database is closed
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted

Examples

database/definitions

466 B

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

Result / 27 B

{:value ["people/by_role"]}

database/definitions

466 B

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

Result / 11 B

{:value []}

database/definitions

466 B

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

Result / 27 B

{:value ["people/by_role"]}

database/definitions

466 B

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

Result / 11 B

{:value []}

Also calls: stardust_result_take_document, stardust_result_error, stardust_result_release

stardust_db_definition_patch

161 B

uint32_t stardust_db_definition_patch(stardust_db *db, stardust_bytes kind, stardust_bytes path, const stardust_document *patch_input, stardust_result **output);

102 B

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

96 B

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

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_db_definition_patch

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`kind`	`stardust_bytes`	Value	Required	The definition folder kind.
`path`	`stardust_bytes`	Value	Required	The stored definition path.
`patch_input`	`const stardust_document *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_db_result_commit_info

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

stardust_result_error

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

stardust_result_release

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

Errors

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

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]}

484 B

stardust_document *definition = NULL;
stardust_result *result = NULL;
stardust_bytes kind = {(const uint8_t *)"queries", 7};
stardust_bytes path = {(const uint8_t *)"people/by_role", 14};
uint32_t status = stardust_parse(definition_text, STARDUST_EDN, &definition);
if (status == STARDUST_OK) status = stardust_db_definition_patch(db, kind, path, definition, &result);
stardust_document_release(definition);
if (status != STARDUST_OK) {stardust_result_release(result); return status;}

Result / 153 B

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

Also calls: stardust_db_result_commit_info, stardust_result_error, stardust_result_release