实体

本页记录了 Apache Polaris 中可管理的各类实体。

实体名称约束

REST 层对实体名称（命名空间层级、表名、视图名以及通用表名）强制执行以下规则。违反这些规则的名称将被拒绝，并返回 HTTP 400。

合法的实体名称：

• 不能为空；
• 不能是 . 或 ..；
• 不能包含 ISO 控制字符（U+0000–U+001F 或 U+007F–U+009F）；
• 不能包含以下任何字符：/:*?"<>|#+` ；
• 开头和结尾不能是空白字符。

这些约束适用于创建、注册和重命名操作。在该校验规则生效之前就已存在的实体，其名称不受读取或更新操作的影响。

策略的名称受更严格的约束；详见下文。

目录（Catalog）

目录是 Polaris 中的顶层实体，可以包含其他实体，例如命名空间和表。它们直接对应于 Apache Iceberg 目录。

有关使用 REST API 管理目录的信息，或有关可与目录关联哪些数据的更多信息，请参阅 CreateCatalogRequest OpenAPI。

⚠️ 警告

目录属性是客户端可见的配置值。Polaris 会通过 Iceberg REST /config 响应将它们返回给已认证的目录客户端。目录属性仅应用于存放非敏感的客户端配置。请勿在目录属性中存储密码、令牌、访问密钥或其他机密信息。

存储类型

Polaris 中的所有目录都关联一种存储类型。有效的存储类型包括 S3、Azure 和 GCS。此外，测试时还可使用 FILE 类型。这些类型分别对应目录内数据可能存放的不同存储提供商。根据存储类型的不同，还可以为目录设置其他各种配置，包括访问目录内数据时使用的凭据。

有关如何在 REST API 中使用存储类型的详细信息，请参阅 StorageConfigInfo OpenAPI。

有关存储类型的使用示例，请参阅文档。

命名空间（Namespace）

命名空间是一种逻辑实体，位于目录之内，可以包含其他实体，例如表或视图。其他一些系统可能会将命名空间称为 schema 或数据库。

在 Polaris 中，命名空间可以嵌套。例如，a.b.c.d.e.f.g 是一个合法的命名空间。可以说 b 位于 a 之内，依此类推。

有关使用 REST API 管理命名空间的信息，或有关命名空间可关联哪些数据的更多信息，请参阅 CreateNamespaceRequest OpenAPI。

表

Polaris 表是映射到 Apache Iceberg 表、Delta 表或 Hudi 表的实体。

有关使用 REST API 管理表的信息，或有关表可关联哪些数据的更多信息，请参阅 CreateTableRequest OpenAPI。

⚠️ 警告

表属性是可读的元数据，而不是密钥存储。请勿在表属性中存储密码、令牌、访问密钥或其他机密信息。

视图

Polaris 视图是映射到 Apache Iceberg 视图的实体。

有关使用 REST API 管理视图的信息，或有关视图可关联哪些数据的更多信息，请参阅 CreateViewRequest OpenAPI。

⚠️ 警告

视图属性是可读的元数据，而不是密钥存储。请勿在视图属性中存储密码、令牌、访问密钥或其他机密信息。

主体

Polaris 主体（principal）是可用于表示用户或服务的唯一身份。每个主体可以被分配一个或多个主体角色，以便访问目录及其内部的实体。

有关使用 REST API 管理主体的信息，或有关主体可关联哪些数据的更多信息，请参阅 CreatePrincipalRequest OpenAPI。

主体角色

Polaris 主体角色是可授予给主体的标签。每个主体可以拥有一个或多个主体角色，同一个主体角色也可以授予给多个主体。主体角色的分配可以基于给定主体的角色或职责，也可以基于该主体需要如何访问 Polaris 中的不同实体。

有关使用 REST API 管理主体角色的信息，或有关主体角色可关联哪些数据的更多信息，请参阅 CreatePrincipalRoleRequest OpenAPI。

目录角色

Polaris 目录角色是可授予给目录的标签。每个目录可以拥有一个或多个目录角色，同一个目录角色也可以被授予给多个目录。目录角色可以根据将要存放在目录中的数据性质来分配，也可以根据可能需要访问这些数据的用户和服务所属的组来分配。

每个目录角色可以被授予多个权限，并且每个目录角色可以被授予给一个或多个主体角色。这就是主体被授予访问目录内实体（例如命名空间和表）权限的机制。

策略

Polaris 策略是一组规则，用于在预定义条件下管理对指定资源的操作。Polaris 支持针对 Iceberg 表压缩、快照过期、行级访问控制以及自定义策略的策略。

策略名称只能包含字母（A–Z、a–z）、数字（0–9）、连字符（-）和下划线（_）。不符合此模式的名称会被拒绝并返回 HTTP 400。

策略可以应用于目录级别、命名空间级别或表级别。通过将策略附加到更高级别的作用域（如命名空间或目录），可以实现策略继承。因此，注册在这些实体下的表无需单独声明相同的策略。如果某个表或命名空间需要不同的策略，用户可以指派不同的策略，从而覆盖在更高级别实体上声明的同类型策略。

权限

Polaris 权限会授予给目录角色，以便让拥有某个主体角色的主体获得对拥有某个目录角色的目录的一定程度的访问权限。当某个权限被授予给一个目录角色时，被授予该目录角色的所有主体角色都会获得该权限；进而，被授予该主体角色的所有主体也会获得该权限。

权限的作用域可以是目录内的任何实体，包括目录本身。

有关每个权限类所支持的权限列表，请参阅 OpenAPI（TablePrivilege、ViewPrivilege、NamespacePrivilege、CatalogPrivilege）。