Skip to content

Query model reference

Every mounted Dataset is a SQL schema. A positional Dataset is named dataset; --mount NAME=DATASET creates a named schema. The schema exposes six stable relations even when no compatible Source contributes rows.

Relation One row represents Available from
sources one discovered Source candidate every Dataset
runs one normalized Run/session every ready run data source
steps one normalized Step every ready run data source
tool_calls one tool invocation and its linked result every ready run data source
trajectories one complete Run with ordered Step and tool aggregates normalized run data sources

Use DESCRIBE for the exact columns exposed by the installed version:

DESCRIBE dataset.sources;
DESCRIBE dataset.runs;
DESCRIBE dataset.steps;
DESCRIBE dataset.tool_calls;
DESCRIBE dataset.trajectories;

Source identity

Entity IDs are Source-local. runs, steps, tool_calls retain _file_, the Dataset-relative source_path. A durable entity address includes the Dataset URI, _file_, entity kind, and original ID.

When joining built-in Run relations inside one Dataset, include _file_ alongside the entity key:

SELECT r.run_id, s.step_id, s.message_kind, s.message_value
FROM dataset.runs r
JOIN dataset.steps s
  ON r._file_ = s._file_
 AND r.session_id = s.session_id;

A built-in join that omits _file_ is rejected because equal IDs in two Sources do not identify the same entity. Across separately named Datasets, _file_ equality is not required because each schema is already a different namespace.

sources

Column Type Meaning
_file_ UTF-8, non-null Dataset-relative Source path
format UTF-8, nullable detected or declared representation
kind UTF-8, non-null store or file
snapshot_ref UTF-8, nullable generation, manifest revision, fingerprint, version, or ETag
size_bytes UInt64, nullable candidate file or marker-object size
last_modified UTF-8, nullable RFC 3339 timestamp when available
status UTF-8, non-null ready or error
error UTF-8, nullable sanitized discovery or resolution error

format may remain null until a selected peripheral file is opened lazily. Filtering _file_ can prevent unrelated Sources from being opened. snapshot_ref is a display projection; Rust/API consumers use the typed CatalogSourceRevision for consistency decisions.

Find expressions

pchronicle find --match is the current locate syntax. The installed CLI parser (FindExpr) is authoritative. RFC-0012 records the accepted decision and is not a command reference.

Plain terms search indexed Storyline Step content (FTS / Jieba). Scoped text uses #field(term):

Selector Meaning
#content message_value (message body; the default for plain text)
#message message_value
#user message_value where source = 'user'
#assistant message_value where source = 'agent' (#agent is an alias)
#system prompt and message_value where source = 'system'
#reasoning reasoning_content
#observation observation
#prompt prompt and message_value
#model model_name (#model_name is an alias)
#env env
#all all indexed Step text columns

AND / OR / NOT and parentheses combine predicates. JSONB uses $.path OP value or #json.COLUMN("$.path") OP value, where OP is =, !=, >, >=, <, or <=. Repeat --match to AND expressions.

The current implementation infers search.scope from the expression:

Expression search.scope search.mode
Text only steps fts
JSON only, no Step column runs json
#json.metrics(...) only steps json
Text plus JSON steps fts+json
Identity flags only runs identity

A JSON-only expression without #json.metrics(...) searches run-level JSONB columns (agent_extra, final_metrics, extra, meta, unknown_fields). Mixed text/JSON and explicit #json.metrics(...) search step-level JSONB (metrics, extra).

Query boundary

The engine accepts one read-only SELECT, VALUES, DESCRIBE, or EXPLAIN statement. It rejects DDL, DML, COPY, mutating functions, and multiple statements. CLI row, byte, discovery, and timeout limits still apply.

Exact physical Storyline columns are documented by Storyline Lance. Discovery and predicate-pruning mechanisms belong to Snapshot design. Use the query guide for a complete workflow.