ponder() and embed(), run on the same connection.
Connectors and Ingestion
explain how a Provider connects and syncs. This section explains the tables
that a sync produces, and the pools beside them.
Quality is a companion catalog,
providers_quality. It is
not a fifth data pool. It holds quality checks, statistical process control
(SPC), shape statistics, and health for Provider tables.
providers_quarantine is a second companion catalog. It holds the records
that a Provider sent and that failed validation. Its tables use the same
{connector}.{table} names as the providers pool.
References are fully qualified. There is no USE statement or
search_path. The Workspace that the request names selects the tables you
see. A catalog name never contains the Workspace slug.
The catalog
The catalog lists the Workspace’s tables across the pools. For each table, it can report:- Shape: the Arrow schema, the semantic type of each column, and row counts.
- Freshness: when Provider data last arrived, when a file was published, or when a Plot last completed. Workspace tables are current at query time.
- Quality: the latest checks and SPC results. Query their history in Quality.
- Lineage: the Provider stream, file, or Plot that produces the table.
PARABLE_API_TOKEN
holds that token on this page. The Workspace API refuses a SQL token:
Response (shortened)
system: true marks a column that Parable adds,
such as dt and the _parable_* state columns.
The app hides these columns behind Show system columns. You can still
select them in SQL. Flight SQL marks the same columns with the field metadata
parable.annotation.system.
GET /api/v2/catalog/table-stats returns the row count, size, quality, and
freshness of each Provider table. Quality says how one status
comes from a table’s two latest quality results. The
API Reference lists both operations. Both need the
tenant.data.catalog permission.
What the catalog shows depends on who asks:
- Statistics follow your access. When a Provider Policy or source permissions narrow or hide a table for you, the catalog withholds its row count and validation rates, because they describe rows you cannot read. The table and its columns are still listed. People with All data access see every statistic.
- An agent sees its owner’s pools. With an MCP token, or through the Parable MCP server after an MCP host signs in, the catalog and table statistics list only the tables in the pools that the owner can query over SQL. A Parable token lists what its owner’s session lists.
information_schema. To find the tables and columns that hold some kind of
data, call the search_available_data table function:
search_available_data searches the Provider and Workspace pools. It runs in
interactive queries only, so a Plot cannot call it. Search
explains it, and search_everything, which finds Provider records by what
their text says.
A table can be in the catalog before it has rows. A table with no rows still
has a schema, so an empty result is not a missing table. To find out whether a
table has data, count its rows:
Query the pools
The pools are queryable over Arrow Flight SQL atsql.parable.work, port
443, with TLS. ADBC and JDBC drivers work, and so do SQL tools such as
DBeaver and DataGrip.
Every call sends two values:
authorization: Bearer <token>. Use a SQL token that a Workspace member creates in Protection → Access Tokens. A SQL token works only over SQL. The Workspace API refuses it.x-tenant: <workspace-slug>, such asacme-corp.
No role reads the namespace of a Parable’s files,
artifacts.parable_<parable>,
outside that Parable. Only SQL in the Parable reads it
(Who reads a Parable’s tables).
A query that names a pool your role does not reach fails with
FROM or JOIN names a source this Workspace cannot read. Choose an available source, or ask a Workspace Administrator to check your data access. (QL-PL-002).
Rows you can read
Your role decides which pools you reach. Two Workspace controls then decide which rows of a Provider table you read:- Provider Policies. A Workspace administrator gives each role All rows, Rows where some conditions hold, Hidden (no rows), or Provider Permissions on a table, in Protection → Provider Policies.
- Provider Permissions. You read only the rows that you can open in the Provider itself, such as the files shared with you. They apply when a Provider Policy rule says so, or when the Workspace enforces them. Provider Permissions explains how a Provider declares them.
tenant.data.unrestricted), such as
Workspace Administrators, read every row past both controls. That covers
Flight SQL with a SQL token, SQL in the app, and the Refreshes they run.
Parable records each such read in the Workspace’s audit events, with a hash of
the SQL. The SQL over HTTP operations are an
exception: Policies narrow them for everyone.
Two errors come from these controls:
Provider Policies
explains each rule.
The examples below query the providers pool. To query
another pool, change the table to
artifacts.{namespace}.{table},
parables.{parable}.{plot}, workspace.{table}, or
providers_quality.summary.{table}. Set PARABLE_SQL_TOKEN to your SQL
token and PARABLE_WORKSPACE to your Workspace slug first. Keep the SQL token
apart from PARABLE_API_TOKEN, which the Workspace API examples use.
Query Provider Pools with SQL
shows how to get a role, create a SQL token, and connect DBeaver or Python,
step by step.
See the plan of a query
PutEXPLAIN before a query to see how Parable will run it. Parable plans
the query exactly as it would run it, and runs nothing. No AI function is
called.
plan_type and plan:
The plan holds no cost figures. To see how much data a query reads and how
many AI calls it can make, use the
dry run.
Only plain
EXPLAIN followed by one query works:
EXPLAIN works over Flight SQL and SQL over HTTP. A
Plot’s SQL cannot hold it.
More ways to read data
SQL over HTTP
Run read-only SQL over the Provider Pools with JSON requests, without a
Flight SQL client. Check a query’s cost before you run it.
Search
Find tables by what they hold, and Provider records by what their text
says.
Build a Lab
Run your own React app inside a Parable, and read Workspace data from it.
AI functions
Call models from SQL with
ponder(), embed(), and the Jev functions.