# Hudi常见配置参数
本章节介绍Hudi重要配置的详细信息，更多配置请参考hudi官网：https://hudi.apache.org/cn/docs/0.11.0/configurations/。
- 提交DLI Spark SQL作业时，在SQL编辑器界面右上角的"设置"-\>"参数设置"中可以配置Hudi参数。
- 提交DLI Spark jar作业时，Hudi参数可以通过Spark datasource API的option来配置。 或者，在提交作业时配置到"Spark参数(--conf)" 中，注意，此处配置的参数，键需要添加前缀 "spark.hadoop."，例如"spark.hadoop.hoodie.compact.inline=true"
  
#### 写入操作配置
表1写入操作重要配置项 
| 参数                                              | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | 默认值                                                     |
|:---|:---|:---|
| 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表类型，一旦这个表类型被指定，后续禁止修改该参数，可选值MERGE_ON_READ。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | 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保持一致，建议该值设置为true。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | true                                                    |
| hoodie.datasource.write.keygenerator.class      | 配合hoodie.datasource.write.partitionpath.field，hoodie.datasource.write.recordkey.field产生主键和分区方式。 说明： 写入设置KeyGenerator与表保存的参数值不一致时将提示需要保持一致。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | org.apache.hudi.keygen.ComplexKeyGenerator              |
   
#### 同步Hive表配置
由DLI提供的元数据服务是一种Hive Metastore服务（HMS），因此下列参数与同步元数据服务相关。
表2同步Hive表参数配置 
| 参数                                                    | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | 默认值                                                         |
|:---|:---|:---|
| hoodie.datasource.hive_sync.enable                    | 是否同步hudi表信息到Hive。当使用DLI提供的元数据服务时，配置该参数代表同步至DLI的元数据中。 注意： 建议该值设置为true，统一使用元数据服务管理hudi表。                                                                                                                                                                                                                                                                                                                                                                                                                                                             | true                                                        |
| hoodie.datasource.hive_sync.database                  | 要同步给hive的数据库名。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | default                                                     |
| hoodie.datasource.hive_sync.table                     | 要同步给hive的表名，建议这个值和hoodie.datasource.write.table.name保证一致。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | unknown                                                     |
| 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.datasource.hive_sync.fast_sync                 | Hudi同步Hive分区方式： - true：从最近一次hive同步后所修改的分区直接向Hive表中做add partition if not exist操作。  - false：会根据修改的分区去hive表查询是否已存在，不存在的进行添加。                                                                                                                                                                  | true                                                        |
| hoodie.datasource.hive_sync.mode                      | hudi表同步hive表的方式，在使用DLI提供的元数据服务时需要保证为hms： - hms：通过hive metastore client同步元数据。  - jdbc：通过hive jdbc方式同步元数据。（DLI元数据服务不支持）  - hiveql：执行hive ql方式同步元数据。（DLI元数据服务不支持）   | hms                                                         |
| hoodie.datasource.hive_sync.username                  | 使用jdbc方式同步Hive时，指定的用户名。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | hive                                                        |
| hoodie.datasource.hive_sync.password                  | 使用jdbc方式同步Hive时，指定的密码。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | hive                                                        |
| hoodie.datasource.hive_sync.jdbcurl                   | 连接hive jdbc指定的连接。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | ""                                                          |
| hoodie.datasource.hive_sync.use_jdbc                  | 是否使用Hive jdbc方式连接Hive同步Hudi表信息。建议该值设置为false，设置为false后jdbc连接相关配置无效。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | true                                                        |
   
#### index相关配置
表3index相关参数配置 
| 参数                                       | 描述                                                                                                                                                                                                                                                                                                                         | 默认值         |
|:---|:---|:---|
| hoodie.index.class                       | 用户自定义索引的全路径名，索引类必须为HoodieIndex的子类，当指定该配置时，其会优先于hoodie.index.type配置。                                                                                                                                                                                                                                                        | ""          |
| hoodie.index.type                        | 使用的索引类型，默认为布隆过滤器。可能的选项是\[BLOOM \| GLOBAL_BLOOM \| SIMPLE \| GLOBAL_SIMPLE\] 。 布隆过滤器消除了对外部系统的依赖，并存储在Parquet数据文件的页脚中。                                                                                                                                                                                                        | BLOOM       |
| hoodie.index.bloom.num_entries           | 存储在布隆过滤器中的条目数。 假设maxParquetFileSize为128MB，averageRecordSize为1024B，因此，一个文件中的记录总数约为130K。 默认值（60000）大约是此近似值的一半。 注意： 将此值设置得太低，将产生很多误报，并且索引查找将必须扫描比其所需的更多的文件；如果将其设置得非常高，将线性增加每个数据文件的大小（每50000个条目大约4KB）。 | 60000       |
| hoodie.index.bloom.fpp                   | 根据条目数允许的错误率。 用于计算应为布隆过滤器分配多少位以及哈希函数的数量。通常将此值设置得很低（默认值：0.000000001），在磁盘空间上进行权衡以降低误报率。                                                                                                                                                                                                                                       | 0.000000001 |
| hoodie.bloom.index.parallelism           | 索引查找的并行度，其中涉及Spark Shuffle。 默认情况下，根据输入的工作负载特征自动计算的。                                                                                                                                                                                                                                                                        | 0           |
| hoodie.bloom.index.prune.by.ranges       | 为true时，从文件框定信息，可以加快索引查找的速度。 如果键具有单调递增的前缀，例如时间戳，则特别有用。                                                                                                                                                                                                                                                                      | true        |
| hoodie.bloom.index.use.caching           | 为true时，将通过减少用于计算并行度或受影响分区的IO来缓存输入的RDD以加快索引查找。                                                                                                                                                                                                                                                                              | true        |
| hoodie.bloom.index.use.treebased.filter  | 为true时，启用基于间隔树的文件过滤优化。与暴力模式相比，此模式可根据键范围加快文件过滤速度。                                                                                                                                                                                                                                                                           | true        |
| hoodie.bloom.index.bucketized.checking   | 为true时，启用了桶式布隆过滤。这减少了在基于排序的布隆索引查找中看到的偏差。                                                                                                                                                                                                                                                                                   | true        |
| hoodie.bloom.index.keys.per.bucket       | 仅在启用bloomIndexBucketizedChecking并且索引类型为bloom的情况下适用。 此配置控制"存储桶"的大小，该大小可跟踪对单个文件进行的记录键检查的次数，并且是分配给执行布隆过滤器查找的每个分区的工作单位。 较高的值将分摊将布隆过滤器读取到内存的固定成本。                                                                                                                     | 10000000    |
| hoodie.bloom.index.update.partition.path | 仅在索引类型为GLOBAL_BLOOM时适用。 为true时，当对一个已有记录执行包含分区路径的更新操作时，将会导致把新记录插入到新分区，而把原有记录从旧分区里删除。为false时，只对旧分区的原有记录进行更新。                                                                                                                                                   | true        |
   
#### 存储配置
表4存储参数配置 
| 参数                                          | 描述                                                                                        | 默认值                      |
|:---|:---|:---|
| 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压缩编解码方式名称，默认值为gzip。可能的选项是\[gzip \| snappy \| uncompressed \| lzo\]                 | snappy                   |
| hoodie.logfile.max.size                     | LogFile的最大值。这是在将日志文件移到下一个版本之前允许的最大值。                                                      | 1GB                      |
| hoodie.logfile.data.block.max.size          | LogFile数据块的最大值。这是允许将单个数据块附加到日志文件的最大值。 这有助于确保附加到日志文件的数据被分解为可调整大小的块，以防止发生OOM错误。此大小应大于JVM内存。 | 256MB                    |
| hoodie.logfile.to.parquet.compression.ratio | 随着记录从日志文件移动到parquet，预期会进行额外压缩的比例。 用于merge_on_read存储，以将插入内容发送到日志文件中并控制压缩parquet文件的大小。      | 0.35                     |
   
#### compaction\&cleaning配置
表5compaction\&cleaning参数配置 
| 参数                                           | 描述                                                                                                                                                       | 默认值                                                                                                                                             |
|:---|:---|:---|
| hoodie.clean.automatic                       | 是否执行自动clean。                                                                                                                                             | true                                                                                                                                            |
| hoodie.cleaner.policy                        | 要使用的清理政策。Hudi将删除旧版本的parquet文件以回收空间。 任何引用此版本文件的查询和计算都将失败。建议确保数据保留的时间超过最大查询执行时间。                                                                           | KEEP_LATEST_COMMITS                                                                                                                             |
| hoodie.cleaner.commits.retained              | 保留的提交数。因此，数据将保留为num_of_commits \* time_between_commits（计划的），这也直接转化为逐步提取此数据集的数量。                                                                          | 10                                                                                                                                              |
| hoodie.keep.max.commits                      | 触发归档操作的commit数阈值。                                                                                                                                        | 30                                                                                                                                              |
| hoodie.keep.min.commits                      | 归档操作保留的commit数。                                                                                                                                          | 20                                                                                                                                              |
| hoodie.commits.archival.batch                | 这控制着批量读取并一起归档的提交即时的数量。                                                                                                                                   | 10                                                                                                                                              |
| hoodie.parquet.small.file.limit              | 该值应小于maxFileSize，如果将其设置为0，会关闭此功能。由于批处理中分区中插入记录的数量众多，总会出现小文件。Hudi提供了一个选项，可以通过将对该分区中的插入作为对现有小文件的更新来解决小文件的问题。此处的大小是被视为"小文件大小"的最小文件大小。                       | 104857600 byte                                                                                                                                  |
| hoodie.copyonwrite.insert.split.size         | 插入写入并行度。为单个分区的总共插入次数。写出100MB的文件，至少1KB大小的记录，意味着每个文件有100K记录。默认值是超额配置为500K。 为了改善插入延迟，请对其进行调整以匹配单个文件中的记录数。将此值设置为较小的值将导致文件变小（尤其是当compactionSmallFileSize为0时）。 | 500000                                                                                                                                          |
| hoodie.copyonwrite.insert.auto.split         | Hudi是否应该基于最后24个提交的元数据动态计算insertSplitSize，默认关闭。                                                                                                           | true                                                                                                                                            |
| hoodie.copyonwrite.record.size.estimate      | 平均记录大小。如果指定，Hudi将使用它，并且不会基于最后24个提交的元数据动态地计算。 没有默认值设置。这对于计算插入并行度以及将插入打包到小文件中至关重要。                                                                         | 1024                                                                                                                                            |
| hoodie.compact.inline                        | 当设置为true时，紧接在插入或插入更新或批量插入的提交或增量提交操作之后由摄取本身触发压缩。                                                                                                          | 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                                                                                                                                           |
| hoodie.cleaner.parallelism                   | 如果清理变慢，请增加此值。                                                                                                                                            | 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时有效。                                                                                                         | false                                                                                                                                           |
| hoodie.run.compact.only.inline               | 通过Sql执行run compaction命令时，是否只执行压缩操作，压缩计划不存在时直接退出。                                                                                                         | false                                                                                                                                           |
   
#### 单表并发控制配置
表6单表并发控制参数配置 
| 参数                                                  | 描述                                                                                                                         | 默认值                                                                                                         |
|:---|:---|:---|
| hoodie.write.lock.provider                          | 指定lock provider，在元数据由DLI托管的场景。 推荐配置：com.huawei.luxor.hudi.util.DliCatalogBasedLockProvider | Spark SQL作业和Flink SQL作业会根据元数据服务切换对应的实现类，由DLI托管元数据的场景为com.huawei.luxor.hudi.util.DliCatalogBasedLockProvider |
| hoodie.write.lock.hivemetastore.database            | HMS服务中的database                                                                                                            | 无                                                                                                           |
| hoodie.write.lock.hivemetastore.table               | HMS服务中的table name                                                                                                          | 无                                                                                                           |
| hoodie.write.lock.client.num_retries                | 重试次数                                                                                                                       | 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                     |
   
#### Clustering配置
![](https://support.huaweicloud.com/sqlref-hudi-dli/public_sys-resources/note_3.0-zh-cn.png)
Clustering中有两个策略分别是hoodie.clustering.plan.strategy.class和hoodie.clustering.execution.strategy.class。一般情况下指定plan.strategy为SparkRecentDaysClusteringPlanStrategy或者SparkSizeBasedClusteringPlanStrategy时，execution.strategy不需要指定。但当plan.strategy为SparkSingleFileSortPlanStrategy时，需要指定execution.strategy为SparkSingleFileSortExecutionStrategy。
表7Clustering参数配置 
| 参数                                                    | 描述                                                                                                                                                         | 默认值                                                                                  |
|:---|:---|:---|
| hoodie.clustering.inline                              | 是否同步执行clustering                                                                                                                                           | false                                                                                |
| hoodie.clustering.inline.max.commits                  | 触发clustering的commit数                                                                                                                                       | 4                                                                                    |
| hoodie.clustering.async.enabled                       | 是否启用异步执行clustering                                                                                                                                         | false                                                                                |
| hoodie.clustering.async.max.commits                   | 异步执行时触发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                                                       |