Polaris 演进

本页讨论随着项目的发展，Apache Polaris 可以带来哪些预期。

将 Polaris 用作目录（Catalog）

Polaris 主要设计用作表和视图的目录。为此，它实现了 Iceberg REST Catalog API 以及自身的 REST API。

Iceberg REST Catalog API 的修订由 Apache Iceberg 社区控制。Polaris 会尽力准确地实现该规范。即便如此，某些可选的 REST Catalog 功能可能不会立即获得支持。总体而言，不保证 Polaris 的每个版本都实现最新版的 Iceberg REST Catalog API。

任何由 Polaris 掌控且不处于「实验性」或「测试版（beta）」状态的 API（例如 Management API），都以带版本号的 REST API 形式进行维护。Polaris 的新版本可能会对当前版本的 API 进行修改。当发生此类情况时，这些修改旨在与先前版本的 Polaris 客户端保持兼容。某些端点和参数可能会被弃用（deprecated）。

如果某个 API 需要进行无法向后兼容的重大变更，则可能会引入新的端点（URI 路径）。同时也可能引入新的 URI「根路径」（例如 api/catalog/v2）。

请注意，这些「v1」「v2」等 URI 路径片段并不与 Polaris 的发布版本或 Polaris 项目版本号一一对应（例如，出现「v2」路径片段并不意味着它是在 Polaris 2.0 中加入的）。

对于已弃用的 API 端点 / 参数 / 版本等，Polaris 服务器会在一段过渡期内继续提供支持，以便客户端完成迁移。

管理 Polaris 数据库

Polaris 将其数据存储在数据库中，这在其他文档中有时被称为「Metastore」或「Persistence」。

每个 Polaris 版本可能支持多种持久化实现，例如「JDBC」。

每种持久化类型各自独立演进。在每种持久化类型内部，Polaris 会尝试支持滚动升级（即版本 X 和 X + 1 的服务器同时运行）。

不过，不同持久化类型之间的迁移不支持以滚动升级的方式进行。Polaris 提供了工具用于在不同目录之间迁移，这些工具也可用于在不同持久化类型之间迁移。在这种情况下，预期会出现服务中断（停机）。

将 Polaris 用作构建期依赖

Polaris 会生成多个 jar。根据 Polaris 发行版中所包含的许可条款，下游项目可以使用这些 jar 或 Polaris 代码的自定义构建产物。

Polaris 代码所要求的最低 JRE 版本（编译目标）可能在任何版本中更新。不同的 Polaris jar 可能有不同的最低 JRE 版本要求。

无论模块名称如何，也无论类 / 方法是否为 public，Java 类的变更都可能随时发生。

这种方法并非意在阻止下游项目使用 Polaris 代码，而是为了在演进代码库以支持新的目录级特性并提升代码效率时，提供更大的灵活性。我们鼓励下游项目的维护者加入 Polaris 邮件列表，以便跟踪项目变更、提出改进建议，并在遇到特定兼容性问题时与 Polaris 社区进行交流。

语义化版本

Polaris 努力遵循语义化版本规范，涵盖 REST API（beta 和 experimental API 除外）、Polaris 策略以及面向用户的配置。

以下是 Polaris 在 REST API / 配置方面遵循 SemVer 的一些示例。这些示例仅用于说明，并不详尽无遗。

• Polaris 实现了上一版本中尚未实现的某个可选 Iceberg REST Catalog 特性，这不被视为重大变更。
• 以向后兼容的方式支持 Iceberg REST Catalog 规范的新版本，不被视为重大变更。具体而言，支持新的 REST API 前缀（例如 v2）不属于重大变更，因为它不会影响旧版客户端。
• 以非向后兼容的方式更改 Iceberg REST Catalog 特性 / 端点的实现（例如移除或重命名请求参数）属于重大变更。
• 停止支持带有 polaris. 名称前缀的配置属性属于重大变更。
• 停止支持任何先前定义的策略类型或属性属于重大变更。
• 将 Quarkus Runtime 升级到其下一个主要版本属于重大变更（因为由 Quarkus 管理的配置可能会发生变化）。