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

queryText holds this document:

dust

58B

find    [?name]
where   [[?e name ?name]]
orderBy [?name]

337B

definition, err := stardust.Parse(queryText, stardust.DUST)
if err != nil {
	return err
}
defer definition.Close()

query, err := db.Query(definition)
if err != nil {
	return err
}
defer query.Close()

var result stardust.QueryExplain
rows, err := query.Run(nil, stardust.RunOptions{}, &result)
if err != nil {
	return err
}
rows.Close()

Result / 618B

{load_definition  {cpu         370
                   wall        376
                   arena_bytes 1680}
 parameters       {cpu         3
                   wall        5
                   arena_bytes 0}
 run              {cpu         2299
                   wall        2299
                   arena_bytes 6408}
 total            {cpu         2693
                   wall        2700
                   arena_bytes 8088}
 arena_capacity   4194304
 work             360
 rows             3
 compile          43
 plan             30
 execute          255
 group            0
 order            27
 stages_completed 3}

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.

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`	`time.Duration`	Host duration (100 ns ticks at the ABI)	Tick range	-1	Thread CPU time. The call measures this value. Independent calls can differ.
`wall`	`time.Duration`	Host duration (100 ns ticks at the ABI)	Tick range	—	Wall time. The call measures this value. Independent calls can differ.
`arena_bytes`	`int64`	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`	`int64`	Bytes	Bytes the scratch arena reserved. The call measures this value. Independent calls can differ.
`stages_completed`	`int`	Count	Stages that ran.
`cache_hit`	`bool`	None	The leased runtime holds a compiled copy of the expression.

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`	`int64`	Bytes	Bytes the scratch arena reserved. The call measures this value. Independent calls can differ.
`document_bytes`	`int64`	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`	`int`	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`	`int64`	Bytes	Host type range	Bytes the scratch arena reserved. The call measures this value. Independent calls can differ.
`work`	`time.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`	`int64`	Count	Host type range	Result rows.
`compile`	`time.Duration`	Host duration (100 ns ticks at the ABI)	Tick range	The call measures this value. Independent calls can differ.
`plan`	`time.Duration`	Host duration (100 ns ticks at the ABI)	Tick range	The call measures this value. Independent calls can differ.
`execute`	`time.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`	`time.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`	`time.Duration`	Host duration (100 ns ticks at the ABI)	Tick range	The call measures this value. Independent calls can differ.
`stages_completed`	`int`	Count	Host type range	Stages that ran.

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`	`int64`	Bytes	Bytes the scratch arena reserved. The call measures this value. Independent calls can differ.
`stages_completed`	`int`	Count	Stages that ran.
`attempts`	`int`	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`	`int64`	Bytes	Bytes the scratch arena reserved. The call measures this value. Independent calls can differ.
`stages_completed`	`int`	Count	Stages that ran.

Explain examples

The generator captured each result from the native library.

Inspect one measured cost stage

expressionText holds this document:

dust

[+ ?x 1]

284B

expression, err := stardust.Parse(expressionText, stardust.DUST)
if err != nil {
	return err
}
defer expression.Close()

var explain stardust.BuildExplain
program, err := stardust.Build(expression, &explain)
if err != nil {
	return err
}
defer program.Close()

result := explain.Total

Result / 47B

{cpu         15
 wall        16
 arena_bytes 0}

Explain expression compilation

expressionText holds this document:

dust

[+ ?x 1]

278B

expression, err := stardust.Parse(expressionText, stardust.DUST)
if err != nil {
	return err
}
defer expression.Close()

var explain stardust.BuildExplain
program, err := stardust.Build(expression, &explain)
if err != nil {
	return err
}
defer program.Close()

result := explain

Result / 393B

{prepare_expression {cpu         2
                     wall        3
                     arena_bytes 0}
 compile            {cpu         6
                     wall        6
                     arena_bytes 0}
 total              {cpu         11
                     wall        11
                     arena_bytes 0}
 arena_capacity     65536
 stages_completed   2
 cache_hit          true}

Explain patch validation and commit

patchText holds this document:

dust

232B

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

209B

patch, err := stardust.Parse(patchText, stardust.DUST)
if err != nil {
	return err
}
defer patch.Close()

var result stardust.PatchExplain
if _, err := db.MergePatch(patch, &result); err != nil {
	return err
}

Result / 372B

{copy_patch       {cpu         399
                   wall        434
                   arena_bytes 3080}
 commit           {cpu         248
                   wall        15494
                   arena_bytes 8200}
 total            {cpu         685
                   wall        15966
                   arena_bytes 11294}
 arena_capacity   4194304
 stages_completed 2}

Explain mutation execution

birthdayText holds this document:

dust

68B

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

328B

source, err := stardust.Parse(birthdayText, stardust.DUST)
if err != nil {
	return err
}
defer source.Close()

mutation, err := db.Mutation(source)
if err != nil {
	return err
}
defer mutation.Close()

var result stardust.MutationExplain
if _, err := mutation.Run(nil, stardust.RunOptions{}, &result); err != nil {
	return err
}

Result / 495B

{load_definition  {cpu         343
                   wall        348
                   arena_bytes 2304}
 parameters       {cpu         4
                   wall        6
                   arena_bytes 0}
 run              {cpu         2019
                   wall        28517
                   arena_bytes 24640}
 total            {cpu         2395
                   wall        28900
                   arena_bytes 26944}
 arena_capacity   4194304
 stages_completed 3
 attempts         1}

Explain expression evaluation

expressionText holds this document:

dust

[+ ?x 1]

inputText holds this document:

dust

x 41

458B

expression, err := stardust.Parse(expressionText, stardust.DUST)
if err != nil {
	return err
}
defer expression.Close()

program, err := stardust.Build(expression, nil)
if err != nil {
	return err
}
defer program.Close()

input, err := stardust.Parse(inputText, stardust.DUST)
if err != nil {
	return err
}
defer input.Close()

var result stardust.EvalExplain
output, err := program.Evaluate(input, &result)
if err != nil {
	return err
}
defer output.Close()

Result / 484B

{prepare_variables {cpu         4
                    wall        6
                    arena_bytes 0}
 evaluate          {cpu         22
                    wall        23
                    arena_bytes 0}
 adopt_document    {cpu         2
                    wall        2
                    arena_bytes 0}
 total             {cpu         32
                    wall        34
                    arena_bytes 0}
 arena_capacity    65536
 document_bytes    42
 stages_completed  3}

Explain query execution

queryText holds this document:

dust

58B

find    [?name]
where   [[?e name ?name]]
orderBy [?name]

343B

definition, err := stardust.Parse(queryText, stardust.DUST)
if err != nil {
	return err
}
defer definition.Close()

query, err := db.Query(definition)
if err != nil {
	return err
}
defer query.Close()

var result stardust.QueryExplain
rows, err := query.Run(nil, stardust.RunOptions{}, &result)
if err != nil {
	return err
}
defer rows.Close()

Result / 618B

{load_definition  {cpu         361
                   wall        366
                   arena_bytes 1664}
 parameters       {cpu         3
                   wall        5
                   arena_bytes 0}
 run              {cpu         1988
                   wall        1987
                   arena_bytes 6408}
 total            {cpu         2368
                   wall        2374
                   arena_bytes 8072}
 arena_capacity   4194304
 work             308
 rows             3
 compile          37
 plan             25
 execute          224
 group            0
 order            14
 stages_completed 3}