Explain and cost

Explain output shows the work that a call completed. The example executes the names query with an explain record and reads its completed stages.

Example

Explain a query

query_text holds this document:

json

134 B

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

rust

234 B

let definition = stardust::parse(query_text, Format::JSON)?;
let query = db.query(&definition)?;
let mut result = stardust::QueryExplain::default();
let rows = query.run(None, &RunOptions::default(), Some(&mut result))?;
rows.close();

Result / 665 B

{
  "load_definition": {
    "cpu": 439,
    "wall": 445,
    "arena_bytes": 1680
  },
  "parameters": {
    "cpu": 6,
    "wall": 8,
    "arena_bytes": 0
  },
  "run": {
    "cpu": 9296,
    "wall": 9371,
    "arena_bytes": 7424
  },
  "total": {
    "cpu": 9770,
    "wall": 9853,
    "arena_bytes": 9104
  },
  "arena_capacity": 4194304,
  "work": 6155,
  "rows": 3,
  "compile": 150,
  "plan": 502,
  "execute": 0,
  "group": 0,
  "order": 0,
  "memory_bytes": 5995,
  "memory_refusals": 0,
  "budget_bytes": 10489856512,
  "budget_used_bytes": 10194,
  "budget_peak_bytes": 14267,
  "budget_refusals": 0,
  "retry": 0,
  "stages_completed": 3,
  "retries": 0
}

Failure output

A failed call can still supply explain output for the stages that completed.

Read stages_completed.
Then read the fields of the stages that completed.

The record tables below give the fields, absent values, and time units of each operation.

A call's cost record describes that execution. It does not load stored plan history. Use the plan operation in Definitions with the explain action to read accepted plans and their history. Each revision reports its version, source and reason. Trial decisions include candidate proposals and measured verdicts.

Set page_size and max_bytes to bound one diagnostic response. The response includes the current accepted transaction, the complete plan state and a history page from one snapshot. Pass a nonzero next_after as the next page's argument.

The adaptive query planner can retry a capped plan with the statistics plan. Query explain reports those attempts in retry and retries.

cost

This record measures one explain stage. The cpu and wall fields are durations. The ABI gives 100-ns ticks. Thus, a time less than one tick is zero.

Field	Type	Unit	Range	Absent	Meaning
`cpu`	`Option<Duration>`	Host duration (100 ns ticks at the ABI)	Tick range	None	Thread CPU time. The call measures this value. Independent calls can differ.
`wall`	`Duration`	Host duration (100 ns ticks at the ABI)	Tick range	—	Wall time. The call measures this value. Independent calls can differ.
`arena_bytes`	`i64`	Bytes	Host type range	—	Bytes the stage allocated from the scratch arena of the call. Heap-owned outputs and the LuaJIT heap are not included. The call measures this value. Independent calls can differ.

build_explain

This record contains explain output for build.

Field	Type	Unit	Meaning
`prepare_expression`	`Cost`	None	—
`compile`	`Cost`	None	—
`total`	`Cost`	None	The cost of all stages. `arena_bytes` records the peak scratch-arena allocation.
`arena_capacity`	`i64`	Bytes	Bytes the scratch arena reserved. The call measures this value. Independent calls can differ.
`stages_completed`	`u32`	Count	Stages that ran.
`cache_hit`	`bool`	None	The leased runtime holds a compiled copy of the expression. The call measures this value. Independent calls can differ.

eval_explain

This record contains explain output for evaluate.

Field	Type	Unit	Meaning
`prepare_variables`	`Cost`	None	—
`evaluate`	`Cost`	None	—
`adopt_document`	`Cost`	None	—
`total`	`Cost`	None	The cost of all stages. `arena_bytes` records the peak scratch-arena allocation.
`arena_capacity`	`i64`	Bytes	Bytes the scratch arena reserved. The call measures this value. Independent calls can differ.
`document_bytes`	`i64`	Bytes	Used bytes of the native value, string and source buffers of the result. The call measures this value. Independent calls can differ.
`stages_completed`	`u32`	Count	Stages that ran.

query_explain

This record contains explain output for query run. The compile, plan, execute, group and order fields divide the wall time of run into stages.

Field	Type	Unit	Range	Meaning
`load_definition`	`Cost`	None	Host type range	—
`parameters`	`Cost`	None	Host type range	—
`run`	`Cost`	None	Host type range	Planning, execution and aggregation. Pages render later, in next.
`total`	`Cost`	None	Host type range	The cost of all stages. `arena_bytes` records the peak scratch-arena allocation.
`arena_capacity`	`i64`	Bytes	Host type range	Bytes the scratch arena reserved. The call measures this value. Independent calls can differ.
`work`	`Duration`	Host duration (100 ns ticks at the ABI)	Tick range	Thread CPU duration consumed by the query. The call measures this value. Independent calls can differ.
`rows`	`i64`	Count	Host type range	Result rows.
`compile`	`Duration`	Host duration (100 ns ticks at the ABI)	Tick range	The call measures this value. Independent calls can differ.
`plan`	`Duration`	Host duration (100 ns ticks at the ABI)	Tick range	The call measures this value. Independent calls can differ.
`execute`	`Duration`	Host duration (100 ns ticks at the ABI)	Tick range	Production of solutions. A streamed result produces solutions while pages render. Thus, execute measures only the solutions that run reads. The call measures this value. Independent calls can differ.
`group`	`Duration`	Host duration (100 ns ticks at the ABI)	Tick range	Aggregates, windows and computed columns. The call measures this value. Independent calls can differ.
`order`	`Duration`	Host duration (100 ns ticks at the ABI)	Tick range	The call measures this value. Independent calls can differ.
`memory_bytes`	`i64`	Bytes	Host type range	The most working memory the run held reserved in the database's memory budget at once. The call measures this value. Independent calls can differ.
`memory_refusals`	`i64`	Count	Host type range	Reservations of the run that the memory budget granted less than asked. The call measures this value. Independent calls can differ.
`budget_bytes`	`i64`	Bytes	Host type range	The database's memory budget (`memory_budget_bytes`).
`budget_used_bytes`	`i64`	Bytes	Host type range	Bytes every query of the database held reserved when run returned. The call measures this value. Independent calls can differ.
`budget_peak_bytes`	`i64`	Bytes	Host type range	The most bytes the database's queries held reserved at once since it opened. The call measures this value. Independent calls can differ.
`budget_refusals`	`i64`	Count	Host type range	Reservations the database's budget granted less than asked since it opened. The call measures this value. Independent calls can differ.
`retry`	`Duration`	Host duration (100 ns ticks at the ABI)	Tick range	Thread CPU duration of the attempts given up because the planner's plan passed its cap. work includes it. The call measures this value. Independent calls can differ.
`stages_completed`	`u32`	Count	Host type range	Stages that ran.
`retries`	`u32`	Count	Host type range	Attempts given up because the planner's plan passed its cap; the query then ran the statistics' plan within the rest of its budget.

mutation_explain

This record contains explain output for mutation run.

Field	Type	Unit	Meaning
`load_definition`	`Cost`	None	—
`parameters`	`Cost`	None	—
`run`	`Cost`	None	—
`total`	`Cost`	None	The cost of all stages. `arena_bytes` records the peak scratch-arena allocation.
`arena_capacity`	`i64`	Bytes	Bytes the scratch arena reserved. The call measures this value. Independent calls can differ.
`stages_completed`	`u32`	Count	Stages that ran.
`attempts`	`u32`	Count	Evaluations. More than one when a concurrent write forced a retry.

patch_explain

This record contains explain output for merge_patch.

Field	Type	Unit	Meaning
`copy_patch`	`Cost`	None	—
`commit`	`Cost`	None	Validation and the commit.
`total`	`Cost`	None	The cost of all stages. `arena_bytes` records the peak scratch-arena allocation.
`arena_capacity`	`i64`	Bytes	Bytes the scratch arena reserved. The call measures this value. Independent calls can differ.
`stages_completed`	`u32`	Count	Stages that ran.

Explain examples

The generator captured each result from the native library.

Inspect one measured cost stage

expression_text holds this document:

json

23 B

[
  "+",
  "?x",
  1
]

rust

212 B

let expression = stardust::parse(expression_text, Format::JSON)?;
let mut explain = stardust::BuildExplain::default();
let _program = stardust::build(&expression, Some(&mut explain))?;
let result = explain.total;

Result / 49 B

{
  "cpu": 23,
  "wall": 24,
  "arena_bytes": 0
}

Explain expression compilation

expression_text holds this document:

json

23 B

[
  "+",
  "?x",
  1
]

rust

206 B

let expression = stardust::parse(expression_text, Format::JSON)?;
let mut explain = stardust::BuildExplain::default();
let _program = stardust::build(&expression, Some(&mut explain))?;
let result = explain;

Result / 298 B

{
  "prepare_expression": {
    "cpu": 4,
    "wall": 5,
    "arena_bytes": 0
  },
  "compile": {
    "cpu": 15,
    "wall": 14,
    "arena_bytes": 0
  },
  "total": {
    "cpu": 23,
    "wall": 24,
    "arena_bytes": 0
  },
  "arena_capacity": 65536,
  "stages_completed": 2,
  "cache_hit": true
}

Explain patch validation and commit

seed_text holds this document:

json

333 B

{
  "#_ada": {
    "name": "Ada",
    "role": "engineer",
    "age": 36
  },
  "#_bob": {
    "name": "Bob",
    "role": "engineer",
    "age": 41,
    "mentor": {
      "#link": "#_ada"
    }
  },
  "#_cy": {
    "name": "Cy",
    "role": "designer",
    "age": 29
  },
  "#_tx": {
    "author": "smoke",
    "reason": "seed"
  }
}

rust

174 B

let patch = stardust::parse(seed_text, Format::JSON)?;
let mut explain = stardust::PatchExplain::default();
db.merge_patch(&patch, Some(&mut explain))?;
let result = explain;

Result / 295 B

{
  "copy_patch": {
    "cpu": 9048,
    "wall": 9966,
    "arena_bytes": 3096
  },
  "commit": {
    "cpu": 351,
    "wall": 41242,
    "arena_bytes": 8008
  },
  "total": {
    "cpu": 9515,
    "wall": 51329,
    "arena_bytes": 11118
  },
  "arena_capacity": 4194304,
  "stages_completed": 2
}

Explain mutation execution

birthday_text holds this document:

json

186 B

{
  "query": {
    "find": [
      "?e"
    ],
    "where": [
      [
        "?e",
        "name",
        "Ada"
      ]
    ]
  },
  "patch": {
    "?e": {
      "age": 37
    }
  }
}

rust

240 B

let source = stardust::parse(birthday_text, Format::JSON)?;
let mutation = db.mutation(&source)?;
let mut explain = stardust::MutationExplain::default();
mutation.run(None, &RunOptions::default(), Some(&mut explain))?;
let result = explain;

Result / 390 B

{
  "load_definition": {
    "cpu": 1202,
    "wall": 1209,
    "arena_bytes": 2320
  },
  "parameters": {
    "cpu": 9,
    "wall": 11,
    "arena_bytes": 0
  },
  "run": {
    "cpu": 8205,
    "wall": 52900,
    "arena_bytes": 43856
  },
  "total": {
    "cpu": 9520,
    "wall": 54231,
    "arena_bytes": 46176
  },
  "arena_capacity": 4194304,
  "stages_completed": 3,
  "attempts": 1
}

Explain expression evaluation

expression_text holds this document:

json

23 B

[
  "+",
  "?x",
  1
]

input_text holds this document:

json

14 B

{
  "x": 41
}

rust

313 B

let expression = stardust::parse(expression_text, Format::JSON)?;
let program = stardust::build(&expression, None)?;
let input = stardust::parse(input_text, Format::JSON)?;
let mut explain = stardust::EvalExplain::default();
let _output = program.evaluate(Some(&input), Some(&mut explain))?;
let result = explain;

Result / 378 B

{
  "prepare_variables": {
    "cpu": 5,
    "wall": 6,
    "arena_bytes": 0
  },
  "evaluate": {
    "cpu": 57,
    "wall": 57,
    "arena_bytes": 0
  },
  "adopt_document": {
    "cpu": 4,
    "wall": 4,
    "arena_bytes": 0
  },
  "total": {
    "cpu": 70,
    "wall": 72,
    "arena_bytes": 0
  },
  "arena_capacity": 65536,
  "document_bytes": 42,
  "stages_completed": 3
}

Explain query execution

query_text holds this document:

json

134 B

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

rust

245 B

let definition = stardust::parse(query_text, Format::JSON)?;
let query = db.query(&definition)?;
let mut explain = stardust::QueryExplain::default();
let _rows = query.run(None, &RunOptions::default(), Some(&mut explain))?;
let result = explain;

Result / 674 B

{
  "load_definition": {
    "cpu": 1428,
    "wall": 1455,
    "arena_bytes": 1680
  },
  "parameters": {
    "cpu": 11,
    "wall": 13,
    "arena_bytes": 0
  },
  "run": {
    "cpu": 14265,
    "wall": 14308,
    "arena_bytes": 7424
  },
  "total": {
    "cpu": 15759,
    "wall": 15831,
    "arena_bytes": 9104
  },
  "arena_capacity": 4194304,
  "work": 10348,
  "rows": 3,
  "compile": 351,
  "plan": 730,
  "execute": 0,
  "group": 0,
  "order": 0,
  "memory_bytes": 5995,
  "memory_refusals": 0,
  "budget_bytes": 10489856512,
  "budget_used_bytes": 10194,
  "budget_peak_bytes": 14267,
  "budget_refusals": 0,
  "retry": 0,
  "stages_completed": 3,
  "retries": 0
}