Apache DataFu 配置参数详解
系统讲解 Apache DataFu 各子模块的构成与可调参数，包括哈希、采样、统计类 UDF 的构造参数取值，序列化与编码说明，Maven 依赖管理、作用域与排除，以及 JDK 与 JVM 内存等运行参数配置与实测建议。
Apache DataFu 配置参数详解
Apache DataFu 是「库」形态的 Java 组件，其配置不像服务那样集中在配置文件里，而是分散在三个层面：依赖声明（Maven 坐标与作用域）、UDF/工具类的构造参数、运行期 JVM 与集群资源参数。本文基于对 datafu-pig:1.6.1、datafu-hourglass:1.6.1 构件的实测，逐层说明可调项与推荐取值。
一、子模块构成
1.1 构件总览
Maven 中央仓库 org/apache/datafu/ 下可用构件（实测版本）：
| 构件 | 最新版本 | 定位 |
|---|---|---|
datafu-pig | 1.6.1 | 核心库 + Pig UDF（datafu.pig.*），本文重点 |
datafu-hourglass | 1.6.1 | 面向 Hadoop 的增量/日期分区作业框架（datafu.hourglass.*） |
datafu-spark_2.12 | 2.1.0 | Spark（Scala 2.12）集成库 |
datafu-spark_2.11 | — | Spark（Scala 2.11）集成库，按集群 Scala 版本选择 |
重要：不存在
org.apache.datafu:datafu核心库构件。DataFu 的核心工具类与 UDF 实际全部打包在datafu-pig中，因此「引入核心库」请使用datafu-pig。
1.2 datafu-pig 内部结构
对 datafu-pig-1.6.1.jar 实测统计共 1437 个 class，datafu.pig.* 为 DataFu 自身的 UDF 包，另有若干被重定位（shade 到 datafu/ 前缀）的第三方库，便于在 Pig 中避免冲突：
| 包 | 说明 |
|---|---|
datafu.pig.hash / hash.lsh | 哈希、局部敏感哈希 |
datafu.pig.sampling | 采样：蓄水池、随机、按键、加权 |
datafu.pig.bags | DataBag 集合操作 |
datafu.pig.sets | 集合交/并/差 |
datafu.pig.stats / stats.entropy | 统计、中位数、分位数、方差、熵 |
datafu.pig.util | 工具 UDF（Base64、Coalesce、断言等） |
datafu.pig.random | 随机数、随机 UUID |
datafu.pig.sessions / linkanalysis / urls / geo / text.opennlp | 会话化、链接分析、URL、地理、NLP |
datafu.com.clearspring.analytics.* | 重定位的 stream-lib（HyperLogLog 等基数估计） |
datafu.org.apache.commons.math、datafu.com.google.common.*、datafu.it.unimi.dsi.fastutil | 重定位的数学/集合基础库 |
1.3 datafu-hourglass 内部结构
实测 datafu-hourglass-1.6.1.jar 包结构：datafu.hourglass.avro、fs、jobs、mapreduce、model、schemas。其关键类包括增量作业 IncrementalJob / PartitionPreservingIncrementalJob / PartitionCollapsingIncrementalJob、日期范围可配置接口 DateRangeConfigurable、执行计划 ExecutionPlanner、分区器 TimePartitioner。该模块面向 Hadoop MapReduce 作业编排，配置以 Job 对象与属性方式注入，需 Hadoop 运行环境，本文不做运行验证，参数细节请以对应 Job 类 API 为准。
二、依赖管理参数
2.1 作用域（scope）
datafu-pig 自身把 Pig / Hadoop 声明为 provided，因此不会传递引入。工程侧应根据运行形态选择 scope：
| 场景 | datafu-pig | pig / hadoop-common | 说明 |
|---|---|---|---|
| 独立 Java 工程直接调用 UDF | compile | compile（需自行补充） | 实测：仅引入 datafu-pig 时 mvn dependency:build-classpath 只输出 datafu-pig jar |
| 提交到已含 Pig/Hadoop 的集群 | compile | provided | 避免与集群内置版本冲突 |
| 仅写 Pig 脚本、由集群执行 | provided | provided | 依赖只参与编译，不打包 |
2.2 dependencyManagement 统一版本
多模块工程建议用 dependencyManagement 统一版本，子模块只声明 groupId+artifactId：
<properties>
<datafu.version>1.6.1</datafu.version>
<pig.version>0.17.0</pig.version>
<hadoop.version>2.7.7</hadoop.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.apache.datafu</groupId>
<artifactId>datafu-pig</artifactId>
<version>${datafu.version}</version>
</dependency>
<dependency>
<groupId>org.apache.pig</groupId>
<artifactId>pig</artifactId>
<version>${pig.version}</version>
</dependency>
<dependency>
<groupId>org.apache.hadoop</groupId>
<artifactId>hadoop-common</artifactId>
<version>${hadoop.version}</version>
</dependency>
</dependencies>
</dependencyManagement>
2.3 exclusions 排除冲突项
若工程已自带高版本 Hadoop，可在引入 datafu-pig 时排除其可能带入的传递依赖（本例 datafu-pig 本身不传递 Pig/Hadoop，但若换用 datafu-spark_* 等则需关注）：
<dependency>
<groupId>org.apache.datafu</groupId>
<artifactId>datafu-pig</artifactId>
<version>1.6.1</version>
<exclusions>
<exclusion>
<groupId>org.apache.hadoop</groupId>
<artifactId>hadoop-common</artifactId>
</exclusion>
</exclusions>
</dependency>
2.4 Spark 集成坐标
在 Spark 工程使用 DataFu 时按 Scala 版本选择：
<dependency>
<groupId>org.apache.datafu</groupId>
<artifactId>datafu-spark_2.12</artifactId>
<version>2.1.0</version>
<scope>provided</scope>
</dependency>
provided 交由 Spark 集群运行时提供，避免与集群 Spark 版本冲突。
三、UDF 构造参数（核心可调项）
以下构造签名均来自对 datafu-pig-1.6.1.jar 的 javap 实测。
3.1 哈希相关（datafu.pig.hash）
| 类 | 构造签名（实测） | 参数含义与取值 |
|---|---|---|
MD5 | MD5() | 无参，输出 32 位十六进制摘要 |
SHA | SHA(String) / SHA() | 参数为算法后缀，内部补 SHA- 前缀。写 "256" → SHA-256，"512" → SHA-512。实测 new SHA("SHA-256") 会抛 SHA-SHA-256 MessageDigest not available |
Hasher | Hasher() / Hasher(String) / Hasher(String, String) | 第 1 参为算法名，第 2 参可指定 Provider；另提供静态方法 longFromHex / intFromHex |
HasherRand | HasherRand() / HasherRand(String) | 可选随机种子参数，便于结果可复现 |
哈希输出为确定性结果，实测两机一致，例如：
MD5(apache-datafu) = f3faa986c556bc49f4131c987f22d04a
SHA-256(apache-datafu) = 07ee215182b6749bc26d1afa300da5f2bf1833d8f0c5396e56a2f36110dafc56
3.2 采样相关（datafu.pig.sampling）
| 类 | 构造签名（实测） | 可调参数 |
|---|---|---|
ReservoirSample | ReservoirSample(String) | 参数为样本数 k，如 '2'。基于蓄水池算法，单遍扫描即可 |
SimpleRandomSample | SimpleRandomSample() / SimpleRandomSample(String) | 可选样本数参数 |
WeightedReservoirSample | WeightedReservoirSample(String, String) | 第 1 参样本数；第 2 参为权重字段索引 |
SampleByKey | SampleByKey(String) / SampleByKey(String, String) | 第 1 参抽样概率；第 2 参可选随机种子 |
采样类为随机抽取：ReservoirSample 样本数固定，抽取元素随机。实测同一程序两次运行分别得到 [1,9]（Ubuntu）与 [6,10]（CentOS 8），属正常行为。若需结果可复现，优先使用带种子参数的 SampleByKey(String, String) 或 HasherRand(String)。
3.3 统计相关（datafu.pig.stats）
| 类 | 构造签名（实测） | 可调参数 |
|---|---|---|
Quantile | Quantile(String...) | 变参，可指定多个分位点 |
StreamingQuantile | StreamingQuantile(String...) | 变参，流式（内存受限）分位数估计 |
Median | Median() | 中位数 |
VAR / IntVAR / LongVAR / DoubleVAR / FloatVAR | 默认构造 | 按数据类型计算方差 |
HyperLogLogPlusPlus | 默认构造 | 基数（去重计数）估计 |
StreamingMedian | 默认构造 | 流式中位数 |
分位数类通过构造参数指定要计算的 K 值，用于在有限内存下估计分布，适合大数据集。
3.4 工具与编码相关（datafu.pig.util / random）
| 类 | 构造签名（实测） | 可调参数 |
|---|---|---|
Base64Encode | Base64Encode() | 无参，输出标准 Base64 字符串 |
Base64Decode | Base64Decode() | 无参 |
Coalesce | Coalesce() / Coalesce(String) | 可选默认值，用于取首个非空字段 |
RandInt | RandInt() | 无参，生成随机整数 |
RandomUUID | RandomUUID() | 无参，生成随机 UUID |
实测编码输出：
Base64Encode(datafu) = ZGF0YWZ1
3.5 序列化与编码说明
- DataFu UDF 的输入输出数据类型由 Pig 的
Tuple/DataBag承载；在 Java 工程中直接调用时用TupleFactory.getInstance().newTuple(...)构造元组、BagFactory.getInstance().newDefaultBag()构造 bag。 - 序列化本身由 Pig/Hadoop 的
Writable机制处理，DataFu 不额外引入自定义序列化协议，因此不存在独立序列化配置项。 - 对二进制哈希结果，
Hasher提供longFromHex/intFromHex便于把十六进制摘要还原为数值参与计算。
四、JDK 与 JVM 内存参数
4.1 JDK 版本
DataFu 兼容 JDK 8 与 JDK 11（实测：CentOS 8 用 JDK 8、Ubuntu 22.04 用 JDK 11 均编译运行成功）。maven-compiler-plugin 建议：
<properties>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
</properties>
以 JDK 11 编译、目标字节码 1.8，可同时兼容两类运行环境。
4.2 JVM 堆内存
DataFu 单次调用的内存开销不大，按规范建议把堆限制在 256–512 MB。实测统一使用：
java -Xmx384m -cp "target/classes:$(cat cp.txt)" demo.DataFuDemo
-Xmx256m：内存极受限场景的最小可用值。-Xmx384m：本文实测默认值，兼顾稳定与占用。-Xmx512m：处理较大 bag（如大样本量采样、分位数估计）时的上限。
4.3 集群侧资源参数
当 DataFu UDF 在 Pig on MapReduce 上运行时，运行内存主要由集群参数决定（以下为通用 MapReduce 参数，供参考）：
| 参数 | 作用 |
|---|---|
mapreduce.map.memory.mb | 映射任务可用内存 |
mapreduce.reduce.memory.mb | 归约任务可用内存 |
mapreduce.map.java.opts / mapreduce.reduce.java.opts | 任务 JVM 参数（如 -Xmx） |
pig.exec.reducers.bytes.per.reducer | 控制 reducer 数量，影响聚合型 UDF（Median/Quantile/VAR）压力 |
建议任务 JVM 的 -Xmx 取任务内存的约 80%，为堆外与本地库留出余量。
五、参数配置建议汇总
5.1 选型建议
- 只用核心工具类/UDF：引入
datafu-pig，独立 Java 工程补pig+hadoop-common，集群工程用provided。 - Spark 场景：引入对应的
datafu-spark_2.12（或2.11），scope 用provided。 - Hadoop 增量作业编排：
datafu-hourglass，需 Hadoop 环境。
5.2 可复现性建议
- 需要稳定输出：哈希类（
MD5/SHA/Hasher）天然确定；随机类优先选带种子构造（HasherRand(String)、SampleByKey(String,String)）。 - 需要稳定抽样结果但不想改代码：固定输入数据顺序并接受随机性，或在业务侧用固定种子封装。
5.3 常见参数陷阱
Q1： 用 new SHA("SHA-256") 报错？
A： 构造参数只填后缀，用 new SHA("256")。
Q2： 只加 datafu-pig 依赖，编译却报找不到 org.apache.hadoop.io.WritableComparable？
A： provided 依赖不会传递，需显式补 hadoop-common。
Q3： dependency:build-classpath 只输出 datafu-pig 一项，是否解析失败？
A： 正常。因为 datafu-pig 未声明可传递依赖，需按场景自行补充 Pig/Hadoop。