Flight SQL API

Gnok implements the Arrow Flight SQL specification for high-throughput SQL execution over gRPC.

Endpoint

Use the Flight SQL endpoint provided for your organization, with TLS. For a URI-based Arrow client the shape is grpc+tls://<host>:<port>. Flight SQL access from outside Studio isn't self-service yet; email support@gnok.io to request it. See connectivity.

Supported Actions

Action	Description
CommandStatementQuery	Execute a SQL query and stream results
CommandStatementUpdate	Execute a DML statement and return affected row count
CommandStatementIngest	Data ingestion
CommandStatementSubstraitPlan	Execute a Substrait plan
CommandGetCatalogs	List available catalogs
CommandGetDbSchemas	List schemas in a catalog
CommandGetTables	List tables in a schema
CommandGetTableTypes	List supported table types
CommandGetPrimaryKeys	Get primary key constraints
CommandGetImportedKeys	Get imported keys
CommandGetExportedKeys	Get exported keys
CommandGetCrossReference	Get cross-references
CommandGetXdbcTypeInfo	Get type information
CommandGetSqlInfo	Get SQL metadata
CommandPreparedStatementQuery	Execute a prepared SELECT
CommandPreparedStatementUpdate	Execute a prepared DML
ActionCreatePreparedStatement	Create a prepared statement
ActionClosePreparedStatement	Close a prepared statement
ActionBeginTransaction	Begin a transaction
ActionEndTransaction	Commit or rollback a transaction
ActionCancelQuery	Cancel a running query
ActionBeginSavepoint	Create a savepoint
ActionEndSavepoint	Release or rollback a savepoint

Authentication

Use the Flight SQL handshake to pass a bearer token:

Authorization: Bearer <jwt-token>

Session headers x-gnok-session-id, snapshot mode, and TTL are extracted from the handshake metadata.

Data Format

Results are streamed as Arrow IPC record batches in columnar format for zero-copy consumption.

Error Handling

Errors are returned as gRPC status codes:

Code	Meaning
INVALID_ARGUMENT	SQL syntax error or invalid parameters
NOT_FOUND	Table or schema does not exist
PERMISSION_DENIED	Insufficient privileges
RESOURCE_EXHAUSTED	Query exceeded memory or time limits
INTERNAL	Unexpected engine error