Hudi常见配置参数

hoodie.datasource.write.table.name

指定写入数据的Hudi表名。

无

hoodie.datasource.write.operation

写Hudi表数据时指定的操作类型，当前支持upsert、delete、insert、bulk_insert等方式。

• upsert：更新插入混合操作。
• delete：删除操作。
• insert：插入操作。
• bulk_insert： 用于初始建表导入数据， 注意初始建表禁止使用upsert、insert方式。
• insert_overwrite：对静态分区执行insert overwrite。
• insert_overwrite_table：动态分区执行insert overwrite，该操作并不会立刻删除全表做overwrite，会逻辑上重写Hudi表的元数据，无用数据后续由hudi的clean机制清理。效率比bulk_insert加overwrite高。

upsert

hoodie.datasource.write.table.type

指定Hudi表类型，一旦这个表类型被指定，后续禁止修改该参数。表类型分为COPY_ON_WRITE和MERGE_ON_READ。

• COPY_ON_WRITE：写时复制表也简称cow表，使用parquet文件存储数据，内部的更新操作需要通过重写原始parquet文件完成。
• MERGE_ON_READ：读时合并表也简称mor表，使用列格式parquet和行格式Avro两种方式混合存储数据。其中parquet格式文件用于存储基础数据，Avro格式文件（也可叫做log文件）用于存储增量数据。

COPY_ON_WRITE

hoodie.datasource.write.precombine.field

该值用于在写之前对具有相同的key行进行合并去重。

指定为具体的表字段

hoodie.datasource.write.payload.class

在更新过程中，该类用于提供方法将要更新的记录和更新的记录做合并，该实现可插拔，如要实现自己的合并逻辑，可自行编写。

org.apache.hudi.common.model.DefaultHoodieRecordPayload

hoodie.datasource.write.recordkey.field

用于指定Hudi的主键，Hudi表要求有唯一主键。

指定为具体的表字段

hoodie.datasource.write.partitionpath.field

用于指定分区键，该值配合hoodie.datasource.write.keygenerator.class使用可以满足不同的分区场景。

无

hoodie.datasource.write.hive_style_partitioning

用于指定分区方式是否和Hive保持一致。Hive分区将数据按分区字段的值存储在不同的目录中，使得数据更容易管理和查询。建议该值设置为true。

• true：表示指定分区方式和Hive保持一致。
• false：表示指定分区方式和Hive不保持一致。

true

hoodie.datasource.write.keygenerator.class

配合hoodie.datasource.write.partitionpath.field，hoodie.datasource.write.recordkey.field产生主键和分区方式。

org.apache.hudi.keygen.ComplexKeyGenerator

hoodie.datasource.hive_sync.enable

Hudi写入数据时，是否启用Hive元数据同步。启用此配置后，Hudi会在写入数据时自动同步表的元数据到Hive Metastore，使得 Hive可以直接查询Hudi表。建议该值设置为true，统一使用Hive管理Hudi表。

• true：表示启用Hive元数据同步。
• false：表示不启用Hive元数据同步。

false

hoodie.datasource.hive_sync.database

启用Hive元数据同步后，指定同步给Hive的数据库名。

default

hoodie.datasource.hive_sync.table

启用Hive元数据同步后，指定同步给Hive的表名。建议这个值和hoodie.datasource.write.table.name保证一致。

unknown

hoodie.datasource.hive_sync.username

启用Hive元数据同步后，用于指定连接Hive Metastore的用户名。

hive

hoodie.datasource.hive_sync.password

启用Hive元数据同步后，用于指定连接Hive Metastore的密码。

hive

hoodie.datasource.hive_sync.jdbcurl

启用Hive元数据同步后，连接Hive Metastore的JDBC URL。

""

hoodie.datasource.hive_sync.use_jdbc

是否使用Hive JDBC方式连接Hive同步Hudi表信息。

建议该值设置为false，设置为false后JDBC连接相关配置无效。

• true：表示使用Hive JDBC方式连接Hive同步Hudi表信息。
• false：表示不使用Hive JDBC方式连接Hive同步Hudi表信息。

true

hoodie.datasource.hive_sync.partition_fields

用于决定Hive分区列。通过分区，可以显著提高查询性能，特别是对于大数据集，因为查询时可以只扫描相关的分区目录。

""

hoodie.datasource.hive_sync.partition_extractor_class

用于提取Hudi分区列值，将其转换成Hive分区列。

org.apache.hudi.hive.SlashEncodedDayPartitionValueExtractor

hoodie.datasource.hive_sync.support_timestamp

当Hudi表存在timestamp类型字段时，需指定此参数为true，以实现同步timestamp类型到Hive元数据中。

该值默认为false，默认将timestamp类型同步为bigInt，默认情况可能导致使用SQL查询包含timestamp类型字段的Hudi表出现错误。

true

hoodie.index.class

用户自定义索引的全路径名，索引类必须为HoodieIndex的子类，当指定该配置时，其会优先于hoodie.index.type配置。

""

hoodie.index.type

使用的索引类型，默认为布隆过滤器。可能的选项是[BLOOM | HBASE | GLOBAL_BLOOM | SIMPLE | GLOBAL_SIMPLE] 。 布隆过滤器消除了对外部系统的依赖，并存储在Parquet数据文件的页脚中。

BLOOM

hoodie.index.bloom.num_entries

存储在布隆过滤器中的条目数。 假设maxParquetFileSize为128MB，averageRecordSize为1024B，因此，一个文件中的记录总数约为130K。 默认值（60000）大约是此近似值的一半。

60000

hoodie.index.bloom.fpp

根据条目数允许的错误率。 用于计算应为布隆过滤器分配多少位以及哈希函数的数量。通常将此值设置的很低（默认值0.000000001），在磁盘空间上进行权衡以降低误报率。

0.000000001

hoodie.bloom.index.parallelism

指定布隆过滤器索引查找的并行度，其中涉及Spark Shuffle。

增加并行度可以提高索引构建的性能，但也会增加资源消耗。默认情况下，根据输入的工作负载特征自动计算的。

0

hoodie.bloom.index.prune.by.ranges

是否在构建布隆过滤器索引时通过范围修剪来优化索引。从文件框定信息，可以加快索引查找的速度。 如果键具有单调递增的前缀，例如时间戳，则更加有用。

• true：启用范围修剪。
• false：禁用范围修剪。

true

hoodie.bloom.index.use.caching

用于指定是否在构建和使用布隆过滤器索引时启用缓存。启用缓存，将通过减少用于计算并行度或受影响分区的IO来缓存输入的RDD以加快索引查找，从而提高查询性能，特别是在频繁查询相同数据的情况下。

• true：启用缓存。
• false：禁用缓存。

true

hoodie.bloom.index.use.treebased.filter

用于指定是否在布隆过滤器索引中启用基于间隔树（Tree-based Filter）的文件过滤优化。与暴力模式相比，此模式可根据键范围加快文件过滤速度。

• true：启用基于间隔树的文件过滤优化。
• false：禁用基于间隔树的文件过滤优化。

true

hoodie.bloom.index.bucketized.checking

用于指定是否在布隆过滤器索引中启用桶式布隆过滤。启用桶式布隆过滤可以减少了在基于排序的布隆索引查找中看到的偏差。

• true：启用桶式布隆过滤。
• false：禁用桶式布隆过滤。

true

hoodie.bloom.index.keys.per.bucket

仅在启用bloomIndexBucketizedChecking并且索引类型为bloom的情况下适用。

此配置控制“存储桶”的大小，该大小可跟踪对单个文件进行的记录键检查的次数，并且是分配给执行布隆过滤器查找的每个分区的工作单位。 较高的值将分摊将布隆过滤器读取到内存的固定成本。

10000000

hoodie.bloom.index.update.partition.path

用于指定在使用索引类型为GLOBAL_BLOOM时，是否在更新记录时更新分区路径。

• true：当对一个已有记录执行包含分区路径的更新操作时，将会导致把新记录插入到新分区，而把原有记录从旧分区里删除。
• false：只对旧分区的原有记录进行更新。

true

hoodie.index.hbase.zkquorum

仅在索引类型为HBase时适用，必填选项。要连接的HBase ZooKeeper Quorum URL。

无

hoodie.index.hbase.zkport

仅在索引类型为HBase时适用，必填选项。要连接的HBase ZooKeeper Quorum端口。

无

hoodie.index.hbase.zknode.path

仅在索引类型为HBase时适用，必填选项。这是根znode，它将包含HBase创建及使用的所有znode。

无

hoodie.index.hbase.table

仅在索引类型为HBase时适用，必填选项。HBase表名称，用作索引。Hudi将row_key和[partition_path, fileID, commitTime]映射存储在表中。

无

hoodie.parquet.max.file.size

Hudi写阶段生成的parquet文件的目标大小。对于DFS，这需要与基础文件系统块大小保持一致，以实现最佳性能。

120 * 1024 * 1024 byte

hoodie.parquet.block.size

parquet页面大小，页面是parquet文件中的读取单位，在一个块内，页面被分别压缩。

120 * 1024 * 1024 byte

hoodie.parquet.compression.ratio

当Hudi尝试调整新parquet文件的大小时，预期对parquet数据进行压缩的比例。 如果bulk_insert生成的文件小于预期大小，请增加此值。

0.1

hoodie.parquet.compression.codec

parquet压缩编解码方式名称，默认值为snappy。可能的选项是gzip、snappy、uncompressed、lzo。

• snappy：一种快速的压缩算法，适用于大多数场景。
• gzip：提供较高的压缩比，但压缩和解压速度较慢。
• uncompressed：不进行压缩。
• lzo：提供较高的压缩比，但需要额外的库支持。

snappy

hoodie.logfile.max.size

用于指定Hudi日志文件的最大值。这是在将日志文件移到下一个版本之前允许的最大值。

1GB

hoodie.logfile.data.block.max.size

LogFile数据块的最大值。这是允许将单个数据块附加到日志文件的最大值。 这有助于确保附加到日志文件的数据被分解为可调整大小的块，以防止发生OOM错误。此大小应大于JVM内存。

256MB

hoodie.logfile.to.parquet.compression.ratio

随着记录从日志文件移动到parquet，预期会进行额外压缩的比例。 用于merge_on_read存储，以将插入内容发送到日志文件中并控制压缩parquet文件的大小。

0.35

hoodie.clean.automatic

用于控制是否自动执行数据清理操作。数据清理是 Hudi 中的一个重要功能，用于删除过期的或不再需要的数据文件，以优化存储空间和查询性能。

• true：Hudi会在每次写入操作后自动执行数据清理操作。
• false：需要手动执行数据清理操作。

true

hoodie.cleaner.policy

Hudi使用的清理策略。Hudi将删除旧版本的parquet文件以回收空间。 任何引用此版本文件的查询和计算都将失败。建议确保数据保留的时间超过最大查询执行时间。

清理策略如下：

• KEEP_LATEST_FILE_VERSIONS：保留最新的文件版本，删除旧的文件版本。
• KEEP_LATEST_COMMITS：保留最新的提交，删除旧的提交。
• KEEP_LATEST_FILE_VERSIONS_BY_FILE_SIZE：保留最新的文件版本，但根据文件大小进行优化。
• KEEP_LATEST_COMMITS_AND_FILE_VERSIONS：结合 KEEP_LATEST_COMMITS 和 KEEP_LATEST_FILE_VERSIONS 策略，保留最新的提交和文件版本。

KEEP_LATEST_COMMITS

hoodie.cleaner.commits.retained

在Hudi中，每次写入操作（如插入、更新或删除）都会生成一个新的提交（commit）。每个提交都有一个唯一的提交时间戳（commit time），用于标识该次写入操作。

该参数用于Hudi清理操作中保留的commit数。当commit数超过这个值时，Hudi会删除最早的commit及其相关数据文件，以释放存储空间。

10

hoodie.keep.max.commits

在Hudi中，每次写入操作都会生成一个新的提交。每个提交都有一个唯一的提交时间戳（commit time），用于标识该次写入操作。

Hudi支持时间旅行查询（time travel queries），允许用户查询数据在特定时间点的状态。为了支持这一功能，Hudi会保留多个历史版本的数据。

该参数用于指定Hudi保留的最大提交数。当提交数超过这个值时，Hudi会删除最早的提交及其相关数据文件，以释放存储空间。

30

hoodie.keep.min.commits

归档操作至少保留的commit数。

20

hoodie.commits.archival.batch

控制着批量读取并一起归档的提交即时的数量。通过调整这个参数，可以控制归档操作的频率和每次归档的记录数量。

10

hoodie.parquet.small.file.limit

该值应小于maxFileSize，如果将其设置为0，会关闭此功能。由于批处理中分区中插入记录的数量众多，总会出现小文件。Hudi提供了一个选项，可以通过将对该分区中的插入作为对现有小文件的更新来解决小文件的问题。此处的大小是被视为“小文件大小”的最小文件大小。

104857600 B

hoodie.copyonwrite.insert.split.size

插入写入并行度。为单个分区的总共插入次数。写出100MB的文件，至少1KB大小的记录，意味着每个文件有100K记录。默认值是超额配置为500K。 为了改善插入延迟，请对其进行调整以匹配单个文件中的记录数。将此值设置为较小的值将导致文件变小（尤其是当compactionSmallFileSize为0时）。

500000

hoodie.copyonwrite.insert.auto.split

Hudi是否应该基于最后24个提交的元数据动态计算insertSplitSize，默认关闭。

• true：Hudi会在插入数据时，基于最后24个提交的元数据动态计算insertSplitSize，自动拆分大文件，以避免生成过大的文件。
• false：插入数据时保持文件的完整性，不进行自动拆分。

true

hoodie.copyonwrite.record.size.estimate

平均记录大小。如果指定，Hudi将使用它，并且不会基于最后24个提交的元数据动态地计算。 没有默认值设置。这对于计算插入并行度以及将插入打包到小文件中至关重要。

1024

hoodie.compact.inline

用于控制是否在写操作中启用内联（inline）压缩。压缩是Hudi中用于优化存储和性能的重要机制，通过合并小文件和删除冗余数据来减少文件数量和提高读取性能。

内联压缩（Inline Compaction）: 在写操作（如插入、更新、删除）过程中自动进行的压缩操作。这种方式可以减少单独的压缩任务，提高整体的写入性能。

异步压缩（Async Compaction）: 通过单独的压缩任务在后台进行的压缩操作。这种方式可以更灵活地控制压缩的频率和时间，但可能会增加系统的复杂性。

• true：在写操作中摄取本身触发压缩。
• false：在写操作中不进行压缩。

true

hoodie.compact.inline.max.delta.commits

用于控制在内联压缩过程中最多包含的增量提交数。这个参数在启用内联压缩时非常重要，因为它决定了在一次写操作中可以合并多少个增量提交。

5

hoodie.compaction.lazy.block.read

当CompactedLogScanner合并所有日志文件时，此配置有助于选择是否应延迟读取日志块。选择true以使用I/O密集型延迟块读取（低内存使用），或者为false来使用内存密集型立即块读取（高内存使用）。

true

hoodie.compaction.reverse.log.read

HoodieLogFormatReader会从pos=0到pos=file_length向前读取日志文件。如果此配置设置为true，则Reader会从pos=file_length到pos=0反向读取日志文件。如果设置为false，则按顺序读取日志文件。

false

hoodie.cleaner.parallelism

在Hudi中，清理操作用于删除不再需要的数据文件，例如过期的增量文件或冗余的基线文件。通过调整该参数值，可以控制清理操作的并行度，从而影响清理操作的性能和资源使用。

如果清理变慢，请增加此值。

200

hoodie.compaction.strategy

用来决定在每次压缩运行期间选择要压缩的文件组的压缩策略。默认情况下，Hudi选择具有累积最多未合并数据的日志文件。

org.apache.hudi.table.action.compact.strategy.

LogFileSizeBasedCompactionStrategy

hoodie.compaction.target.io

LogFileSizeBasedCompactionStrategy的压缩运行期间要花费的MB量。当压缩以内联模式运行时，此值有助于限制摄取延迟。

500 * 1024 MB

hoodie.compaction.daybased.target.partitions

由org.apache.hudi.io.compact.strategy.DayBasedCompactionStrategy使用，表示在压缩运行期间要压缩的最新分区数。

10

hoodie.compaction.payload.class

这需要与插入/插入更新过程中使用的类相同。就像写入一样，压缩也使用记录有效负载类将日志中的记录彼此合并，再次与基本文件合并，并生成压缩后要写入的最终记录。

org.apache.hudi.common.model.DefaultHoodieRecordPayload

hoodie.schedule.compact.only.inline

用于控制在内联压缩时，是否只生成压缩计划。在hoodie.compact.inline=true时有效。

• true：只在内联压缩中生成压缩任务。
• false：在写操作中和单独的压缩任务中都生成压缩任务。

false

hoodie.run.compact.only.inline

通过Sql执行run compaction命令时，是否只执行压缩操作，压缩计划不存在时直接退出。

• true：只会在写操作中执行压缩任务，而不会启动单独的异步压缩任务。
• false：在写操作中和单独的压缩任务中都进行压缩任务。

false

hoodie.write.lock.provider

指定写操作的Lock Provider。不建议使用默认值，使用org.apache.hudi.hive.HiveMetastoreBasedLockProvider。

Lock Provider用于在分布式环境中确保写操作的原子性和一致性，防止多个写操作同时修改同一数据，从而避免数据冲突和不一致。

org.apache.hudi.client.transaction.lock.ZookeeperBasedLockProvider

hoodie.write.lock.hivemetastore.database

用于指定在使用Hive作为Lock Provider时的database名称。

无

hoodie.write.lock.hivemetastore.table

用于指定在使用Hive作为Lock Provider时的table name。

无

hoodie.write.lock.client.num_retries

用于控制在获取锁失败时的重试次数。

在Hudi中，写操作需要获取锁以确保数据的一致性和原子性。如果在获取锁时遇到问题（例如网络问题、锁竞争等），客户端可以重试获取锁。

10

hoodie.write.lock.client.wait_time_ms_between_retry

用于控制客户端在两次重试之间的等待时间（以毫秒为单位）。适当的等待时间可以帮助避免因短暂的网络问题或锁竞争导致的写操作失败。

10000

hoodie.write.lock.conflict.resolution.strategy

lock provider类，必须是ConflictResolutionStrategy的子类。

org.apache.hudi.client.transaction.SimpleConcurrentFileWritesConflictResolutionStrategy

hoodie.write.lock.zookeeper.base_path

用于指定在使用ZooKeeper作为锁提供者时存放ZNodes的路径，同一张表的并发写入需配置一致。

无

hoodie.write.lock.zookeeper.lock_key

ZNode的名称，建议与Hudi表名相同。

无

hoodie.write.lock.zookeeper.connection_timeout_ms

用于指定在使用ZooKeeper作为锁提供者时，连接ZooKeeper超时时间。

15000

hoodie.write.lock.zookeeper.port

用于指定在使用ZooKeeper作为锁提供者时，连接ZooKeeper端口号。

无

hoodie.write.lock.zookeeper.url

用于指定在使用ZooKeeper作为锁提供者时，连接ZooKeeper的url。

无

hoodie.write.lock.zookeeper.session_timeout_ms

用于指定在使用ZooKeeper作为锁提供者时，连接ZooKeeper的session会话超时时间（以毫秒为单位）。

60000

hoodie.clustering.inline

Clustering即数据布局，该服务可重新组织数据以提高查询性能，也不会影响摄取速度。Hudi Clustering分为同步执行clustering和异步执行clustering。

• true：启用同步执行clustering。
• false：不启用同步执行clustering。

false

hoodie.clustering.inline.max.commits

同步执行clustering中，触发clustering的commit数。

这个参数可以限制同步执行clustering的范围，避免在单次写入操作中处理过多的commit，从而影响写入性能。

4

hoodie.clustering.async.enabled

是否启用异步执行clustering，通过异步执行clustering操作，可以减少写入延迟，提高写入性能。

• true：启用异步执行clustering。
• false：不启用异步执行clustering。

false

hoodie.clustering.async.max.commits

异步执行clustering中，触发clustering的commit数。

4

hoodie.clustering.plan.strategy.target.file.max.bytes

指定clustering后每个文件大小最大值。

1024 * 1024 * 1024 byte

hoodie.clustering.plan.strategy.small.file.limit

小于该大小的文件会被clustering。

300 * 1024 * 1024 byte

hoodie.clustering.plan.strategy.sort.columns

clustering用以排序的列。

无

hoodie.layout.optimize.strategy

Clustering执行策略，可选linear、z-order、hilbert三种排序方式。

linear

hoodie.layout.optimize.enable

使用z-order、hilbert时需要开启。

false

hoodie.clustering.plan.strategy.class

筛选FileGroup进行clustering的策略类，默认筛选小于hoodie.clustering.plan.strategy.small.file.limit阈值的文件。

org.apache.hudi.client.clustering.plan.strategy.SparkSizeBasedClusteringPlanStrategy

hoodie.clustering.execution.strategy.class

执行clustering的策略类（RunClusteringStrategy的子类），用以定义群集计划的执行方式。

默认类按指定的列对计划中的文件组进行排序，同时满足配置的目标文件大小。

org.apache.hudi.client.clustering.run.strategy.SparkSortAndSizeExecutionStrategy

hoodie.clustering.plan.strategy.max.num.groups

设置执行clustering时最多选择多少个FileGroup，该值越大并发度越大。

30

hoodie.clustering.plan.strategy.max.bytes.per.group

设置执行clustering时每个FileGroup最多有多少数据参与clustering。

2 * 1024 * 1024 * 1024 byte