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#

async with (await db.mutation("people/promote")) as promote:
    (await promote.run())
async with (await db.query("people/by_role")) as query, (await query.run()) as rows:
    result = (await rows.next())

{: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#

Database.definition#

def definition(self, kind: str, path: str, as_of: int = 0) -> Document

Parameters#

Errors#

Examples#

Read a stored query definition#

result = (await db.definition("queries", "people/by_role"))

{: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

Database.plan#

def plan(self, kind: str, path: str, action: str, argument: int = 0, page_size: int = 0, max_bytes: int = 0) -> Document

Parameters#

Errors#

Examples#

Pin a plan and explain its revision history#

async with await db.plan("queries", "people/by_role", "pin"):
    pass
result = await db.plan("queries", "people/by_role", "explain", 0, 16, 1 << 20)

{: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

Database.definitions#

def definitions(self, kind: str, pattern: str = "") -> Document

Parameters#

Errors#

Examples#

database/definitions#

result = (await db.definitions("queries", "people/.*"))

{:value ["people/by_role"]}

database/definitions#

result = (await db.definitions("queries", "people/.*"))

{:value []}

database/definitions#

result = (await db.definitions("queries", "people/.*"))

{:value ["people/by_role"]}

database/definitions#

result = (await db.definitions("queries", "people/.*"))

{:value []}

C exports: stardust_db_definition_list, stardust_result_take_document, stardust_result_error, stardust_result_release

Database.patch_definition#

def patch_definition(self, kind: str, path: str, patch: Document) -> Commit

Parameters#

Errors#

Examples#

database/patch_definition#

definition_text holds this document:

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

async with (await stardust.parse(definition_text, "edn")) as definition:
    result = (await db.patch_definition("queries", "people/by_role", definition))

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

C exports: stardust_db_definition_patch, stardust_db_result_commit_info, stardust_result_error, stardust_result_release