Branches

Apache Polaris (incubating)

Apache Polaris™ is an open-source, fully-featured catalog for Apache Iceberg™. It implements Iceberg's REST API, enabling seamless multi-engine interoperability across a wide range of platforms, including Apache Doris™, Apache Flink®, Apache Spark™, StarRocks, and Trino.

Documentation is available at https://polaris.apache.org. The REST OpenAPI specifications are available here: Polaris management API doc and Polaris Catalog API doc.

Subscribe to the dev mailing list to join discussions via email or browse the archives. Check out the CONTRIBUTING guide for contribution guidelines.

Polaris Overview

Click here for a quick overview of Polaris.

Quickstart

Click here for the quickstart experience, which will help you set up a Polaris instance locally or on any supported cloud provider.

Building and Running

Apache Polaris is organized into the following modules:

polaris-core - The main Polaris entity definitions and core business logic
API modules (implementing the Iceberg REST API and Polaris management API):
- polaris-api-management-model - The Polaris management model
- polaris-api-management-service - The Polaris management service
- polaris-api-iceberg-service - The Iceberg REST service
Runtime modules:
- polaris-runtime-service - The runtime components of the Polaris server
- polaris-runtime-defaults - The runtime configuration defaults
- polaris-server - The Polaris server
- polaris-admin - The Polaris admin & maintenance tool
Persistence modules:
- polaris-eclipselink - The Eclipselink implementation of the MetaStoreManager interface
- polaris-relational-jdbc - The JDBC implementation of BasePersistence to be used via AtomicMetaStoreManager

Apache Polaris is built using Gradle with Java 21+ and Docker 27+.

./gradlew build - To build and run tests. Make sure Docker is running, as the integration tests depend on it.
./gradlew assemble - To skip tests.
./gradlew check - To run all checks, including unit tests and integration tests.
./gradlew run - To run the Polaris server locally; the server is reachable at localhost:8181. This is also suitable for running regression tests, or for connecting with Spark. Set your own credentials by specifying system property ./gradlew run -Dpolaris.bootstrap.credentials=POLARIS,root,s3cr3t where:
- POLARIS is the realm
- root is the CLIENT_ID
- secret is the CLIENT_SECRET
- If credentials are not set, it will use preset credentials POLARIS,root,s3cr3t
./regtests/run_spark_sql.sh - To connect from Spark SQL. Here are some example commands to run in the Spark SQL shell:

create database db1;
show databases;
create table db1.table1 (id int, name string);
insert into db1.table1 values (1, 'a');
select * from db1.table1;

env POLARIS_HOST=localhost ./regtests/run.sh - To run regression tests locally, see more options here.

Makefile Convenience Commands

To streamline the developer experience, especially for common setup and build tasks, a root-level Makefile is available. This Makefile acts as a convenient wrapper around various Gradle commands and other tooling, simplifying interactions. While Gradle remains the primary build system, the Makefile provides concise shortcuts for frequent operations like:

Building Polaris components: e.g., make build-server, make build-admin
Managing development clusters: e.g., make minikube-start-cluster, make minikube-cleanup
Automating Helm tasks: e.g., make helm-doc-generate, make helm-unittest
Handling dependencies: e.g., make install-dependencies-brew
Managing client operations: e.g., make client-lint, make client-regenerate

To see available commands:

make help

For example, to build the Polaris server and its container image, you can simply run:

make build-server

More build and run options

Running in Docker

To build the image locally:

./gradlew \
  :polaris-server:assemble \
  :polaris-server:quarkusAppPartsBuild --rerun \
  -Dquarkus.container-image.build=true

docker run -p 8181:8181 -p 8182:8182 apache/polaris:latest - To run the image.

The Polaris codebase contains some docker compose examples to quickly get started with Polaris, using different configurations. Check the ./getting-started directory for more information.

Running in Kubernetes

See README in helm/polaris for more information.

Configuring Polaris

Polaris Servers can be configured using a variety of ways. Please see the Configuration Guide for more information.

Default configuration values can be found in runtime/defaults/src/main/resources/application.properties.

Building docs

Docs are generated using Hugo using the Docsy theme.
To view the site locally, run
```
site/bin/run-hugo-in-docker.sh
```
See README in site/ for more information.

License

Apache Polaris is under the Apache License Version 2.0. See the LICENSE.

ASF Incubator disclaimer

Apache Polaris™ is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.

Apache®, Apache Polaris™, Apache Iceberg™, Apache Spark™ are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries.

Apache Polaris, the interoperable, open source catalog for Apache Iceberg