You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polaris.apache.org by yu...@apache.org on 2026/05/15 16:37:18 UTC
(polaris) branch main updated: docs: tidy and correct top-level README (#4427)
This is an automated email from the ASF dual-hosted git repository.
flyrain pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git
The following commit(s) were added to refs/heads/main by this push:
new a0a99ad8d2 docs: tidy and correct top-level README (#4427)
a0a99ad8d2 is described below
commit a0a99ad8d2ec63c629ac50331ae6b6fd8836acbf
Author: Yufei Gu <yu...@apache.org>
AuthorDate: Fri May 15 09:37:12 2026 -0700
docs: tidy and correct top-level README (#4427)
---
README.md | 224 ++++++++++++++++++++++++++------------------------------------
1 file changed, 92 insertions(+), 132 deletions(-)
diff --git a/README.md b/README.md
index 8761a1e07b..1404eece73 100644
--- a/README.md
+++ b/README.md
@@ -6,9 +6,9 @@
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
-
+
http://www.apache.org/licenses/LICENSE-2.0
-
+
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -19,88 +19,76 @@
# Apache Polaris
-Apache Polaris™ is an open-source, fully-featured catalog for Apache Iceberg™. It implements Iceberg's
+Apache Polaris™ is an open-source, fully-featured catalog for Apache Iceberg™. It implements Iceberg's
[REST API](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml),
-enabling seamless multi-engine interoperability across a wide range of platforms, including Apache Doris™, Apache Flink®,
-Apache Spark™, Dremio® OSS, StarRocks, and Trino.
+enabling seamless multi-engine interoperability across a wide range of platforms, including Apache Doris™, Apache Flink®,
+Apache Spark™, Dremio® OSS, StarRocks, and Trino.
-Documentation is available at https://polaris.apache.org. The REST OpenAPI specifications are available here:
-[Polaris management API doc](https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/apache/polaris/refs/heads/main/spec/polaris-management-service.yml)
-and [Polaris Catalog API doc](https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/apache/polaris/refs/heads/main/spec/generated/bundled-polaris-catalog-service.yaml).
+Documentation is available at https://polaris.apache.org. The REST OpenAPI specifications can be browsed online:
+[Polaris Management API](https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/apache/polaris/refs/heads/main/spec/polaris-management-service.yml)
+and [Polaris Catalog API](https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/apache/polaris/refs/heads/main/spec/generated/bundled-polaris-catalog-service.yaml).
For a high-level, auto-generated tour of the codebase's modules and relationships, see the
[Code Wiki for Apache Polaris](https://codewiki.google/github.com/apache/polaris).
It is a third-party, auto-generated navigation aid, useful for orientation, but the
source tree remains the authoritative reference.
-[Subscribe to the dev mailing list][dev-list-subscribe] to join discussions via email or browse [the archives](https://lists.apache.org/list.html?dev@polaris.apache.org). Check out the [CONTRIBUTING guide](CONTRIBUTING.md)
-for contribution guidelines.
+To get involved, [subscribe to the dev mailing list][dev-list-subscribe] (or browse [the archives](https://lists.apache.org/list.html?dev@polaris.apache.org))
+and read the [CONTRIBUTING guide](CONTRIBUTING.md).
[](https://join.slack.com/t/apache-polaris/shared_invite/zt-2y3l3r0fr-VtoW42ltir~nSzCYOrQgfw)
[](https://github.com/apache/polaris/actions/workflows/ci-main.yml?query=branch%3Amain)
[dev-list-subscribe]: mailto:dev-subscribe@polaris.apache.org
-## Polaris Overview
-Click [here](https://polaris.apache.org/releases/latest/) for a quick overview of Polaris.
+## Overview & Quickstart
-## Quickstart
-Click [here](https://polaris.apache.org/releases/latest/getting-started/) for the quickstart experience, which will help you set up a Polaris instance locally or on any supported cloud provider.
+- [Overview](https://polaris.apache.org/releases/latest/) of what Polaris is and how it works.
+- [Quickstart](https://polaris.apache.org/releases/latest/getting-started/) to set up a Polaris instance locally or on a supported cloud provider.
## Project Structure
-Apache Polaris is organized into the following modules:
-- Primary modules:
- - [`polaris-core`](./polaris-core/README.md) - The main Polaris entity definitions and core business logic
- - [API modules](./api/README.md) - Build scripts for generating Java classes from the OpenAPI specifications:
- - `polaris-api-management-model` - Polaris Management API model classes
- - `polaris-api-management-service` - Polaris Management API service classes
- - `polaris-api-iceberg-service` - The Iceberg REST service classes
- - `polaris-api-catalog-service` - The Polaris Catalog API service classes
- - Runtime modules:
- - [`polaris-admin`](./runtime/admin/README.md) - The Polaris Admin Tool; mainly for bootstrapping persistence
- - [`polaris-runtime-defaults`](./runtime/defaults/README.md) - The runtime configuration defaults
- - [`polaris-distribution`](./runtime/distribution/README.md) - The Polaris distribution
- - [`polaris-server`](./runtime/server/README.md) - The Polaris Quarkus Server
- - [`polaris-runtime-service`](./runtime/service/README.md) - The package containing the Polaris service.
- - `polaris-runtime-spark-tests` - Integration tests for the Polaris Spark plugin
- - `polaris-runtime-test-common` - Test utilities
- - Persistence modules:
- - `polaris-relational-jdbc` - The JDBC implementation of BasePersistence to be used via AtomicMetaStoreManager
- - Extensions modules:
- - `polaris-extensions-federation-hadoop` - The Hadoop federation extension
- - [`polaris-extensions-federation-hive`](./extensions/federation/hive/README.md) - The Hive federation extension
-- Secondary modules:
- - `agregated-license-report` - Generates the aggregated license report
- - `polaris-bom` - The Bill of Materials (BOM) for Polaris
- - `polaris-build-logic` - Establishes consistent build logic
- - [`polaris-tests`](./integration-tests/README.md) - Normative integration tests for reuse in downstream projects
-- Tool modules:
- - Documentation configuration:
- - `polaris-config-docs-annotations` - Annotations for documentation generator
- - `polaris-config-docs-generator` - Generates Polaris reference docs
- - `polaris-config-docs-site` - The configuration documentation site
- - Other Tools:
- - `polaris-container-spec-helper` - Helper for container specifications
- - `polaris-immutables` - Predefined Immutables configuration & annotations for Polaris
- - `polaris-minio-testcontainer` - Minio test container
- - `polaris-rustfs-testcontainer` - RustFS test container
- - `polaris-misc-types` - Miscellaneous types for Polaris
- - `polaris-version` - Versioning for Polaris
-
-In addition to modules, there are:
-- [API specifications](./spec/README.md) - The OpenAPI specifications
-- [Python client](./client/python/README.md) - The Python client
-- [codestyle](./codestyle) - The code style guidelines
-- [getting-started](https://polaris.apache.org/releases/latest/getting-started/) - A collection of getting started examples
-- [gradle](./gradle) - The Gradle wrapper and Gradle configuration files including banned dependencies
-- [helm](./helm) - The Helm charts for Polaris.
-- [Spark Plugin](./plugins/spark/README.md) - The Polaris Spark plugin
-- [regtests](./regtests/README.md) - Regression tests
-- [server-templates](./server-templates) - OpenAPI Generator templates to generate the server code
-- [site](./site/README.md) - The Polaris website
-
-Outside of this repository, there are several other tools that can be found in a separate [Polaris-Tools](https://github.com/apache/polaris-tools) repository.
+The repository is organized into the following groups of Gradle modules. Each leaf is a Gradle subproject; some link to a per-module README.
+
+- **Core**
+ - [`polaris-core`](./polaris-core/README.md) - entity definitions and core business logic
+- **[API](./api/README.md)** - generated from the OpenAPI specifications:
+ - `polaris-api-management-model`, `polaris-api-management-service` - Polaris Management API
+ - `polaris-api-iceberg-service` - Iceberg REST service
+ - `polaris-api-catalog-service` - Polaris Catalog API
+- **Runtime**
+ - [`polaris-server`](./runtime/server/README.md) - Quarkus-based server
+ - [`polaris-admin`](./runtime/admin/README.md) - admin tool, mainly for bootstrapping persistence
+ - [`polaris-runtime-service`](./runtime/service/README.md) - the Polaris service package
+ - [`polaris-runtime-defaults`](./runtime/defaults/README.md) - default runtime configuration
+ - [`polaris-distribution`](./runtime/distribution/README.md) - distribution packaging
+ - `polaris-runtime-common`, `polaris-runtime-test-common` - shared runtime and test utilities
+ - `polaris-runtime-spark-tests` - integration tests for the Spark plugin
+- **Persistence**
+ - `polaris-relational-jdbc` - JDBC implementation of `BasePersistence`
+- **Extensions**
+ - [`polaris-extensions-federation-hive`](./extensions/federation/hive/README.md), `polaris-extensions-federation-hadoop`, `polaris-extensions-federation-bigquery` - catalog federation
+ - `polaris-extensions-auth-opa`, `polaris-extensions-auth-ranger` (plus `*-tests`) - external authorization
+- **Tooling & build support**
+ - `polaris-bom`, `polaris-build-logic`, `polaris-version` - BOM, shared build logic, versioning
+ - `polaris-immutables`, `polaris-misc-types`, `polaris-container-spec-helper` - shared utilities
+ - `polaris-minio-testcontainer`, `polaris-rustfs-testcontainer`, `polaris-hms-testcontainer` - test containers
+ - `polaris-config-docs-{annotations,generator,site}` - reference-doc generation
+ - `aggregated-license-report` - aggregated license report
+- **Tests**
+ - [`polaris-tests`](./integration-tests/README.md) - normative integration tests, reusable downstream
+
+Other top-level directories:
+
+- [`spec/`](./spec/README.md) - OpenAPI specifications
+- [`client/python/`](./client/python/README.md) - Python client
+- [`plugins/spark/`](./plugins/spark/README.md) - Polaris Spark plugin
+- [`regtests/`](./regtests/README.md) - regression tests
+- [`helm/`](./helm) - Helm charts
+- [`site/`](./site/README.md) - documentation site
+- [`codestyle/`](./codestyle), [`gradle/`](./gradle), [`server-templates/`](./server-templates) - build, style, and codegen support
+
+Additional tooling lives in the separate [Polaris-Tools](https://github.com/apache/polaris-tools) repository.
## Building and Running
@@ -126,90 +114,62 @@ select * from db1.table1;
## 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`
+- `make build-server`, `make build-admin` build components and container images
+- `make minikube-start-cluster`, `make minikube-cleanup` manage a local minikube cluster
+- `make helm-doc-generate`, `make helm-unittest` work with the Helm charts
+- `make client-lint`, `make client-regenerate` work with the Python client
+- `make install-dependencies-brew` install developer prerequisites on macOS
-To see available commands:
-```bash
-make help
-```
+### Running in Docker
+
+Build the image locally:
-For example, to build the Polaris server and its container image, you can simply run:
```bash
-make build-server
+./gradlew \
+ :polaris-server:assemble \
+ :polaris-server:quarkusAppPartsBuild --rerun \
+ -Dquarkus.container-image.build=true
```
-### More build and run options
-
-#### Running in Docker
+Run the published image:
-- To build the image locally:
- ```bash
- ./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. See the [Quickstart](https://polaris.apache.org/releases/latest/getting-started/quick-start/)
-for more information.
-
-#### Running in Kubernetes
+```bash
+docker run -p 8181:8181 -p 8182:8182 apache/polaris:latest
+```
-- See [README in `helm/polaris`](helm/polaris/README.md) for more information.
+The repository also ships docker-compose examples for various configurations. See the
+[Quickstart](https://polaris.apache.org/releases/latest/getting-started/quick-start/) for details.
-#### Configuring Polaris
+### Running in Kubernetes
-Polaris Servers can be configured using a variety of ways.
-Please see the [Configuration Guide](https://polaris.apache.org/releases/latest/configuration/)
-for more information.
+See [`helm/polaris/README.md`](helm/polaris/README.md).
-Default configuration values can be found in `runtime/defaults/src/main/resources/application.properties`.
+### Configuring Polaris
-#### Building docs
+Servers can be configured in several ways: see the [Configuration Guide](https://polaris.apache.org/releases/latest/configuration/).
+Default values live in [`runtime/defaults/src/main/resources/application.properties`](./runtime/defaults/src/main/resources/application.properties).
-- Docs are generated using [Hugo](https://gohugo.io/) using the [Docsy](https://www.docsy.dev/docs/) theme.
-- To view the site locally, run
- ```bash
- site/bin/run-hugo-in-docker.sh
- ```
-- See [README in `site/`](site/README.md) for more information.
+### Building the docs
-#### Publishing Build Scans to develocity.apache.org
+Docs use [Hugo](https://gohugo.io/) with the [Docsy](https://www.docsy.dev/docs/) theme. To preview locally:
-Build scans of CI builds from a branch or tag in the `apache/polaris` repository on GitHub publish build scans
-to the ASF Develocity instance at
-[develocity.apache.org](https://develocity.apache.org/scans?search.rootProjectNames=polaris), if the workflow runs have access to the Apache organization-level secret
-`DEVELOCITY_ACCESS_KEY`.
+```bash
+site/bin/run-hugo-in-docker.sh
+```
-Build scans of local developer builds publish build scans only if the Gradle command line option `--scan` is used.
-Those build scans are published to Gradle's public Develocity instance (see advanced configuration options below).
-Note that build scans on Gradle's public Develocity instance are publicly accessible to anyone.
-You have to accept Gradle's terms of service to publish to the Gradle's public Develocity instance.
+See [`site/README.md`](site/README.md) for more.
-CI builds originating from pull requests against the `apache/polaris` GitHub repository are published to Gradle's
-_public_ Develocity instance.
+### Develocity build scans
-Other CI build scans do only publish build scans to the Gradle's _public_ Develocity instance, if the environment
-variable `GRADLE_TOS_ACCEPTED` is set to `true`.
-By setting this variable you agree to the [Gradle's terms of service](https://gradle.com/terms-of-service), because
-accepting these ToS is your personal decision.
-You can configure this environment variable for your GitHub repository in the GitHub repository settings under
-`Secrets` > `Secrets and variables` > `Actions` > choose the `Variables` tab > `New repository variable`.
+Build scans for `apache/polaris` branch and tag CI runs are published to the ASF Develocity instance at
+[develocity.apache.org](https://develocity.apache.org/scans?search.rootProjectNames=polaris) when the
+`DEVELOCITY_ACCESS_KEY` org secret is available. Pull-request CI publishes to Gradle's public Develocity
+instance instead.
-Advanced configuration options for publishing build scans (only local and non-`apache/polaris` repository CI):
-* The project ID published with the build scan can be specified using the environment variable `DEVELOCITY_PROJECT_ID`.
- The project ID defaults to the GitHub repository owner/name, for example `octocat/polaris`.
-* The Develocity server can be specified using the environment variable `DEVELOCITY_SERVER` if build scans should be
- published to another than Gradle's public Develocity instance.
-* If you have to publish build scans to your own Develocity instance, you can configure the access key using a
- GitHub secret named `DEVELOCITY_ACCESS_KEY`.
+Local builds publish a scan only when invoked with `--scan`, and only after you accept Gradle's
+[terms of service](https://gradle.com/terms-of-service). Forks and other CI environments can opt in by setting
+`GRADLE_TOS_ACCEPTED=true`. Optional overrides: `DEVELOCITY_PROJECT_ID`, `DEVELOCITY_SERVER`, and a
+`DEVELOCITY_ACCESS_KEY` GitHub secret if you self-host Develocity.
## License