> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleander.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tables

> Create and query tables in your private Iceberg catalog.

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

```sql theme={null}
-- 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');
```

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

```sql theme={null}
-- 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](/platform/lake/catalogs) for full schema definitions of the telemetry tables.

## Querying across sources

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

```sql theme={null}
-- 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 [Query](/platform/lake/query) for how to set up BigQuery connections and external catalogs.