Ursa

Ursa is StreamNative's implementation of Lakestream. It provides protocol-neutral stream and log APIs, an Oxia-backed catalog, an object-storage engine, and a separate compaction service. Concepts explains the model; the specification defines the storage format and the materialization policy model, and the API reference documents the Java interfaces.

Storage and stream–table duality

With an object-storage backend, appends are batched into write-ahead log (WAL) objects. Compaction rewrites log ranges into per-log compacted objects and records their per-file indexes, so readers can continue across both representations. Those compacted objects are storage files, not catalog tables. External table materialization writes a separate output from the same compaction pass, with its own files and lifecycle. See lakehouse tables.

Oxia stores catalog metadata, offset indexes, and cursor state. The catalog is implemented by a Java library, not a separate catalog-server binary that every deployment must run. Broker routing and ownership remain the responsibility of the integration above it.

Integrations

Ursa for Apache Kafka (UFK) is a Kafka distribution built on the Lakestream API; it stores diskless topics through Ursa. UFK compiles against lakestream-api and loads ursa-storage-kafka-runtime and its implementation dependencies on an isolated runtime classpath. The current Ursa reactor no longer includes the historical Pulsar/ManagedLedger adapter modules.

Ursa also includes Iceberg and Delta Lake integration, a Kafka compacted-data reader, and a ClickHouse materialization sink. See architecture for module boundaries and feature matrix for supported paths.

Version compatibility

This section covers Ursa 1.0.0, published to Maven Central under the org.openlakestream group; the Java packages remain io.lakestream. UFK uses the same Ursa version. Keep the API and runtime dependencies aligned when building either project.

Research background

The design behind Ursa is described in the VLDB 2025 paper. For current module names, configuration, and behavior, use this documentation rather than treating the paper as an implementation reference.

Where next

• Quickstart — write to a stream and read it back through the Lakestream API from a Java program.

Evaluate

• Architecture — module boundaries, the write and read paths, and the compaction lifecycle.
• Feature matrix — which formats, clouds and catalogs are supported.

Build

• Embedding Ursa — artifacts, the two ways to open a catalog, and lifecycle rules.
• Schemas — Avro, JSON Schema and Protobuf, registry configuration, and schema evolution.
• Lakehouse tables — internal compacted objects versus external materialization.
• Table catalogs — declaring Iceberg, Delta, Unity Catalog and ClickHouse destinations.
• Materialization SPI and writing a materializer — the sink interface and how to implement one.

Operate

• Operations — running the compaction service, leadership and failure handling.
• Observability — the metrics Ursa exports and what to alert on.
• Storage backends — S3, GCS, Azure and local: addressing, credentials and permissions.
• Command-line tools — the ursa launcher and its admin subcommands.

Reference

• Configuration — how properties load, and a complete reference for WAL, object storage, compaction and table settings.
• Build from source — only needed to change Ursa itself.

Source: openlakestream/ursa