Query with SDKs

Use a Flight SQL client SDK to execute SQL and receive Arrow results. Every client sends the same three connection values:

The Flight SQL endpoint: sql.parable.work:443 in production or sql.staging.parable.work:443 in staging, with TLS.
authorization: Bearer <token>.
x-tenant: <workspace-slug>.

A member whose role can query the Provider Pools creates a SQL token in Protection → Access Tokens. Query Provider Pools with SQL walks through the role, the token, and a first query in DBeaver or Python.

The Workspace API SDKs expose resource operations. SQL uses Flight SQL client SDKs because query results stream as Arrow data.

Install a client

pip install adbc-driver-flightsql pyarrow

go get github.com/apache/arrow-go/v18/arrow/flight/flightsql

cargo add arrow-flight futures tonic

There is no published TypeScript Flight SQL client yet.

Query Provider data

Set PARABLE_API_TOKEN and PARABLE_WORKSPACE, then provide the endpoint in the form expected by your client:

Rust uses PARABLE_FLIGHT_URL=https://sql.parable.work.
Python ADBC uses PARABLE_FLIGHT_URL=grpc+tls://sql.parable.work:443.
Go uses PARABLE_FLIGHT_ENDPOINT=sql.parable.work:443.

Replace the table and columns with values from catalog discovery.

import os

import adbc_driver_flightsql.dbapi
from adbc_driver_flightsql import DatabaseOptions

with 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"],
    },
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("""
            SELECT id, primaryemail, orgunitpath
            FROM providers.google.users
            WHERE suspended = false
            LIMIT 10
        """)
        print(cursor.fetch_arrow_table())

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/apache/arrow-go/v18/arrow/flight/flightsql"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

ctx := metadata.AppendToOutgoingContext(
	context.Background(),
	"authorization", "Bearer "+os.Getenv("PARABLE_API_TOKEN"),
	"x-tenant", os.Getenv("PARABLE_WORKSPACE"),
)

client, err := flightsql.NewClient(
	os.Getenv("PARABLE_FLIGHT_ENDPOINT"),
	nil,
	nil,
	grpc.WithTransportCredentials(credentials.NewTLS(nil)),
)
if err != nil {
	log.Fatal(err)
}
defer client.Close()

info, err := client.Execute(ctx, `
  SELECT id, primaryemail, orgunitpath
  FROM providers.google.users
  WHERE suspended = false
  LIMIT 10
`)
if err != nil {
	log.Fatal(err)
}

reader, err := client.DoGet(ctx, info.Endpoint[0].Ticket)
if err != nil {
	log.Fatal(err)
}
defer reader.Release()

for reader.Next() {
	fmt.Println(reader.Record())
}

let token = std::env::var("PARABLE_API_TOKEN")?;
let workspace = std::env::var("PARABLE_WORKSPACE")?;
let channel = tonic::transport::Channel::from_shared(
    std::env::var("PARABLE_FLIGHT_URL")?,
)?
.connect()
.await?;

let mut client = arrow_flight::sql::client::FlightSqlServiceClient::new(channel);
client.set_header("authorization", format!("Bearer {token}"));
client.set_header("x-tenant", workspace);

let info = client
    .execute(
        r#"
        SELECT id, primaryemail, orgunitpath
        FROM providers.google.users
        WHERE suspended = false
        LIMIT 10
        "#
        .to_string(),
        None,
    )
    .await?;

let ticket = info.endpoint[0].ticket.clone().expect("ticket");
let mut stream = client.do_get(ticket.into()).await?;
while let Some(batch) = futures::TryStreamExt::try_next(&mut stream).await? {
    println!("{batch:?}");
}

Keep queries portable

Use fully qualified names such as providers.google.users.
Discover schemas instead of assuming that a Provider or stream is enabled.
Treat results as Arrow data and preserve its types until the application boundary.
Use prepared statements when a value comes from user input.

See SQL behavior for the shared language contract and Flight SQL for protocol operations and client capability negotiation.

Admin

​Install a client

​Query Provider data

​Keep queries portable

Install a client

Query Provider data

Keep queries portable