Transcript Lake

Documentation / CLI

transcript-lake query

Execute operator-supplied DuckDB SQL after loading the canonical Lake views.

Invocation#

sh
transcript-lake [--data-dir <path>] query [--json] "<sql>"

Purpose#

Execute operator-supplied DuckDB SQL after loading the canonical Lake views.

Inputs and options#

  • Required <sql> is formed by joining positional tokens; quote it in the shell to preserve SQL syntax.
  • --json passes DuckDB its JSON output mode.
  • DuckDB CLI is a required optional dependency for this command.

Output and state effect#

Loads the selected data root and embedded canonical views, then gives the SQL to DuckDB and adopts its exit status. Ordinary SELECT use is read-only, but the SQL is arbitrary operator input, so any side effect requested by that SQL is owned by the operator.

Loading events and labels creates no scratch file. If either store has no partitions, its view keeps the documented column types and returns zero rows. Reading an absent data root does not create a Lake. For example, SELECT (SELECT count(*) FROM events) AS events, (SELECT count(*) FROM labels) AS labels returns both counts as zero for an empty Lake.

Only the views the statement references are created, with the views those are written over: DuckDB binds a view when it creates it, and binding events lists every event part file, so SELECT 1 binds no view and SELECT count(*) FROM sessions binds events once, then sessions. The references are read from DuckDB's own parser (json_serialize_sql). A statement that parser does not serialize binds every view and says so on standard error: transcript-lake: DuckDB's parser does not read this statement's references (<reason>); every view is bound. The sections of views.sql, including an override in TRANSCRIPT_LAKE_SQL, each open with -- view: <name> [after <view> ...]; a section line without a view, with a word other than after, or written over a view no section creates is refused naming the line.

Exact refusals#

  • Missing or blank SQL is refused as usage: transcript-lake query [--json] "<sql>".
  • An unrecognized --wat is refused as unknown query flag: --wat.
  • Repeating --json is refused as query received duplicate --json.

All long flags are exact and single-use. A value flag never consumes another --flag. Global --data-dir may appear anywhere in the invocation, must appear once, and selects an absolute root.

Back to the complete CLI command tree.