revenueForecast becomes revenue_forecast. workspace.parables
lists each Parable’s slug. Use the slug, not the handle, because a handle
can be renamed.
The pool serves the Plots of each Parable that is published and not
archived.
Who can read a Plot
A role is not enough to read a Plot. You need all of these:- A role that reaches the Plot. In SQL, the Member, Member with All Data
Access, Data Access or Workspace Administrator role. Over the Workspace API,
tenant.parables.view, which the Viewer, Member, Member with All Data Access, Integrator, Data Access, and Workspace Administrator roles hold. - A seat on the Parable. Any seat works, Peeking included. A seat can be yours, your Workspace’s, or one of your roles’. Without a seat, you cannot read the Parable’s Plots.
- The Parable Policies of the Plot’s Pane must let you view it.
- Access to the sources that the Plot reads. Provider Policies and source permissions still apply (Rows you can read).
Stored results and views
A Plot reads one of two ways:- A Pipeline is a Plot whose Pipeline switch is on. A Report run
stores its output. In the app, a stored run is a Refresh.
parables.{parable}.{plot}reads the newest completed Refresh that fits the published Plot. Until one completes, it is an empty table. - Every other Plot whose SQL binds no parameters is a view. A read runs the Plot’s published SQL as part of your query. One Plot can therefore build on another without waiting for a stored result.
parables.{parable}.{plot}
within moments.
When Reports run
A Plot has no schedule of its own. Its Report runs it, in three ways:- On demand, when someone with a Publishing or Primary seat runs it, in the app or over the API.
- On a schedule, from the Report plan: a recurrence of daily or less often, in the plan’s time zone.
- After its sources refresh. The plan waits until the Provider streams and Platform Parables that its Pipelines read have been quiet for a time (30 minutes by default, 5 minutes to 1 day). It runs no later than a set delay after the first change (4 hours by default, up to 7 days), and at most a set number of times a day (6 by default, 1 to 24).
trigger says which of these started it: manual, scheduled, or
sources.
How long Refreshes stay
For each Report, Parable keeps:- Every completed Refresh for 2 days.
- After that, the newest Refresh of each day (UTC), until 30 days.
- At any age: its newest completed Refresh and its newest Refresh with no failed Plot, and the same two of each Release that another Parable reads.
- The newest 3 Previews, each for 7 days. Previews do not count toward the Refreshes kept.
- Every failed or cancelled Refresh for 90 days after it ended. The newest failed Refresh stays however old it is, and so does the newest failed Preview. Failed and cancelled Refreshes do not change which completed Refreshes are kept.
- Every Refresh that someone kept (Keep This Refresh), and every Refresh of another Parable that a kept Refresh read. Kept Refreshes do not change which other Refreshes are kept.
Stored results and your access
A Refresh stores its rows once, for everyone who opens it. A Refresh that read every row of a Provider table cannot be cut down to the rows that you can read. So when a Provider Policy or Provider Permissions narrow a table that a Refresh read, you cannot open that Refresh. The read fails with403 and
QL-TN-007. Someone whom nothing narrows on those tables can open it. A Plot
that reads its tables live, as a view, is filtered for each reader instead.
Shared ids for merged records
A live merge can give the same Person a differentparable_id for each
reader. A Provider Policy can hide the record that supplied the id. The merge
then chooses another record for that reader.
Keeping each stored row’s source key does not by itself make the stored merge
safe to read. That row can also hold a name chosen from a hidden record. A
filter on the source key would keep the row and that hidden name.
PARABLE-5420 needs a
contract that separates shared ids from values that each reader may see.
Until then, the QL-TN-007 guard still applies to stored merges. The
Provider Permissions spec
records this limit.
Stable-key ids in live reads
parable_stable_id(namespace, natural_key) returns a 64-character lowercase
SHA-256 hex string. It hashes a versioned prefix, the namespace’s UTF-8 byte
length as an unsigned 64-bit big-endian integer, the namespace bytes, then
the key bytes. The prefix is parable-stable-id:v1 followed by a zero byte.
Length framing keeps different namespace and key pairs apart.
The function is immutable. Query Layer and Report workers use the same
implementation. A NULL or empty argument returns NULL. Other text stays
unchanged. Normalize a natural key explicitly:
QL-TN-007 still refuses stored
results for restricted readers, including a live view over a stored result.
Read a past Refresh
A Report run reads every table at one moment, its AS OF time. Two errors come from that:Build on Plot results
Plots read Provider and Artifact tables. Other queries and Plots can then read their results:- The other Plots of its own Parable.
- The rows saved on its own Parable’s Panes, by the Pane’s name.
- Pane data of a Platform Parable that it reads, as
<pane>_data. workspace.*tables.- The Plots of a Platform Parable, by the same address.
Rows saved on a Pane
A Pane can save rows of its own type, such as the categories that people edit on it. Each row belongs to an actor: a person (Me), a group, the whole Parable (This Parable), or the Parable’s Default. A Plot reads these rows by the Pane’s name:view.data Policies must admit you. Under
View as, they must admit the viewer too. A refused Pane has no readable
relation. The refusal does not say
whether the table exists. This path exposes no Preference or subject rows.
Direct Platform Pane data reads run live. A Report cannot capture them yet.
The runtime planner refuses a bound direct read with QL-PL-016. For a
Report, publish a view Plot over the data in the Platform Parable. Then read
that Plot from the Report.
workspace.preferences returns the same rows as raw JSON, for a look in a SQL
tool. A Plot never reads it: Parable refuses to publish a Plot that does.
Platform Parables
A Platform Parable is a Parable that Parable staff deploy to every Workspace. A Workspace made later gets it too. When Parable staff turn Platform off, the audience becomes the Workspaces that hold an open copy: a copy that reads a Release, from a Pull it published or from a Delivery that was not cancelled or superseded. Each of these Workspaces keeps its copy, and a Delivery on its way there still finishes. A Workspace whose copy reads no Release leaves the audience. A Workspace made after Platform off does not get the Parable. The next Deploy chooses the Workspaces again. It is the only kind of Parable whose Plots other Parables can read. Your SQL names no Release of it. The read decides:- A published Version of your Parable reads the Release of the Platform Parable that was newest when your Version was published. A later Release does not change what it reads. Publish your Parable again to read the newest Release.
- Your unpublished Changes read the newest Release.
- A Refresh of your Parable reads the Refresh of the Platform Parable that it recorded when it ran.
Read a Parable as a graph
Each Parable is also a graph. Its Plots are the vertices. A Plot that is marked as an edge is an edge. Read the graph withGRAPH_TABLE, as the SQL/PGQ
standard writes it:
graphEdge and each of its two ends
has a foreign key (foreignKeys) or a kind-column declaration
(fromKinds or toKinds), as
Foreign keys and graph edges
says. An edge whose ends do not resolve, for example a key that names a Plot
that is gone, is left out of the graph, and a pattern that names it is
refused. A Plot view whose own SQL holds a GRAPH_TABLE reads the same graph.
The graph also holds each Plot whose joins Parable refuses: a Plot that has
no data yet in the Version or Changes that the query reads, and a Plot whose
table the catalog cannot build. Parable refuses a pattern whose joins would
read such a Plot, for the reason that it refuses the joins that name the
Plot: at an element without a label when one of its combinations of Plots
reaches such a Plot, and at a label that names one. Give the element labels
that name only other Plots.
The graph holds each Plot that you may not read too, because its Pane or
Page Policies refuse its output to your participation. A refusal never names
such a Plot, and never tells its columns, its foreign keys or its edge mark.
Such a Plot contributes no labels. A readable Plot can still declare the
same label. A label that a Plot you may not read also carries reads only
the Plots you may read. It does not refuse the query or report the hidden
Plot. A reader who may read that Plot gets its rows too. An element without
a label that joins it is refused. A kind end that reads only edge-backed
identity values does not join a node, so it applies no node access check.
An edge without a label can match it between any two vertices, so
Parable refuses each edge without a label while the graph holds such a Plot.
A vertex without a label is refused unless a labeled edge next to it leads
only to Plots that you may read. Give each element labels that name only
Plots that you may read. The Plot editor holds such Plots in its graph too,
so it shows the refusal before you run the query. The save’s check judges
the Parable for every person alike, so it reads every Plot as readable.
These rules hold for the Plots of another Parable that your SQL reads too.
They also hold for SQL that names no Parable, such as a Flight SQL statement,
which reads each Parable’s published graph. Before your pattern reads that
graph, Parable asks, for each Plot of it, whether you may read the Plot. It
asks the same question that a read of the Plot asks. A Plot that you may not
read joins the graph with no columns, foreign keys or edge mark. The same
holds when Parable plans a Plot of yours, for the graph of each other
Parable that the Plot or one of its views reads. It holds for a Report run
too: a Preview or a Run you start reads each graph as you may read it, and a
scheduled Refresh reads it as the Workspace may.
A published GRAPH_TABLE reads the reader’s graph too, wherever it runs: in
your own SQL, in a published view that your SQL reads, in a Report run and in
a Pane. Its rows follow what that reader may read, as the rows of a Plot that
a row Policy narrows do. For a Plot you may not read, you get the answer you
get for a Plot that does not exist, and no refusal names it.
A published view keeps the column types it declares, and so does a view in a
Preview of a set of Changes. A property that some
matched Plots lack is a NULL with the type of the first Plot of its element
that has the property. When your graph lacks that Plot, because you may not
read it or it has no data yet, and no other Plot types the NULL, the column
is a NULL of no type. It holds no value, so the view gives it the declared
type. Every other type difference refuses the read as “no longer returns its
declared columns”, as in any view:
- A column whose type changed under the view, such as an
integerwhere the view declares anumber. This refusal is the same for every reader. - A NULL that another Plot you may read types, when its type is not the declared one.
- A column whose Plots have different types, when your Plots combine to
another type than all the Plots do. A
UNIONgives its column one type, which it takes from the types of its branches, in order. Your graph can lack some of those branches. A cast of your type to the declared one could then give values that the whole graph never gives, such as5.0where the whole graph gives5.
QL-PL-025. The view’s
SQL does not parse, the engine refuses it, or it no longer returns its
declared columns. The message names the view and says which of these it
is. It never quotes the view’s SQL, because a reader of the rows may not see
that source. The fault is in that view’s Plot, not in the SQL that reads it.
Read that Plot to see why it fails, and fix its own SQL.
A pattern that no combination of Plots can match, such as
(a IS people)-[IS reviews]->(b IS teams) when no review joins people to
teams, reads no Plot. As in Postgres, it gives no rows, and its columns keep
their names and types. So it adds no Plot that your Plot depends on, and no
refused Plot refuses it. When such a path has a label, the editor and the
save check report PV_REF_012. This warning names the line and column of the
path. Check its labels and each edge’s foreign keys or kind declarations. A matching combination
of Plots can still return no rows when its tables are empty. That case gets
no warning.
- Kind ends. An edge can map its kind columns to several node Plots or
labels. A labeled end joins only the named declared Plots and filters the
kind column. An unlabeled end that needs only
idandkindreads those values from the edge without a node join. Other properties join only declared nodes. Unknown kind values match nothing. Edge-only reads can retain a missing node’s id. They apply edge Policies, not node Policies. Node joins keep the same Policies, dependencies and pins as ordinary SQL. See Kind properties. - Labels. A label is a Plot’s slug or one of its
graphLabels.(r IS people)matches the rows ofparables.engineering_delivery.people.IS people | teamsmatches the rows with either label. Several Plots can carry the same label. The rewrite joins each matching Plot with its own foreign keys, then combines the rows withUNION ALL. A Plot that matches several labels in one disjunction contributes its rows once per direction, not once per label. For example,peoplewithgraphLabels: ["actors"]answers to bothpeopleandactors. These are two names for one vertex, not two vertices. A vertex without a label matches each Plot that is not an edge. An edge without a label matches each edge whose ends fit. A Pane that SQL reads by name, such asparables.engineering_delivery.filters, is not a Plot. No element matches its rows. Its slug is a label only if a Plot declares it. The editor, save, publish and every read apply the same graph. - A Plot’s own pattern. A
GRAPH_TABLEin the SQL of a Plot never matches that Plot. It reads the graph as if the Plot were not in it, so it also matches no edge to the Plot. A label that names only that Plot is refused. A shared label still matches the other Plots that carry it. A viewnameswithMATCH (n) COLUMNS (n.name AS name)gives the names of the other node Plots. Every other query still matchesnamesas a node. So a Plot never reads itself through a pattern. The editor, save, publish and every read apply the same rule. ISand:.(r IS people)and(r:people)are the same.- Properties. A property is an output column of the Plot.
r.emailreads the columnemail. When only some of the Plots that an element matches have the column, the value is NULL in the rows of the others. That NULL has exactly the type that the column has in the first Plot of the element, in slug order, that has it: aDECIMAL(18,4)staysDECIMAL(18,4), text stays text in the same encoding, a time keeps its unit, a timestamp keeps its unit and its time zone, and a list stays a list. When the Plots that have the column give it one type, the column keeps that type, wherever the rows of the others come. When they give it different types, such as an integer in one and a number in another, the column has the type that aUNION ALLof them gives, as the same joins written by hand do. When no Plot that has the column can match the pattern, or no Plot can match it at all, the column has the type of that first Plot. Some types have no NULL of exactly that type: a list or an object whose items or fields carry a scalar, an object field name that holds a double quote or a backslash, and a list item name that holds a single quote. Such a Plot is passed over for the NULL’s type. When no other Plot gives one, the NULL has no type: theUNION ALLgives it the type of the Plots that match, and a pattern that none of them can match is refused at publish as a column of no type. When no Plot has the property, Parable refuses the query. Write each property with its variable. Parable refuses a name alone, such asemail, because Postgres reads it as a column of a table outside theGRAPH_TABLE. - Edges. An edge is a Plot that is marked as an edge, with one key column
for each end. Each key column holds the key of a Plot of the same Parable.
(a)-[e]->(b)joinsetoaby itsfromkey and tobby itstokey.<-is the other direction.-matches both directions. An edge’sgraphEdge.reverseLabelnames the same rows fromtotofrom. For example, an Employee Of edge from People to Companies with the reverse labelemploysmatches(b IS companies)-[IS employs]->(a IS people). This gives the same pairs as(a IS people)-[IS employee_of]->(b IS companies). A pattern without a label does not count the reverse label as another edge. As in Postgres, the-and the>of a right arrow may stand apart, as in]- >. A left edge ends at<-[e]-. A>after it is a syntax error at that>. Each match ofa,eandbis one row, also whenefits both directions, as an edge from a row to the same row does. - Variables. A variable that you write twice is one row:
(a)->(b)->(a)finds the pairs that point at each other. An edge variable that you write twice is one edge, so each of its edge patterns must point the same way and join the same source and the same destination:(a)-[f]->(a)-[f]->(a)finds the edges from a row to itself. As Postgres does, Parable refuses(a)-[f]->(b)<-[f]-(a)and(a)-[f]->(c)-[f]->(a). When you write labels for a variable in two places, write the same labels in the same order: Postgres and Parable refuse(a IS x | y)->(b)->(a IS y | x). AWHEREinside an element names only its own variable. Compare two elements in theWHEREafter the path. - Columns. Each entry of
COLUMNSis an expression and an optionalASname. A property without a name keeps the name of its column. Any other entry needs a name, as in Postgres: Parable refusesCOLUMNS (p.id + 1)and acceptsCOLUMNS (p.id + 1 AS next). Two entries can have the same name, as in Postgres. The columns of a result must have different names, so a repeated name gets the first free suffix_1,_2, and so on:COLUMNS (a.id, b.id)gives the columnsidandid_1. Aggregate and set-returning functions are refused inside the graph pattern. Apply them to the rows of theGRAPH_TABLE, ascount(*)does above.
GRAPH_TABLE into the joins that you would write, before
it checks or plans the SQL. So Policies, pins, and the Plots that a Plot
depends on are the same as for those joins. An error in the SQL around the
GRAPH_TABLE gives the line and the column in your SQL, in a query, a
Preview and a Refresh.
GRAPH_TABLE can also read the graph of another Parable, as
parables.<other_parable>, where your SQL can read that Parable’s Plots. SQL
in a Plot can read the Plots of a Platform Parable that you may read, and no
other Parable’s. When you may not read the other Parable, Parable refuses the
GRAPH_TABLE as it refuses the joins. The refusal gives the line and the
column of the Parable’s name in your SQL. It is the refusal of a Parable that
does not exist, so it tells nothing of the other Parable’s Plots, their
columns or their edges. A Refresh reads the other Parable’s
graph at the Release of it that your Release pinned, also when your pattern
matches none of its Plots.
Paths of any depth
Put a hop count after an edge to walk a hierarchy:->+ means ->{1,32}. {n} asks for exactly n hops.
{min,max} asks for any count in that range. Each bound must be a whole
number from 1 through 32. Reverse and either-direction edges take the same
hop counts. A quantified edge can follow or precede a fixed edge.
A quantified edge with foreign-key ends must reference the same vertex
Plot and key column at both ends. For example, both foreign keys of part_of can reference
teams.parable_id. Several edge labels can share the walk when their ends
reference that same Plot and key. A walk can mix those labels at each hop.
An either-direction walk can change direction at each hop.
Parable uses a recursive join, not one fixed join per hop. It keeps each
(start, end, depth) state once. The depth cap stops cycles in the data.
The result holds each endpoint pair once, even when several routes reach it.
A cycle can reach its own start. A missing intermediate vertex breaks a foreign-key
walk. Vertex labels and vertex conditions apply to the written endpoints,
not to intermediate vertices.
Your access applies at every table read. Foreign-key walks read intermediate
vertices and edges. A hidden vertex or edge breaks those walks.
Kind-column walks carry (id, kind) through each step. They can mix declared
kinds and matching edge Plots. Intermediate kind identities read no node
columns, so they join no node table. They apply edge Policies only, just as
the equivalent edge-only recursive SQL does. Written endpoint labels and node
properties still require ordinary node joins and their Policies.
Either-direction walks over large hierarchies can cost more than directed
walks. A walk can return along an edge, so even a tree can reach the full
depth cap. Cycles can also reach the cap. Parable keeps states at each depth,
and each recursive step can read the edge and vertex Plots again.
Use a smaller bound, such as -[IS part_of]-{1,4}, when four hops are enough.
The query’s memory budget and timeout still apply.
An edge condition such as [e IS part_of WHERE e.active] applies at every
hop. It can name only that edge variable. The variable does not name one
edge row, so the path WHERE and COLUMNS cannot read its properties.
Read the endpoint properties there instead.
GRAPH_TABLE reads one path pattern. Parable refuses:
- A
GRAPH_TABLEanywhere but where a table stands: afterFROMorJOIN, after a comma between tables, or inside parentheses around a join, as inFROM (GRAPH_TABLE (...) g JOIN teams t ON g.team_id = t.id). Postgres’s grammar has it only there, and withoutLATERAL. So Parable refusesFROM (GRAPH_TABLE (...)). - A quantified vertex, zero hops,
*, an open range, or a bound above 32. - A quantified foreign-key edge between different vertex Plots or different key columns. Use kind declarations for a walk across several kinds.
- A path of more than 15 edge patterns. A quantified edge counts as one pattern, not one pattern per hop. Fixed joins become slower to plan as the path grows.
- Two paths in one
MATCH. Join twoGRAPH_TABLEs. - A star, such as
*orr.*. Name each property. - A subquery or another
GRAPH_TABLEinside aGRAPH_TABLE, as Postgres refuses it, with or without parentheses around it. Use the subquery outside theGRAPH_TABLE, on its rows. - More than one expression in a
WHEREor aCOLUMNSitem, as in Postgres’s grammar. Write each column’s name afterAS:COLUMNS (p.email AS mail). - A column of a table outside the
GRAPH_TABLEthat Parable cannot plan. A quantified pattern cannot read an outside table. Join that table to the result instead. As Postgres does, Parable readst.idinFROM teams t, GRAPH_TABLE (... (p IS people WHERE p.team_id = t.id) ...)when the table comes before theGRAPH_TABLEin itsFROM, after a comma or an inner, left or crossJOIN, only aWHEREreads it, and the pattern matches one combination of Plots. TheWHEREnames the table as theFROMdoes: by its alias, or else by the last part of its name. An alias with a list of column names also names the table, including an alias afterWITH ORDINALITY. AfterFROM teams AS t(tid, tname), theWHEREreadst.tid. Each table of a join in parentheses without an alias keeps its name. AfterFROM (teams t JOIN code_changes c ON TRUE), theWHEREreadst.id. With an alias, as in(...) AS j, only the alias names the join, so theWHERErefusest.id. A word that names no table, such assysteminTABLESAMPLE system (10), is refused. Inside parentheses around a join, theWHEREalso reads tables before the parentheses in the sameFROM. A subquery such as(TABLE teams)exposes its alias only, when it has one. Parable refuses the column inCOLUMNS, in a pattern of more combinations, after aRIGHTorFULLJOIN, and from the query around a subquery that holds theGRAPH_TABLE. Then join the table to the rows of theGRAPH_TABLEoutside it: putp.team_id AS team_idinCOLUMNS, and compareg.team_id = t.idin theWHEREof the query. - A pattern whose elements can match a Plot that you may not read, or whose joins would read a Plot that has no data yet or that the catalog cannot serve. Add labels that name only other Plots.
- A pattern that can match more than 64 combinations of Plots, or whose search tries more than 4,096 partial combinations beyond one for each element. Add labels to its elements.
- A statement whose
GRAPH_TABLEs together join more Plots than oneGRAPH_TABLEat both limits can: 64 combinations of 31 elements, 1,984 joined Plots. A quantified edge also counts its recursive source reads. Add labels, or split the statement.
AI functions in Plots
A Plot can call the AI functions, such asponder() and
embed(). A Pipeline that selects embed(...) keeps the vectors in its own
table, with the model that wrote them. Parable makes no separate vector
table.
Read Plot data over the Workspace API
You can read a Plot without SQL. Each operation names the Parable by itsrootRefId, which is the root_ref_id column of workspace.parables. A
Parable token or an MCP token works. An MCP token works only while the
Workspace allows external agents
(SQL over HTTP).
Each takes an optional
versionId query parameter to read a published
Version, or refId to read a ref. Send one of them at most.
plot, or by its key in plotKey. reading
selects Latest (CURRENT) or one stored Refresh (REPORT_RUN, with its
reportRunId). The response has columns, rows, and nextCursor. Send
nextCursor back as cursor to read the next page. meta says what was
read: the reading, whether it came from a stored Refresh, the contract, and
the Version.
An agent that connects through the Parable MCP server can also list the
published Plots of the Workspace and read their SQL. See
MCP tools.
Name the Platform Parable Release and Refresh
A Plot data read can name, for each Platform Parable that it reads, the Release and the Refresh it must read, in two headers:400 and PA-AU-058.
Run and manage Reports over the Workspace API
These operations need a Parable token. The API refuses an MCP token for them with403 and WA-PAT-005.
The run and cancel paths start differently:
/api/parable/ and
/api/parables/. Use each path as shown.
Run a Report
id, status, trigger, and the result of
each Plot. Send the same idempotencyKey again to get the same run back. Read
the run’s progress from the run list.
To raise a paused Plot’s budget, send at least one of maxExternalCalls,
maxCost (in the smallest unit of the currency), and maxRuntime (in
milliseconds). Each new cap must be above the current cap and above what the
run already used.
Errors
Use the catalog to confirm a Plot’s columns and its
latest completed run before you depend on a result.
Query the pools has the Flight SQL clients for each
language.
Reports and
Plots explain how to
build them in the app.