本文详细介绍了ApacheIceberg的表配置，包括表属性（如读写行为、默认值和描述）、Catalog属性、Hadoop配置以及与HiveCatalog的集成，涉及表锁定机制和注意事项。
Apache Iceberg 中文教程2-表配置
表属性
Iceberg表支持使用表属性来配置表的行为，例如读取器的默认拆分大小。
读取属性
| 属性名 | 默认值 | 描述 |
|---|---|---|
| read.split.target-size | 134217728 (128 MB) | 合并数据输入拆分时的目标大小 |
| read.split.metadata-target-size | 33554432 (32 MB) | 合并元数据输入拆分时的目标大小 |
| read.split.planning-lookback | 10 | 在合并输入拆分时要考虑的bin数 |
| read.split.open-file-cost | 4194304 (4 MB) | 打开文件的估计成本，在合并拆分时作为最小权重使用 |
| read.parquet.vectorization.enabled | true | 控制是否使用Parquet矢量化读取 |
| read.parquet.vectorization.batch-size | 5000 | Parquet矢量化读取的批处理大小 |
| read.orc.vectorization.enabled | false | 控制是否使用ORC矢量化读取 |
| read.orc.vectorization.batch-size | 5000 | ORC矢量化读取的批处理大小 |
写入属性
| 属性名 | 默认值 | 描述 |
|---|---|---|
| write.format.default | parquet | 表的默认文件格式；parquet、avro或orc |
| write.delete.format.default | data file format | 表的默认删除文件格式；parquet、avro或orc |
| write.parquet.row-group-size-bytes | 134217728 (128 MB) | Parquet行组大小 |
| write.parquet.page-size-bytes | 1048576 (1 MB) | Parquet页面大小 |
| write.parquet.page-row-limit | 20000 | Parquet页面行数限制 |
| write.parquet.dict-size-bytes | 2097152 (2 MB) | Parquet字典页面大小 |
| write.parquet.compression-codec | gzip | Parquet压缩编解码器：zstd、brotli、lz4、gzip、snappy或uncompressed |
| write.parquet.compression-level | null | Parquet压缩级别 |
| write.parquet.bloom-filter-enabled.column.col1 | (not set) | 提示Parquet为列col1编写一个Bloom过滤器 |
| write.parquet.bloom-filter-max-bytes | 1048576 (1 MB) | Bloom过滤器位集的最大字节数 |
| write.avro.compression-codec | gzip | Avro压缩编解码器：gzip(deflate级别9)、zstd、snappy或uncompressed |
| write.avro.compression-level | null | Avro压缩级别 |
| write.orc.stripe-size-bytes | 67108864 (64 MB) | 默认ORC条带大小，以字节为单位 |
| write.orc.block-size-bytes | 268435456 (256 MB) | ORC文件的默认文件系统块大小 |
| write.orc.compression-codec | zlib | ORC压缩编解码器：zstd、lz4、lzo、zlib、snappy或none |
| write.orc.compression-strategy | speed | ORC压缩策略：speed或compression |
| write.orc.bloom.filter.columns | (not set) | 必须创建Bloom过滤器的列名称的逗号分隔列表 |
| write.orc.bloom.filter.fpp | 0.05 | Bloom过滤器的误报率（必须> 0.0且< 1.0） |
| write.location-provider.impl | null | LocationProvider的可选自定义实现 |
| write.metadata.compression-codec | none | 元数据压缩编解码器；none或gzip |
| write.metadata.metrics.max-inferred-column-defaults | 100 | 定义要收集指标的最大列数 |
| write.metadata.metrics.default | truncate(16) | 表中所有列的默认指标模式；none、counts、truncate(length)或full |
| write.metadata.metrics.column.col1 | (未设置) | 列 ‘col1’ 的指标模式，允许根据列进行调整；none、counts、truncate(length)或full |
| write.target-file-size-bytes | 536870912 (512 MB) | 控制生成的文件大小，以目标字节数为准 |
| write.delete.target-file-size-bytes | 67108864 (64 MB) | 控制生成的删除文件大小，以目标字节数为准 |
| write.distribution-mode | none | 定义写入数据的分布方式：none：不混洗行；hash：按分区键哈希分发；range：按分区键或排序键范围分发（如果表有SortOrder） |
| write.delete.distribution-mode | hash | 定义写入删除数据的分布方式 |
| write.update.distribution-mode | hash | 定义写入更新数据的分布方式 |
| write.merge.distribution-mode | none | 定义写入合并数据的分布方式 |
| write.wap.enabled | false | 启用写入审计发布 |
| write.summary.partition-limit | 0 | 如果更改的分区数小于此限制，则在快照摘要中包含分区级别的汇总统计信息 |
| write.metadata.delete-after-commit.enabled | false | 控制提交后是否删除最旧版本的元数据文件 |
| write.metadata.previous-versions-max | 100 | 在提交后删除之前要保留的先前版本元数据文件的最大数量 |
| write.spark.fanout.enabled | false | 启用Spark中不需要对数据进行聚类的扇出写入器；使用更多内存 |
| write.object-storage.enabled | false | 启用对象存储位置提供程序，向文件路径添加散列组件 |
| write.data.path | table location + /data | 数据文件的基本位置 |
| write.metadata.path | table location + /metadata | 元数据文件的基本位置 |
| write.delete.mode | copy-on-write | 删除命令的模式：copy-on-write或merge-on-read（仅适用于v2） |
| write.delete.isolation-level | serializable | 删除命令的隔离级别：serializable或snapshot |
| write.update.mode | copy-on-write | 更新命令的模式：copy-on-write或merge-on-read（仅适用于v2） |
| write.update.isolation-level | serializable | 更新命令的隔离级别：serializable或snapshot |
| write.merge.mode | copy-on-write | 合并命令的模式：copy-on-write或merge-on-read（仅适用于v2） |
| write.merge.isolation-level | serializable | 合并命令的隔离级别：serializable或snapshot |
表行为属性
| Property | Default | Description |
|---|---|---|
| commit.retry.num-retries | 4 | 在失败之前重试提交的次数 |
| commit.retry.min-wait-ms | 100 | 重试提交之前等待的最小时间（毫秒） |
| commit.retry.max-wait-ms | 60000 (1 分钟) | 重试提交之前等待的最大时间（毫秒） |
| commit.retry.total-timeout-ms | 1800000 (30 分钟) | 提交的总重试超时时间（毫秒） |
| commit.status-check.num-retries | 3 | 在连接丢失后检查提交是否成功的次数，在未知提交状态下失败 |
| commit.status-check.min-wait-ms | 1000 (1 秒) | 重试状态检查之前等待的最小时间（毫秒） |
| commit.status-check.max-wait-ms | 60000 (1 分钟) | 重试状态检查之前等待的最大时间（毫秒） |
| commit.status-check.total-timeout-ms | 1800000 (30 分钟) | 提交状态检查必须成功的总超时时间（毫秒） |
| commit.manifest.target-size-bytes | 8388608 (8 MB) | 合并清单文件时的目标大小 |
| commit.manifest.min-count-to-merge | 100 | 累积清单文件进行合并之前的最小数量 |
| commit.manifest-merge.enabled | true | 控制在写入时是否自动合并清单 |
| history.expire.max-snapshot-age-ms | 432000000 (5 天) | 在过期快照时表及其所有分支上保留的默认最大快照年龄 |
| history.expire.min-snapshots-to-keep | 1 | 在过期快照时表及其所有分支上保留的默认最小快照数量 |
| history.expire.max-ref-age-ms | Long.MAX_VALUE (永远) | 在过期快照时保留快照引用的默认最大年龄（除主分支外）。主分支永不过期。 |
保留表属性
保留表属性仅用于在创建或更新表时控制行为。这些属性的值不会作为表元数据的一部分进行持久化。
| Property | Default | Description |
|---|---|---|
| format-version | 1 | 表的格式版本（可以是 1 或 2）根据规范定义。 |
兼容性标志
| Property | Default | Description |
|---|---|---|
| compatibility.snapshot-id-inheritance.enabled | false | 启用无需显式快照ID提交快照 |
Catalog 属性
IcebergCatalog支持使用Catalog属性来配置Catalog行为。下面是常用catalog 属性的列表：
| Property | Default | Description |
|---|---|---|
| catalog-impl | null | 自定义Catalog实现，由引擎使用 |
| io-impl | null | 自定义FileIO实现，用于Catalog中 |
| warehouse | null | 数据仓库的根路径 |
| uri | null | URI字符串，如Hive metastore的URI |
| clients | 2 | 客户端池大小 |
| cache-enabled | true | 是否缓存catalog条目 |
| cache.expiration-interval-ms | 30000 | catalog条目在本地缓存的时间间隔（毫秒）；0禁用缓存，负值禁用过期 |
| metrics-reporter-impl | org.apache.iceberg.metrics.LoggingMetricsReporter | 自定义MetricsReporter实现，用于catalog。有关更多详细信息，请参见Metrics reporting部分 |
HadoopCatalog和HiveCatalog可以在其构造函数中访问这些属性。任何其他自定义Catalog可以通过实现Catalog.initialize(catalogName, catalogProperties)来访问这些属性。属性可以手动构建或从计算引擎（如Spark或Flink）传递。Spark使用其会话属性作为catalog属性，在Spark配置部分中可以找到更多详细信息。Flink通过CREATE CATALOG语句传递目录属性，有关更多详细信息，请参见Flink部分。
锁定Catalog 属性
以下是与锁定相关的Catalog 属性。某些Catalog 实现使用它们来控制提交期间的锁定行为。
| Property | Default | Description |
|---|---|---|
| lock-impl | null | 锁管理器的自定义实现，实际接口取决于所使用的目录 |
| 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配置
Hive Metastore连接器使用Hadoop配置中的以下属性。HMS表锁定是一个两步过程：
- 锁创建：在HMS中创建锁并排队等待获取
- 锁检查：检查是否成功获取锁
| Property | Default | Description |
|---|---|---|
| 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 Metastore服务器上可用HIVE-26882
- 所有提交到与此HiveCatalog提交的表相同的其他HiveCatalog都是Iceberg 1.3或更高版本
- 所有提交到与此HiveCatalog提交的表相同的其他HiveCatalog在提交时也已禁用了Hive锁
未能确保这些条件会导致表损坏。
即使将iceberg.engine.hive.lock-enabled设置为false，HiveCatalog仍然可以通过设置表属性engine.hive.lock-enabled=true来为单个表使用锁。这在其他HiveCatalog无法升级并设置为在提交时不使用Hive锁的情况下非常有用。
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
