Apache CarbonData 2.3.0 常用 CLI 命令与工具详解

Apache CarbonData 2.3.0 常用 CLI 命令与工具详解，覆盖 CarbonCli 独立工具的 summary、benchmark 用法与 Spark SQL 管理命令 SHOW SEGMENTS、SHOW COLUMNS、COMPACT，附完整实测回显与数据目录结构。

Apache CarbonDataCarbonData2026/10/14

Apache CarbonData 2.3.0 常用 CLI 命令与工具详解

目标：梳理 Apache CarbonData 2.3.0 的两类命令行入口——独立 CarbonCli 诊断工具与 Spark SQL 管理命令，逐一给出用法与实测回显，并说明数据目录结构与使用限制。

一、工具概览

CarbonData 2.3.0 提供两类命令行能力：

  • CarbonCli 独立工具：org.apache.carbondata.tool.CarbonCli，随 carbondata-cli-2.3.0.jar 发布，离线分析数据文件，无需启动 Spark
  • Spark SQL 管理命令：SHOW SEGMENTS、SHOW COLUMNS、ALTER TABLE COMPACT、SHOW TABLES 等，需在启用了 CarbonExtensions 的 SparkSession 内执行

CarbonData 是列式存储家族成员，与 ORC、Parquet 同属大数据列式格式：

💡 技术拓展：列式存储按列组织数据，同一列的相邻值连续存放，配合压缩与索引可大幅减少扫描量；行式存储（如 MySQL、PostgreSQL 的普通表）整行连续存放，适合点查与小事务。与 ORC、Parquet 相比，CarbonData 内置多维索引（Blocklet/Page 级 min-max、倒排索引、布隆索引）与 Segment 化增量写入、Compaction 合并机制，过滤下推更快，增量写入与更新场景更友好。

二、环境准备

本机实测环境：CentOS 8.4（JDK 1.8.0_312）、CarbonData 2.3.0、Spark 3.1.3。通过 Maven 生成全部依赖 Classpath：

cd /opt/carbondata/demo
mvn -s maven-settings.xml dependency:build-classpath -Dmdep.outputFile=/opt/carbondata/cp.txt

Classpath 内容包含 carbondata-cli-2.3.0.jar 与 carbondata-core-2.3.0.jar 等，供 CarbonCli 直接调用：

grep -o "carbondata-cli[^:]*" /opt/carbondata/cp.txt

实测回显：

carbondata-cli/2.3.0/carbondata-cli-2.3.0.jar

三、CarbonCli 独立工具

3.1 查看用法

java -cp "$(cat /opt/carbondata/cp.txt)" org.apache.carbondata.tool.CarbonCli -cmd summary -p /opt/carbondata/data/carbon_table

如命令拼写不受支持，会打印完整用法（节选）：

usage: CarbonCli
 -a,--all                         print all information
 -b,--limitSize <limitSize>       print blocklet size detail
 -B,--blockDetail <blockDetail>   print block details
 -c,--column <column name>        column to print statistics
 -C,--columns                     print statistics for all columns
 -cmd <command name>              command to execute, supported commands
                                  are: summary, benchmark
 -f,--file <file>                 the carbondata file path
 -h,--help                        print this message

3.2 summary 摘要

java -cp "$(cat /opt/carbondata/cp.txt)" org.apache.carbondata.tool.CarbonCli \
  -cmd summary -p /opt/carbondata/data/carbon_table

实测回显：

Input Folder: /opt/carbondata/data/carbon_table
## Summary
total: 2 blocks, 2 shards, 2 blocklets, 2 pages, 3 rows, 1.70KB
avg: 869.0B/block, 869.0B/blocklet, 1 rows/block, 1 rows/blocklet

解读：全表共 2 个块、2 个分片（Shard，对应 2 个数据文件）、2 个 Blocklet、3 行数据，数据总大小 1.70KB。

3.3 summary -a 全量信息

java -cp "$(cat /opt/carbondata/cp.txt)" org.apache.carbondata.tool.CarbonCli \
  -cmd summary -a -p /opt/carbondata/data/carbon_table

实测回显（节选）：

## Summary
total: 2 blocks, 2 shards, 2 blocklets, 2 pages, 3 rows, 1.70KB

## Schema
schema in part-0-1_batchno0-0-0-1791908380958.snappy.carbondata
version: V3
timestamp: 2026-10-13 16:19:39.366
Column Name  Data Type  Column Type  SortColumn  Encoding  Ordinal  Id
name         STRING     dimension    false       []        1        *0d39
city         STRING     dimension    false       []        2        *701c
id           INT        measure      false       []        0        *053c

## Segment
SegmentID  Status   Load Start               Load End                 Merged To  Format       Data Size  Index Size
0          Success  2026-10-13 16:19:40.958  2026-10-13 16:19:42.234  NA         columnar_v3  1.70KB     1.06KB

## Table Properties
Property Name              Property Value
'sort_columns'             ''
'hasexternalkeyword'       'false'
'local_dictionary_enable'  'true'
'indextableexists'         'false'
'indexexists'              'false'
'_external'                'true'
'comment'                  ''
'bad_record_path'          ''

## Block Detail
Shard #1 (0_batchno0-0-0-1791908380958)
BLK  BLKLT  NumPages  NumRows  Size
0    0      1         1        372.0B

Shard #2 (1_batchno0-0-0-1791908380958)
BLK  BLKLT  NumPages  NumRows  Size
0    0      1         2        394.0B

解读：Schema 展示每列的列类型（dimension 维度列 / measure 度量列）、排序标记与字典编码；Segment 展示段状态与数据/索引大小；Table Properties 展示建表属性；Block Detail 展示各数据文件的块与页分布。

3.4 benchmark 基准测试

java -cp "$(cat /opt/carbondata/cp.txt)" org.apache.carbondata.tool.CarbonCli \
  -cmd benchmark -p /opt/carbondata/data/carbon_table

实测回显：

Input Folder: /opt/carbondata/data/carbon_table

## Benchmark
ReadHeaderAndFooter takes 1,168 us
ConvertFooter takes 11,607 us
ReadAllMetaAndConvertFooter takes 3,153 us

解读：benchmark 输出读取文件头尾、转换页脚元数据等环节的耗时（微秒），用于评估文件解析开销。

四、Spark SQL 管理命令

管理命令必须在启用了 CarbonExtensions 的 SparkSession 内执行，且建表与查询需在同一会话。以下回显来自完整管理 Demo 的一次运行。

4.1 SHOW TABLES

SHOW TABLES

实测回显：

+--------+---------+-----------+
|database|tableName|isTemporary|
+--------+---------+-----------+
+--------+---------+-----------+

注意：未配置 Hive Metastore 时表元数据仅存于内存 Catalog，同会话内建表后此处即可看到表。

4.2 SHOW SEGMENTS 查看段

SHOW SEGMENTS FOR TABLE carbon_table LIMIT 10

实测回显：

+---+-------+--------------------+---------------+---------+---------+----------+-----------+
| ID| Status|     Load Start Time|Load Time Taken|Partition|Data Size|Index Size|File Format|
+---+-------+--------------------+---------------+---------+---------+----------+-----------+
|  0|Success|2026-10-13 16:23:26.0|         1.781S|       NA|   1.71KB|    1.06KB|columnar_v3|
+---+-------+--------------------+---------------+---------+---------+----------+-----------+

4.3 SHOW COLUMNS 查看列

SHOW COLUMNS FROM carbon_table

实测回显：

+--------+
|col_name|
+--------+
|      id|
|    name|
|    city|
+--------+

4.4 ALTER TABLE COMPACT 合并段

ALTER TABLE carbon_table COMPACT 'MINOR'

实测回显：

AUDIT {"opName":"ALTER TABLE COMPACTION MINOR","opStatus":"SUCCESS","opTime":"41 ms","table":"default.carbon_table","extraInfo":{}}

4.5 清理命令

TRUNCATE TABLE carbon_table;
DROP TABLE carbon_table;

TRUNCATE 清空数据并保留表结构，DROP 删除表与元数据。两者均在 SparkSession 会话内立即生效。

五、数据目录结构

find /opt/carbondata/data/carbon_table -type f

实测回显：

/opt/carbondata/data/carbon_table/Metadata/segments/0_1791908380958.segment
/opt/carbondata/data/carbon_table/Metadata/tablestatus
/opt/carbondata/data/carbon_table/Metadata/schema
/opt/carbondata/data/carbon_table/LockFiles/compaction.lock
/opt/carbondata/data/carbon_table/LockFiles/tablestatus.lock
/opt/carbondata/data/carbon_table/LockFiles/meta.lock
/opt/carbondata/data/carbon_table/LockFiles/Segment_0.lock
/opt/carbondata/data/carbon_table/Fact/Part0/Segment_0/part-0-1_batchno0-0-0-1791908380958.snappy.carbondata
/opt/carbondata/data/carbon_table/Fact/Part0/Segment_0/part-0-0_batchno0-0-0-1791908380958.snappy.carbondata
/opt/carbondata/data/carbon_table/Fact/Part0/Segment_0/0_1791908380958.carbonindexmerge
路径内容
Fact/Part0/Segment_0/段内列式数据文件（.snappy.carbondata）与段级索引（.carbonindexmerge）
Metadata/segments/段元数据文件（.segment）
Metadata/tablestatus表状态文件
Metadata/schema表 Schema 文件
LockFiles/并发控制锁文件

六、使用限制与注意事项

  • Spark SQL 管理命令依赖 CarbonExtensions，脱离 Spark 会话不可用；独立场景使用 CarbonCli
  • 未配置外部 Metastore 时，SHOW SEGMENTS 等命令必须在建表的同一会话内执行，否则报 Table not found
  • CarbonCli 的 -p 参数指向表数据目录（含 Metadata 与 Fact 的父目录），指向单文件需改用 -f 参数
  • 大数据量生产场景应使用 spark-submit 方式提交，本地 local 模式仅用于验证

七、参考链接