Apache Polaris

Apache Polaris™ 是一个开源的、功能完备的 Apache Iceberg™ 目录。它实现了 Iceberg 的 REST API，实现了跨多种平台的无缝多引擎互操作性，包括 Apache Doris™、Apache Flink®、 Apache Spark™、Dremio® OSS、StarRocks 和 Trino。

文档可在 https://polaris.apache.org 获取。REST OpenAPI 规范可在线浏览： Polaris Management API 和 Polaris Catalog API。

如需对代码库的模块及关系进行高层级的自动概览，请参阅 Apache Polaris 代码维基。它是一个第三方的自动生成的导航辅助工具，有助于了解整体结构，但源代码树仍然是权威的参考依据。

如需参与贡献，请订阅开发邮件列表（或浏览存档）并阅读CONTRIBUTING 指南。

概述与快速入门

Polaris 是什么及其工作原理的概述
快速入门，用于在本地或受支持的云提供商上设置 Polaris 实例。

项目结构

该仓库组织为以下 Gradle 模块组。每个叶子节点都是一个 Gradle 子项目；部分链接到每个模块的 README。

核心
- polaris-core - 实体定义和核心业务逻辑
API - 从 OpenAPI 规范生成：
- polaris-api-management-model, polaris-api-management-service - Polaris 管理 API
- polaris-api-iceberg-service - Iceberg REST 服务
- polaris-api-catalog-service - Polaris 目录 API
运行时
- polaris-server - 基于 Quarkus 的服务器
- polaris-admin - 管理工具，主要用于引导持久化
- polaris-runtime-service - Polaris 服务包
- polaris-runtime-defaults - 默认运行时配置
- polaris-distribution - 发行版打包
- polaris-runtime-common, polaris-runtime-test-common - 共享运行时和测试工具
- polaris-runtime-spark-tests - Spark 插件的集成测试
持久化
- polaris-relational-jdbc - BasePersistence 的 JDBC 实现
扩展
- polaris-extensions-federation-hive, polaris-extensions-federation-hadoop, polaris-extensions-federation-bigquery - 目录联合
- polaris-extensions-auth-opa, polaris-extensions-auth-ranger (加上 *-tests) - 外部授权
工具与构建支持
- polaris-bom, polaris-build-logic, polaris-version - BOM、共享构建逻辑、版本控制
- polaris-immutables, polaris-misc-types, polaris-container-spec-helper - 共享工具
- polaris-floci-aws-testcontainer, polaris-floci-az-testcontainer, polaris-floci-gcp-testcontainer, polaris-minio-testcontainer, polaris-rustfs-testcontainer, polaris-hms-testcontainer - 测试容器
- polaris-config-docs-{annotations,generator,site} - 参考文档生成
- aggregated-license-report - 聚合许可证报告
测试
- polaris-tests - 规范性集成测试，可下游复用

其他顶级目录：

spec/ - OpenAPI 规范
client/python/ - Python 客户端
plugins/spark/ - Polaris Spark 插件
regtests/ - 回归测试
helm/ - Helm 图表
site/ - 文档站点
codestyle/, gradle/, server-templates/ - 构建、样式和代码生成支持

额外的工具位于独立的 Polaris-Tools 仓库中。

构建和运行

Apache Polaris 使用 Java 21+ 和 Docker 27+ 通过 Gradle 进行构建。

./gradlew build - 用于构建和运行测试。请确保 Docker 正在运行，因为集成测试依赖于它。
./gradlew assemble - 用于跳过测试。
./gradlew check - 用于运行所有检查，包括单元测试和集成测试。要运行除集成测试外的所有检查，请使用 ./gradlew check -PnoIntegrationTests。
./gradlew run - 用于在本地运行 Polaris 服务器；服务器可在 localhost:8181 访问。这也适用于运行回归测试，或与 Spark 连接。通过指定系统属性 ./gradlew run -Dpolaris.bootstrap.credentials=POLARIS,root,secret 来设置您自己的凭据，其中：
- POLARIS 是 realm
- root 是 CLIENT_ID
- secret 是 CLIENT_SECRET
- 如果未设置凭据，它将使用预设凭据 POLARIS,root,s3cr3t
./regtests/run_spark_sql.sh - 用于从 Spark SQL 连接。以下是一些在 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 - 用于在本地运行回归测试，更多选项请参见此处。

Makefile 便捷命令

make build-server, make build-admin 构建组件和容器镜像
make minikube-start-cluster, make minikube-cleanup 管理本地 minikube 集群
make helm-doc-generate, make helm-unittest 使用 Helm charts
make client-lint, make client-regenerate 使用 Python 客户端
make install-dependencies-brew 在 macOS 上安装开发者前置依赖

在 Docker 中运行

在本地构建镜像：

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

运行已发布的镜像：

docker run -p 8181:8181 -p 8182:8182 apache/polaris:latest

该仓库还提供了针对各种配置的 docker-compose 示例。请参阅快速入门以获取详细信息。

在 Kubernetes 中运行

请参阅 helm/polaris/README.md。

配置 Polaris

服务器可以通过多种方式配置：请参阅配置指南。默认值位于 runtime/defaults/src/main/resources/application.properties。

构建文档

文档使用 Hugo 和 Docsy 主题。要在本地预览：

site/bin/run-hugo-in-docker.sh

参见 site/README.md 以获取更多信息。

Develocity 构建扫描

apache/polaris 分支和标签 CI 运行的构建扫描会发布到 ASF Develocity 实例 develocity.apache.org，前提是 DEVELOCITY_ACCESS_KEY 组织密钥可用。Pull-request CI 则发布到 Gradle 的公共 Develocity 实例。

本地构建仅在以 --scan 调用时发布扫描，且仅在你接受 Gradle 的服务条款之后。Forks 和其他 CI 环境可通过设置 GRADLE_TOS_ACCEPTED=true 选择加入。可选覆盖项：DEVELOCITY_PROJECT_ID、DEVELOCITY_SERVER，以及如果你自托管 Develocity，则需设置 DEVELOCITY_ACCESS_KEY GitHub 密钥。

许可证

Apache Polaris 采用 Apache License Version 2.0。参见 LICENSE。