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
events	one canonical write-time fact	canonical event Sources only
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.events;
DESCRIBE dataset.trajectories;

Source identity

Entity IDs are Source-local. runs, steps, tool_calls, and events 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
projection_status	UTF-8, nullable	fresh or stale for a canonical events Source with a linked Storyline projection
projection_generation	UTF-8, nullable	generation selected as the read acceleration projection
projection_candidates	UInt64, non-null	number of linked projection candidates considered
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, observation, and prompt
#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.