Skip to main content
The Parable Data Engine is the read-only SQL surface over your Workspace’s data. It puts four pools on one SQL connection. Each pool is a catalog that you address by name. AI functions, such as 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.
When the catalog omits a value, the value is not known yet. Read the catalog over the Workspace API with a Parable token or an MCP token. An MCP token works only while the Workspace allows external agents (SQL over HTTP). PARABLE_API_TOKEN holds that token on this page. The Workspace API refuses a SQL token:
Response (shortened)
Other fields are not shown. 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.
SQL tools read the same tables through standard Flight SQL metadata and 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 at sql.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 as acme-corp.
Your Workspace role decides which pools you can query: 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.
A narrowed query is not an error. It returns fewer rows, or none. The Quality tables of a narrowed table read as empty for you, and the catalog withholds its statistics. People who hold All data access (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.
There is no published TypeScript Flight SQL client. A query can run for up to one hour and return up to 2,000,000 rows. A query past a limit fails. Parable does not truncate the result. Flight SQL lists every limit and error code.
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

Put EXPLAIN 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.
The result has two rows, with the columns 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.