Skip to main content

​
Sources

Docs: Panes, Preferences, Policies, and Execution context. Web App: Select a Pane, open Plots, and choose a named side tab. Results and errors appear below its SQL. React source is in Pane. While you edit SQL, an advisory check runs after a short pause. Markers identify SQL problems; a marker with a suggested replacement offers a Monaco quick fix. The existing Plot panel also shows findings without a source location. Findings with a location can focus that position in the selected source. The panel distinguishes Advisory SQL from Server validation. A pending or unavailable check is not an all-clear. Missing catalog access or an unavailable browser validator leaves the source editable and keeps the existing save controls available. Server checks and Policies still apply when you save. Saving definition SQL records server validation diagnostics. An unavailable validator does not prevent saving: the draft, last successful schema, reference pins, and dependencies stay available. Each draft keeps its own dependencies. Completed, trustworthy reference checks replace that draft’s dependencies; references that would introduce a cycle retain the previous dependency set. A save shares one ten-second budget across all Plot validation calls, including any second pass needed for changed sibling columns. When time runs out, the remaining checks are skipped and those Plots record PV_SYS_001 (unchecked). Your SQL draft still saves, but unchecked Plots cannot be published. This bounds validation waiting; database work can take additional time. An explicit re-check on the Primary or Proposal retries unchecked or stale verdicts with the same shared budget. It skips current completed verdicts, including SQL errors that need an author edit. Re-checking does not change your authored content. See the Primary re-check API and Proposal re-check API. Static validation derives schemas for SQL without parameter defaults. Sources with explicit defaults, including [], retain their last successful bound schema until native planning validates their actual inputs. Publishing checks the candidate definition and its parameters, diagnostics, and scheduled plan before sealing it. Saving a live SQL Preference still requires successful planning as described below. When publication is blocked, the current Prepare findings identify the Plot and retain the server’s reason, including after reloading the Proposal. Saved findings belong to the exact SQL and selected Workspace and definition. They replace advisory feedback for that saved text and clear when a completed server verdict clears them. Publication findings show the server’s reason for the named Plot; changing its SQL starts a new check. The catalog follows the selected Workspace and Changes. Historical versions remain read-only and do not borrow the current definition’s advisory catalog. Unsaved definition siblings can contribute trustworthy schemas to the current check; saved SQL Preferences keep their separate live source and planning lifecycle. Typing a Plot back to its saved SQL withdraws its unsaved draft, including when an earlier save is still pending. Other Plots then validate against the saved schema again. In the Admin editor, select the Workspace whose data the Plot uses before checking it. This editor uses the Workspace adapter and its tenant.data.catalog permission, alongside current RACI and Policies. Without catalog permission, you can keep editing and saving. Unavailable checking is shown as unavailable, never as a successful check against an empty catalog. The native Admin catalog operation separately requires admin.tenant.data.catalog. Native Admin Prepare and Publish use the selected Workspace and authenticated staff account. Planning and execution still require their current Workspace authority. A successful check in one Workspace does not certify the data or Policies of other deployment targets. The SQL validation specification describes diagnostics, catalog snapshots, and publication checks. For typed access from TypeScript Pieces, the data SDK specification explains manifests, reading selection, and pagination. It distinguishes the implemented runtime and server foundations from execution-host integration.

​
Structure

A Plot is a typed computation owned by a Pane. Its Perception declares PlotContract<Input, Output> under a local Plot name. SQL is the current implementation language; React rendering belongs to the Pane. The input describes positional parameters and the output describes rows. A fixed tuple has exact arity. A dynamic query builder can declare an array of supported scalar types. Both paths validate parameter values and the SQL’s placeholder count. The contract exists even when no SQL has been saved. React imports other application components through declared Pane references. It accesses owned logic through its Pane SDK. For a Plot declared with no parameters:
  • plots.activityFacts() is a hook exposing status, rows, errors, and rerun.
  • plotApi.run('activityFacts') runs from an action handler.
  • result.meta identifies the data that answered the request, including a resolved Report when relevant.
Generated types come from the Perception’s declared inputs and outputs. SQL planning and execution check that contract, including columns, nullability, and scalar representations. The editor’s Preview sends its edited SQL under the selected Plot’s same contract and current output Policies. A missing saved implementation is reported without creating SQL or data. SQL Output contracts support explicit object fields and homogeneous arrays, including nested objects and arrays of objects. Dictionary maps, tuple columns, multidimensional arrays, and mixed unions refuse at compilation. These SQL restrictions do not limit ordinary Perception primitives used by Panes and Preferences. Saved planning accepts equivalent Arrow string storage and timestamp units while preserving the original values and timestamp precision. Mounted Plot actions and hooks retain the contract they were compiled against, including hooks reached through a referenced Pane. If the selected contract changes, existing callers refuse until refreshed; they cannot silently inherit the new input or output type. Changing current access still takes effect on each request.

​
Services

Kysely is available by default. It compiles query structure into SQL and a separate parameters array. Preview the result through:
A SQL Preference stores { sql, parameters? }. Create or update that value through preferences, then execute it with plotApi.runPreference('activityFacts', id). create.plots and edit.plots govern those writes even though the API is the shared Preference API. Saving SQL also requires successful planning. Planning uses the same current definition and permissions as the save. A failed plan preserves the previous saved revision and output schema. SQL definition source can also retain parameter defaults alongside its code. Those defaults belong to the definition, survive publication and archive export/import, and must match the Perception’s declared Input. Older published versions retain their own defaults after a later edit changes or clears them. React and CSS sources cannot carry SQL parameters. An explicit empty array stays distinct from omitted defaults. Use a declared tuple or scalar array for nonempty parameters. Native Dates serialize as timestamps; strings, finite numbers, booleans, and null retain their values. Parameters remain bound values and are not interpolated into SQL. Omitting a live-query override uses saved parameters; an explicit array replaces them, including an empty array. Use explicit casts when needed to keep the planned output type stable. Native numeric values must be finite. Integer-valued numbers must fit JavaScript’s safe range, from -9007199254740991 through 9007199254740991. This also applies inside nested values, parameters, saved defaults, and Report results. Unsupported values refuse before a write or result completes; retained values and Report bytes are never rounded or rewritten during a typed read. Finite fractions remain supported. Use an explicitly declared string contract when an application needs to retain larger integral identifiers as text. A saved Plot edit uses the revision last read. A refused save preserves the local draft; reload explicitly before replacing it. Previewing a generated query does not save a Preference. An application may offer separate create, update, and run actions for the selected saved query. Each saved SQL Use names one owned Plot. Its members cannot run under another Plot’s contract, even when both Plots belong to the same Pane. plotApi.key('activityFacts') returns that declared Plot’s stable identity for explicit Use setup; the identity grants no access by itself. React source uses { source }. paneApi.renderPreference(sourcePreferenceId) loads a renderer for its saved owner. The host determines its Pane, references, selected value, and policy decisions; caller-supplied owner or policy objects cannot replace those checks.

​
Storage

A definition version identifies code and schema. A Report identifies produced data. For a pipeline Plot, Current selects the newest completed Report whose output fits the selected definition. It can come from an earlier compatible definition. Publishing does not run a Report or change its schedule. Choosing a Report pins that run; an unavailable or incompatible result does not fall back to Current. Ordinary SQL Plots and previews can query completed pipeline outputs while using their own SQL and parameters. Direct reads of a materialization retain its captured inputs and refuse different overrides. Use plotApi.readReport('activityFacts') to read completed output with its captured inputs. It returns the Perception’s typed rows without requiring today’s input tuple. It uses the selected Report, or Current’s newest compatible completed result, and refuses when no materialized result is available. run and preview keep their declared input requirements. Named reads let the server select the captured default source. runPreference always checks the exact requested source ID and optional revision, including when reading a Report. A materialized response retains its producer contract and source metadata; consumerContractHash records admission for the selected definition, and materialized distinguishes captured output from an ordinary query running in Report context. SQL catalog addresses use the stored Parable and Plot slugs. Both segments begin with a lowercase letter and contain lowercase letters, digits, and underscores between groups. Hyphens and case-only replacements are refused. Renaming a handle does not move those addresses. Query builders take the stored slugs from the selected definition’s metadata; they do not derive an address from a handle. Publication plans Plot dependencies from the candidate definition’s schemas. A missing dependency or a cycle refuses publication. Planning does not fabricate rows or require an existing Report. Results retain the producing source and Report separately from the consuming definition.

​
Security

Source inspection uses view.plots; source edits use edit.plots. SQL output uses its Data Policies’ view.preferences and row filters. Permission to read data need not disclose its query. The generic Preference API does not collapse these targets into one grant. Using a React renderer requires permitted Pane/value access. It can be delivered without granting its source-editor view, but executable JavaScript necessarily reaches the browser. CSS has the same limitation. These restrictions cannot promise secrecy for delivered code or styles. A constructed preview and a saved named output both apply their declared Plot’s Data Policies and their actual inputs’ restrictions. Restrictions that must apply to every query over a Provider belong on that Provider’s binding. Invalid or unsupported filters refuse execution rather than returning unfiltered rows.

​
Stability

A Report pipeline cannot yet consume another pipeline Plot’s newly produced output within the same run. The worker refuses that dependency until it can bind the intermediate output. Ordinary consumers of completed pipeline outputs support Current and explicit Report readings. A Report can consume a compatible output completed in an earlier run. Its captured definition supplies the planned input schemas, while current Policies authorize the recorded data. Contract validation and current-authority checks remain active through result streaming and completion, including empty results. Provider input replay is not yet available. A historical result whose Provider filter uses request_principal() requires the captured principal, including email. Source filters using now(), current_timestamp, current_date, full parable_context(), or another execution-dependent function refuse both Report materialization and historical reads. Use Current data for those filters until input replay is available. Typed Preference inputs support captured-value checks under current Policies. These limits matter when assembling a real classification pipeline; having SQL or a model UDF available does not itself connect that flow. Historical source admission follows immutable Plot or SQL Preference identities, including a retained SQL Preference’s declared Plot association. Retired, replaced, or ambiguous identities refuse. Current access must cover every captured contributor: unchanged filters or removed restrictions can qualify; new restrictions require replay and refuse. An equivalent Policy conversion can preserve access even when its internal lookup records change. Once a read starts, any change to its admitted authority aborts that read before completion.