KnowForge目录属性
师成· 更新于 2026-09-28· 阅读 17 分钟· 0 次阅读Catalog 属性
通用属性
Iceberg catalog 支持使用 catalog 属性来配置 catalog 的行为。以下是常用的 catalog 属性列表：
| 属性 | 默认值 | 描述 |
|---|---|---|
| catalog-impl | null | 引擎要使用的自定义 Catalog 实现 |
| io-impl | null | 目录（catalog）中要使用的自定义 FileIO 实现 |
| warehouse | null | 数据仓库的根路径 |
| uri | null | URI 字符串，例如 Hive metastore 的 URI |
| clients | 2 | 客户端池大小 |
| cache-enabled | true | 是否缓存目录（catalog）条目 |
| cache.expiration-interval-ms | 30000 | 目录条目在本地的缓存时长，单位为毫秒；0 表示禁用缓存，负值表示永不过期 |
| metrics-reporter-impl | org.apache.iceberg.metrics.LoggingMetricsReporter | 目录中要使用的自定义 MetricsReporter 实现。更多详情参见指标上报章节 |
| unique-table-location | false | 是否为新表使用唯一的位置 |
| encryption.kms-impl | null | 目录中用于与 KMS（密钥管理服务）交互的自定义 KeyManagementClient 实现。更多详情参见加密文档 |
HadoopCatalog 与 HiveCatalog 可以在其构造函数中访问这些属性。任何其他自定义 catalog 都可以通过实现 Catalog.initialize(catalogName, catalogProperties) 来访问这些属性。这些属性可以手动构造，也可以从 Spark 或 Flink 等计算引擎传入。Spark 将其会话属性作为 catalog 属性使用，详见 Spark 配置一节。Flink 通过 CREATE CATALOG 语句传入 catalog 属性，详见 Flink一节。
REST catalog 属性
以下属性用于配置 REST catalog 客户端的行为。
| 属性 | 默认值 | 描述 |
|---|---|---|
snapshot-loading-mode | ALL | 控制如何从 REST 服务器加载快照。支持的值：ALL（加载所有快照）、REFS（仅加载被引用的快照）。 |
rest-metrics-reporting-enabled | true | 是否启用向 REST 服务器上报指标。 |
view-endpoints-supported | false | 用于兼容较旧的 REST 服务器。如果服务器支持视图端点，但未在 ConfigResponse 中发送 endpoints 字段，则应设置为 true。 |
rest-page-size | null | 列出命名空间、表或其他分页资源时使用的分页大小。 |
namespace-separator | %1F | 与 REST 服务器通信时，用于分隔命名空间层级的分隔符字符。 |
scan-planning-mode | CLIENT | 控制扫描计划的执行位置。支持的值：CLIENT（客户端规划）、SERVER（服务端规划）。服务器可在 LoadTableResponse 中按表覆盖此设置。 |
表缓存属性
以下属性用于配置面向时效性的表加载所使用的表缓存。请注意，此缓存与通常可在 catalog 级别配置的缓存不同。
| 属性 | 默认值 | 说明 |
|---|---|---|
rest-table-cache.expire-after-write-ms | 300000（5 分钟） | 缓存表条目在写入后经过多少毫秒过期。 |
rest-table-cache.max-entries | 100 | 要缓存的表条目最大数量。 |
认证属性
以下目录属性用于配置 REST 目录的认证。它们支持 Basic、OAuth2、SigV4 和 Google 认证。
REST 认证属性
| 属性 | 默认值 | 说明 |
|---|---|---|
rest.auth.type | none | REST 目录访问的认证机制。支持的取值：none、basic、oauth2、sigv4、google。 |
rest.auth.basic.username | null | Basic 认证的用户名。当 rest.auth.type = basic 时必填。 |
rest.auth.basic.password | null | Basic 认证的密码。当 rest.auth.type = basic 时必填。 |
rest.auth.sigv4.delegate-auth-type | oauth2 | sigv4 签名之后要委托使用的认证类型。 |
OAuth2 认证属性
使用 oauth2 认证时需要包含的必需属性和可选属性。
| 属性 | 默认值 | 说明 |
|---|---|---|
token | null | 用于与服务器交互的 Bearer 令牌。必须提供 token 或 credential 之一。 |
credential | null | 形如 client_id:client_secret 的凭证字符串，用于在 OAuth2 客户端凭据流程中换取令牌。必须提供 token 或 credential 之一。 |
oauth2-server-uri | v1/oauth/tokens | OAuth2 令牌端点 URI。如果 REST catalog 不是 OAuth2 认证服务器，则必须提供。 |
token-expires-in-ms | 3600000 (1 小时) | 以毫秒为单位的时间，超过该时间后 Bearer 令牌被视为过期。用于决定何时刷新或重新换取令牌。 |
token-refresh-enabled | true | 决定在获取到过期详情时是否自动刷新令牌。 |
token-exchange-enabled | true | 决定是否使用令牌交换流程获取新令牌。禁用后将回退到客户端凭据流程。 |
scope | catalog | oauth2 的附加作用域。 |
audience | null | 可选参数，用于指定令牌的 audience |
resource | null | 可选参数，用于指定 resource |
Google 认证属性
使用 google 认证时需要包含的必需属性和可选属性。
| 属性 | 默认值 | 说明 |
|---|---|---|
gcp.auth.credentials-path | 应用默认凭据 (ADC) | 服务账号 JSON 密钥文件的路径。 |
gcp.auth.credentials-json | 应用默认凭据 (ADC) | 服务账号凭据的 JSON 字符串。 |
gcp.auth.scopes | https://www.googleapis.com/auth/cloud-platform | 请求的 OAuth 作用域，以逗号分隔的列表。 |
锁相关的 Catalog 属性
以下是与加锁相关的 catalog 属性。某些 catalog 实现会使用它们来控制提交期间的加锁行为。
| 属性 | 默认值 | 说明 |
|---|---|---|
| lock-impl | null | 锁管理器的自定义实现，实际接口取决于所使用的 catalog |
| lock.table | null | 用于加锁的辅助表，例如 AWS DynamoDB 锁管理器 |
| lock.acquire-interval-ms | 5000 (5 秒) | 每次尝试获取锁之间的等待间隔 |
| lock.acquire-timeout-ms | 180000 (3 分钟) | 尝试获取锁的最长等待时间 |
| lock.heartbeat-interval-ms | 3000 (3 秒) | 获取锁后每次心跳之间的等待间隔 |
| lock.heartbeat-timeout-ms | 15000 (15 秒) | 在判定锁已过期前，允许的最长无心跳时间 |
Hadoop 配置
HadoopTables 锁配置
在使用 HadoopTables（没有 catalog 的表）时，可以通过为 锁相关的 Catalog 属性一节中的属性添加 iceberg.tables.hadoop. 前缀来进行配置。这可以确保在 S3 等缺乏原生写互斥机制的文件系统上实现原子提交。
信息
要将 DynamoDB 作为锁管理器配合 HadoopTables 使用，请将 iceberg.tables.hadoop.lock-impl 设置为 org.apache.iceberg.aws.dynamodb.DynamoDbLockManager，并将 iceberg.tables.hadoop.lock.table 设置为你的 DynamoDB 表名。更多详情请参阅 DynamoDB Lock Manager。
Hive Metastore 配置
Hive Metastore 连接器会使用 Hadoop 配置中的以下属性。HMS 的表锁定是一个两步过程：
- 创建锁：在 HMS 中创建锁并排队等待获取
- 检查锁：检查锁是否已成功获取
| 属性 | 默认值 | 说明 |
|---|---|---|
| iceberg.hive.client-pool-size | 5 | 在 HMS 中跟踪表时 Hive 客户端池的大小 |
| iceberg.hive.lock-creation-timeout-ms | 180000（3 分钟） | 在 HMS 中创建锁的最长耗时（毫秒） |
| iceberg.hive.lock-creation-min-wait-ms | 50 | 在 HMS 中重试创建锁之间的最小等待时间（毫秒） |
| iceberg.hive.lock-creation-max-wait-ms | 5000 | 在 HMS 中重试创建锁之间的最大等待时间（毫秒） |
| iceberg.hive.lock-timeout-ms | 180000（3 分钟） | 获取锁的最长耗时（毫秒） |
| iceberg.hive.lock-check-min-wait-ms | 50 | 检查锁获取状态之间的最小等待时间（毫秒） |
| iceberg.hive.lock-check-max-wait-ms | 5000 | 检查锁获取状态之间的最大等待时间（毫秒） |
| iceberg.hive.lock-heartbeat-interval-ms | 240000（4 分钟） | HMS 锁的心跳间隔 |
| iceberg.hive.metadata-refresh-max-retries | 2 | 元数据文件缺失时的最大重试次数 |
| iceberg.hive.table-level-lock-evict-ms | 600000（10 分钟） | JVM 表锁的超时时间 |
| iceberg.engine.hive.lock-enabled | true | 使用 HMS 锁来确保提交的原子性 |
注意：iceberg.hive.lock-check-max-wait-ms 和 iceberg.hive.lock-heartbeat-interval-ms 应小于 Hive Metastore 的事务超时时间（hive.txn.timeout，较新版本中为 metastore.txn.timeout）。否则，锁上的心跳（在锁检查期间发送）会在 Iceberg 重试该锁之前就在 Hive Metastore 中过期。
警告：将 iceberg.engine.hive.lock-enabled 设置为 false 会使 HiveCatalog 在提交表变更时不使用 Hive 锁。只有在满足以下所有条件时，才应将其设置为 false：
- HIVE-26882 已在 Hive Metastore 服务器上可用
- 如果 Hive Metastore 使用 MySQL 或 MariaDB 作为后端，则 HIVE-28121 已在 Hive Metastore 服务器上可用
- 所有其他向此 HiveCatalog 所提交的表进行提交的 HiveCatalog 也都使用 Iceberg 1.3 或更高版本
- 所有其他向此 HiveCatalog 所提交的表进行提交的 HiveCatalog 也都已在提交时禁用 Hive 锁
未能确保满足这些条件可能会损坏表。
即使将 iceberg.engine.hive.lock-enabled 设置为 false，HiveCatalog 仍可以通过将表属性 engine.hive.lock-enabled 设置为 true 来对单个表使用锁。当其他 HiveCatalog 无法升级、无法设置为不使用 Hive 锁进行提交时，这一功能非常有用。
评论
登录后参与评论