Plots

​

Sources

​

Structure

import type { BasePerception, PlotContract } from 'parable/foundation';

export interface Perception extends BasePerception<null, {
  activityFacts: PlotContract<
    readonly [],
    readonly { category: string | null; hours: number }[]
  >;
}> {
  readonly panes: {};
}

• When Latest moves to a newer Refresh while the Pages read Latest, every result read as Latest is dropped. A result read from a chosen Refresh stays.
• When a read or a write is refused, every kept result is dropped, so no row read under the reader’s old access answers again.
• When the reader saves or deletes a setting, the Parable’s kept results are dropped, since a Plot’s SQL may read settings.

​

Plots read as views

• Columns. A view serves its output schema, the columns a stored table of the Plot would serve: the schema publication planned for its SQL, or, for SQL a draft added or changed, the schema the draft’s last save derived, with every column nullable. If its SQL no longer returns those columns with those types, the read refuses until the Plot is planned again, or for a draft, until a save derives its schema again. A value of the declared type in another storage is served as declared: text that SQL functions return as Utf8View or LargeUtf8 (CAST(… AS VARCHAR), string_agg) reads as Utf8, and a timestamp in another unit in the declared unit. A finer timestamp, such as the nanoseconds CAST(x AS TIMESTAMP) returns, is rounded down, so an instant never moves into the next second or day; inside a list or struct it refuses the read.
• Version. A Pane read and a Plot preview read each view from the definition they show: a draft reads the draft’s SQL, so an author previewing a Concept Plot in Changes sees their draft mapping Plots, including Plots only the draft has, and a published Version reads that Version’s SQL. SQL outside a Parable reads the current published Version.
• Views of views. A view can read another view. Views that read each other are refused: reading one answers Plot views form a cycle: … reads …, and publication names the cycle instead of planning it.
• Report runs. A Pipeline may read views of its own Parable. Planning writes each view’s SQL into the run’s plan, so the run’s pinned inputs are the Provider tables and stored Plots under the views. A view of the run’s Parable must come from the Version the run captured; a run captured before a later publication of the view is refused, and running the Report again uses the new Version. A run whose view the Workspace catalog serves from an earlier Version is refused with that cause instead: the catalog has not caught up with the captured Version yet, or that Version was retracted. A run a few minutes later reads the Version the Workspace serves.
• Schedules. A Plot on its own schedule plans with no principal, so it cannot apply a view’s Pane Policies and is refused. Read the view from a Pipeline, or store it.

• plots.activityFacts() is a hook exposing status, rows, refreshing, rerun and breakCache. Pane code draws three states: reading (status is running with no rows yet), empty (ready with no rows) and rows. A read that fails never reaches it: the host shows the failure in the Pane’s place, with Retry (below).
• plotApi.run('activityFacts') runs from an action handler.
• result.meta identifies the data that answered the request, including a resolved Report when relevant.

const facts = props.plots.activityFacts();
if (facts.status === 'running' && facts.rows.length === 0) return <p>Reading activity…</p>;
if (facts.rows.length === 0) return <p>No activity in this reading.</p>;

​

Services

await plotApi.preview('activityFacts', { sql: compiled.sql, parameters: [] });

​

Large results

SELECT subcategory_name AS category, SUM(hours_estimated) AS hours
FROM parables.teamtimespend.time_spend_facts
WHERE date_day >= $1
GROUP BY subcategory_name
ORDER BY hours DESC

SELECT COUNT(*) AS actions, SUM(hours) AS hours
FROM parables.teamtimespend.action_hours
WHERE person_key = $1

-- One page of a person's Actions, newest first, after the last row shown.
-- $2 and $3 are that row's day and action_key, both NULL for the first page.
SELECT action_key, day, title, hours
FROM parables.teamtimespend.action_hours
WHERE person_key = $1
  AND ($2 IS NULL OR day < $2 OR (day = $2 AND action_key < $3))
ORDER BY day DESC, action_key DESC
LIMIT 200

SELECT action_key, day, title, hours
FROM parables.teamtimespend.action_hours
WHERE person_key = $1
ORDER BY day DESC, action_key DESC
LIMIT 50 OFFSET $2

​

Storage

​

Its Panes’ Plots

​

Run history and status

• Results shows the selected reading. On Latest it holds Preview’s rows with their count and time. Above them it lists what Prepare would block this Plot for, if anything: Preview runs Prepare’s own checks on the edited SQL, judged by how the Plot runs (a Pane, a schedule, or a Report), and still shows the rows. Preview in the Refresh menu shows the same for each reporting Plot. On a stored Report run it holds that run’s own rows, read without running the Plot. A run that is queued, running, paused at its budget, failed, cancelled or skipped shows that status instead of rows, and a failed run shows its message. A Plot that finished inside a run that is still moving, or that did not complete, has no readable rows either: only a complete run is readable. When the selected run does not include the Plot, because the Plot is not a Pipeline or the run has no result for it, Results says so and reads nothing. Preview runs on Latest only, so it is unavailable while a stored run is selected.
• History lists every stored Report run, newest first. Each row is named by when the run happened, in your time zone and clock: 12:31pm ET today, Sep 29, 9:00am ET before, with the whole moment on hover. Results names a stored run the same way, as in Refresh Sep 29, 9:00am ET · 1,204 rows. Each row shows this Plot’s status, whether the run was Manual or Scheduled and for which Report, who pressed Run, when the Plot started and last changed, how long it ran, how long it waited to start, its row count, its spend in US dollars and paid calls against the caps captured when the run started, and the catalog address with the run’s short id. A row count the reader may not see reads Hidden, never 0. Choosing a row selects that Refresh in the Refresh menu and the address (refresh); choosing one in the menu selects its row.
• Details lists the catalog address parables.{parable}.{plot}, whether Report runs include the Plot, its published caps and its output columns.

​

Security

• A Plot’s own table and a Report run’s output are written by query-runner. When the run holds the Plot’s contract, query-runner checks every row against it before it writes. A run whose rows break the contract writes nothing and fails with QR-QU-011, and the Plot keeps the output of its last successful run. A Report run and a manual Plot run hold the contract; a scheduled Plot run does not yet (PARABLE-5289) and writes unchecked.
• The read of those rows makes the same check, whoever wrote them. It checks every value in each column the query reads whose contract says more than the column’s type, such as a literal, a scalar format, a bound, a required value, or a Date’s precision. This includes columns used by Policies, filters, joins, grouping and aggregation. An independent column the query never reads is not read from storage or checked, so COUNT(*) reads no column. Contracts that relate columns retain whole-row checks. A column whose type already satisfies its contract, such as an optional string, needs no value check.
• A Report artifact was checked row by row when it was written. Its read confirms the contract, the stored bytes’ digest, and the row count before it opens the file, and does not check the rows again.

​

Stability