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#

db.mutation("people/promote")?.run(None, &RunOptions::default(), None)?;
let query = db.query("people/by_role")?;
let mut rows = query.run(None, &RunOptions::default(), None)?;
let result = rows.next_page()?;

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

pub fn definition(&self, kind: &str, path: &str, as_of: i64) -> Result<Document>

Parameters#

Errors#

Examples#

Read a stored query definition#

let result = db.definition("queries", "people/by_role", 0)?;

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

pub fn plan(
        &self,
        kind: &str,
        path: &str,
        action: &str,
        argument: i64,
        page_size: i64,
        max_bytes: i64,
    ) -> Result<Document>

Parameters#

Errors#

Examples#

Pin a plan and explain its revision history#

let pinned = db.plan("queries", "people/by_role", "pin", 0, 0, 0)?;
pinned.close();
let result = db.plan("queries", "people/by_role", "explain", 0, 16, 1 << 20)?;

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

pub fn definitions(&self, kind: &str, pattern: &str) -> Result<Document>

Parameters#

Errors#

Examples#

database/definitions#

let result = db.definitions("queries", "people/.*")?;

[
  "people/by_role"
]

database/definitions#

let result = db.definitions("queries", "people/.*")?;

[]

database/definitions#

let result = db.definitions("queries", "people/.*")?;

[
  "people/by_role"
]

database/definitions#

let result = db.definitions("queries", "people/.*")?;

[]

C exports: stardust_db_definition_list, stardust_result_take_document, stardust_result_error, stardust_result_release

Database::patch_definition#

pub fn patch_definition(&self, kind: &str, path: &str, patch: &Document) -> Result<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"
  ]
}

let definition = stardust::parse(definition_text, Format::JSON)?;
let result = db.patch_definition("queries", "people/by_role", &definition)?;

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

C exports: stardust_db_definition_patch, stardust_db_result_commit_info, stardust_result_error, stardust_result_release