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

odin

388 B

promote := stardust.mutation(db, "people/promote") or_return
defer stardust.close(&promote)

commit := stardust.run(promote) or_return
defer stardust.close(&commit)

query := stardust.query(db, "people/by_role") or_return
defer stardust.close(&query)

rows := stardust.run(query) or_return
defer stardust.close(&rows)

result := stardust.next(rows) or_return
defer stardust.close(&result)

Result / 82 B

[
  {
    "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

odin

141 B

definition :: proc(
	db: Database,
	kind, path: string,
	as_of: builtin.i64 = 0,
	allocator := context.allocator,
) -> (
	Document,
	Error,
)

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`	`string`	Value	Required	The stored definition path.
`as_of`	`builtin.i64`	Value	0	The committed snapshot to read. Zero selects the latest snapshot.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

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

odin

102 B

result := stardust.definition(db, "queries", "people/by_role") or_return
defer stardust.close(&result)

Result / 233 B

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

odin

199 B

plan :: proc(
	db: Database,
	kind, path, action: string,
	argument: builtin.i64 = 0,
	page_size: builtin.i64 = 0,
	max_bytes: builtin.i64 = 0,
	allocator := context.allocator,
) -> (Document, Error)

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`	`string`	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`	`builtin.i64`	Value	0	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`	`builtin.i64`	Value	0	For history or explain, the positive maximum revision count. Other actions require zero. History remains durable; this count only bounds one response.
`max_bytes`	`builtin.i64`	Value	0	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.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

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

odin

221 B

pinned := stardust.plan(db, "queries", "people/by_role", "pin") or_return
stardust.close(&pinned)
result := stardust.plan(db, "queries", "people/by_role", "explain", 0, 16, 1 << 20) or_return
defer stardust.close(&result)

Result / 796 B

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

odin

127 B

definitions :: proc(
	db: Database,
	kind: string,
	pattern := "",
	allocator := context.allocator,
) -> (
	Document,
	Error,
)

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`	`string`	Value	Required	The definition folder kind.
`pattern`	`Name`	Value	""	The pattern for definition paths. An absent pattern selects all paths in the requested folder.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

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

odin

98 B

result := stardust.definitions(db, "queries", "people/.*") or_return
defer stardust.close(&result)

Result / 22 B

[
  "people/by_role"
]

database/definitions

odin

98 B

result := stardust.definitions(db, "queries", "people/.*") or_return
defer stardust.close(&result)

Result / 2 B

[]

database/definitions

odin

98 B

result := stardust.definitions(db, "queries", "people/.*") or_return
defer stardust.close(&result)

Result / 22 B

[
  "people/by_role"
]

database/definitions

odin

98 B

result := stardust.definitions(db, "queries", "people/.*") or_return
defer stardust.close(&result)

Result / 2 B

[]

C exports: stardust_db_definition_list, stardust_result_take_document, stardust_result_error, stardust_result_release

patch_definition

odin

138 B

patch_definition :: proc(
	db: Database,
	kind, path: string,
	patch: Document,
	allocator := context.allocator,
) -> (
	Commit,
	Error,
)

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`	`string`	Value	Required	The stored definition path.
`patch`	`Document`	Borrowed for the call	Required	An object merges or creates the definition. Null deletes it.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

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:

json

234 B

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

odin

221 B

patch := stardust.parse(definition_text, .JSON) or_return
defer stardust.close(&patch)

commit := stardust.patch_definition(db, "queries", "people/by_role", patch) or_return
defer stardust.close(&commit)

result := commit

Result / 111 B

{
  "status": "committed",
  "transaction": 3,
  "facts": 0,
  "committed_at": 17923367877515249,
  "ids": {}
}

C exports: stardust_db_definition_patch, stardust_db_result_commit_info, stardust_result_error, stardust_result_release