External Connections

oleander lets you connect external storage systems so you can query them alongside your Iceberg tables - joining cloud warehouse data with your lake data in a single SQL statement. Connections are managed in Settings → Lake.

BigQuery

Connect a Google Cloud project to query BigQuery tables directly from the oleander lake via DuckDB.

Setup

Navigate to Settings → Lake and open BigQuery connections.
Give the connection a name (lowercase letters, numbers, underscores - e.g. my_bq).
Enter your GCP Project ID.
Paste your service account JSON. The service account needs roles/bigquery.dataViewer (or narrower table-level permissions).

The service account key is stored encrypted and is never returned to the browser after saving.

Querying

Once connected, every BigQuery table in that project is reachable in DuckDB queries as connection_name.dataset.table:

-- Query a BigQuery table
SELECT *
FROM my_bq.analytics.events
WHERE _PARTITIONDATE = '2024-06-01'
LIMIT 100;

-- Join BigQuery with your Iceberg lake
SELECT e.user_id, u.plan
FROM my_bq.analytics.events e
JOIN oleander.default.users u ON e.user_id = u.id
WHERE e.event_type = 'signup';

Snowflake

Connect a Snowflake account to query your Snowflake tables from the oleander lake. Authentication uses key-pair signing - no passwords are stored.

Setup

Navigate to Settings → Lake and open Snowflake connections.
Fill in the required fields:

Field	Description
Name	A short identifier for this connection (e.g. `prod_sf`)
Account identifier	Your Snowflake account in `orgname-accountname` format
Username	The Snowflake user to authenticate as
Private key	RSA private key in PEM format (the user must have the matching public key registered in Snowflake)

Optionally specify a default warehouse, database, and role to scope queries.

Generating a key pair

If you don’t already have a key pair registered with Snowflake:

# Generate an RSA key pair
openssl genrsa -out snowflake_key.pem 2048
openssl rsa -in snowflake_key.pem -pubout -out snowflake_key.pub

# Register the public key with your Snowflake user
ALTER USER my_user SET RSA_PUBLIC_KEY='<contents of snowflake_key.pub>';

Paste the contents of snowflake_key.pem into the Private key field in oleander. The key is stored encrypted.

Querying

Tables are accessible as connection_name.schema.table in DuckDB:

-- Query a Snowflake table
SELECT *
FROM prod_sf.public.orders
WHERE created_at >= '2024-01-01'
LIMIT 100;

-- Join Snowflake with your Iceberg lake
SELECT o.order_id, c.segment
FROM prod_sf.public.orders o
JOIN oleander.default.customers c ON o.customer_id = c.id;

Snowflake Horizon

Snowflake Horizon is Snowflake’s built-in Iceberg catalog, powered by Polaris. Registering it in oleander gives you full Iceberg REST catalog access - including DuckDB queries, Polars workloads, and Spark jobs - against your Snowflake-managed Iceberg tables.

Setup

Navigate to Settings → Lake and open External catalogs.
Select Snowflake Horizon as the catalog type.
Fill in the required fields:

Field	Description
Name	A short catalog name (e.g. `sf_horizon`)
Catalog URI	Your Snowflake account URL, e.g. `https://orgname-accountname.snowflakecomputing.com`
Database	The Snowflake database to expose as an Iceberg catalog
Role	The Snowflake role used to access the catalog
Cloud provider	`aws`, `gcp`, or `azure`
Region	The cloud region your Snowflake account is in

Choose an authentication method:

Personal Access Token (PAT)
Key-pair

Generate a PAT in Snowflake and paste it into the Secret field. This is the simplest option.

-- Generate a PAT in Snowflake
ALTER USER my_user ADD PROGRAMMATIC ACCESS TOKEN my_pat;

Use an RSA key pair for authentication. Provide:

Field	Description
Username	The Snowflake user
Private key	RSA private key in PEM format
Passphrase	Passphrase for the private key (if encrypted)

The same key pair used for a Snowflake connection can be reused here.

Querying

Once registered, the catalog is available under its name in DuckDB, Polars, and Spark:

-- DuckDB: query a Snowflake Horizon Iceberg table
SELECT species, COUNT(*) AS n
FROM sf_horizon.default.flowers
GROUP BY 1
ORDER BY n DESC;

# Polars script mode
flowers = scan("sf_horizon.default.flowers")
result = flowers.group_by("species").agg(pl.len().alias("count"))

Credential vending is handled automatically via the Iceberg REST protocol - no S3 or GCS credentials need to be configured manually.

Getting Started

Platform

Coding with agents

Connections

CLI

External Connections

BigQuery

Setup

Querying

Snowflake

Setup

Generating a key pair

Querying

Snowflake Horizon

Setup

Querying

​BigQuery

​Setup

​Querying

​Snowflake

​Setup

​Generating a key pair

​Querying

​Snowflake Horizon

​Setup

​Querying

BigQuery

Setup

Querying

Snowflake

Setup

Generating a key pair

Querying

Snowflake Horizon

Setup

Querying