baml query — The Tables (catalog v1)

A plain-language guide to what baml query lets you query, what each table means, and where its data comes from. The engineering specs are TASK/baml-query-scope.md (query layer) and TASK/profiling-backend-streams.md (the storage it reads). This document restates their catalog for readers who want to use it, not build it.

1. What it is

Every time a BAML function runs — from baml run, baml test, the playground, or a host program — the profiler records what happened into .baml/profiles-v1/. baml query is a SQL prompt over those recordings:

baml query "SELECT thread_id, status, total_errors, started_at FROM threads WHERE parent_thread_id IS NULL ORDER BY started_at DESC LIMIT 20"
baml query "SELECT fqn, sum(self_ns) FROM call_path_stats GROUP BY fqn ORDER BY 2 DESC LIMIT 10"
baml query "SELECT call_id, args['customer']['age'] FROM calls WHERE args['customer']['age'] >= 30"
baml query --schema          # prints everything below as JSON

It is DataFusion SQL (PostgreSQL-flavoured): joins, GROUP BY, CTEs, window functions all work. Every result ends with an outcome (complete / incomplete / budget / cancelled, plus how many captured values could and could not be evaluated), so you always know whether the answer is whole.

The three ideas you need

1. An execution is a thread with no parent. When a host calls a BAML function, the engine starts a fresh logical thread for it. That thread, plus every thread it spawns, is one execution. There is no separate "run" object — not even a view: an execution's row is its root thread, selected with threads WHERE parent_thread_id IS NULL, and its id is the root thread's id (baml_thread_1_…).
2. Population vs. retained. The profiler counts every call into a calling-context tree (call_path_stats: "this function, called from this call site, under this parent — N times, this much time"), but keeps an exact record (calls) only for selected calls: the execution root, every LLM call, and calls the program marked with $id. So call_path_stats answers "how much / how often", calls answers "show me this one".
3. Values are captured, not copied into rows. Inputs/outputs/errors of retained calls live in a content-addressed store. In SQL they appear as virtual columns (args, output, error) you can subscript and compare; they are loaded only when a query touches them. Their identity (args_cid) is a plain column you can join on without loading anything.

Identity scheme

Times: *_ns columns are nanoseconds relative to the process start (exact, always present); *_at columns are wall-clock timestamps derived from them.

2. The tables

Every table name is versioned (threads_v1) with an unversioned alias (threads). ? marks a nullable column. Types are Arrow/DataFusion types.

threads — one row per logical thread (root rows are executions)

call_path_stats (alias cct_population) — the calling-context tree

One row per distinct path: (parent call path, function, call site, call/spawn edge). Repeated calls update counters; they never add rows.

calls (alias retained_calls) — exact records of selected calls

args is a named-argument object: args['customer']['age']. A missing path or a captured null is simply a non-match; a value that could not be loaded is reported in the query outcome, never silently treated as NULL.

errors — one row per captured error

function_definitions — the compiled program's function table

health — did the profiler lose anything? (long format)

Rows: the profiler's loss/saturation counters (e.g. evidence_queue_full, value_attempt_transport_exceeded, corrupt_records), CCT saturation flags, one row per overflow bucket, and the data-completeness result of reading the execution. Zero rows with value > 0 ⇒ nothing was lost.

Views (SQL on top of the tables)

(No executions view ships today — decided 2026-08-24; use threads WHERE parent_thread_id IS NULL.)

Internal tables (BAML_INTERNAL / playground only)

processes (one per process: stream_id, pid, zero_unix_ns, baml_version, os_arch, alive, meta_hw, data_hw), store_files (one per file on disk), value_index (one per stored value) — for debugging the store itself.

3. How the tables relate

threads (root row = execution) ──execution_id──┬── contexts ──call_path_id──┐
                                               ├── calls ─────────────────┘  calls.parent_call_id → calls
                                               ├── errors   errors.throw_call_id → calls, throw_call_path_id → contexts
                                               └── health
threads.spawn_call_id → calls                   (program_id, function_id) → functions

• Everything execution-scoped carries execution_id, so no parent-walking is needed to scope a query to one execution.
• Across executions and processes, group by definition_key or fqn (function_id/call_path_id are per-build: program_id is a conservative content hash of the compiled sources — any byte change, comments included, is a new program — so call_path_id is comparable across runs of one build and deliberately not across edits).

4. The data structures underneath (for the curious)

Value columns are Arrow Binary with field metadata baml.virtual = value; the planner rewrites args['a'][0] >= 30 into internal functions that load and compare the value, and renders a bare SELECT args as JSON. Every other column is an ordinary Arrow column (Utf8, UInt64, Boolean, List, Timestamp).

Status/completeness semantics: status comes from RootEnded if present, otherwise running while the writing process holds its stream.lock and abandoned once it doesn't; index_state says whether the index records are whole; the health rows (plane = data) say whether the execution's data data files were all present and readable.