Arrow Flight SQL

Arrow Flight SQL is the primary high-throughput protocol for connecting to Gnok. It uses gRPC with Apache Arrow for zero-copy data transfer.

Connection

Client connectivity is set up by request

Flight SQL access from outside Studio isn't self-service for new organizations yet; use Gnok Studio in the meantime. Email support@gnok.io to request client connectivity. Gnok support provides the endpoint, client package, and credentials for your organization.

Connect to the Flight SQL host and port provided for your organization with TLS enabled. The example host flight.example.com and port 443 are placeholders. The Python examples read your token from a variable named GNOK_TOKEN in your own shell or secret manager. See connection details.

JDBC

Use the Arrow Flight SQL JDBC driver:

jdbc:arrow-flight-sql://flight.example.com:443?useEncryption=true

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
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
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

Python (pygnok)

import os
import pygnok

conn = pygnok.connect(host="flight.example.com", port=443, tls=True, token=os.environ["GNOK_TOKEN"])
cursor = conn.cursor()
cursor.execute("SELECT * FROM my_table")
df = cursor.fetch_arrow_table().to_pandas()

See the Python SDK page for the full API.

Data Format

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

Authentication

Pass a JWT bearer token via the standard Flight SQL auth handshake:

conn = pygnok.connect(
    host="flight.example.com",
    tls=True,
    port=443,
    token=os.environ["GNOK_TOKEN"]
)

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