Flight SQL - Parable

Arrow Flight SQL is the protocol Parable’s SQL endpoint speaks. Parable authenticates and authorizes each gRPC call, then streams the Arrow results back unchanged. To connect DBeaver or Python step by step, start with Query Provider Pools with SQL. For language clients, see Query with SDKs. Use this page when you configure an ADBC, JDBC, or custom Flight SQL client.

Connection contract

Setting	Value
Endpoint	`sql.parable.work:443` (production) or `sql.staging.parable.work:443` (staging), with TLS: `grpc+tls://sql.parable.work:443` for ADBC
Service path	`/arrow.flight.protocol.FlightService/*`
Authentication metadata	`authorization: Bearer <token>`
Workspace metadata	`x-tenant: <workspace-slug>`; for ADBC, the option `adbc.flight.sql.rpc.call_header.x-tenant`
Workspace permission	`tenant.data.query.providers` (the Provider Pools Reader role) to query the Provider Pools; `tenant.data.query` (the Data Access role) to query every pool. `tenant.view` alone, as in the Viewer role, is refused.

x-tenant-slug is accepted as an alias for x-tenant. Send the authorization metadata on every call. The Flight Handshake RPC is accepted and does nothing, so a client cannot authenticate through it.

Pools each role reaches

Role	Permission	Pools
Provider Pools Reader	`tenant.data.query.providers`	`providers`, `providers_quarantine`, `providers_quality`
Data Access	`tenant.data.query`	Every pool
Workspace Administrator	`tenant`	Every pool

A query that names a pool the caller’s role does not reach fails with INVALID_ARGUMENT, the message Query references an unknown relation, and error code QL-PL-002. Catalog discovery leaves that pool out. Inside the pools a role reaches, the Workspace’s Provider Policies decide which rows of each Provider table it reads. Table metadata leaves out the row count and validation rates of a table they narrow for the caller.

Tokens

A SQL tool authenticates with a pat_ token (API tokens). A SQL token a member creates in Protection → Access Tokens reaches that Workspace only and queries with its owner’s Workspace roles at the time of each query; a staff role never counts. Flight SQL refuses a call with:

Status	Message	Cause
`UNAUTHENTICATED`	`authentication required`	The call carries no `authorization` metadata.
`UNAUTHENTICATED`	`invalid token`	The token is unknown, for example incomplete or from another environment.
`UNAUTHENTICATED`	`token has been revoked`, `token expired`, `user not found`	The token was revoked, expired, or its owner was deactivated.
`INVALID_ARGUMENT`	`X-Tenant header required`	The call names no Workspace.
`NOT_FOUND`	`tenant not found`	No Workspace has that slug.
`PERMISSION_DENIED`	`personal access tokens are turned off for this Workspace`	The Workspace turned tokens off.
`PERMISSION_DENIED`	`tenant not in token scope`	`x-tenant` names a Workspace outside the token’s scope.
`PERMISSION_DENIED`	`insufficient permissions`	The owner’s roles in the Workspace cannot query: their role changed or they left it.

Connect with ADBC

import os

import adbc_driver_flightsql.dbapi
from adbc_driver_flightsql import DatabaseOptions

connection = adbc_driver_flightsql.dbapi.connect(
    os.environ["PARABLE_FLIGHT_URL"],
    db_kwargs={
        DatabaseOptions.AUTHORIZATION_HEADER.value:
            f"Bearer {os.environ['PARABLE_API_TOKEN']}",
        f"{DatabaseOptions.RPC_CALL_HEADER_PREFIX.value}x-tenant":
            os.environ["PARABLE_WORKSPACE"],
    },
)

cursor = connection.cursor()
cursor.execute("SELECT * FROM providers.google.users LIMIT 10")
print(cursor.fetch_arrow_table())

Set PARABLE_FLIGHT_URL to grpc+tls://sql.parable.work:443. The public endpoints use TLS. A local development stack can serve cleartext HTTP/2 at a grpc:// URL.

Request lifecycle

For a statement query:

GetFlightInfo validates and plans the SQL, then returns an opaque ticket.
DoGet executes from that ticket and streams Arrow record batches.
The client releases the result stream when it has consumed or abandoned it.

Prepared statements follow the same read path with a server-issued handle. See supported operations for the complete command matrix.

Limits

A query may run for up to one hour. The clock starts when Parable admits the query and covers planning and the whole result stream, including the time your client spends reading it. A query that runs longer fails with DEADLINE_EXCEEDED, Parable error code QL-TO-002 (QUERY_TIMEOUT), and the message query <id> exceeded timeout of 3600s. The server sets this limit. A longer deadline on your client does not extend it, and a shorter one ends the call early, so set your driver’s timeout to at least an hour before running a long query.

Row limit

A query may return up to 2,000,000 rows. DoGet sends them batch by batch as Query Layer produces them, and the Workspace API forwards each batch without collecting the result. A query whose result has more rows fails. Nothing is truncated: the stream ends with RESOURCE_EXHAUSTED, Parable error code QL-SQ-005 (RESULT_ROW_CAP_EXCEEDED), and this message:

Query result has more than 2,000,000 rows, the most one query can return. Add a LIMIT clause, or narrow the query with a WHERE filter or an aggregation.

The error can arrive after some record batches. Your driver raises it when you read past them, so discard the rows it returned before the error: they are not the result. To stay under the limit, add LIMIT, filter with WHERE, or aggregate in SQL. To read more rows than the limit, run one query per range of a column, such as one month at a time. Each IP address may send 600 calls a minute. A query takes at least two calls, GetFlightInfo and DoGet. Calls over the limit are refused with HTTP status 429 at Parable’s edge, which gRPC clients report as UNAVAILABLE.

Metadata discovery

Flight SQL supports catalog, schema, table, table-type, SQL capability, and logical key discovery. GetTables can include an Arrow IPC schema for every matching table, including optional Parable semantic metadata. Discover tables and columns shows how to use those operations.

Semantic types in comparisons

A column can carry a semantic scalar, such as Contact.Email or Contact.PhoneNumber, in its parable.scalar.canonical_name field metadata. Parable uses it when a query plans:

Two columns with different scalars can be compared only when scalar-lib declares them comparable, such as Temporal.Date and Temporal.DateTime. contacts.email = people.phone fails with INVALID_ARGUMENT and error code QL-PL-007 (INCOMPARABLE_SCALARS). The message names both columns and both scalars. The check covers comparison operators, BETWEEN, IN, subquery comparisons, join keys, and UNION, INTERSECT and EXCEPT columns.
To compare across scalars on purpose, cast one side where it is compared: CAST(contacts.email AS VARCHAR) = people.phone. A column without a scalar compares with any column.
A value you supply is never refused and needs no cast. A string literal or bound parameter compared with an Identity.UUID or Contact.Email column is converted to that scalar’s canonical form, so email = 'Jane@Example.com' matches the stored jane@example.com. A value that is not valid for the scalar is compared as written: email = '' returns no rows, and email <> '' returns every row with an email.

Embedding vectors in comparisons

embed() stamps its model identity (provider, name, variant, version, dimensions, normalization) in its output field’s parable.model_* metadata. Vectors are comparable only within one identity, so array_distance over two vectors stamped with different identities fails with INVALID_ARGUMENT and error code QL-PL-008 (INCOMPARABLE_EMBEDDING_MODELS), even when their dimensions match. The message names the function and both models. A Plot’s embed() column carries the identity of the model that wrote it. A vector without an identity, such as a literal vector, is compared on its dimensions alone; see Embed.

Recursive queries

WITH RECURSIVE walks a hierarchy, such as everyone below each manager at any depth. Join its two terms with UNION: it stops when an iteration adds no new row, so a loop in the data, such as a person listed as their own manager, ends. UNION ALL fails with INVALID_ARGUMENT and error code QL-PL-014 (RECURSIVE_UNION_ALL), because nothing else would stop it.

WITH RECURSIVE chain (manager_email, member_email) AS (
  SELECT manager_email, email FROM people WHERE manager_email IS NOT NULL
  UNION
  SELECT chain.manager_email, people.email
  FROM chain JOIN people ON people.manager_email = chain.member_email
)
SELECT manager_email, member_email FROM chain

A recursive query works the same way in SQL over Flight, in a Plot, in a Pipeline and in SQL over a Parable’s Plots. A large hierarchy is cheaper as a Pipeline: it is computed once per Refresh, and readers read its stored rows.

Errors and retries

Unsupported commands return gRPC UNIMPLEMENTED. Invalid authentication and Workspace selection return gRPC authentication, permission, or argument statuses rather than HTTP JSON errors. A Parable error code, such as QL-PL-002, arrives in the parable-error-code response metadata beside the gRPC status. Facts a refusal names for you, when it names any, arrive as a JSON object of strings in the binary parable-error-details-bin metadata. When query concurrency is saturated, Parable returns RESOURCE_EXHAUSTED with error code QL-IN-008. A client can retry a read-only query with bounded exponential backoff. Do not retry invalid SQL, authentication failures, or permission failures without changing the request. QL-PL-007 (INCOMPARABLE_SCALARS) is deterministic: change the comparison or add a CAST rather than retrying. QL-PL-008 (INCOMPARABLE_EMBEDDING_MODELS) is too: embed both sides with the same model. So is QL-PL-015 (FILTER_POLICY_COLUMN_MISSING, FAILED_PRECONDITION): a Plot that reads Provider data lacks a column a Parable filter Policy that binds you reads, usually identity_account_id; the Plot’s author adds the column. SQL the query engine cannot run is the query’s to fix. It returns INVALID_ARGUMENT with one of these codes, and the message never repeats the SQL or its values. Change the query rather than retrying:

Code	Cause	Message
`QL-PL-009` (`UNSUPPORTED_CAST`)	A `CAST` between types that do not convert, such as a struct or a list of structs to `VARCHAR`	Names both Arrow types (`VARCHAR` is `Utf8View`). For a struct it suggests selecting a field, `column['field']`; for a list, `cardinality(column)` for the element count or `unnest(column)` for one row per element.
`QL-PL-010` (`UNKNOWN_FUNCTION`)	A function that does not exist	Names the function and, when there is one, a function with a similar name.
`QL-PL-011` (`DUPLICATE_EXPRESSION_NAME`)	Two output expressions with the same name, such as `SELECT count(), count()`	Asks for an alias with `AS` on each duplicate.
`QL-PL-012` (`UNSUPPORTED_SQL`)	Other SQL the engine does not implement, such as `IN (SELECT ...)` inside a select-list expression, or an aggregate with its own `ORDER BY` used as a window function, such as `array_agg(DISTINCT x ORDER BY x) OVER ()`	`Query uses SQL that is not supported`, with no detail, because the engine’s own description can quote the query’s values. For a window aggregate’s own `ORDER BY`, the message names the construct and asks you to sort the result with `array_sort`, as in `array_sort(array_agg(DISTINCT x) OVER ())`, or to order the window with `OVER (ORDER BY ...)`.
`QL-PL-013` (`INVALID_FUNCTION_ARGUMENT`)	An AI function argument that `ask`, `noul`, `choice`, `score`, `ponder`, `model` or `embed` refuses while the query is planned, such as Jev criteria that are not valid JSON, `ask` questions read from a column, or an unknown `ponder` output type	The function’s own refusal, such as `Jev criteria must be valid JSON without duplicate keys`. It names the function, the argument and what the argument must be, never the value you gave.
`QL-PL-014` (`RECURSIVE_UNION_ALL`)	A `WITH RECURSIVE` query whose two terms are joined with `UNION ALL`	Names the recursive query and asks for `UNION`, which stops when an iteration adds no new row.

Casts and some unsupported expressions are checked when the result is read, so QL-PL-009 and QL-PL-012 can arrive from DoGet after GetFlightInfo succeeded. Other engine failures keep INTERNAL with QL-IN-001 (DATAFUSION_ERROR) and the message Query execution failed. That includes an error raised by a row while the query runs, such as a string value that does not cast to a number, because its description carries the value. A Jev argument read from a column, rather than written in the query, is checked on each row, so a row it refuses fails this way under the default on_error = fail. A row a Plot returns that its declared contract does not allow, read through parables.*, fails with FAILED_PRECONDITION and error code PA-AU-047, naming the Plot and never the value. When a workspace table is briefly unavailable, Parable returns UNAVAILABLE with error code QL-IN-005 (UPSTREAM_UNAVAILABLE), and the message names the table. Retry the query with the same backoff. Three error codes arrive with RESOURCE_EXHAUSTED, and each one needs a different response. Read the error code before you retry:

Error code	What happened	What to do
`QL-IN-008` (`QUERY_CONCURRENCY_REJECTED`)	Too many queries were running at once, so Parable did not run this one.	Retry with bounded exponential backoff.
`QL-IN-009` (`QUERY_RESOURCES_EXHAUSTED`)	The query ran out of memory or temporary disk space while it ran. Queries running at the same time share both, so other queries can be the cause, not only the size of yours.	Retry once after a backoff. If it fails again, narrow the query: add `LIMIT`, filter with `WHERE`, or sort, join, and group fewer rows at once.
`QL-SQ-005` (`RESULT_ROW_CAP_EXCEEDED`)	The result has more rows than the row limit.	Do not retry: the query fails the same way again. Add `LIMIT` or narrow the query.

RESOURCE_EXHAUSTED can also arrive with no error code, for example when a workspace table returns more rows than one query may read: do not retry it, because the message says why the query was refused. Like QL-SQ-005, QL-IN-009 can arrive after some record batches. Discard the rows your driver returned before the error: they are not the result. QL-TO-002 (QUERY_TIMEOUT) is a query past the time limit. Filter, aggregate, or split it before running it again.

Admin

​Connection contract

​Pools each role reaches

​Tokens

​Connect with ADBC

​Request lifecycle

​Limits

​Row limit

​Metadata discovery

​Semantic types in comparisons

​Embedding vectors in comparisons

​Recursive queries

​Errors and retries