play

func (*CardDriver) ColumnClasses ¶ added in v0.0.14

func (inst *CardDriver) ColumnClasses() []streamreadaccess.ColumnClass

ColumnClasses returns the per-Arrow-column leeway classification for the current result — each column's section, role bucket (value / support / membership), backbone flag, and collection shape — or nil when the schema is not leeway-shaped. Like TableDesc it is derived once per schema in EnsureFor (the play app's single leeway-schema reconstruction point); the Table pane reads it to group and filter result columns by section for its leeway display modes. Keyed by ArrowIdx — a schema column absent from the slice is un-classified (non-leeway, implicit, or projected-in) and shown verbatim.

func (*CardDriver) Driver ¶

func (inst *CardDriver) Driver() *streamreadaccess.Driver

Driver returns the underlying leeway streamreadaccess.Driver iff the schema is leeway-shaped (EnsureFor returned true). Otherwise nil. Used by the Projector to drive a FeatureExtractor over the same record batch the card view consumes, so we don't pay for a second schema-discovery round.

func (*CardDriver) EnsureFor ¶

func (inst *CardDriver) EnsureFor(schema *arrow.Schema) bool

EnsureFor (re)builds the driver if the schema changed. Returns true iff the schema is leeway-shaped and Render can proceed.

func (*CardDriver) Prepare ¶ added in v0.0.14

func (inst *CardDriver) Prepare(rec arrow.RecordBatch, row int64) error

Prepare walks a single-row slice of rec through the Driver, buffering the leeway card rows in the emitter without drawing them (the emitter runs with DeferRender set). Call it before SectionDigests and before Render. A no-op on a non-leeway or out-of-range input. Prepare drives every frame — the emitter re-bases its widget-id counter at each drive, so the deferred Render stays id-stable frame to frame.

func (*CardDriver) Render ¶

func (inst *CardDriver) Render()

Render draws the rows buffered by the last Prepare into the current ui scope. Call it after Prepare (and after any SectionDigests read), inside a ScrollArea or Vertical container.

func (*CardDriver) SectionDigests ¶ added in v0.0.14

func (inst *CardDriver) SectionDigests() []leewaywidgets.SectionDigest

SectionDigests returns the per-tagged-section summaries (memberships split primary / secondary + co-attribute values) buffered by the last Prepare, or nil when the schema is not leeway-shaped. The Detail timeline reuses these to label its temporal flags with the same content the card draws below.

func (*CardDriver) SetCellBlock ¶ added in v0.0.20

func (inst *CardDriver) SetCellBlock(fn leewaywidgets.CellBlockFunc)

SetCellBlock installs the per-value block face on the card emitter (ADR-0186, block faces on the card) — the host's renderer for the values whose gloss has one. Passing nil clears it. A no-op until EnsureFor has built an emitter.

func (*CardDriver) SetCellGloss ¶ added in v0.0.20

func (inst *CardDriver) SetCellGloss(fn leewaywidgets.CellGlossFunc)

SetCellGloss installs the per-value gloss on the card emitter (ADR-0186 §SD4) — the host's inline face over the marshalled text of each value. Passing nil clears it. A no-op until EnsureFor has built an emitter.

func (*CardDriver) SetTagClickHandler ¶

func (inst *CardDriver) SetTagClickHandler(fn func(display, detail string))

SetTagClickHandler wires a clipboard / filter pivot callback through to the emitter. Passing nil clears it. Note: Table2CardEmitter renders chips as comma-joined strings, so the callback never fires in practice — kept for API parity with the older two-emitter model.

func (*CardDriver) TableDesc ¶ added in v0.0.13

func (inst *CardDriver) TableDesc() *common.TableDesc

TableDesc returns the leeway schema reconstructed from the current result's physical column names, or nil when the schema is not leeway-shaped. This is the play app's single leeway-schema derivation — the Schema pane renders it rather than re-running discovery. EnsureFor must have been called for the current schema first (it is, every frame, via the Detail card).

func (*ClickHouseDocsSource) AbsoluteURL ¶ added in v0.0.20

func (inst *ClickHouseDocsSource) AbsoluteURL(url string) string

AbsoluteURL turns a corpus link target into something a browser can open. Relative forms are resolved against SiteBase rather than against the entity's own page, whose location the corpus does not record — good enough to land the reader on the right site, and honest about being a fallback for the case where nothing here could answer.

func (*ClickHouseDocsSource) AbsolutiseLinks ¶ added in v0.0.20

func (inst *ClickHouseDocsSource) AbsolutiseLinks(md string) string

AbsolutiseLinks rewrites the corpus's site-relative link targets onto SiteBase.

ClickHouse authors these for its own site — `[DateTime](/sql-reference/…)` — and the widget has no base to resolve them against, so left alone they render as hyperlinks that go nowhere. This is a textual pre-pass rather than a resolver because the markdown widget's resolver seam covers wikilinks and embeds, not plain CommonMark links.

Deliberately narrow: only `](/` is rewritten. A protocol-relative `](//host` is already absolute and must not gain a prefix, and an in-document anchor `](#section)` resolves within the page.

func (*ClickHouseDocsSource) Close ¶ added in v0.0.20

func (inst *ClickHouseDocsSource) Close()

Close tears down the lookup lane. Idempotent, nil-safe.

func (*ClickHouseDocsSource) EmptyHint ¶ added in v0.0.20

func (inst *ClickHouseDocsSource) EmptyHint() string

EmptyHint names this source so a reader knows what a blank pane is waiting on.

func (*ClickHouseDocsSource) ExplainError ¶ added in v0.0.20

func (inst *ClickHouseDocsSource) ExplainError(err error) string

ExplainError explains a failed lookup, separating the one cause a reader can act on from the rest.

`system.documentation` arrived in ClickHouse 26.x. Against an older server the query fails with an unknown-table error, and saying "this endpoint does not ship the documentation table" is a different message from "the lookup failed" — the first is a fact about the server, the second a fault.

The match is gated on THIS instance's own Query mentioning system.documentation, not on the error text alone: a re-user who repurposed Query for a different table would otherwise have every unknown-table error on THEIR table misreported as "needs ClickHouse 26.x".

func (*ClickHouseDocsSource) LinkCandidates ¶ added in v0.0.20

func (inst *ClickHouseDocsSource) LinkCandidates(label string, url string) (out []string)

LinkCandidates ranks the names a claimed link might be naming, best first, for the pane to try in order.

The LABEL leads, because it is what the author wrote to name the thing: "[`UInt8`](/sql-reference/data-types/int-uint)" points at a page covering a dozen types and only the label says which one. Measured over the corpus the label and the URL's last segment each resolve about 60% of links on their own, and they fail on different links — the page-per-family targets (`int-uint`, `special-data-types/expression`) are exactly where the label carries the answer.

The fragment comes second: doc URLs point at a section of a page, and the section is usually the entity (`.../date-time-functions#tohour`).

func (*ClickHouseDocsSource) LinkClaimed ¶ added in v0.0.20

func (inst *ClickHouseDocsSource) LinkClaimed(url string) bool

LinkClaimed reports whether a link target is a ClickHouse documentation page, and so belongs in this pane rather than in a browser.

It runs once per link per frame during layout, so it is a cheap syntactic test and never a lookup: whether the target names something this server documents is decided on the click, where a query is affordable. Claiming a page that turns out to be undocumented is recoverable — the pane says so and offers the original URL — whereas consulting the cache here would make a link's appearance depend on what happened to be cached, and links would change shape as the reader scrolled.

Absolute URLs are claimed only for SiteBase; a link out to GitHub or an RFC is exactly the case that should still leave for a browser.

func (*ClickHouseDocsSource) Lookup ¶ added in v0.0.20

func (inst *ClickHouseDocsSource) Lookup(name string) (entries []DocsEntry, ready bool, err error)

Lookup runs Query for name through the lane. See DocsSourceI for the polling contract this implements against nodeLane.demand.

func (*Client) BuildStatement ¶ added in v0.0.12

func (inst *Client) BuildStatement(sql string) (body string, params map[string]string)

BuildStatement performs the client-side rewrite of a raw editor buffer into the statement body and URL params that ExecuteArrowStream ships:

1. Harvest top-level `SET param_*=...` statements (ExtractParams) so they can ride the HTTP `param_*` channel rather than being inlined — values can be larger than fits comfortably in a single SQL literal, and the typed substitution from `{name:Type}` placeholders is what ClickHouse expects this way.
2. Apply the registered pre-execute rewrites (ADR-0108 §SD6) — e.g. LW_ID_* macro expansion — best-effort: a pass that fails is skipped and the SQL from before it ships instead.
3. Rewrite the query so it ends with `FORMAT ArrowStream`, replacing any existing FORMAT clause; falls back to a textual append when the SQL is outside Grammar1.

Every step degrades rather than fails, so a usable body always comes back and the server reports the real problem to the user. The Preview tab's "as sent" view calls this too, so what it shows can never drift from what executes.

func (*Client) DatasetAliases ¶ added in v0.0.20

func (inst *Client) DatasetAliases() (aliases []string)

DatasetAliases are the ad-hoc dataset aliases bound in this session, sorted.

They are tables no catalogue enumerates — they exist because this session bound them (ADR-0134 §SD4) — which is why the completion engine's table answers are routed per buffer rather than per build (ADR-0190 §SD12).

func (*Client) Dispatch ¶ added in v0.0.17

func (inst *Client) Dispatch(sql string, affinity string) (dec dispatchDecision)

Dispatch resolves where the statement authored as sql will execute.

It resolves from the residual — the SQL the request will actually carry — by running the same client-side rewrites the request runs. That costs one extra rewrite per run (the schema probes behind it are cached), and buys the property that no resolver ever judges a form the server will not see.

Callers hand the result to ExecuteArrowStream or ProbeStatement. Because the decision is a function of the authored buffer alone, two issuers that start from the same buffer — a run and the diagnostic probe describing it — cannot reach different endpoints.

func (*Client) ExecuteArrowStream ¶

func (inst *Client) ExecuteArrowStream(ctx context.Context, sql string, alloc memory.Allocator, opts *ExecOptions, signals map[string]string, dec dispatchDecision) (rdr *ipc.Reader, rs *resultStream, summary Summary, err error)

ExecuteArrowStream rewrites the query's FORMAT clause to `ArrowStream` via the nanopass pipeline, POSTs it, and returns an ipc.Reader over the response body and the body closer. The caller must close the body after fully draining the reader.

Top-level `SET param_*=...` statements in sql are extracted by ExtractParams and shipped on the URL query string (`?param_<name>=<value>`); the residual SQL goes in the body. ClickHouse rejects multi-statement bodies, so this split is what makes a script like `SET param_a=1; SELECT {a:UInt64}` work over a single HTTP request.

Size limits ¶

We do not use multipart/form-data, so the only relevant cap is the request URI cap. Concretely:

• ClickHouse's `http_max_uri_size` (default 1 MiB) bounds the *total* URL length, including the URL-encoded param names and `&` separators. Exceeding it returns HTTP 414 / "URI is too long" from the server.
• Reverse proxies may impose tighter caps (nginx default `large_client_header_buffers` is 8 KiB). When deployed behind one, bump that knob or move to a temp-table strategy for large values.
• For reference: ClickHouse's `http_max_field_value_size` (default 128 KiB) is the *multipart/form-data* per-field cap. It is stricter per-value than the URL channel, so switching to multipart only helps when the *number* of params (not the size of any one) is the bottleneck — and that switch is not implemented here.

For a single value above the URL cap, stage it in a temp table or raise `http_max_uri_size` server-side; there is no client-side fall-back.

opts may be nil; when set, its query_id / replace_running_query ride the URL alongside the params (see ExecOptions).

signals carries the caller's resolved signal values (ADR-0097 slice 5a), URL-keyed (`param_<name>` → raw); nil/empty means none. They ride the same `param_*` channel as the SET-bound constants BuildStatement harvests from the body's prelude, and a SET-bound name SHADOWS a same-named signal (slice-5 D1: a SET pins a signal into a constant) — the harvested params are applied second.

dec is required and names the endpoint (play_dispatch.go): obtain it from Client.Dispatch. It is a parameter rather than something read here so that every issuer of a request is enumerated by the compiler, and so a run and the diagnostic probe describing it provably share one decision.

func (*Client) ExecuteWrite ¶ added in v0.0.20

func (inst *Client) ExecuteWrite(ctx context.Context, sql string, signals map[string]string) (summary Summary, err error)

ExecuteWrite ships a write statement (the INSERT wrapper) and returns the server's summary. The body is BuildStatement's — every pre-execute rewrite applied, target adoption included, and no FORMAT appended — and the response is drained to its terminal, because ClickHouse can raise a failure after the status line and a write path that stops at the header would report such a run as OK (the documented chclient.Exec gap; this path must not inherit it).

func (*Client) ExposeConditions ¶ added in v0.0.14

func (inst *Client) ExposeConditions() (on bool)

ExposeConditions reports whether the selection-condition rewrite is on.

func (*Client) ExprSubstituted ¶ added in v0.0.20

func (inst *Client) ExprSubstituted(sql string) (out string, err error)

ExprSubstituted is sql with its SQL-valued placeholders replaced — the body ADR-0187 §SD5 classifies.

It substitutes and stops. That is the whole point of its existing separately from [Client.buildResidual]: the class must be judged AFTER the user's expression enters and BEFORE the pass registry runs, because ADR-0132 §SD5 classifies the authored buffer precisely so a `keelson('…')` macro is not mistaken for the `url()` it may expand into. Running the passes first would reverse that decision silently.

The prelude is left in place, so the only difference from the buffer the classifier reads today is the substitution.

An unparseable buffer comes back unchanged with the error; the caller then classifies what the user wrote, which the classifier already fails closed on.

func (*Client) LastDecision ¶ added in v0.0.17

func (inst *Client) LastDecision() (dec dispatchDecision, ok bool)

LastDecision returns the most recently resolved decision, and whether anything has been resolved yet. It is what the toolbar reports: where the last query actually went and why — a fact about a run that happened, not a prediction about the buffer currently being typed. Predicting would mean running the client-side rewrites on the render thread every frame, and those can reach the network.

func (*Client) PassRegistry ¶ added in v0.0.14

func (inst *Client) PassRegistry() *passreg.Registry

PassRegistry exposes the registry Execute applies at StagePreExecute — the Passes tab draws its catalog (ADR-0119 M3).

func (*Client) ProbeStatement ¶ added in v0.0.13

func (inst *Client) ProbeStatement(ctx context.Context, sql string, params map[string]string, opts *ExecOptions, dec dispatchDecision) (err error)

ProbeStatement POSTs sql verbatim (params riding the URL exactly as in ExecuteArrowStream) and reports only whether the server accepted it — no FORMAT rewrite, no Arrow decode. The diagnostics EXPLAIN probe consumes the verdict, not the rows: a FORMAT appended to `EXPLAIN AST <stmt>` would bind to the inner statement and leave EXPLAIN's own output undecodable, so the probe must stay off the Arrow pipeline. Non-200 responses fold the server's diagnostic into the error exactly like ExecuteArrowStream ("clickhouse http <code>: <body>"), which classifyProbeError keys on.

dec is required (play_dispatch.go). A probe that resolved its own endpoint from its own `EXPLAIN AST …` text would answer about a server the run it describes never talks to, so the caller passes the decision the run uses.

func (*Client) RewriteTrace ¶ added in v0.0.17

func (inst *Client) RewriteTrace(sql string) (obs []passreg.ApplyObservation)

RewriteTrace runs the client-side rewrite of sql for its per-step outcomes and discards the statement. Callers get what the registry stage and play's own steps did to this buffer — including passes that failed and were skipped, which otherwise appear only as a warn line in the process log (ADR-0108 §SD3 makes every unit degrade rather than fail, so a skipped rewrite is invisible in the result).

It costs a full rewrite — the passes re-parse — so callers memoise it by buffer rather than recomputing per frame. Safe from any goroutine: the state the rewrite reads is either immutable after wiring or guarded (Client.mu, the exposeConditions atomic).

func (*Client) SetExposeConditions ¶ added in v0.0.14

func (inst *Client) SetExposeConditions(on bool)

SetExposeConditions turns the opt-in selection-condition rewrite (ADR-0121) on or off.

func (*Client) SetExprValues ¶ added in v0.0.20

func (inst *Client) SetExprValues(values map[string]string)

SetExprValues publishes the LIVE-tier expression values (ADR-0187 §SD3) — the ones a panel or the pane holds in the signal store rather than in the buffer's `-- play: expr` lines.

They cannot travel the way an ordinary live value does. A `param_*` entry on the request URL is a VALUE to ClickHouse, so a predicate sent that way is a string; the only route into the query is the splice, and the splice reads text. Hence a client binding, in the shape SetExposeConditions and bindDataset already established: written from the render thread, read wherever a query is built.

Whole-map replacement, so a name that left the live tier stops being substituted rather than lingering as a stale binding.

func (*Client) SetResolver ¶ added in v0.0.17

func (inst *Client) SetResolver(r endpointResolverI)

SetResolver installs the endpoint resolver. A nil resolver restores the static one, which always answers with the pinned endpoint.

func (*Client) SetStampIdentity ¶ added in v0.0.14

func (inst *Client) SetStampIdentity(runId string, appId string, instanceKey uint64)

SetStampIdentity records the process/run identity the stamps carry: the runtime's run id (MountContextI.RunId — joins captured runs to the runtime-start fact) and the app id (the Manifest Id, the same value the MembRuntimeApp membership carries elsewhere). Callable any time; empty values simply leave those stamp fields out. The launcher wires it at Mount; the standalone CLI never does, and its runs stamp lane + fingerprints only.

func (*Client) SetURL ¶ added in v0.0.12

func (inst *Client) SetURL(u string)

SetURL switches the target endpoint. Safe to call from the UI goroutine while a query runs on another: ExecuteArrowStream reads the target once at request-build time. An empty url is ignored (keeps the current target).

func (*Client) URL ¶ added in v0.0.12

func (inst *Client) URL() (u string)

URL returns the current target endpoint.

func (*MapDriver) Render ¶ added in v0.0.10

func (inst *MapDriver) Render(sig SignalEnvI, emit SignalEmitterI)

Render draws the controls, the last-good raster overlay, and the map; and, once the viewport has settled (debounced), publishes it as the vp_* signals and demands the raster node compiled against the frame's signal snapshot (sig; emits land next frame — the 5a frame consistency). Order matters: the mapRaster overlay is a register-drain node, so it must be emitted BEFORE the walkersMap that drains it.

func (*PlayApp) ActivateTab ¶ added in v0.0.14

func (inst *PlayApp) ActivateTab(id string) (err error)

ActivateTab focuses the dock tab with the given registry slug ("editor", "table", … — the ids from Tabs().Specs()) on the next dock send. An unknown slug is an error, matching the registry's validation style. The SQL delivery ops focus the editor for you; reach for this to raise a different pane.

func (*PlayApp) BindDataset ¶ added in v0.0.15

func (inst *PlayApp) BindDataset(alias, handle string) error

BindDataset binds a stable alias — as written in the buffer, keelson('<alias>') — to an ephemeral dataset handle, so the client rewrites the alias to the handle before the request leaves play (ADR-0134 §SD4). Both must be bare identifiers. The binding is instance state, applied by the embedder between construction and mount.

func (*PlayApp) BindTab ¶ added in v0.0.14

func (inst *PlayApp) BindTab(tabID string, cteName string) (err error)

BindTab points a panel tab at a split node by CTE name (ADR-0097 slice 6c). An unknown tab id is an error, matching ActivateTab's validation style; an unknown node name is deliberately NOT one — bindings key on CTE names, sit inert while a split lacks the name, and revive when it returns.

func (*PlayApp) CanCopy ¶ added in v0.0.20

func (inst *PlayApp) CanCopy() bool

CanCopy reports whether the clipboard is reachable from this instance — what an affordance that only exists to copy is gated on.

func (*PlayApp) Close ¶ added in v0.0.12

func (inst *PlayApp) Close()

Close tears down the app's async machinery (Unmount): cancels in-flight work, releases held results, and closes every lane. Late completions from still-running goroutines hit their generation/closed guards and are dropped. Idempotent; the app is unusable afterwards.

func (*PlayApp) ComposeLaunch ¶ added in v0.0.20

func (inst *PlayApp) ComposeLaunch() (cfg launchcfg.PlayLaunch)

ComposeLaunch renders the window's current user-authored state as the launch that would reproduce it (ADR-0148 §SD2/§SD8): the editor buffer, the Timeline bands buffer, the Live toggle, and the active pane.

AutoRun composes false unconditionally — re-executing a buffer is something a user asks for, not something a restoration does — and At is stamped now, which is also why nothing in the save path byte-compares two composed configs.

Endpoint is deliberately left empty: which target a buffer ran against is a property of the run that authored it, not of the state, and a restored window resolves keelson reads through the auto-routing resolver (ADR-0141) anyway.

Caches, result history, selections and pane-local view state are out of scope by SD1 — a workingset carries what the user authored or chose.

func (*PlayApp) Frame ¶ added in v0.0.20

func (inst *PlayApp) Frame(ctx app.FrameContextI) (err error)

Frame renders one frame with the per-frame capabilities the host offers on ctx. It is the entry point for every host: the launcher below, and equally any library that builds a PlayApp of its own and re-hosts it.

Two capabilities arrive this way, both in the ADR-0155 §SD1 shape — an optional interface type-asserted off the context, so a host that cannot offer one owes nothing and nothing errors:

• app.WindowFocusI gates the process-global Ctrl+Enter chord. The chord is drained once from egui's shared queue and is visible to every open instance alike, so without the gate one press runs a query in all of them. A host that cannot say is taken as focused: single-surface hosts and tests have only the one instance, and it is the active one.
• colwidth.HostI carries the column-width store (ADR-0151). It is acquired here rather than at Mount because it is a frame-context capability; ensureColWidthRes does the once-only work.

The render pass itself is unexported precisely because of this: a re-host holding a frame context has no reason to skip either capability, and every re-host that called the pass directly silently lost both. Making the context the only way in turns that from a rule to remember into a signature.

func (*PlayApp) InsertSqlAtCaret ¶ added in v0.0.14

func (inst *PlayApp) InsertSqlAtCaret(text string)

InsertSqlAtCaret hands text to the SQL editor to splice at its caret on the next editor render (TextEditFluid.InsertAtCursor, ADR-0063) and focuses the Editor tab. The activation is a correctness step, not cosmetic: a hidden tab's body buffer is discarded uninterpreted, so an insert into an unfocused editor is silently lost — bundling it here keeps the visibility invariant the API's to hold, not each caller's to remember.

func (*PlayApp) MainSQL ¶ added in v0.0.14

func (inst *PlayApp) MainSQL() string

MainSQL returns the executed SQL text behind the `main` node's current result — the query MainSnapshot's record was produced by — or "" when none has landed yet. It is the thread-safe companion to MainSnapshot for embedders that need the query behind the live result (e.g. deriving per-result query lineage): the read is guarded by the main lane's lock, so it is safe off the render loop. Being a second, independent lock acquisition, a result that completes between a MainSnapshot and a MainSQL call can momentarily pair rows from one query with the SQL of the next; for human-driven single-query flows that window is not observable.

func (*PlayApp) MainSnapshot ¶ added in v0.0.14

func (inst *PlayApp) MainSnapshot() (rec arrow.RecordBatch, schema *arrow.Schema, numRows int64, loading bool, elapsed time.Duration, summary Summary, executed time.Time, err error)

MainSnapshot returns a retained view of the `main` node's current result — the sink result the Table tab shows by default — with its metadata. It is the thread-safe embedder seam for reading the live resultset OFF the render loop (e.g. an on-demand report server behind a re-user's own pane): the read is guarded by the main lane's QueryStore lock, so it is safe from any goroutine, unlike the render-thread-only activeSnapshot (which observes the intermediate lane and per-frame split state). The caller MUST Release the returned record (nil-safe); rec is nil until the first result lands, with loading/err then reflecting the lane state. See doc/howto/play-pluggable-detail.md for the companion body/tab seams.

func (*PlayApp) NotifyDatasetRevision ¶ added in v0.0.15

func (inst *PlayApp) NotifyDatasetRevision(alias string, revision uint64)

NotifyDatasetRevision signals that a bound dataset was republished at a new revision. Under Live main it triggers the ordinary auto-run path so the applet re-queries the fresh data; an explicit Run always works regardless. This is the instance-level realization of ADR-0134 §SD5 freshness (a trigger, not a graph signal). The alias identifies which dataset changed and is advisory today — the trigger re-runs the whole main buffer.

func (*PlayApp) RenderDefaultDetailContent ¶ added in v0.0.12

func (inst *PlayApp) RenderDefaultDetailContent(rec arrow.RecordBatch, schema *arrow.Schema, row int64)

RenderDefaultDetailContent is the built-in Detail body: the leeway card stack when the schema is leeway-shaped (co-sections, real tags, per-type formatters), else a prefix-grouped ad-hoc section layout for arbitrary SQL results. Exported so a custom DetailContentFunc can delegate to it and append its own widgets.

The leeway card view (Table2CardEmitter) renders into an egui_extras::TableBuilder that owns its own ScrollArea, so it must NOT be wrapped in an outer ScrollArea: that hands the table unbounded available height and egui_extras then crops its tail rows. The driver emits the plain section first and the tagged / co-sections after it, so the cropped rows are exactly the tagged sections — leaving "only plain value sections" visible. Render the card directly in the bounded dock tab, matching the leewaywidgets demo's renderActiveView. The ad-hoc fallback has no self-scrolling widget, so it keeps an explicit ScrollArea.

func (*PlayApp) ReplaceSql ¶ added in v0.0.14

func (inst *PlayApp) ReplaceSql(text string)

ReplaceSql swaps the whole SQL editor buffer with text on the next editor render and focuses the Editor tab. A same-frame ReplaceSql supersedes an InsertSqlAtCaret. See InsertSqlAtCaret for the activation rationale.

func (*PlayApp) RequestRun ¶ added in v0.0.15

func (inst *PlayApp) RequestRun()

RequestRun schedules a run of the main buffer after the current frame — the same one-shot the Run button and the Live auto-run path use.

func (*PlayApp) RestorePersistedSql ¶

func (inst *PlayApp) RestorePersistedSql()

RestorePersistedSql replaces inst.sql with the value stored under persistKeyLastSql when storage is wired and the value is non-empty. Best-effort: errors are logged at debug level and the existing inst.sql stays.

Read-only bridge (ADR-0148 §SD8, added 2026-07-29): nothing writes this key any more — the editor buffer now survives as a workingset record the window host pulls at close. Mount consults the key only for a window that received no config at all, so a session that predates the workingset era still finds its buffer. Retire the key, this function, and the PersistedKeys entry one release on.

func (*PlayApp) RestorePersistedTimelineBandsSql ¶

func (inst *PlayApp) RestorePersistedTimelineBandsSql()

RestorePersistedTimelineBandsSql loads the bands-SQL editor buffer from the persist cap. Same best-effort semantics — and the same one-release read-only bridge — as RestorePersistedSql.

func (*PlayApp) SetCapabilities ¶

func (inst *PlayApp) SetCapabilities(bus app.BusI, storage app.StorageI, logger zerolog.Logger)

SetCapabilities is the host-side seam for wiring the runtime's M2 capabilities (ADR-0026). Called once from PlayLauncher.Mount with ctx.Bus() and ctx.Storage(). Either argument may be nil — the "Load .sql" button stays hidden when bus is nil; persist save/ restore is skipped when storage is nil.

func (*PlayApp) SetColumnResolver ¶ added in v0.0.14

func (inst *PlayApp) SetColumnResolver(resolver passes.ColumnResolverI)

SetColumnResolver wires the leeway column resolver into the Diagnostics pane, so it can warn — client-side, before a Run — about `section:column` handles that name no known section or column. Safe to call with nil (no resolver).

func (*PlayApp) SetDatasetNotice ¶ added in v0.0.20

func (inst *PlayApp) SetDatasetNotice(src []byte)

SetDatasetNotice hands play a runtime notice about this instance's data preconditions — in practice, that a declared ad-hoc dataset alias has no dataset behind it yet (ADR-0134 §SD4). It renders above the preamble, inside the central panel, so the reader meets the reason the panes are empty before the prose explaining what the panes would mean.

Unlike PlayApp.SetPreambleMarkdown this is expected to be re-set while the instance is live, as the condition it reports appears and clears; empty source clears it. It reparses on every call, so a caller that re-derives the same text each frame should compare before setting.

It is the host's surface, not the document's: play has no idea what produces a given alias, and the embedder that declared the alias does.

func (*PlayApp) SetDefinitionMarkdown ¶ added in v0.0.20

func (inst *PlayApp) SetDefinitionMarkdown(src []byte)

SetDefinitionMarkdown hands play the document this instance was defined by: a sqlapplet's markdown source (ADR-0132 §SD1) — frontmatter as the manifest, prose as the explanation, the first `sql` fence as this buffer. It turns on the top bar's "Definition" toggle and the drawer behind it. Call it between construction and mount, like the tab registry; empty source leaves the affordance off, which is what an ordinary playground wants.

Parsing happens here rather than per frame. Images resolve through no vault — the seam carries the document's bytes and not the book's FS, so a doc that embeds one degrades to markdown's glyph-hyperlink fallback.

func (*PlayApp) SetDetailContent ¶ added in v0.0.12

func (inst *PlayApp) SetDetailContent(fn DetailContentFunc)

SetDetailContent overrides the Detail panel's body renderer. Passing nil restores the built-in body (RenderDefaultDetailContent). The header PlayApp draws above the body is unaffected.

func (*PlayApp) SetDocsSource ¶ added in v0.0.20

func (inst *PlayApp) SetDocsSource(src DocsSourceI)

SetDocsSource overrides the Docs pane's lookup, replacing whatever source is currently installed (closing it first). Passing nil restores ClickHouse's own system.documentation via NewClickHouseDocsSource — what an unconfigured PlayApp with a live client already uses. Takes effect on the next frame; there is nothing else to unregister. See doc/howto/play-pluggable-docs.md.

func (*PlayApp) SetLiveMain ¶ added in v0.0.14

func (inst *PlayApp) SetLiveMain(on bool)

SetLiveMain presets the `main` lane's Live toggle (ADR-0097 slice 5e, D2). The toggle stays user-reachable in the top bar; presetting it on lets an embedder open with signal-driven re-runs active (e.g. a sqlapplet whose buffer reads `{selection_id:UInt64}`, ADR-0132 §SD3).

func (*PlayApp) SetPreambleMarkdown ¶ added in v0.0.20

func (inst *PlayApp) SetPreambleMarkdown(src []byte)

SetPreambleMarkdown hands play the explanatory passage an applet author wants standing over the results — a sqlapplet's `md preamble` aux fence. It renders above every result pane, inside the central panel, so it reads as a header on the data rather than as another piece of toolbar. Call it between construction and mount; empty source renders nothing.

Separate from PlayApp.SetDefinitionMarkdown on purpose: the definition is the whole document a reader opens deliberately, the preamble is the couple of sentences they should not have to open anything to see. An applet may have either, both, or neither.

func (*PlayApp) SetSecurityCeiling ¶ added in v0.0.20

func (inst *PlayApp) SetSecurityCeiling(class analysis.QuerySecurityClassE)

SetSecurityCeiling declares the strongest class this instance's queries may reach (ADR-0187 §SD5). An applet passes its mint-time class; play leaves it unset, and the zero value refuses nothing.

It is a ceiling on the SUBSTITUTED body, so it constrains what a knob may turn the document into — not what the document already is. Raising the document's own class is the author's business and the mint-time classification already covers it.

func (*PlayApp) SetSignal ¶ added in v0.0.15

func (inst *PlayApp) SetSignal(name string, value any)

SetSignal publishes value under signal name through the same emit path panels use (play_graph.go): last-write-wins within a frame, visible from the next frame's snapshot. Supported value kinds are the signal-store encodable set (string, integers, float64, bool); others are dropped with a warning by the emitter.

func (*PlayApp) SetTimelineBandsSql ¶ added in v0.0.14

func (inst *PlayApp) SetTimelineBandsSql(sql string)

SetTimelineBandsSql seeds the Timeline panel's bands editor (the panel-local SQL of ADR-0097 slice 5d). An embedder whose own definition carries bands SQL — e.g. a sqlapplet aux fence (ADR-0132 §SD1) — applies it between construction and mount; empty is a valid value (no bands).

func (*PlayApp) SetToolbarMinimal ¶ added in v0.0.14

func (inst *PlayApp) SetToolbarMinimal(on bool)

SetToolbarMinimal attenuates the top bar to the applet surface (ADR-0132 §SD3): Load .sql, the endpoint switcher, and the prelude/conditions toggles disappear; Run/Cancel, the Live toggle, and the unfilled-inputs hint stay; the "Open in Playground" escape hatch (ADR-0135 §SD7) appears when a bus is wired. Call it between construction and mount, like the tab registry. The other escape hatch, "Definition", rides PlayApp.SetDefinitionMarkdown rather than this flag — it is offered wherever a document exists to show.

func (*PlayApp) Tabs ¶ added in v0.0.13

func (inst *PlayApp) Tabs() *TabRegistry

Tabs is the instance's dock-tab set (ADR-0097 slice 6a, D4): an embedder customizes it — Add/Replace/Remove — between construction and mounting; the first Render freezes it. See TabSpec for the registration shape.

func (*PlayApp) UnbindDataset ¶ added in v0.0.20

func (inst *PlayApp) UnbindDataset(alias string) error

UnbindDataset drops the alias→handle binding BindDataset installed, so the alias passes through unrewritten again (and a query naming it fails readably as an unknown keelson table). The embedder calls it when the dataset behind the alias is withdrawn — the ADR-0188 §SD3 `retracted` event — and binds afresh when a new dataset appears under the alias. Unbinding an alias that is not bound is a no-op.

func (*PlayApp) WorkingsetDirty ¶ added in v0.0.20

func (inst *PlayApp) WorkingsetDirty() (dirty bool)

WorkingsetDirty reports whether user intent occurred in this window since Mount (ADR-0148 §SD4): an edit to either SQL buffer, a manual Run, a Live toggle, or a pane raised through the delivery seam. It is the whole save gate — a window nobody acted in leaves the stored record alone.

func (*PlayLauncher) ComposeWorkingset ¶ added in v0.0.20

func (inst *PlayLauncher) ComposeWorkingset() (cfg []byte, dirty bool, err error)

ComposeWorkingset implements app.WorkingsetComposerI for the launcher (ADR-0148 §SD4). The host calls it at close, before Unmount — which is load-bearing: Unmount releases the inner app, so the nil guard below is the honest answer for anything that asks afterwards, not a fallback.

func (*PlayLauncher) Frame ¶

func (inst *PlayLauncher) Frame(ctx app.FrameContextI) (err error)

func (*PlayLauncher) Manifest ¶

func (inst *PlayLauncher) Manifest() (m app.Manifest)

func (*PlayLauncher) Mount ¶

func (inst *PlayLauncher) Mount(ctx app.MountContextI) (err error)

func (*PlayLauncher) Unmount ¶

func (inst *PlayLauncher) Unmount(ctx app.MountContextI) (err error)

func (*Projector) Cancel ¶

func (inst *Projector) Cancel()

Cancel signals the in-flight run to stop. The goroutine sees the closed channel on the next stepFunc fire (or the next phase boundary) and exits. While the goroutine winds down (UMAP can take seconds with no per-epoch hook) the status sits at Cancelling so the UI can show that the click was registered. Final transition to Cancelled happens in markCancelled(). No-op if nothing is running.

func (*Projector) Detach ¶ added in v0.0.12

func (inst *Projector) Detach()

Detach cancels any in-flight run and orphans it — Invalidate's semantics without installing a new dataset. For app teardown (PlayApp.Close): the winding-down goroutine's terminal writes become no-ops and it releases its retained record on exit.

func (*Projector) Invalidate ¶

func (inst *Projector) Invalidate(schema *arrow.Schema, executed time.Time) (matches bool)

Invalidate is called every frame with the current (schema, executed). Returns true iff the projection state matches the current result and may be displayed. If the result changed since the last call, any in-flight computation is cancelled and the state is reset to idle.

Uses detachCurrentRunLocked (not signalCancelLocked) so a goroutine that is still winding down for the previous dataset becomes a no-op on its terminal status write — the new tab state (Idle) survives instead of being overwritten with the stale run's Cancelled / Failed / Done.

func (*Projector) Snapshot ¶

func (inst *Projector) Snapshot() (snap projectorSnapshot)

Snapshot returns a value-copy of the current state. Safe to read on the render thread without holding the mutex. The coords slice is shared (not copied) — the goroutine treats it as immutable once published.

func (*Projector) Start ¶

func (inst *Projector) Start(rec arrow.RecordBatch)

Start kicks off a projection run on the given record batch. No-op if a run is already in flight (Cancel first if you want to restart). The caller must have called Invalidate(schema, executed) earlier this frame so the cache key is set.

func (*QueryStore) Cancel ¶

func (inst *QueryStore) Cancel()

Cancel aborts the in-flight query (if any).

func (*QueryStore) Close ¶ added in v0.0.12

func (inst *QueryStore) Close()

Close cancels any in-flight query, releases the held result, and marks the store closed so a late finish() is dropped rather than resurrecting state. Idempotent; the store is unusable afterwards.

func (*QueryStore) Execute ¶

func (inst *QueryStore) Execute(sql string, signals map[string]string, sourceBuffer string)

Execute kicks off an async query. signals carries the URL-keyed signal values resolved for this run (ADR-0097 slice 5a; nil = none) — they ride the request URL and are snapshotted into the history entry (D4). Subsequent calls while a query is running are ignored; call Cancel first.

sourceBuffer is the editor buffer sql was derived from, recorded on the history entry so a restore brings back the whole buffer rather than the fragment that ran (ADR-0130 L3 run-under-cursor). Pass "" when sql IS the buffer — every lane but `main` does.

func (*QueryStore) History ¶

func (inst *QueryStore) History() []HistoryEntry

func (*QueryStore) IsLoading ¶

func (inst *QueryStore) IsLoading() bool

func (*QueryStore) Progress ¶ added in v0.0.14

func (inst *QueryStore) Progress() (p runstream.Progress, fresh bool)

Progress returns the in-flight run's latest in-band progress tick; fresh is false when no run is loading or no tick has arrived yet.

func (*QueryStore) SQL ¶ added in v0.0.14

func (inst *QueryStore) SQL() string

SQL returns the SQL text of the run that produced the current Snapshot result, or "" before the first run finishes. Guarded by the same lock as Snapshot; as a separate call it can race a concurrent finish (see PlayApp.MainSQL).

func (*QueryStore) Snapshot ¶

func (inst *QueryStore) Snapshot() (rec arrow.RecordBatch, schema *arrow.Schema, numRows int64, loading bool, elapsed time.Duration, summary Summary, executed time.Time, err error)

Snapshot returns a retained view of the last result. Caller MUST call rec.Release() when done (nil-safe). Retaining under the read lock ensures a concurrent Execute→finish can't pull the record out from under us. executed is the time the most recent finish() completed — use it as an identity token for the current dataset (changes ⇒ new query). loading is read under the same lock as executed, so the pair is consistent: feed this loading to the FSM mirror rather than a separate IsLoading() call, which could observe the post-finish flag against this pre-finish snapshot.

func (*QueryStore) Truncation ¶ added in v0.0.17

func (inst *QueryStore) Truncation() (reason string)

Truncation reports the reason the last result is a prefix, or "" when it is whole (or when the run failed, which err already says). Read it beside Snapshot: a capped result looks exactly like a complete one otherwise, which is the confusion R9 exists to prevent.

func (Summary) String ¶

func (inst Summary) String() string

func (*TabRegistry) Add ¶ added in v0.0.13

func (inst *TabRegistry) Add(spec TabSpec) (err error)

Add appends a tab. New body-zone tabs render after the built-ins.

func (*TabRegistry) Remove ¶ added in v0.0.13

func (inst *TabRegistry) Remove(id string) (err error)

Remove drops the tab with the given id.

func (*TabRegistry) Replace ¶ added in v0.0.13

func (inst *TabRegistry) Replace(id string, spec TabSpec) (err error)

Replace swaps the tab with spec.ID == id, keeping its position. The replacement may change every field including DockID (a different pane identity for the persisted layout).

func (*TabRegistry) SetZone ¶ added in v0.0.20

func (inst *TabRegistry) SetZone(id string, z TabZoneE) (err error)

SetZone moves a registered tab to another layout zone, leaving the rest of its spec alone.

It exists so an embedder can place a pane without rebuilding the spec that declares it: a document says where its panes go, and everything else about them — the panel, the dock identity, the shape contract — belongs to whoever registered the tab. Replace would make the caller restate all of it, and a caller restating a spec it did not author is a caller that will eventually restate it wrongly.

Like the other mutators, valid only before the first Render.

func (*TabRegistry) Specs ¶ added in v0.0.13

func (inst *TabRegistry) Specs() (out []TabSpec)

Specs returns a copy of the registered tabs in registration order — the read surface for embedders (asserting their registrations) and, later, the binding UI. Mutate the set only through Add/Replace/Remove.

func (*TimelineDriver) RenderContractHelp ¶

func (inst *TimelineDriver) RenderContractHelp()

RenderContractHelp emits a descriptive multi-line block listing the three column-shape modes the Timeline panel accepts (Points, Intervals, Annotations) and the slot constraints. Intended for empty-state and rejection-state surfaces so first-time users learn the contract from the panel itself instead of having to chase it elsewhere. Body line is body-sized; slot rows use the monospace style so column names line up visually; the closing note is small + weak so it doesn't compete with surrounding controls.