Tables

Overview

Tables in oleander live inside your private oleander Iceberg catalog. There are two namespaces:

oleander.default: tables you create, upload, or sync from S3
oleander.telemetry: platform-managed tables written automatically as your pipelines run (run_events, traces, logs)

All tables are Iceberg format, which means they support time-travel queries, schema evolution, and are readable from any Iceberg-compatible engine including Spark.

User tables (`default` namespace)

Tables in oleander.default are yours to create and manage. You can:

Run a CREATE TABLE statement in the lake SQL editor
Upload a parquet file via the upload dialog
Schedule an S3 sync to automatically import parquet files from your S3 bucket on a daily cadence
Write via DuckDB import from any external source

-- Create from a query
CREATE TABLE oleander.default.my_table AS
SELECT * FROM oleander.default.source_table WHERE region = 'us-west-2';

-- Time-travel query
SELECT * FROM oleander.default.my_table
AT (TIMESTAMP => now() - INTERVAL '7 DAYS');

Table health and maintenance

Every table in oleander.default shows a health status dot at the end of its row in the catalog tree: green for healthy, amber for warning, red for critical, or grey for unknown - a writer that recorded no snapshot statistics, so there’s nothing to grade. Hover the dot for row and delete-file counts, size, and (when degraded) what’s driving the grade. The usual cause is delete-file pressure: a CDC sink or streaming writer (Debezium, Kafka Connect, Flink, Fivetran) issues equality or position deletes that accumulate between compactions. A table with heavy delete pressure is routed to Spark for queries rather than DuckDB or Bloom, since applying a large equality-delete anti-join is what makes those queries slow to the point of not returning rather than just slow - explicitly requesting a different engine still runs it there, with a warning, instead of silently overriding your choice. Click the dot to schedule maintenance - it reads Schedule maintenance on a healthy or ungradeable table and Run maintenance on one that needs it. Maintenance compacts the table on Spark, rewriting data files and clearing the delete files that rewrite strands. Runs can fire once or on a recurring schedule; scheduled maintenance is listed under Maintenance in the lake panel’s Schedules tab, next to scheduled queries and transfers, with pause/resume/delete, per-operation toggles, and run history. Every run also appears on the Pipelines page like any other job.

Telemetry tables (`telemetry` namespace)

The telemetry namespace is populated automatically. These tables capture everything that flows through oleander’s observability pipeline - you can query them like any other table.

-- Recent pipeline failures
SELECT job.name, run.run_id, event_time
FROM oleander.telemetry.run_events
WHERE event_type = 'FAIL'
  AND event_time > now() - INTERVAL '24 HOURS'
ORDER BY event_time DESC;

-- Slow spans
SELECT span_name, start_time, end_time,
       epoch_ms(end_time - start_time) / 1000.0 AS duration_sec
FROM oleander.telemetry.traces
WHERE start_time > now() - INTERVAL '1 HOUR'
ORDER BY duration_sec DESC
LIMIT 20;

-- Error logs
SELECT time, severity, body
FROM oleander.telemetry.logs
WHERE severity = 'ERROR'
  AND time > now() - INTERVAL '1 HOUR';

See Catalogs for full schema definitions of the telemetry tables.

Querying across sources

Because BigQuery, Snowflake, and Postgres connections and external Iceberg catalogs are attached to the same DuckDB session, you can join across all of them in a single query:

-- Join your lake data with BigQuery
SELECT l.user_id, b.plan_name
FROM oleander.default.signups l
JOIN my_bq_connection.analytics.plans b ON l.plan_id = b.id;

See BigQuery, Snowflake, and Postgres for how to set up connections, and Catalogs for external Iceberg catalogs. A query that names a connection table always runs on DuckDB.

Getting Started

Platform

Connections

Coding with agents

CLI

External Compute

Overview

User tables (`default` namespace)

Table health and maintenance

Telemetry tables (`telemetry` namespace)

Querying across sources

​Overview

​User tables (default namespace)

​Table health and maintenance

​Telemetry tables (telemetry namespace)

​Querying across sources

Overview

User tables (`default` namespace)

Table health and maintenance

Telemetry tables (`telemetry` namespace)

Querying across sources