Apache ORC 2.3 配置参数详解

目标：系统讲解 Apache ORC 2.3.1 在 Java 应用（org.apache.orc:orc-core）中的关键配置参数。覆盖写参数（orc.stripe.size 默认 64 MB、orc.compress 默认 ZSTD、orc.row.index.stride 默认 1 万行、orc.bloom.filter.columns）、读参数、hive-storage-api 2.8.1 与 protobuf-java 3.25.8 的依赖配置，并给出标注数据量/内存/磁盘的分析场景生产配置模板。示例基于实测的 struct<id:int,name:string,score:double> 工程（Ubuntu 22.04.5、OpenJDK 17.0.20.1、Maven 3.6.3）、ORC 2.3.1。

一、环境信息

二、前置条件

• 已按《Ubuntu 22.04 安装 Apache ORC 2.3 指南》装好 OpenJDK 17、Maven 3.6.3 与 orc-tools 2.3.1。
• 工程 pom.xml 已声明 orc-core:2.3.1、hive-storage-api:2.8.1、protobuf-java:3.25.8 三个必选依赖。

三、参数查看与修改方式

ORC 的配置通过 Hadoop Configuration 对象传入 OrcFile.writerOptions(conf) / OrcFile.readerOptions(conf)。查看某参数的默认/生效值：对已生成的 ORC 文件用 orc-tools meta 查看实际生效的压缩、Stripe、行组索引；对读本用 orc-tools sizes 查看各列/footer 字节占比。修改方式为在构造 Configuration 时 set（见五、写参数详解）。

写入后可用 meta 子命令核对生效值：

orc-tools meta /opt/orc/data/demo.orc

回显中的 Compression: ZSTD、Rows: 8、File length: 583 bytes 即实际生效参数的结果。

四、参数总览

五、写参数详解

写参数通过 Configuration 设置后传给 writerOptions，示例：

Configuration conf = new Configuration();
conf.set("orc.compress", "ZSTD");
conf.set("orc.stripe.size", "134217728");        // 128 MB
conf.set("orc.row.index.stride", "20000");        // 2 万行一个 stride
conf.set("orc.bloom.filter.columns", "id,1");     // 为第 0、1 列建布隆过滤器
TypeDescription schema =
    TypeDescription.fromString("struct<id:int,name:string,score:double>");
Path path = new Path("/opt/orc/data/demo.orc");
Writer writer = OrcFile.createWriter(path,
    OrcFile.writerOptions(conf).setSchema(schema));

5.1 orc.stripe.size：Stripe 数据量

• 含义：单个 Stripe 的目标数据量（字节）。ORC 文件由若干 Stripe 组成，每个 Stripe 含 index + data + tail 三部分；行按 Stripe（默认 64 MB 数据）组织。
• 默认值：67108864（64 MB）。
• 作用：值越大单文件 Stripe 越少、元信息索引开销越小，但读单 Strip 时需加载的数据越多。分析场景按需调大（如 128 MB 或 256 MB）以提升顺序扫描吞吐；小文件/低延迟场景调小（如 16 MB）。
• 实测参考：8 行示例单批 1 个 Stripe，meta 输出 Stripe: offset: 3 data: 102 rows: 8 tail: 80 index: 118。

5.2 orc.compress：压缩算法

• 含义：Stripe 内数据使用的压缩算法。
• 默认值：ZSTD（ORC 2.3.1；可选 NONE / ZLIB / SNAPPY / LZO / LZ4 / ZSTD）。
• 作用：列式 + 压缩带来高压缩率。实测写 8 行到 demo.orc 为 583 字节，而 meta 显示原始数据 840 字节，压缩态 < 原始态。
• 设置：conf.set("orc.compress", "SNAPPY") 或直接 OrcFile.writerOptions(conf).setCompress(CompressionKind.SNAPPY)。

5.3 orc.row.index.stride：行组（stride）大小

• 含义：行索引（Row_Index）的间隔行数。stripe 内再按 stride 划分行组，每个行组记录该批列的 min/max 统计与行级偏移。
• 默认值：10000（1 万行）。
• 作用：predicate pushdown 的基础——只读取命中谓词的行组与列。stride 越小索引越密集、剪枝越细但索引开销越大；分析全表扫描用默认即可。
• 实测参考：写 8 行读回 batches(=row groups)=1，即 1 个行组；元信息 Encoding column 0: DIRECT、column 1/2: DIRECT_V2（列式编码独立）。

5.4 orc.bloom.filter.columns：布隆过滤器

• 含义：为指定列生成布隆过滤器，配合谓词下推做更细的过滤。列以逗号分隔，可用列名或列 id。
• 默认值：空（关闭）。
• 注意：布隆过滤器适合等值/点查（如 WHERE id = 1005），不适合范围查询；生成会增加写开销与文件体积，只在频繁过滤的低基数/点查列上启用。
• 关联：orc.bloom.filter.fpp 默认 0.05，越小越精确但索引越大。

5.5 其余写参数

• orc.compress.size：默认 262144（256 KB），压缩块大小，影响压缩与读取解压粒度。
• orc.encoding.strategy：SPEED（更快写入）或 COMPRESSION（更高压缩）。实测 int/string 列写入时用了 DIRECT_V2、double 用 DIRECT，属不同列类型独立编码。

六、读参数详解

读参数通过 readerOptions 传入：

Configuration conf = new Configuration();
conf.set("orc.include", "0,2");      // 只读 id、score 两列（列序 0、2）
Reader reader = OrcFile.createReader(path, OrcFile.readerOptions(conf));

6.1 orc.include / orc.exclude：列剪裁

• 含义：按列 id（0 起）指定读取包含/排除的列。配合列式存储只拉取命中列，减少磁盘 IO。
• 默认值：空（读取全部列）。
• 示例：分析只需 id 与 score，orc.include=0,2 即可跳过 name 列。

6.2 谓词下推（predicate pushdown）

• ORC 基于 Row_Index（行组索引）、列统计（min/max/sum/bytesOnDisk）与布隆过滤器实现谓词下推：Reader.rows()（返回 RecordReader/RowReader）逐 batch 读时，仅返回命中谓词的行组与列。
• 示例文件 meta 的 Stripe/File Statistics 中可见每列 min/max/sum 统计，这些正是谓词下推的依据：Column 1: count 8 min: 1000 max: 1007 sum: 8028。

6.3 读批量参数

• reader.getSchema().createRowBatch() 创建读 batch；RecordReader.nextBatch(rbatch) 每次填满一个 VectorizedRowBatch，rbatch.size 为本次有效行数（上限默认 1024 行/批），逐批循环直到返回空。

6.4 schema 演进相关

• orc.force.positional.evolution：默认 false，按列名做 schema 演进（新列用默认值填充）；true 则按位置对齐。对应 ORC 的 schema 演进能力（与 Avro/Parquet 的 default/别名演进类似）。

七、依赖与压缩配置

7.1 hive-storage-api 与 protobuf-java（必选）

<dependency>
  <groupId>org.apache.orc</groupId>
  <artifactId>orc-core</artifactId>
  <version>2.3.1</version>
</dependency>
<dependency>
  <groupId>org.apache.hive</groupId>
  <artifactId>hive-storage-api</artifactId>
  <version>2.8.1</version>
</dependency>
<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java</artifactId>
  <version>3.25.8</version>
</dependency>

• hive-storage-api 提供 Writer.addRowBatch 所需的 org.apache.hadoop.hive.ql.exec.vector.*，orc-core 与 hadoop-client 3.4.3 均不传递引入；
• protobuf-java 必须 3.25.x（3.25.8），版本过低 makeMutableCopy 报 NoSuchMethodError。

7.2 压缩后端（可选，传递依赖）

snappy-java（1.1.10.8）、lz4-java（1.11.1）、zstd-jni（1.5.7-7）、aircompressor（2.0.2）、brotli4j（1.20.0）随 orc-core:2.3.1 自动引入，无需手工添加。切换压缩只改 orc.compress 即可。

八、生产配置模板

适用业务场景：分析型（OLAP）数据落盘，例如明细表/宽表写入、后续扫描聚合。

8.1 场景与资源标注

8.2 写侧模板示例

Configuration conf = new Configuration();
conf.set("orc.compress", "ZSTD");              // 高压缩，分析读友好
conf.set("orc.compress.size", "262144");       // 256 KB 压缩块
conf.set("orc.stripe.size", "268435456");      // 256 MB Stripe，减少元信息
conf.set("orc.row.index.stride", "20000");     // 2 万行一个行组索引
conf.set("orc.bloom.filter.columns", "id");    // 仅对低基数的等值过滤列
conf.set("orc.encoding.strategy", "COMPRESSION");

8.3 读侧模板示例

Configuration conf = new Configuration();
conf.set("orc.include", "0,2");   // 只读需要的列，减少 IO
RecordReader rr = OrcFile.createReader(path,
    OrcFile.readerOptions(conf)).rows();

💡 说明：分析场景优先 ZSTD + 大 Stripe（256 MB）+ 大 stride；只对等值点查列开布隆过滤器；读侧用列剪裁减少扫描 IO。写侧 -Xms256m -Xmx512m 作为 JVM 兜底参考见《Ubuntu 22.04 安装 Apache ORC 2.3 指南》七、配置说明。

九、常见问题（FAQ）

Q1：改了 orc.compress 读出来还是 ZSTD？

压缩在写侧生效、写入后固化在文件 footer，读取方按文件头/ footer 解压，不受读侧 orc.compress 影响。若要改压缩，需按新参数重新写文件；用 orc-tools meta 的 Compression: 行核对生效值。

Q2：orc.bloom.filter.columns 配了但没生效？

布隆过滤器只对等值/点查（=）谓词生效，范围查询不走布隆。确认列名/列 id 正确，且写过文件后 orc-tools meta 中该列应有 BloomFilter 相关统计。

Q3：设置多个参数都记不住，有没有统一核对方法？

对同一个写工程，写好文件后用 orc-tools meta /opt/orc/data/demo.orc 一次核对 Compression、Compression size、Stripe 统计、行组索引（Stream 的 section ROW_INDEX）等全部生效值。

Q4：读时提示缺列或列序不对？

orc.include/exclude 用列 id（0 起）。用 meta 的 Type:（如 struct<id:int,name:string,score:double>）确认列顺序后，再按序填 include。

十、参考链接

• Apache ORC 配置文档：https://orc.apache.org/docs/
• ORC Java 配置属性说明：https://orc.apache.org/docs/java-api.html
• orc-core Maven 坐标：https://repo1.maven.org/maven2/org/apache/orc/orc-core/
• hive-storage-api：https://repo1.maven.org/maven2/org/apache/hive/hive-storage-api/