Catalogs

Your private Iceberg catalog

Every oleander organization is automatically provisioned a private Apache Iceberg catalog named oleander. It is backed by Lakekeeper and stored on S3, and it exposes a standard Iceberg REST catalog endpoint, making it natively compatible with Spark, DuckDB, and any other Iceberg-aware tool. Creating an organization takes two steps: name it, then choose oleander managed or Your own S3 bucket under Storage. With your own bucket, the catalog’s data lives under warehouses/<organization id>/ in an S3 bucket in us-east-2, encrypted with a customer managed KMS key, and oleander reaches it through an IAM role in your account. The setup form generates the role’s permission and trust policies as you enter the bucket and key, and Test Connection writes a test object to the bucket before you continue. Only the organization owner can complete storage setup. The catalog contains two namespaces out of the box:

Namespace	Purpose
`default`	Your own tables, created via SQL, upload, or S3 sync
`telemetry`	Platform events written automatically by oleander

Create more namespaces with Add namespace on a catalog in the lake’s catalog tree, or from the CLI. To delete one you no longer need, choose Drop namespace from its more-options menu in the lake’s catalog tree, or call DELETE /api/v1/catalogs/{catalog}/namespaces/{namespace}. Only an empty namespace can be deleted, and default and telemetry are protected. Reference any table in your queries with the three-part identifier:

SELECT * FROM oleander.<namespace>.<table_name> LIMIT 100;

Telemetry namespace

The telemetry namespace is populated automatically as your pipelines run. It contains three tables:

`oleander.telemetry.run_events`

OpenLineage run lifecycle events (START, COMPLETE, FAIL, etc.) for every job execution. Partitioned by event_time.

Column	Type	Description
`event_type`	string	START, COMPLETE, FAIL, ABORT
`event_time`	timestamp	When the event occurred
`received_at`	timestamp	When oleander received the event
`telemetry_correlation_id`	string	Correlation ID
`run`	struct	Run ID and facets
`job`	struct	Job namespace and name
`inputs`	list	Input datasets
`outputs`	list	Output datasets

-- Recent failures across all jobs
SELECT
  job.namespace,
  job.name,
  run.runId,
  event_time
FROM oleander.telemetry.run_events
WHERE event_type = 'FAIL'
  AND event_time >= TIMESTAMP '2024-06-01 00:00:00'
ORDER BY event_time DESC
LIMIT 25;

-- Failure rate by job over the last 7 days
SELECT
  job.name,
  COUNT(*) FILTER (WHERE event_type = 'FAIL') AS failures,
  COUNT(*) FILTER (WHERE event_type = 'COMPLETE') AS successes,
  ROUND(100.0 * COUNT(*) FILTER (WHERE event_type = 'FAIL') / COUNT(*), 1) AS failure_pct
FROM oleander.telemetry.run_events
WHERE event_time >= TIMESTAMP '2024-05-25 00:00:00'
  AND event_type IN ('FAIL', 'COMPLETE')
GROUP BY job.name
ORDER BY failure_pct DESC;

`oleander.telemetry.traces`

OpenTelemetry spans from your pipelines and tasks. Partitioned by start_time.

Column	Type	Description
`trace_id`	string	OTel trace ID
`span_id`	string	OTel span ID
`parent_span_id`	string	Parent span ID
`span_name`	string	Span name
`span_kind`	string	CLIENT, SERVER, INTERNAL, etc.
`start_time` / `end_time`	timestamp	Span timing
`status_code`	string	OK, ERROR, UNSET
`span_attributes`	string	JSON-encoded span attributes
`resource_attributes`	string	JSON-encoded resource attributes

-- Slowest spans for a trace
SELECT
  span_name,
  DATEDIFF('millisecond', start_time, end_time) AS duration_ms,
  status_code
FROM oleander.telemetry.traces
WHERE trace_id = '<your-trace-id>'
  AND start_time >= TIMESTAMP '2024-06-01 00:00:00'
ORDER BY duration_ms DESC;

`oleander.telemetry.logs`

Log records emitted by your pipelines. Partitioned by time.

Column	Type	Description
`time`	timestamp	Log record timestamp
`severity`	string	DEBUG, INFO, WARN, ERROR
`trace_id` / `span_id`	string	Correlated trace context
`body`	string	Log message body
`log_attributes`	string	JSON-encoded log attributes
`resource_attributes`	string	JSON-encoded resource attributes

-- Error logs for a specific correlation ID
SELECT time, severity, body
FROM oleander.telemetry.logs
WHERE trace_id = '<your-trace-id>'
  AND severity IN ('ERROR', 'WARN')
  AND time >= TIMESTAMP '2024-06-01 00:00:00'
ORDER BY time DESC;

Spark compatibility

Because oleander is a standard Iceberg REST catalog, you can attach it directly in a Spark session. See the Spark integration guide for full configuration.

spark = SparkSession.builder \
    .config("spark.sql.catalog.oleander", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.oleander.type", "rest") \
    .config("spark.sql.catalog.oleander.uri", "<catalog-uri>") \
    .config("spark.sql.catalog.oleander.credential", "<token>") \
    .getOrCreate()

spark.sql("SELECT * FROM oleander.telemetry.run_events LIMIT 10").show()

Your catalog URI and credentials are available in lake settings.

Bring your own catalog

In addition to your private catalog, you can register an external Iceberg catalog and query it alongside your own data:

Getting Started

Platform

IAM

Connections

Integrations

Coding with agents

CLI

External Compute

Your private Iceberg catalog

Telemetry namespace

`oleander.telemetry.run_events`

`oleander.telemetry.traces`

`oleander.telemetry.logs`

Spark compatibility

Bring your own catalog

​Your private Iceberg catalog

​Telemetry namespace

​oleander.telemetry.run_events

​oleander.telemetry.traces

​oleander.telemetry.logs

​Spark compatibility

​Bring your own catalog

Your private Iceberg catalog

Telemetry namespace

`oleander.telemetry.run_events`

`oleander.telemetry.traces`

`oleander.telemetry.logs`

Spark compatibility

Bring your own catalog