Apache DataSketches 常用 CLI 命令与工具详解

DataSketches 是纯 Java 库，没有独立命令行工具；日常「CLI」主要是围绕它的 Maven 命令与 Java API。本文以 datasketches-java 6.1.1 为准，给出可直接复制的命令、真实回显，以及核心类/方法速查。所有命令与回显均在 Ubuntu 22.04（OpenJDK 11）上实测。

一、Maven 常用命令

1.1 查看依赖树：dependency:tree

确认 DataSketches 及其传递依赖已正确引入：

cd /opt/ds-mini && mvn -B dependency:tree

实测回显：

[INFO] --- maven-dependency-plugin:2.8:tree (default-cli) @ datasketches-demo ---
[INFO] com.example:datasketches-demo:jar:1.0.0
[INFO] \- org.apache.datasketches:datasketches-java:jar:6.1.1:compile
[INFO]    \- org.apache.datasketches:datasketches-memory:jar:3.0.2:compile
[INFO] BUILD SUCCESS

1.2 编译与打包：compile / package

mvn -q -B compile     # 仅编译
mvn -B package        # 编译并打成 jar

实测打包回显：

[INFO] Building jar: /opt/ds-demo/target/datasketches-demo-1.0.0.jar
[INFO] BUILD SUCCESS
[INFO] Total time:  35.089 s
-rw-r--r-- 1 root root 5547 Oct 11 14:57 target/datasketches-demo-1.0.0.jar

1.3 运行测试：test

mvn -B test

test 会先 testCompile 再用 surefire 执行单元测试。无测试类时实测回显：

[INFO] --- maven-compiler-plugin:3.8.1:testCompile (default-testCompile) @ datasketches-demo ---
[INFO] No sources to compile
[INFO] --- maven-surefire-plugin:2.12.4:test (default-test) @ datasketches-demo ---
[INFO] No tests to run.
[INFO] BUILD SUCCESS
[INFO] Total time:  4.092 s

1.4 生成类路径：dependency:build-classpath

运行示例程序前，用它导出依赖 jar 的类路径：

mvn -q -B dependency:build-classpath -Dmdep.outputFile=cp.txt
cat cp.txt

实测输出：

/root/.m2/repository/org/apache/datasketches/datasketches-java/6.1.1/datasketches-java-6.1.1.jar:/root/.m2/repository/org/apache/datasketches/datasketches-memory/3.0.2/datasketches-memory-3.0.2.jar

随后即可直接运行：

java -Xmx256m -Dfile.encoding=UTF-8 -cp target/classes:$(cat cp.txt) com.example.Demo

1.5 其他常用参数

-q：安静模式，仅输出错误；-B：批处理模式，适合脚本；
-o：离线模式，仅使用本地仓库；
dependency:list：以列表形式列出依赖；
dependency:copy-dependencies -DoutputDirectory=libs：把依赖 jar 复制到指定目录，便于离线分发。

二、DataSketches 常用类与方法速查

2.1 五种 sketch 的创建

Sketch	类型	创建方式（实测签名）
HLL	`org.apache.datasketches.hll.HllSketch`	`new HllSketch(lgK, TgtHllType.HLL_8)`
Theta	`org.apache.datasketches.theta.UpdateSketch`	`UpdateSketch.builder().setLogNominalEntries(12).build()`
KLL	`org.apache.datasketches.kll.KllFloatsSketch`	`KllFloatsSketch.newHeapInstance(200)`
Frequent Items	`org.apache.datasketches.frequencies.ItemsSketch`	`new ItemsSketch<>(32)`
CPC	`org.apache.datasketches.cpc.CpcSketch`	`new CpcSketch(11)`

2.2 写入数据：update

各 sketch 统一使用 update(...) 写入（Theta 旧 API 亦保留 updateSketch 语义）：

hll.update(i);        // long
kll.update(0.5f);     // float
fi.update("apple");   // 任意对象
theta.update(i);      // long / double / String / byte[]

批量写入还可直接传数组：hll.update(long[])、hll.update(int[])。

2.3 读取结果

基数估计：hll.getEstimate()、cpc.getEstimate()、compactSketch.getEstimate()；
分位数：kll.getQuantiles(new double[]{0.5, 0.9, 0.99}) 返回 float[]，单点用 kll.getQuantile(0.5)；极值用 kll.getMinItem() / kll.getMaxItem()；
频繁项：fi.getFrequentItems(ErrorType.NO_FALSE_POSITIVES) 返回 Row<T>[]，每行 getItem() / getEstimate() / getUpperBound()；
样本量：kll.getN()、fi.getStreamLength()。

2.4 集合运算：union / intersection / aNotB

Theta 的集合运算通过 SetOperation.builder() 构建：

Union u = SetOperation.builder().buildUnion();
u.union(ca);            // 逐个送入 sketch（增量）
u.union(cb);
CompactSketch r = u.getResult();

Intersection it = SetOperation.builder().buildIntersection();
it.intersect(ca);
it.intersect(cb);
CompactSketch ri = it.getResult();

AnotB anb = SetOperation.builder().buildANotB();
CompactSketch ra = anb.aNotB(ca, cb);   // 直接返回 A-B 结果

实测两集合（各 10 万，交 5 万）的估计：并集 149586.7（真实 150000）、交集 48249.1（真实 50000）、差集 49642.7（真实 50000）。

2.5 边界与误差

最常用的误差边界方法：

double lb = hll.getLowerBound(2);   // 2 个标准差下界
double ub = hll.getUpperBound(2);   // 2 个标准差上界
double est = hll.getEstimate();

实测（HLL lgK=12，n=1000000）：估计 990116.6，95% 下界/上界为 964895.9 / 1016101.2。Theta 的 CompactSketch 同样提供 getLowerBound(int) / getUpperBound(int)。

2.6 序列化与合并

byte[] bytes = sketch.toByteArray();          // 序列化
HllSketch restored = HllSketch.heapify(bytes); // HLL 反序列化

Theta 用 compact() 得到只读 CompactSketch；HLL 还可用 toUpdatableByteArray() / toCompactByteArray()；KLL 用 merge(other) 合并；频繁项用 fi.merge(other)。

三、命令与 API 速查表

目标	命令 / API
查看依赖	`mvn -B dependency:tree`
编译	`mvn -q -B compile`
打包	`mvn -B package`
测试	`mvn -B test`
生成类路径	`mvn -q -B dependency:build-classpath -Dmdep.outputFile=cp.txt`
运行示例	`java -Xmx256m -cp target/classes:$(cat cp.txt) com.example.Demo`
建 HLL	`new HllSketch(lgK, TgtHllType.HLL_8)`
建 Theta	`UpdateSketch.builder().setLogNominalEntries(12).build()`
建 KLL	`KllFloatsSketch.newHeapInstance(200)`
建频繁项	`new ItemsSketch<>(32)`
建 CPC	`new CpcSketch(11)`
写入	`sketch.update(x)`
读基数	`sketch.getEstimate()`
读分位数	`kll.getQuantiles(double[])`
读频繁项	`fi.getFrequentItems(ErrorType.NO_FALSE_POSITIVES)`
并集	`SetOperation.builder().buildUnion()` + `union(sketch)`
交集	`SetOperation.builder().buildIntersection()` + `intersect(sketch)`
差集	`SetOperation.builder().buildANotB()` + `aNotB(a, b)`
序列化	`sketch.toByteArray()` / `compact()`