Apache ORC 2.3 常用工具与 API 详解
Apache ORC 2.3.1 常用工具与 API 详解：orc-tools 子命令速查（check/convert/count/data/json-schema/key/merge/meta/scan/sizes/version，含用 meta/data/sizes 触发真实回显）与 Java 核心 API 速查（TypeDescription/Writer/Reader/RowReader/VectorizedRowBatch），环境 Ubuntu 22.04.5 + OpenJDK 17 + Maven 3.6.3 实测
Apache ORC 2.3 常用工具与 API 详解
目标：整理 Apache ORC 2.3.1 的常用工具与编程 API。工具部分给出 orc-tools 全部子命令速查（
check/convert/count/data/json-schema/key/merge/meta/scan/sizes/version）与meta/data/sizes的真实回显；API 部分给出TypeDescription、Writer、Reader、RowReader（RecordReader）、VectorizedRowBatch的用法速查。全文基于 Ubuntu 22.04.5、OpenJDK 17.0.20.1、Maven 3.6.3、ORC 2.3.1 实测。
一、环境信息
| 项目 | 内容 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS（x86_64） |
| JDK | OpenJDK 17.0.20.1 |
| Maven | Apache Maven 3.6.3 |
| ORC | org.apache.orc:orc-core:2.3.1 |
| hive-storage-api | 2.8.1 |
| protobuf-java | 3.25.8 |
| orc-tools | orc-tools-2.3.1-uber.jar（wrapper：/usr/local/bin/orc-tools） |
| 示例文件 | /opt/orc/data/demo.orc（583 字节，ZSTD，V_0_12） |
| 管理员账号 | root（示例密码 q1w2e3r4） |
二、工具概览
Apache ORC 官方提供 orc-tools 命令行工具（orc-tools-2.3.1-uber.jar）与 Java 编程接口（orc-core）。两者相辅相成：工具用于安装后诊断/巡检既有 ORC 文件，API 用于在应用内读写 ORC。
| 工具/接口 | 形态 | 主要用途 |
|---|---|---|
| orc-tools | 命令行（uber jar） | 查看元信息、读 JSON、校验、合并等 |
| orc-core API | Java 库 | 应用内写读 ORC（TypeDescription/Writer/Reader） |
三、前置条件
- 已安装 OpenJDK 17、Maven 3.6.3、orc-tools 2.3.1（见《Ubuntu 22.04 安装 Apache ORC 2.3 指南》）。
- 拥有一个可验证的 ORC 文件（如示例
/opt/orc/data/demo.orc）。 - 开发工程已声明
orc-core:2.3.1、hive-storage-api:2.8.1、protobuf-java:3.25.8。
四、orc-tools 子命令速查
4.1 子命令一览
不带参数运行 orc-tools 即可列出全部子命令：
orc-tools version
实测回显：
$ orc-tools version
ORC 2.3.1
全部可用子命令（注意无独立 schema 子命令，schema 展示在 meta 中）：
| 子命令 | 作用 | 典型用法 |
|---|---|---|
| meta | 输出文件/schema/压缩/Stripe 统计/列编码/File length | orc-tools meta demo.orc |
| data | 以 JSON 逐行打印文件内容 | orc-tools data demo.orc |
| check | 校验文件完整性并输出统计 | orc-tools check demo.orc |
| sizes | 统计各列与 footer/索引的字节占比 | orc-tools sizes demo.orc |
| scan | 按谓词条件扫描并打印命中行 | orc-tools scan --column name demo.orc |
| count | 统计满足条件的行数 | orc-tools count --column id ">=1000" demo.orc |
| convert | 在 ORC 与其他格式间转换 | orc-tools convert [--reader/-writer] ... |
| merge | 合并多个 ORC 文件 | orc-tools merge out.orc a.orc b.orc |
| json-schema | 输出 JSON Schema | orc-tools json-schema demo.orc |
| key | 管理文件加密密钥 | orc-tools key [options] ... |
| version | 输出 ORC 版本号 | orc-tools version |
4.2 meta：查看元信息（最常用）
orc-tools meta /opt/orc/data/demo.orc
实测回显：
Structure for /opt/orc/data/demo.orc
File Version: 0.12 with ORC_14 by ORC Java 2.3.1
Rows: 8
Compression: ZSTD
Compression size: 262144
Calendar: Julian/Gregorian
Type: struct<id:int,name:string,score:double>
Stripe Statistics:
Stripe 1:
Column 0: count: 8 hasNull: false
Column 1: count: 8 hasNull: false bytesOnDisk: 8 min: 1000 max: 1007 sum: 8028
Column 2: count: 8 hasNull: false bytesOnDisk: 48 min: user0 max: user7 sum: 40
Column 3: count: 8 hasNull: false bytesOnDisk: 46 min: 10.0 max: 80.0 sum: 360.0
File Statistics:
Column 0: count: 8 hasNull: false
Column 1: count: 8 hasNull: false bytesOnDisk: 8 min: 1000 max: 1007 sum: 8028
Column 2: count: 8 hasNull: false bytesOnDisk: 48 min: user0 max: user7 sum: 40
Column 3: count: 8 hasNull: false bytesOnDisk: 46 min: 10.0 max: 80.0 sum: 360.0
Stripes:
Stripe: offset: 3 data: 102 rows: 8 tail: 80 index: 118
Stream: column 0 section ROW_INDEX start: 3 length 11
Stream: column 1 section ROW_INDEX start: 14 length 27
Stream: column 2 section ROW_INDEX start: 41 length 36
Stream: column 3 section ROW_INDEX start: 77 length 44
Stream: column 1 section DATA start: 121 length 8
Stream: column 2 section DATA start: 129 length 43
Stream: column 2 section LENGTH start: 172 length 5
Stream: column 3 section DATA start: 177 length 46
Encoding column 0: DIRECT
Encoding column 1: DIRECT_V2
Encoding column 2: DIRECT_V2
Encoding column 3: DIRECT
File length: 583 bytes
File raw data size: 840 bytes
Padding length: 0 bytes
Padding ratio: 0%
💡 说明：
meta一次性给出文件版本（V_0_12）、压缩（ZSTD）、schema（struct<...>）、Stripe 统计、列编码（DIRECT / DIRECT_V2）与 File length，是巡检首选。
4.3 data：读 JSON
orc-tools data /opt/orc/data/demo.orc
实测回显：
Processing data file /opt/orc/data/demo.orc [length: 583]
{"id":1000,"name":"user0","score":10.0}
{"id":1001,"name":"user1","score":20.0}
{"id":1002,"name":"user2","score":30.0}
{"id":1003,"name":"user3","score":40.0}
{"id":1004,"name":"user4","score":50.0}
{"id":1005,"name":"user5","score":60.0}
{"id":1006,"name":"user6","score":70.0}
{"id":1007,"name":"user7","score":80.0}
4.4 sizes：各列字节占比
orc-tools sizes /opt/orc/data/demo.orc
实测回显：
Percent Bytes/Row Name
48.54 35.38 _file_footer
20.24 14.75 _index
13.72 10.00 _stripe_footer
8.23 6.00 name
7.89 5.75 score
1.37 1.00 id
💡 说明：
sizes输出各列与 footer/index 的百分比与每行字节数，帮助定位尾耗（footer/index）偏高或某列占用异常。
4.5 其他子命令说明
- check：校验文件结构完整性并输出统计，常用于部署前自检。
- scan：支持按列 + 条件扫描输出命中行，可配合行组索引做谓词验证。
- count：对满足
--column <COL> <表达式>条件的行计数。 - convert：ORC ↔ 其他格式/结构转换（需按
-h查看具体 reader/writer 选项）。 - merge：把多个 ORC 文件合并输出到一个文件（按需设置
--batch/--stride等）。 - json-schema：输出 ORC schema 对应的 JSON Schema 描述。
- key：文件加密密钥管理（需在
-h中按需查看选项）。
五、Java 核心 API 速查
5.1 TypeDescription：Schema 定义
import org.apache.orc.TypeDescription;
// 字符串方式声明（与 orc-tools meta 的 Type 行一致）
TypeDescription schema =
TypeDescription.fromString("struct<id:int,name:string,score:double>");
System.out.println(schema); // struct<id:int,name:string,score:double>
fromString(...)解析类型字符串；createRowBatch(rows)创建列式批量；getSchema()从 Reader 取回 schema。
5.2 Writer：写数据
import org.apache.orc.OrcFile;
import org.apache.orc.TypeDescription;
import org.apache.orc.Writer;
import org.apache.hadoop.conf.Configuration;
import org.apache.hadoop.fs.Path;
Configuration conf = new Configuration();
TypeDescription schema =
TypeDescription.fromString("struct<id:int,name:string,score:double>");
Writer writer = OrcFile.createWriter(new Path("/opt/orc/data/demo.orc"),
OrcFile.writerOptions(conf).setSchema(schema));
// ... 填充 VectorizedRowBatch（见 5.4）
writer.addRowBatch(batch);
writer.close(); // 关闭后元信息写入 footer
OrcFile.createWriter(path, writerOptions(conf).setSchema(schema))创建 Writer。writer.addRowBatch(batch)写入一个向量化批量；writer.close()落盘。
5.3 Reader / RowReader：读数据
import org.apache.orc.OrcFile;
import org.apache.orc.Reader;
import org.apache.orc.RecordReader;
Reader reader = OrcFile.createReader(new Path("/opt/orc/data/demo.orc"),
OrcFile.readerOptions(conf));
System.out.println(reader.getFileVersion()); // V_0_12
System.out.println(reader.getNumberOfRows()); // 8
System.out.println(reader.getStripes().size());// 1
System.out.println(reader.getCompression()); // ZSTD
System.out.println(reader.getSchema());
RecordReader rows = reader.rows(); // RowReader（逐 batch）
VectorizedRowBatch rbatch = reader.getSchema().createRowBatch();
while (rows.nextBatch(rbatch)) {
// 逐行处理 rbatch.cols[i].vector，rbatch.size 为有效行数
}
rows.close();
reader.rows()返回RecordReader（即 RowReader），每次nextBatch填满一个VectorizedRowBatch。
5.4 VectorizedRowBatch：列式批量
import org.apache.hadoop.hive.ql.exec.vector.*;
VectorizedRowBatch batch = schema.createRowBatch(rows); // 容量 rows 行
LongColumnVector id = (LongColumnVector) batch.cols[0];
BytesColumnVector name = (BytesColumnVector) batch.cols[1];
DoubleColumnVector score= (DoubleColumnVector) batch.cols[2];
for (int r = 0; r < rows; r++) {
int row = batch.size++;
id.vector[row] = 1000 + r; // long 列
byte[] b = ("user" + r).getBytes("UTF-8");
name.setRef(row, b, 0, b.length); // string 列
score.vector[row] = (r + 1) * 10; // double 列
}
writer.addRowBatch(batch);
💡 说明：
VectorizedRowBatch来自 hive-storage-api（org.apache.hive:hive-storage-api:2.8.1），orc-core与 hadoop-client 3.4.3 均不传递引入，必须显式声明。字符串列用BytesColumnVector的vector/start/length三组表示，读取时按new String(vec.vector[r], vec.start[r], vec.length[r], "UTF-8")还原。
5.5 API 常见返回值参考
| 调用 | 返回值 | 说明 |
|---|---|---|
| reader.getFileVersion() | V_0_12 | 文件格式版本 |
| reader.getNumberOfRows() | 8 | 总行数 |
| reader.getStripes().size() | 1 | Stripe 数 |
| reader.getCompression() | ZSTD | 压缩方式 |
| reader.getSchema() | structid:int,name:string,score:double | schema |
六、注意事项
- 无独立
schema子命令：orc-tools schema在 2.3.1 报Unknown subcommand: schema，schema 展示并入meta的Type:行。 - hive-storage-api 与 protobuf-java 必须显式声明：前者缺则
NoClassDefFoundError，后者版本须 3.25.x（3.25.8）否则NoSuchMethodError: makeMutableCopy。 - 跑 Java 示例建议限制 JVM 堆：
MAVEN_OPTS=-Xms256m -Xmx512m -Xmn128m，用jps -v/ps -ef复核生效值。 - 管理账号 root，示例密码
q1w2e3r4，仅用于文档示例环境。
七、常见问题（FAQ）
Q1：orc-tools data 与 scan/count 有什么区别？
data 无条件、顺序逐行输出全部 JSON；scan/count 支持按列条件过滤（--column <COL> <expr>），可用于验证谓词下推命中。
Q2：orc-tools json-schema 与 meta 的 Type 有什么区别？
二者都是查看 schema：meta 输出 ORC 原生类型字符串 struct<...>；json-schema 输出 JSON Schema 格式，适合给工具链/校验框架消费。
Q3：用 API 读 BytesColumnVector 时中文/字节错乱？
字符串列存储长度前缀，需要用 vector[start:start+length] 精确截取后按 UTF-8 解码，不要直接 new String(vector[r])（整行 buffer 含填充）。
Q4：Writer 在何种情况下会触发落盘（刷新）？
writer.addRowBatch(batch) 是缓冲到当前 batch；只有 batch 达到内部缓冲限制或调用 writer.close() 才写出 Strip/写 footer。要控制落盘时机用 close()，要持续大批量写入就循环填满 batch 再 addRowBatch。
八、参考链接
- Apache ORC 官网：https://orc.apache.org/
- ORC Java 工具与 API 文档：https://orc.apache.org/docs/
- orc-tools 使用说明：https://orc.apache.org/docs/tools/
- orc-core Maven 坐标：https://repo1.maven.org/maven2/org/apache/orc/orc-core/