KnowForge配置参考
师成· 更新于 2026-09-29· 阅读 99 分钟· 0 次阅读配置参考
本文档提供了 Polaris 所有配置选项的完整参考。
此处列出的所有属性均为运行时属性，可以在不重新构建 Polaris 的情况下进行更改。
目录
功能与行为
polaris.features
Polaris 的功能配置。这些是稳定的、面向用户的设置。
polaris.features."ADD_TRAILING_SLASH_TO_LOCATION"
设置后，表或命名空间的基础位置如果末尾没有 /，将会为其添加 / 后缀。
- 类型：
Boolean - 默认值：
true - 目录配置：
polaris.config.add-trailing-slash-to-location
polaris.features."ALLOW_CLIENT_SPECIFIED_TABLE_LOCATION"
如果设置为 true（默认值），Polaris 会接受创建或更新请求中明确提供的 location（以及 write.data.path / write.metadata.path 属性），但须通过常规的结构化位置、允许位置、元数据位置以及重叠校验。如果设置为 false，此类请求将被拒绝，而不考虑其他位置兼容性标志。此设置不适用于联邦目录。
- 类型：
Boolean - 默认值：
true - 目录配置：
polaris.config.allow.client-specified.table.location
polaris.features."ALLOW_DROPPING_NON_EMPTY_PASSTHROUGH_FACADE_CATALOG"
如果启用，则允许删除包含命名空间或表的透传门面目录（passthrough-facade catalog）。透传门面目录在与源目录同步时可能残留实体。短期内这些实体将被忽略，长期来看会有相应的方法或后台作业来清理它们。
- 类型：
Boolean - 默认值：
false - 目录配置：
polaris.config.allow-dropping-non-empty-passthrough-facade-catalog
polaris.features."ALLOW_EXTERNAL_CATALOG_CREDENTIAL_VENDING"
如果设置为 true，则允许为外部目录发放凭据（credential vending）。
- 类型：
Boolean - 默认值：
true - 目录配置：
polaris.config.enable.credential.vending
polaris.features."ALLOW_EXTERNAL_METADATA_FILE_LOCATION"
若设置为 true，Polaris 允许元数据文件位于表的默认元数据目录之外。这会放宽元数据必须保留在表位置之下的常规检查，仅应在元数据被有意存储于单独受控位置时使用。
- 类型：
Boolean - 默认值：
false - Catalog Config：
polaris.config.allow.external.metadata.file.location
polaris.features."ALLOW_EXTERNAL_TABLE_LOCATION"
已弃用。请改用 ALLOW_EXTERNAL_METADATA_FILE_LOCATION。启用此传统兼容性标志会放宽元数据位置检查；它并不控制表位置是否可以脱离结构化命名空间布局。如需该行为，请使用 ALLOW_UNSTRUCTURED_TABLE_LOCATION。
- 类型：
Boolean - 默认值：
false - Catalog Config：
polaris.config.allow.external.table.location
polaris.features."ALLOW_FEDERATED_CATALOGS_CREDENTIAL_VENDING"
若设置为 true（默认），则允许对外部 catalog 进行凭证分发。请注意，这需要 ALLOW_EXTERNAL_CATALOG_CREDENTIAL_VENDING 先为 true。
- 类型：
Boolean - 默认值：
true - Catalog Config：
polaris.config.allow-federated-catalogs-credential-vending
polaris.features."ALLOW_INSECURE_STORAGE_TYPES"
允许使用被视为不安全的 FileIO 实现。启用此设置可能会使服务面临严重的安全风险！此设置仅应在测试中设为 true！
- 类型：
Boolean - 默认值：
false
polaris.features."ALLOW_NAMESPACE_LOCATION_OVERLAP"
若设置为 true，则允许一个命名空间的位置位于另一个命名空间的位置之内。此规则仅在父 catalog 或命名空间范围内强制执行。
- 类型：
Boolean - 默认值：
false
polaris.features."ALLOW_OPTIMIZED_SIBLING_CHECK"
设置为 true 后，Polaris 允许在运维人员明确确认后启用 OPTIMIZED_SIBLING_CHECK。仅当该 realm 具备所需的索引和回填状态时才应确认；在缺少此状态的既用 realm 中启用该检查，可能导致重叠校验结果不正确。此标志为临时性措施，当 Polaris 能够自动回填所需数据时将被移除。
- 类型：
Boolean - 默认值：
false
polaris.features."ALLOW_OVERLAPPING_CATALOG_URLS"
若设置为 true，则允许 catalog URL 相互重叠。
- 类型：
Boolean - 默认值：
false
polaris.features."ALLOW_SETTING_S3_ENDPOINTS"
若设置为 true（默认），Polaris 将允许 S3 存储配置使用自定义端点。若设置为 false，Polaris 将不接受包含 S3 端点属性的 catalog 创建和更新请求。
- 类型：
Boolean - 默认值：
true
polaris.features."ALLOW_SETTING_SUB_CATALOG_RBAC_FOR_FEDERATED_CATALOGS"
如果设置为 true（默认），Polaris 将允许设置或更改 catalog 属性 polaris.config.enable-sub-catalog-rbac-for-federated-catalogs。如果设置为 false，Polaris 将不允许设置或更改上述 catalog 属性。
- 类型：
Boolean - 默认值：
true
polaris.features."ALLOW_SPECIFYING_FILE_IO_IMPL"
用于控制是否允许通过 catalog 属性设置 FILE_IO_IMPL 的配置键。仅应在开发/测试环境中启用，不应在生产系统中使用。
- 类型：
Boolean - 默认值：
false
polaris.features."ALLOW_TABLE_LOCATION_OVERLAP"
如果设置为 true，Polaris 允许表或视图的位置与现有的表或命名空间位置重叠。这会禁用 Polaris 对 catalog 中表类对象的位置重叠保护，应仅在 Polaris 之外强制实施存储隔离的兼容性场景中使用。
- 类型：
Boolean - 默认值：
false - Catalog 配置：
polaris.config.allow.overlapping.table.location
polaris.features."ALLOW_UNRESTRICTED_STORAGE_CONFIG_ROLE_CHANGES"
如果设置为 true，则在更新 catalog 时允许不受限制地更改存储配置角色属性，包括更改 AWS 账户 ID、角色 ARN、外部 ID 或 Azure 租户 ID。当设置为 false（默认）时，这些更改会受到限制：在之前未配置任何值的情况下可以设置新值，但不能将现有值更改为其他值。
- 类型：
Boolean - 默认值：
false
polaris.features."ALLOW_UNSTRUCTURED_TABLE_LOCATION"
如果设置为 true，Polaris 允许调用方指定结构化命名空间布局之外的表和视图位置。这会移除默认的限制（该限制将新表的位置限制在其父命名空间的位置内）。允许位置的验证仍然适用，但应仅为必须支持外部管理或迁移表位置的 catalog 启用此项。
- 类型：
Boolean - 默认值：
false - Catalog 配置：
polaris.config.allow.unstructured.table.location
polaris.features."ALLOW_WILDCARD_LOCATION"
指示配置的允许位置中的星号（*）是否被处理为表示“任意位置”。如果启用并且允许位置列表中存在 *，Polaris 将接受所有请求的位置。这会移除正常的位置允许列表边界，应仅用于严格受控的兼容性或测试场景。
- 类型：
Boolean - 默认值：
false
polaris.features."AZURE_RETRY_COUNT"
Azure API 请求的重试次数。使用带抖动的指数退避来处理临时故障。
- 类型：
Integer - 默认值：
3
polaris.features."AZURE_RETRY_DELAY_MILLIS"
Azure API 请求在首次重试前的初始延迟（毫秒）。每次重试延迟都会翻倍（指数退避）。
- 类型：
Integer - 默认值：
2000
polaris.features."AZURE_RETRY_JITTER_FACTOR"
应用于 Azure API 请求重试延迟的抖动因子（0.0 到 1.0）。抖动以计算得出的指数退避延迟的随机百分比形式施加。例如，0.5 表示每次重试延迟最多会增加 50%% 的随机抖动。这有助于在多个请求同时失败时避免惊群效应。
- 类型：
Double - 默认值：
0.5
polaris.features."AZURE_TIMEOUT_MILLIS"
Azure API 请求的超时时间（毫秒）。当 Azure 端点响应缓慢或无响应时，可防止无限期阻塞。由 Azure 存储集成在内部用于凭证分发及其他操作。
- 类型：
Integer - 默认值：
15000
polaris.features."CLEANUP_ON_CATALOG_DROP"
设置为 true 时，在删除 catalog 时清理数据
- 类型：
Boolean - 默认值：
false - Catalog 配置：
polaris.config.cleanup.on.catalog.drop
polaris.features."CLEANUP_ON_NAMESPACE_DROP"
设置为 true 时，在删除 namespace 时清理数据
- 类型：
Boolean - 默认值：
false - Catalog 配置：
polaris.config.cleanup.on.namespace.drop
polaris.features."DEFAULT_LOCATION_OBJECT_STORAGE_PREFIX_ENABLED"
启用后，在创建 Iceberg 表和视图时若未指定位置，则会在 catalog 基础位置内的该位置前添加一个前缀，而不是直接使用父命名空间内的位置。注意，这要求启用 ALLOW_UNSTRUCTURED_TABLE_LOCATION，但在启用 OPTIMIZED_SIBLING_CHECK 的情况下，仍然可以确保 catalog 内表位置的唯一性。
- 类型：
Boolean - 默认值：
false - Catalog 配置：
polaris.config.default-table-location-object-storage-prefix.enabled
polaris.features."DEFAULT_UNIQUE_TABLE_LOCATION_ENABLED"
启用后，为未显式指定位置而创建的表或视图所生成的托管位置会带有唯一且不可预测的后缀，从而确保没有两个表共享相同的路径前缀。禁用时（默认值），生成的位置采用传统的 <namespace location>/<table name> 形式。
- 类型：
Boolean - 默认值：
false - Catalog 配置：
polaris.config.default-unique-table-location.enabled
polaris.features."DROP_WITH_PURGE_ENABLED"
设置为 true 时，允许在 purge 参数设置为 true 的情况下删除表。
- 类型：
Boolean - 默认值：
false - Catalog 配置：
polaris.config.drop-with-purge.enabled
polaris.features."ENABLE_CATALOG_FEDERATION"
设置为 true 时，允许创建和使用包含 ConnectionConfigInfos 的 ExternalCatalog，以实现到远程 catalog 的联合查询。
- 类型：
Boolean - 默认值：
false
polaris.features."ENABLE_CREDENTIAL_RESET"
用于启用或禁用重置主体凭证 API 的标志。默认为启用，但服务提供方可能希望将其禁用。
- 类型：
Boolean - 默认值：
true
polaris.features."ENABLE_FINE_GRAINED_UPDATE_TABLE_PRIVILEGES"
当为 true 时，启用更细粒度的更新表权限，这些权限会传递给授权器以执行更新表操作
- 类型：
Boolean - 默认值：
true - 目录配置：
polaris.config.enable-fine-grained-update-table-privileges
polaris.features."ENABLE_GENERIC_TABLES"
如果为 true，则启用通用表（generic tables）相关端点
- 类型：
Boolean - 默认值：
true
polaris.features."ENABLE_POLICY_STORE"
如果为 true，则启用策略存储（policy store）相关端点
- 类型：
Boolean - 默认值：
true
polaris.features."ENABLE_SEMANTIC_MODELS"
如果为 true，则启用语义模型（Apache Ossie）相关端点。这是一个 Beta 功能：API 仍在积极开发中，可能会以不向后兼容的方式发生变更。该功能默认处于禁用状态；请谨慎启用，并报告遇到的任何问题。
- 类型：
Boolean - 默认值：
false
polaris.features."ENABLE_SUB_CATALOG_RBAC_FOR_FEDERATED_CATALOGS"
启用后，允许 RBAC 操作为联邦目录中本地元存储不存在的实体创建合成实体。
- 类型：
Boolean - 默认值：
false - 目录配置：
polaris.config.enable-sub-catalog-rbac-for-federated-catalogs
polaris.features."ENFORCE_PRINCIPAL_CREDENTIAL_ROTATION_REQUIRED_CHECKING"
如果设置为 true，则要求主体在用于其他任何用途之前必须先轮换其凭据。
- 类型：
Boolean - 默认值：
false
polaris.features."ENTITY_CACHE_WEIGHER_TARGET"
实体缓存的最大权重。这是一个启发式值，没有特定的度量单位，大致与缓存值的总堆大小相关。要进行微调需要在具体的部署环境中进行试验。
- 类型：
Long - 默认值：
104857600
polaris.features."GCS_PRINCIPAL_ATTRIBUTION_ENABLED"
通过 Workload Identity Federation 启用 GCS 主体归因。当为 true 时，凭据分发会通过 STS 令牌交换和服务账号模拟来链接一个由目录签名的 JWT，从而使 Polaris 主体出现在 GCS 数据访问审计日志中（serviceAccountDelegationInfo.principalSubject）。还需要同时设置 GCS_PRINCIPAL_ATTRIBUTION_WIF_AUDIENCE、GCS_PRINCIPAL_ATTRIBUTION_TOKEN_ISSUER 和 GCS_PRINCIPAL_ATTRIBUTION_SIGNING_KEY_FILE；缺少必需值将导致致命的配置错误。同时还需要在目录的 StorageConfiguration 上配置 gcpServiceAccount。默认值：false（禁用归因）。
- 类型：
Boolean - 默认值：
false
polaris.features."GCS_PRINCIPAL_ATTRIBUTION_SIGNING_KEY_FILE"
用于签名 GCS 归因 JWT（RS256）的 PKCSdevlive-community/knowforge#8 PEM RSA 私钥的文件系统路径。相应的公钥必须发布在 Workload Identity 池提供方上传的 JWKS 中。当 GCS_PRINCIPAL_ATTRIBUTION_ENABLED=true 时为必需项；否则被忽略。
- 类型：
String - 默认值： ``
polaris.features."GCS_PRINCIPAL_ATTRIBUTION_SIGNING_KEY_ID"
写入 GCS 归因 JWT 头部的密钥 ID（kid），以便 Workload Identity Pool 提供商在密钥轮换时（即 JWKS 中同时包含新旧密钥时）从中选择正确的公钥。必须与所配置签名密钥对应 JWKS 条目的 kid 一致。留空则省略该头部（仅在 JWKS 只含单个密钥时安全）。
- 类型：
String - 默认值： ``
polaris.features."GCS_PRINCIPAL_ATTRIBUTION_TOKEN_ISSUER"
由 catalog 签发的 GCS 归因 JWT 的颁发者（iss 声明）；必须与 Workload Identity Pool OIDC 提供商上配置的颁发者一致。该提供商使用其上传的 JWKS 验证签名，因此无需公开的发现端点。当 GCS_PRINCIPAL_ATTRIBUTION_ENABLED=true 时必填；否则忽略。
- 类型：
String - 默认值： ``
polaris.features."GCS_PRINCIPAL_ATTRIBUTION_WIF_AUDIENCE"
用于 GCS 主体归因的 Workload Identity Pool 提供商的完整资源名称，例如 //iam.googleapis.com/projects//locations/global/workloadIdentityPools//providers/。既用作归因 JWT 的 ‘aud’ 声明，也用作 STS 令牌交换的受众。当 GCS_PRINCIPAL_ATTRIBUTION_ENABLED=true 时必填；否则忽略。
- 类型：
String - 默认值： ``
polaris.features."ICEBERG_COMMIT_MAX_RETRIES"
提交到 Iceberg 表的最大重试次数
- 类型：
Integer - 默认值：
4 - Catalog 配置：
polaris.config.iceberg-commit-max-retries
polaris.features."ICEBERG_ROLLBACK_COMPACTION_ON_CONFLICTS"
回滚由 compaction 创建的替换快照，条件是其快照摘要中设置了 polaris.internal.conflict-resolution.by-operation-type.replace 属性为 rollback
- 类型：
Boolean - 默认值：
false - Catalog 配置：
polaris.config.rollback.compaction.on-conflicts.enabled
polaris.features."INCLUDE_PRINCIPAL_NAME_IN_SUBSCOPED_CREDENTIAL"
若设置为 true，主体名称将包含在临时子作用域凭据中。目前仅支持 AWS 凭据，其生成凭据的会话名称将形如 ‘polaris-’ 而非简单的 ‘polaris’。请注意，启用此功能会导致临时凭据缓存性能下降，因为 catalog 将无法再为主体系复用凭据。
- 类型：
Boolean - 默认值：
false
polaris.features."LIST_PAGINATION_ENABLED"
若设置为 true，则启用 listTables 等 API 的分页功能。
- 类型：
Boolean - 默认值：
false - Catalog 配置：
polaris.config.list-pagination-enabled
polaris.features."MAX_METADATA_REFRESH_RETRIES"
当上一次错误可重试时，刷新元数据的重试次数
- 类型：
Integer - 默认值：
2
polaris.features."OPTIMIZED_SIBLING_CHECK"
设置后，Polaris 会使用索引来对表、视图和命名空间执行同级重叠检查。这不是一种绕过模式，但启用或禁用它可能会改变非标准位置布局的重叠检测覆盖范围。仅在所需索引和回填状态已知正确时才启用它。为获得正确结果，位置应以斜杠结尾；请参阅 ADD_TRAILING_SLASH_TO_LOCATION。JDBC 和 NoSQL 元存储实现均支持该功能。
- 类型：
Boolean - 默认值：
false
polaris.features."POLARIS_TASK_TIMEOUT_MILLIS"
Polaris 任务过期超时时间（毫秒）。较早的未完成任务可能不会被处理。
- 类型：
Long - 默认值：
300000
polaris.features."PURGE_VIEW_METADATA_ON_DROP"
如果设置为 true，Polaris 将在视图被删除时尝试删除视图元数据文件。
- 类型：
Boolean - 默认值：
true - 目录配置项：
polaris.config.purge-view-metadata-on-drop
polaris.features."RESOLVE_CREDENTIALS_BY_STORAGE_NAME"
如果设置为 true，则根据存储配置的 storageName 字段解析 AWS 凭据。禁用时，所有存储都使用默认的 AWS 凭据。
- 类型：
Boolean - 默认值：
false
polaris.features."SESSION_NAME_FIELDS_IN_SUBSCOPED_CREDENTIAL"
在凭证发放期间要包含在会话名称中的字段的有序列表。适用于支持基于会话的子作用域凭证的系统（例如带有 STS 的 S3）。字段之间使用 ‘-’ 连接，默认以 ‘p-’ 作为前缀。结果会被截断为 64 个字符（AWS STS 会话名称的长度上限）；较短字段未使用的长度额度会顺延给后续字段。为空时（默认），将回退到 INCLUDE_PRINCIPAL_NAME_IN_SUBSCOPED_CREDENTIAL 的行为。支持的字段：realm、catalog、namespace、table、principal。字段顺序很重要：字段将按照列出的顺序出现在会话名称中。更改顺序会改变会话名称的结构，并会影响 CloudTrail 查询。若要自定义前缀，请包含一个 ‘prefix-X’ 令牌（例如 ‘prefix-myorg’ 会将前缀设置为 ‘myorg-’）。默认为 ‘p-’。示例：[“realm”,“catalog”,“table”,“principal”] 会生成类似 ‘p-acme-hr_catalog-employee-etl_writer’ 的会话名称（截断为 64 个字符）。注意：当包含特定上下文的字段（例如 table、namespace）时，启用此标志可能会降低凭证缓存的复用率，因为凭证的部分键依赖于会话名称。
- 类型：
List<String> - 默认值：
[]
polaris.features."SESSION_TAGS_IN_SUBSCOPED_CREDENTIAL"
以逗号分隔的字段列表，用于在凭据分发时的 AWS STS AssumeRole 请求中作为会话标签（session tag）附加。这些标签会出现在 CloudTrail 事件中，从而可以将目录（catalog）操作与 S3 数据访问关联起来。空列表（默认值）将完全禁用会话标签。需要 IAM 角色信任策略允许 sts:TagSession 操作。支持的字段：realm、catalog、namespace、table、principal、roles、trace\_id。注意：每个额外字段都可能增加 AWS STS 打包策略（packed policy）的大小（上限为 2048 个字符）。取值较长的字段（例如层级很深的命名空间）可能导致 STS 策略大小超限错误。请仅选择满足 CloudTrail 关联需求所必需的字段。警告：包含 trace\_id 会使凭据缓存复用实际上完全失效，因为每个请求的 trace ID 都是唯一的。这可能会显著增加延迟和 STS API 成本。
- 类型：
List<String> - 默认值：
[]
polaris.features."SKIP_CREDENTIAL_SUBSCOPING_INDIRECTION"
仅用于测试/开发。如果为 true，则完全绕过凭据子作用域处理：FileIO 会回退到服务器的环境凭据（Pod 的 IAM 角色、环境变量、凭据文件）。适用于使用模拟存储路径的测试（不涉及真实 STS）。不适用于生产环境：这些凭据会被传递给每一个客户端，从而破坏纵深防御。对于不支持 STS 的 S3 兼容存储，请改为在存储配置中设置 stsUnavailable: true。
- 类型：
Boolean - 默认值：
false
polaris.features."STORAGE_CREDENTIAL_CACHE_DURATION_SECONDS"
存储凭据在本地缓存中的保存时长。该值应小于 STORAGE_CREDENTIAL_DURATION_SECONDS。
- 类型：
Integer - 默认值：
1800
polaris.features."STORAGE_CREDENTIAL_DURATION_SECONDS"
分发出的存储凭据的有效时长。对更长（或更短）时长的支持取决于具体的存储提供商。GCS 目前不会遵循该值。
- 类型：
Integer - 默认值：
3600
polaris.features."SUPPORTED_CATALOG_CONNECTION_TYPES"
联邦（federation）支持的目录连接类型列表
- 类型：
List<String> - 默认值：
[ICEBERG_REST]
polaris.features."SUPPORTED_CATALOG_STORAGE_TYPES"
目录支持的存储类型列表
- 类型：
List<String> - 默认值：
[S3, AZURE, GCS] - 目录配置：
polaris.config.supported.storage.types
polaris.features."SUPPORTED_EXTERNAL_CATALOG_AUTHENTICATION_TYPES"
目录联邦支持的认证类型列表
- 类型：
List<String> - 默认值：
[OAUTH, BEARER, GCP, SIGV4]
polaris.features."TABLE_METADATA_CLEANUP_BATCH_SIZE"
清理已删除表的相关文件时所使用的元数据批处理大小。
- 类型：
Integer - 默认值：
10
polaris.behavior-changes
内部行为变更配置。这些配置不稳定，可能会被移除。
polaris.behavior-changes."ALLOW_NAMESPACE_CUSTOM_LOCATION"
如果设置为 true，则允许命名空间具有完全任意的位置。这不应影响凭证分发。
- 类型：
Boolean - 默认值：
false - 目录配置：
polaris.config.namespace-custom-location.enabled
polaris.behavior-changes."ENTITY_CACHE_SOFT_VALUES"
是否在实体缓存中使用软引用值
- 类型：
Boolean - 默认值：
false
polaris.behavior-changes."SCHEMA_VERSION_FALL_BACK_ON_DNE"
如果设置为 true，加载 VERSION 表时遇到的、看似由 VERSION 表不存在引起的异常，将被解释为当前 schema 版本为 0。
- 类型：
Boolean - 默认值：
true
polaris.behavior-changes."STORAGE_CONFIGURATION_MAX_LOCATIONS"
一个存储配置可以关联多少个位置，或设为 -1 表示不限制位置数量
- 类型：
Integer - 默认值：
-1
polaris.behavior-changes."TABLE_OPERATIONS_MAKE_METADATA_CURRENT_ON_COMMIT"
如果为 true，BasePolarisTableOperations 应将传入 commit 的元数据标记为当前元数据，并复用它以省去再次访问对象存储重新构建已提交元数据的过程。
- 类型：
Boolean - 默认值：
true
polaris.behavior-changes."VALIDATE_VIEW_LOCATION_OVERLAP"
如果为 true，则在创建视图时校验视图位置是否重叠
- 类型：
Boolean - 默认值：
true
身份验证与授权
polaris.authentication
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.authentication.type | internal | enum (INTERNAL, EXTERNAL, MIXED) | 要使用的认证类型。 |
polaris.authentication.authenticator.type | default | string | 身份提供方的类型。必须是已注册的（Authenticator）标识符。 |
polaris.authentication.token-service.type | default | string | OAuth2 服务的类型。必须是已注册的（IcebergRestOAuth2ApiService）标识符。 |
polaris.authentication.token-broker.max-token-generation | PT1H | duration | 令牌的最长有效期。 |
polaris.authentication.token-broker.type | rsa-key-pair | string | 令牌代理工厂的类型。必须是已注册的（TokenBrokerFactory）标识符。 |
polaris.authentication.token-broker.rsa-key-pair.public-key-file | path | 公钥文件的路径。 | |
polaris.authentication.token-broker.rsa-key-pair.private-key-file | path | 私钥文件的路径。 | |
polaris.authentication.token-broker.symmetric-key.secret | string | 用于签名和验签的密钥。必须提供该选项或（#file()）。 | |
polaris.authentication.token-broker.symmetric-key.file | path | 读取密钥的文件。必须提供该选项或（#secret()）。 | |
polaris.authentication.<realm>.type | internal | enum (INTERNAL, EXTERNAL, MIXED) | 要使用的认证类型。 |
polaris.authentication.<realm>.authenticator.type | default | string | 身份提供方的类型。必须是已注册的（Authenticator）标识符。 |
polaris.authentication.<realm>.token-service.type | default | string | OAuth2 服务的类型。必须是已注册的（IcebergRestOAuth2ApiService）标识符。 |
polaris.authentication.<realm>.token-broker.max-token-generation | PT1H | duration | 令牌的最长有效期。 |
polaris.authentication.<realm>.token-broker.type | rsa-key-pair | string | 令牌代理工厂的类型。必须是已注册的（TokenBrokerFactory）标识符。 |
polaris.authentication.<realm>.token-broker.rsa-key-pair.public-key-file | path | 公钥文件的路径。 | |
polaris.authentication.<realm>.token-broker.rsa-key-pair.private-key-file | path | 私钥文件的路径。 | |
polaris.authentication.<realm>.token-broker.symmetric-key.secret | string | 用于签名和验签的密钥。必须提供该选项或（#file()）。 | |
polaris.authentication.<realm>.token-broker.symmetric-key.file | path | 读取密钥的文件。必须提供该选项或（#secret()）。 |
polaris.authorization
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.authorization.type | internal | string |
polaris.authorization.opa
OPA（Open Policy Agent）授权的配置。
Beta 功能：OPA 授权目前处于 Beta 阶段，并非稳定版本。未来版本中可能会发生破坏性变更。请在生产环境中谨慎使用。
| 属性 | 默认值 | 类型 | 说明 |
|---|---|---|---|
polaris.authorization.opa.policy-uri | uri | ||
polaris.authorization.opa.auth.type | none | enum (NONE, BEARER) | 认证类型 |
polaris.authorization.opa.auth.bearer.static-token.value | string | 静态 Bearer 令牌值 | |
polaris.authorization.opa.auth.bearer.file-based.path | path | 包含 Bearer 令牌的文件路径 | |
polaris.authorization.opa.auth.bearer.file-based.refresh-interval | duration | 基于文件的 Bearer 令牌的刷新频率（未指定时默认为 5 分钟） | |
polaris.authorization.opa.auth.bearer.file-based.jwt-expiration-refresh | boolean | 是否自动检测 JWT 令牌并使用其 exp 字段确定刷新时机。如果设为 true，且令牌是带有 exp 声明的有效 JWT，则将根据过期时间减去缓冲时间来刷新令牌，而不是使用固定的刷新间隔。未指定时默认为 true。 | |
polaris.authorization.opa.auth.bearer.file-based.jwt-expiration-buffer | duration | 在 JWT 过期前提前刷新令牌的缓冲时间。仅当 jwtExpirationRefresh 为 true 且令牌是有效 JWT 时使用。未指定时默认为 1 分钟。 | |
polaris.authorization.opa.auth.bearer.file-based.initial-token-wait | duration | 在请求失败前等待首次令牌加载的时长。默认为 5 秒。 | |
polaris.authorization.opa.auth.bearer.file-based.refresh-retry-interval | duration | 令牌刷新失败后，重试前的等待时长。默认为 1 秒。 | |
polaris.authorization.opa.http.timeout | PT2S | duration | |
polaris.authorization.opa.http.verify-ssl | true | boolean | |
polaris.authorization.opa.http.trust-store-path | path | ||
polaris.authorization.opa.http.trust-store-password | string |
polaris.oidc
针对 OIDC 租户的 Polaris 专属配置。
| 属性 | 默认值 | 类型 | 说明 |
|---|---|---|---|
polaris.oidc.principal-mapper.id-claim-path |
string |
包含主体 ID 的声明路径。嵌套路径可使用“/”作为分隔符来表示，例如 "resource_access/client1/roles" 会查找令牌声明中 resource_access 对象内 client1 对象中的 “roles” 字段。可选。该选项与 ( #nameClaimPath()) 必须提供其中之一。 |
|
polaris.oidc.principal-mapper.name-claim-path |
string |
包含主体名称的声明。嵌套路径可使用“/”作为分隔符来表示，例如 "resource_access/client1/roles" 会查找令牌声明中 resource_access 对象内 client1 对象中的 “roles” 字段。可选。该选项与 ( #idClaimPath()) 必须提供其中之一。 |
|
polaris.oidc.principal-mapper.type |
default |
string |
主体映射器的类型。必须是已注册的 (org.apache.polaris.service.auth.external.mapping.PrincipalMapper) 标识符。 |
polaris.oidc.principal-roles-mapper.type |
default |
string |
主体角色映射器的类型。必须是已注册的 (org.apache.polaris.service.auth.external.mapping.PrincipalRolesMapper) 标识符。 |
polaris.oidc.principal-roles-mapper.filter |
string |
匹配身份中角色名称的正则表达式。只有匹配该正则的角色才会被包含在 Polaris 专属角色中。 | |
polaris.oidc.principal-roles-mapper.mappings |
list of |
一个正则映射列表，将应用于身份中的每个角色名称。 | |
polaris.oidc.principal-roles-mapper.mappings.regex |
string |
将应用于身份中每个角色名称的正则表达式。它与 (#replacement()) 一起使用，用于将身份中的角色名称转换为 Polaris 专属角色。 |
|
polaris.oidc.principal-roles-mapper.mappings.replacement |
string |
身份中角色名称的替换字符串。它与 (#regex()) 一起使用，用于将身份中的角色名称转换为 Polaris 专属角色。 |
|
polaris.oidc.<tenant>.principal-mapper.id-claim-path |
string |
包含主体 ID 的声明路径。嵌套路径可使用“/”作为分隔符来表示，例如 "resource_access/client1/roles" 会查找令牌声明中 resource_access 对象内 client1 对象中的 “roles” 字段。可选。该选项与 ( #nameClaimPath()) 必须提供其中之一。 |
|
polaris.oidc.<tenant>.principal-mapper.name-claim-path |
string |
包含主体名称的声明。嵌套路径可使用“/”作为分隔符来表示，例如 "resource_access/client1/roles" 会查找令牌声明中 resource_access 对象内 client1 对象中的 “roles” 字段。可选。该选项与 ( #idClaimPath()) 必须提供其中之一。 |
polaris.oidc.<tenant>.principal-mapper.type``default``string主体映射器的类型。必须是已注册的（org.apache.polaris.service.auth.external.mapping.PrincipalMapper）标识符。
polaris.oidc.<tenant>.principal-roles-mapper.type``default``string主体角色映射器的类型。必须是已注册的（org.apache.polaris.service.auth.external.mapping.PrincipalRolesMapper）标识符。
polaris.oidc.<tenant>.principal-roles-mapper.filter``string匹配身份中角色名称的正则表达式。只有与该正则表达式匹配的角色才会被包含在 Polaris 特定角色中。
polaris.oidc.<tenant>.principal-roles-mapper.mappings``list of一组正则表达式映射，将应用于身份中的每个角色名称。
polaris.oidc.<tenant>.principal-roles-mapper.mappings.regex``string将应用于身份中每个角色名称的正则表达式。与（#replacement()）配合使用时，该正则表达式用于将身份中的角色名称转换为 Polaris 特定角色。
polaris.oidc.<tenant>.principal-roles-mapper.mappings.replacement``string身份中角色名称的替换字符串。与（#regex()）配合使用，用于将身份中的角色名称转换为 Polaris 特定角色。
polaris.oidc.tenant-resolver.type``default``stringOIDC 租户解析器的类型。必须是已注册的（OidcTenantResolver）实现。
polaris.service-identity
用于在 Polaris 中跨多个 realm 管理服务身份的配置接口。
服务身份表示 Polaris 服务本身需要向外部系统进行身份验证时的身份（例如，用于 SigV4 身份验证的 AWS 服务）。每个 realm 都可以为不同的云服务商配置各自的服务身份集合。
该接口既支持多租户部署——每个 realm（租户）可以拥有各自不同的服务身份，也支持单租户部署——在所有 catalog 之间共享一套默认配置。
配置在启动时从 polaris.service-identity.* 属性加载，其中包含 Polaris 在访问联合 catalog 时用来承担客户提供角色所使用的凭据。
配置示例：
# Default service identity (used when no realm-specific configuration exists)
polaris.service-identity.aws-iam.iam-arn=arn:aws:iam::123456789012:user/polaris-default-user
# Optional: provide static credentials, or omit to use AWS default credential chain
polaris.service-identity.aws-iam.access-key-id=<access-key-id>
polaris.service-identity.aws-iam.secret-access-key=<secret-access-key>
polaris.service-identity.aws-iam.session-token=<optional-session-token>
# Realm-specific service identity for multi-tenant deployments
polaris.service-identity.my-realm.aws-iam.iam-arn=arn:aws:iam::123456789012:user/my-realm-user
polaris.service-identity.my-realm.aws-iam.access-key-id=<access-key-id>
polaris.service-identity.my-realm.aws-iam.secret-access-key=<secret-access-key>| 属性 | 默认值 | 类型 | 说明 |
|---|---|---|---|
polaris.service-identity.aws-iam.iam-arn | string | 表示服务身份的 IAM 角色或用户 ARN。若未提供，Polaris 不会在目录身份中展示该信息。 | |
polaris.service-identity.aws-iam.access-key-id | string | 与该 IAM 身份关联的可选 AWS 访问密钥 ID。若未提供，将使用 AWS 默认凭据链。 | |
polaris.service-identity.aws-iam.secret-access-key | string | 与该 IAM 身份关联的可选 AWS 私有访问密钥。若未提供，将使用 AWS 默认凭据链。 | |
polaris.service-identity.aws-iam.session-token | string | 与该 IAM 身份关联的可选 AWS 会话令牌。若未提供，将使用 AWS 默认凭据链。 | |
polaris.service-identity.<realm>.aws-iam.iam-arn | string | 表示服务身份的 IAM 角色或用户 ARN。若未提供，Polaris 不会在目录身份中展示该信息。 | |
polaris.service-identity.<realm>.aws-iam.access-key-id | string | 与该 IAM 身份关联的可选 AWS 访问密钥 ID。若未提供，将使用 AWS 默认凭据链。 | |
polaris.service-identity.<realm>.aws-iam.secret-access-key | string | 与该 IAM 身份关联的可选 AWS 私有访问密钥。若未提供，将使用 AWS 默认凭据链。 | |
polaris.service-identity.<realm>.aws-iam.session-token | string | 与该 IAM 身份关联的可选 AWS 会话令牌。若未提供，将使用 AWS 默认凭据链。 |
存储与凭据
polaris.storage
配置接口，包含 Polaris 服务器客户端访问 S3 服务的参数。
适用于 STS 客户端池，以及通过 S3FileIO 为表操作创建的 Iceberg S3 客户端。
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.storage.aws.access-key | string | 用于认证的 AWS 访问密钥。若未设置，则使用默认凭据提供者链。 | |
polaris.storage.aws.secret-key | string | 用于认证的 AWS 秘密访问密钥。若未设置，则使用默认凭据提供者链。 | |
polaris.storage.aws.<storage>.access-key | string | 使用命名存储时用于认证的 AWS 访问密钥。 | |
polaris.storage.aws.<storage>.secret-key | string | 使用命名存储时用于认证的 AWS 秘密访问密钥。 | |
polaris.storage.gcp.token | string | 用于认证的 GCP 访问令牌。若未设置，则使用默认凭据提供者链。 | |
polaris.storage.gcp.lifespan | duration | GCP 访问令牌的有效期。若未设置，则使用默认令牌有效期（null）。 | |
polaris.storage.clients-cache-max-size | int | STS 客户端缓存中保留的最大条目数。 | |
polaris.storage.max-http-connections | int | 覆盖池化连接的默认最大数量。 | |
polaris.storage.read-timeout | duration | 覆盖默认的连接读取超时时间。 | |
polaris.storage.connect-timeout | duration | 覆盖默认的 TCP 连接超时时间。 | |
polaris.storage.connection-acquisition-timeout | duration | 覆盖默认的连接获取超时时间，即请求从连接池中等待可用连接的时间。 | |
polaris.storage.connection-max-idle-time | duration | 覆盖池化连接的默认最大空闲时间。 | |
polaris.storage.connection-time-to-live | duration | 覆盖池化连接的默认存活时间。 | |
polaris.storage.expect-continue-enabled | boolean | 覆盖默认行为，设置是否等待 HTTP/100-Continue 响应。 |
polaris.storage-credential-cache
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.storage-credential-cache.max-entries | 10000 | long |
polaris.credential-manager
Polaris 凭据管理器的 Quarkus 配置映射。
定义运行时应使用哪种（PolarisCredentialManager）实现。通过配置即可在不同的凭据管理策略之间切换。
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.credential-manager.type | string | 要使用的 PolarisCredentialManager 实现的类型标识符。它对应于该实现上的 @Identifier 注解值（例如 “default”）。 |
polaris.secrets-manager
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.secrets-manager.type | string | 要使用的 UserSecretsManagerFactory 的类型。即（org.apache.polaris.core.secrets.UserSecretsManagerFactory）标识符。 |
polaris.file-io
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.file-io.type | string | 要使用的目录 IO 类型。必须是已注册的（org.apache.polaris.service.catalog.io.FileIOFactory）标识符。 |
持久化
polaris.persistence
| 属性 | 默认值 | 类型 | 说明 |
|---|---|---|---|
polaris.persistence.type | string | 要使用的持久化类型。必须是已注册的（org.apache.polaris.core.persistence.MetaStoreManagerFactory）标识符。 | |
polaris.persistence.auto-bootstrap-types | list of string | ||
polaris.persistence.reference-previous-head-count | 20 | int | |
polaris.persistence.max-index-stripes | 20 | int | |
polaris.persistence.max-embedded-index-size | 32k | MemorySize | |
polaris.persistence.max-index-stripe-size | 128k | MemorySize | |
polaris.persistence.bucketized-bulk-fetch-size | 16 | int | 每次通过（Persistence#bucketizedBulkFetches(Stream,<br> Class)）一次获取的对象数量。 |
polaris.persistence.max-serialized-value-size | 350k | MemorySize | 持久化数据库行中序列化值的最大大小。 |
polaris.persistence.cache
持久化缓存配置。
属性默认值类型说明
polaris.persistence.cache.enable``true``boolean可以选择禁用该缓存，默认值为 true，即缓存默认启用。
polaris.persistence.cache.reference-ttl``PT15M``duration缓存引用状态的时长。
polaris.persistence.cache.reference-negative-ttl``duration缓存某引用不存在这一事实的时长（负缓存）。
polaris.persistence.cache.sizing.fraction-of-max-heap-size``double用于缓存对象的 Java 最大堆内存的比例，设置为 0 可禁用。不得与固定缓存大小同时使用。如果既未配置该值也未配置固定大小，则默认取 .4（40%）；如果启用了 enable-soft-references，则默认取 .6（60%）。
polaris.persistence.cache.sizing.fraction-min-size``64M``MemorySize使用按比例计算的缓存大小时，该值（单位为 MB）表示缓存的最小大小。
polaris.persistence.cache.sizing.fraction-adjustment``256M``MemorySize使用按比例计算的缓存大小时，计算缓存大小时会始终为堆保留该值（单位为 MB）的空间。
polaris.persistence.cache.sizing.fixed-size``MemorySize持久化缓存的容量，单位为 MiB。
polaris.persistence.cache.sizing.cache-capacity-overshoot``0.1``double允许的缓存容量超出比例，默认为 0.1（10%）。
当缓存的大小小于 cache-capacity * (1 + cache-capacity-overshoot) 时，新元素会被允许加入缓存。
缓存淘汰是异步进行的。当淘汰速度无法跟上数据增加的速度时，可能导致内存溢出（out-of-memory）情况。
如果配置了该值，则必须大于 0。
polaris.persistence.distributed-cache-invalidations
属性默认值类型说明
polaris.persistence.distributed-cache-invalidations.service-names``字符串列表访问同一仓库的所有 Polaris 服务器实例的主机名、IP 地址或 Kubernetes 无头服务（headless service）名称。
该值会通过 Polaris Helm chart 自动配置，无需额外配置。
如果你使用自己的 Helm chart 或自定义部署，请确保在此处配置所有 Polaris 实例的 IP 地址。
以等号开头的名称不会被解析，而是按“原样”使用。
polaris.persistence.distributed-cache-invalidations.valid-tokens``字符串列表用于验证传入的缓存失效消息的缓存失效令牌列表。
发出的缓存失效消息中使用列表中的第一个令牌。
polaris.persistence.distributed-cache-invalidations.uri``/polaris-management/cache-coherency``string缓存失效端点的 URI，仅在 Quarkus 管理端口上可用，默认端口为 9000。
polaris.persistence.distributed-cache-invalidations.service-name-lookup-interval``PT10S``duration服务名称查找的间隔，用于将服务名称（#cacheInvalidationServiceNames()）解析为 IP 地址。
polaris.persistence.distributed-cache-invalidations.batch-size``20``int向对等节点发送的单次请求中可包含的缓存失效消息的最大数量。
polaris.persistence.distributed-cache-invalidations.request-timeout``duration发送的缓存失效消息的请求超时时间。超时会触发警告或错误消息。
polaris.persistence.distributed-cache-invalidations.dns.query-timeout``PT5S``duration用于解析对等节点的 DNS 查询超时时间。
polaris.persistence.nosql
Polaris 持久化后端配置。
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.persistence.nosql.backend | string | 要使用的持久化后端名称。 |
polaris.persistence.nosql.maintenance
维护服务配置。
PropertyDefault ValueTypeDescription
polaris.persistence.nosql.maintenance.expected-reference-count``100``long指定所有 realm 中需保留的引用的预期数量，默认为 100，且必须至少为 100。如果不存在上一次维护运行的信息，则使用该值作为默认值；同时它也是预期引用数量的最小值。
polaris.persistence.nosql.maintenance.expected-obj-count``100000``long指定所有 realm 中需保留的对象的预期数量，默认为 100000，且必须至少为 100000。如果不存在上一次维护运行的信息，则使用该值作为默认值；同时它也是预期对象数量的最小值。
polaris.persistence.nosql.maintenance.count-from-last-run-multiplier``1.1``double维护服务根据表达式 lastRun.numberOfIdentified * countFromLastRunMultiplier 来确定用于保存已识别引用和对象的布隆过滤器的大小。默认情况下，会在已识别条目的数量上增加 10%。
polaris.persistence.nosql.maintenance.filter-initialized-fpp``1.0E-5``double用于初始化已识别引用和对象的布隆过滤器的假阳性率（FPP）。
polaris.persistence.nosql.maintenance.max-acceptable-filter-fpp``5.0E-5``double用于检查已识别引用和对象的布隆过滤器的预期最大假阳性率（FPP）。
如果某个布隆过滤器的 FPP 超过该值，则不会清除任何单独的引用或对象。
polaris.persistence.nosql.maintenance.retained-runs``50``int保留的维护运行对象（MaintenanceRunInformation）的数量，必须至少为 2。
polaris.persistence.nosql.maintenance.created-at-grace-time``PT3H``duration在维护运行开始之后创建的对象和引用永远不会被清除。该选项为维护运行的开始时间定义了一段额外的宽限时间。
出于以下两个原因，该值是一项安全保障：
* 考虑 Polaris 节点之间的挂钟时间漂移。
* 考虑 Polaris 持久化中的写入顺序。对象在通过提交变得可达之前就会被写入。提交可能需要一点时间（毫秒级，取决于系统负载，最多几秒）才能完成。因此，各实现会强制要求至少 5 分钟。
polaris.persistence.nosql.maintenance.object-scan-rate-limit-per-second``int可选择性地限制每秒扫描的对象数量。默认情况下不限制对象扫描速率。
polaris.persistence.nosql.maintenance.reference-scan-rate-limit-per-second``int可选地限制每秒扫描的引用数量。
默认情况下不会对引用扫描进行限流。
polaris.persistence.nosql.maintenance.delete-batch-size``10``int清除对象时删除批次的大小。
polaris.persistence.nosql.maintenance.catalog
Polaris 的 NoSQL 持久化实现会按对象类型（主体、主体角色、授权、即时任务、catalog 角色以及 catalog 状态）保存变更历史。
这些规则使用 CEL 脚本 定义。所有对象类型的默认规则是保留 3 天的历史记录，catalog 状态保留 30 天。
脚本可以访问以下已声明的值：
ref（字符串）引用的名称commits（64 位整数）当前处理的提交序号，从1开始ageDays（64 位整数）当前处理的提交的存续天数ageHours（64 位整数）当前处理的提交的存续小时数ageMinutes（64 位整数）当前处理的提交的存续分钟数
脚本必须返回一个 boolean，用于指示该提交是否应当被保留。请注意，维护服务的实现可能会保留首个不需要保留的提交。
示例脚本
ageDays < 30 || commits <= 10保留至少包含 10 个提交的引用历史，以及存续时间不足 30 天的提交true保留整个引用历史false仅保留最新的提交
| 属性 | 默认值 | 类型 | 说明 |
|---|---|---|---|
polaris.persistence.nosql.maintenance.catalog.principals-retain | false | string | |
polaris.persistence.nosql.maintenance.catalog.principal-roles-retain | false | string | |
polaris.persistence.nosql.maintenance.catalog.grants-retain | false | string | |
polaris.persistence.nosql.maintenance.catalog.immediate-tasks-retain | false | string | |
polaris.persistence.nosql.maintenance.catalog.catalogs-history-retain | false | string | |
polaris.persistence.nosql.maintenance.catalog.catalog-roles-retain | false | string | |
polaris.persistence.nosql.maintenance.catalog.catalog-policies-retain | false | string | |
polaris.persistence.nosql.maintenance.catalog.catalog-state-retain | false | string |
polaris.persistence.nosql.mongodb
Polaris 持久化层中 MongoDB 后端的特定配置。
属性默认值类型说明
polaris.persistence.nosql.mongodb.connection-string``string
polaris.persistence.nosql.mongodb.database-name``string
polaris.persistence.nosql.mongodb.allow-prefix-deletion``boolean可选启用通过前缀删除来删除 realm。
前缀删除默认处于禁用状态。
polaris.persistence.relational.jdbc
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.persistence.relational.jdbc.max-retries | int | ||
polaris.persistence.relational.jdbc.max-duration-in-ms | long | ||
polaris.persistence.relational.jdbc.initial-delay-in-ms | long | ||
polaris.persistence.relational.jdbc.database-type | string |
事件
polaris.event-listener
属性默认值类型描述
polaris.event-listener.type``string要使用的事件监听器类型。必须是已注册的（PolarisEventListener）标识符。
自 1.5.0 起已弃用，请改用 polaris.event-listener.types；如果两者都已设置，则 polaris.event-listener.types 优先。
polaris.event-listener.types``字符串列表以逗号分隔的事件监听器列表，每一项都必须是已注册的（PolarisEventListener）标识符。
polaris.event-listener.denylisted-attributes``字符串列表以逗号分隔的附加 EventAttributes 键名列表，用于拒绝将其传递给下游监听器。这些键名会添加到（DefaultEventSanitizer）中的内置拒绝列表中。
polaris.event-listener.<name>.enabled-event-types``枚举列表（BEFORE_CREATE_CATALOG、AFTER_CREATE_CATALOG、BEFORE_DELETE_CATALOG、……）以逗号分隔的已启用事件类型列表。该事件监听器只会接收所选类型的事件。如果事件类型和事件类别配置都已设置，监听器将同时监听两者。如果未提供任何监听器配置，则所有事件类型都会被启用。
polaris.event-listener.<name>.enabled-event-categories``枚举列表（CATALOG、NAMESPACE、TABLE、……）以逗号分隔的已启用事件类型类别列表。每个类别都是一组相关的 Polaris 事件类型。该事件监听器只会接收所选事件类别的事件，例如仅消费目录事件。如果事件类型和事件类别配置都已设置，监听器将同时监听两者。如果未提供任何监听器配置，则所有事件类型都会被启用。
polaris.event-listener.executor.pool-size``-1``int线程池大小。默认值为 -1，表示按可用监听器的数量来解释，并以 CPU 核心数为上限。
polaris.event-listener.executor.queue-size``-1``int队列大小。默认值为 -1，表示无界。该限制是全局生效的，会影响所有监听器。若要配置每个监听器的队列大小，请改用 polaris.event-listener.listener-backlog.queue-size。
polaris.event-listener.listener-backlog.queue-size | -1 | int | 每个监听器的积压队列大小。默认值为 -1，表示不受限制。有界的积压意味着事件投递是尽力而为的，当积压已满时事件将被丢弃/记录日志。
polaris.event-listener.persistence-in-memory-buffer
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.event-listener.persistence-in-memory-buffer.buffer-time | 5000ms | duration | |
polaris.event-listener.persistence-in-memory-buffer.max-buffer-size | 5 | int |
polaris.event-listener.aws-cloudwatch
用于 AWS CloudWatch 事件监听器集成的配置接口。
属性默认值类型描述
polaris.event-listener.aws-cloudwatch.log-group | polaris-cloudwatch-default-group | string | 返回用于事件日志记录的 AWS CloudWatch 日志组名称。
日志组是一组共享相同保留策略、监控和访问控制设置的日志流的集合。如果未指定，则默认为 “polaris-cloudwatch-default-group”。
配置属性：polaris.event-listener.aws-cloudwatch.log-group
polaris.event-listener.aws-cloudwatch.log-stream | polaris-cloudwatch-default-stream | string | 返回用于事件日志记录的 AWS CloudWatch 日志流名称。
日志流是共享同一来源的日志事件序列。每个日志流属于一个日志组。如果未指定，则默认为 “polaris-cloudwatch-default-stream”。
配置属性：polaris.event-listener.aws-cloudwatch.log-stream
polaris.event-listener.aws-cloudwatch.region | us-east-1 | string | 返回应将 CloudWatch 日志发送到的 AWS 区域。
该配置指定 CloudWatch 服务端点所在的 AWS 区域。区域必须是有效的 AWS 区域标识符。如果未指定，则默认为 “us-east-1”。
配置属性：polaris.event-listener.aws-cloudwatch.region
polaris.event-listener.aws-cloudwatch.synchronous-mode | false | boolean | 返回 CloudWatch 日志记录的同步模式设置。
设置为 “true” 时，日志事件会同步发送到 CloudWatch，这可能会影响应用程序性能，但可确保立即投递。设置为 “false”（默认值）时，日志事件以异步方式发送，以获得更好的性能。
配置属性：polaris.event-listener.aws-cloudwatch.synchronous-mode
opentelemetry 事件监听器
将 polaris.event-listener.types=opentelemetry 设置为将 Polaris 事件作为 OpenTelemetry 日志记录发出。
在 Polaris 中 OpenTelemetry 默认是禁用的，因为没有适用于所有部署的采集器端点。要导出这些日志记录，需要启用 OpenTelemetry SDK、启用 OpenTelemetry 日志，并配置 OTLP 采集器端点：
polaris.event-listener.types=opentelemetry
quarkus.otel.sdk.disabled=false
quarkus.otel.logs.enabled=true
quarkus.otel.exporter.otlp.endpoint=http://otlp-collector:4317有关更多 OpenTelemetry 配置详情，请参阅遥测文档。
运行相关
polaris.tasks
| 属性 | 默认值 | 类型 | 说明 |
|---|---|---|---|
polaris.tasks.max-concurrent-tasks | -1 | int | |
polaris.tasks.max-queued-tasks | -1 | int |
polaris.async
用于调整异步活动的高级配置选项。
| 属性 | 默认值 | 类型 | 说明 |
|---|---|---|---|
polaris.async.thread-keep-alive | PT1S | duration | 空闲线程保持存活的时长。 |
polaris.async.max-threads | int | 可用于异步执行的最大线程数。默认为 256。 |
polaris.rate-limiter.filter
| 属性 | 默认值 | 类型 | 说明 |
|---|---|---|---|
polaris.rate-limiter.filter.type | string | 限流器的类型。必须是已注册的标识符（org.apache.polaris.service.ratelimiter.RateLimiter）。 |
polaris.rate-limiter.token-bucket
属性默认值类型说明
polaris.rate-limiter.token-bucket.requests-per-second``long每个 Realm 每秒允许的请求数。该值必须大于零。
polaris.rate-limiter.token-bucket.window``duration此设置已不再使用，并将在未来的版本中移除。
已弃用
polaris.rate-limiter.token-bucket.type``string令牌桶工厂的类型。必须是已注册的标识符（org.apache.polaris.service.ratelimiter.TokenBucketFactory）。
polaris.metrics
属性默认值类型说明
polaris.metrics.tags.<name>string要包含在指标中的附加标签。
polaris.metrics.realm-id-tag.enable-in-api-metrics``false``boolean是否在 API 请求指标中包含 Realm ID 标签。
请注意，如果该标签的基数过高，可能会导致性能问题，甚至使服务器崩溃。
polaris.metrics.realm-id-tag.enable-in-http-metrics``false``boolean是否在 HTTP 服务器请求指标中包含 Realm ID 标签。
请注意，如果该标签的基数过高，可能会导致性能问题，甚至使服务器崩溃。
polaris.metrics.realm-id-tag.http-metrics-max-cardinality 100 int HTTP 服务器请求指标允许的 Realm ID 标签值的最大数量。
此设置用于防止标签数量无限增长，从而避免引发性能问题或导致服务器崩溃。
如果标签数量超过该值，系统会记录一条警告日志，并且不再记录任何 HTTP 服务器请求指标。
polaris.metrics.user-principal-tag.enable-in-api-metrics false boolean 是否在 API 请求指标中包含用户主体（User Principal）标签。
请注意，如果该标签的基数过高，可能会引发性能问题，甚至导致服务器崩溃。
polaris.metrics.http-server-requests.histogram-slos duration 列表 HTTP 服务器请求耗时直方图的服务等级目标（SLO）边界。
设置后，每个边界都会发布一个直方图分桶，以便后端能够在配置的时间点上计算百分位数（例如 p95、p99）。
polaris.iceberg-metrics.reporting
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.iceberg-metrics.reporting.type | default | string |
polaris.log
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.log.request-id-header-name | string | 包含请求 ID 的请求头名称。 | |
polaris.log.mdc.<name> | string | 要包含在日志上下文中的其他 MDC 值。 |
polaris.readiness
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.readiness.ignore-severe-issues | false | boolean | 将其设置为 true 意味着，即使检测到严重的安全风险，Polaris 仍会启动，从而接受拒绝服务、数据丢失、数据损坏及其他风险。 |
polaris.node
节点管理配置。
| 属性 | 默认值 | 类型 | 描述 |
|---|---|---|---|
polaris.node.lease-duration | PT1H | duration | 节点租约的时长。 |
polaris.node.renewal-period | PT15M | duration | 在节点租约到期前续租的时间窗口。 |
polaris.node.num-nodes | 1024 | int | 可同时处于活动状态的 Polaris 节点的最大数量。请勿更改此值或 ID 生成器规范，这是一个相当内部的属性。参见下文的 ID 生成器规范。 |
polaris.node.id-generator-spec.type | snowflake | string | |
polaris.node.id-generator-spec.params.<name> | string |
其他
polaris.realm-context
属性默认值类型描述
polaris.realm-context.realms``字符串列表realm 上下文解析器所支持的 realm 集合。第一个 realm 被视为默认 realm。
polaris.realm-context.header-name``字符串包含 realm 标识符的请求头名称。
polaris.realm-context.require-header``布尔值是否要求请求中必须存在 realm 请求头。如果此值为 true 且 realm 请求头不存在，请求将被拒绝。如果此值为 false 且 realm 请求头不存在，则将使用默认 realm。
注意：这实际上仅在生产环境配置中生效。
polaris.realm-context.type``字符串realm 上下文解析器的类型。必须是一个已注册的（org.apache.polaris.service.context.RealmContextResolver）标识符。
评论
登录后参与评论