SQL
Run read-only DataFusion queries through a local Connect host and consume Arrow results incrementally.
Use the SQL API to run a read-only DataFusion query on your machine and consume its Arrow result batches as they arrive. SQL is one of the Connect APIs, alongside ScanDAL.
Install spiral-cli[sql] to get the CLI and its local SQL and Connect tools.
Start spiral connect and send the caller's normal API access token to
POST /sql/query. The host uses that token to resolve resources and obtain
storage access from their owning services. SQL accepts managed storage;
the paired ScanDAL API separately supports local files.
The request contains SQL, optional Project/ref defaults and optional typed parameters. Constant queries need no Project. Resource resolution follows the shared DataFusion catalog. Use SQL to limit the rows returned to your application. Table previews use ScanDAL.
The response starts with an Arrow schema, including for an empty result, then streams record batches. An explicit Arrow end marker establishes success. A failure after output starts terminates the response without that marker; discard any claim that the partial result is complete. Closing the response cancels execution. Queries are never retried automatically.
Use the TypeScript client to consume batches and cancel an unread response. See the HTTP reference for request fields and errors.
Availability
The API is implemented in local spiral connect. Hosted Connect serves no
SQL. Runtime and SDK releases must be upgraded together; the previous preview
request format is no longer supported.