Apache CarbonData 2.3.0 配置参数详解

目标：系统梳理 Apache CarbonData 2.3.0 的配置加载机制与核心参数，按存储格式、压缩字典、加载排序、Compaction、并发锁、内存六类给出参数名、默认值与调优建议，并结合实测回显验证配置生效方式。

一、配置加载机制

CarbonData 的配置入口是 carbon.properties 文件，路径由 carbon.properties.filepath 参数控制，默认相对路径为 ../../../conf/carbon.properties。进程启动时 CarbonProperties 会读取该文件并打印当前生效配置，未配置的参数自动回退到代码内默认值，并打印 WARN 级别的回退提示。

实测：运行 CarbonData Demo 时，日志开头打印配置加载过程：

INFO  CarbonProperties:844 - Property file path: /../../../conf/carbon.properties
INFO  CarbonProperties:1064 - ------Using Carbon.properties --------
INFO  CarbonProperties:1065 - {}
INFO  CarbonProperties:831 - Considered file format is: V3
INFO  CarbonProperties:689 - Blocklet Size Configured value is "64"
WARN  CarbonProperties:514 - The enable mv value "null" is invalid. Using the default value "true"
INFO  CarbonProperties:1694 - Considered value for min max byte limit for string is: 200
INFO  CarbonProperties:1719 - Using default value for carbon.detail.batch.size 100

验证结果：未提供 carbon.properties 时配置集合为空，各项参数按代码默认值生效；数据文件格式为 V3，Blocklet 尺寸按建表属性为 64（MB 级页配置），字符串 min-max 索引字节上限 200，明细查询批大小 100。

CarbonData 是列式存储家族成员，与 ORC、Parquet 同属大数据列式格式，其参数体系围绕列式文件、段与索引展开：

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

二、存储与格式参数

实测：CarbonData 加载数据后落盘为列式文件，结构如下：

/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 目录存放 .snappy.carbondata 数据文件（snappy 压缩、列式布局），carbonindexmerge 为合并后的段级索引文件。

三、压缩与字典参数

实测：写入 3 行数据后返回段信息，DataSize 1.70KB、IndexSize 1.06KB，数据与索引均采用 snappy 压缩（文件名 .snappy.carbondata 后缀体现压缩器）。

四、加载与排序参数

实测：Demo 使用 INSERT INTO VALUES 写入 3 行，审计日志显示加载耗时与产物大小：

AUDIT {"opName":"INSERT INTO","opStatus":"SUCCESS","opTime":"2169 ms","table":"default.carbon_table","extraInfo":{"SegmentId":"0","DataSize":"1.70KB","IndexSize":"1.06KB"}}

五、Compaction 参数

实测：对 carbon_table 执行 Minor 合并：

ALTER TABLE carbon_table COMPACT 'MINOR'

审计日志显示合并成功：

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

合并后 SHOW SEGMENTS 仍显示原段 0 成功状态，数据未被重写（小数据量下 Minor 合并仅调整段元数据）。

六、并发与锁参数

实测：表目录下 LockFiles 目录生成 meta.lock、tablestatus.lock、compaction.lock 与 Segment_0.lock 四个锁文件，保证并发写入与合并的互斥。

七、内存与 JVM 参数

7.1 JVM 堆限制与参数位置

CarbonData 运行在 Java 进程中，堆内存通过启动命令的 JVM 参数控制。本机按 256-512MB 堆限制运行：-Xms256m 设定初始堆 256MB，-Xmx512m 限定最大堆 512MB。JVM 参数位置在 java 启动命令中、主类名之前：

java -Djava.io.tmpdir=/opt/carbondata/tmp -Xms256m -Xmx512m \
  -cp "target/classes:$(cat /opt/carbondata/cp.txt)" demo.CarbonDemo

7.2 jps -v 生效验证

后台启动进程，运行期间用 jps -v 核对：

jps -v

实测回显：

1933 CarbonDemo -Djava.io.tmpdir=/opt/carbondata/tmp -Xms256m -Xmx512m

验证结果：jps -v 确认 CarbonDemo 进程携带 -Xms256m -Xmx512m，堆限制 512MB 生效。

7.3 CarbonData 内部内存参数

注意：carbon.unsafe.working.memory.in.mb 默认 512，与 JVM 最大堆 512MB 叠加时会挤压堆内空间，本机小数据量场景无需调大；内存紧张时优先下调该参数而非堆上限。

八、用 CarbonCli 校验表级配置

对已建表执行摘要命令，可回看表的实际属性（对应建表 OPTIONS 与默认值合并结果）：

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

实测回显（节选）：

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

验证结果：表属性中的 local_dictionary_enable 为 true 与默认配置一致，未指定 sort_columns 时排序列为空，说明建表 OPTIONS 未覆盖的参数全部继承全局默认值。

九、参考链接

• Apache CarbonData 官方文档：https://carbondata.apache.org/
• CarbonData 配置参数文档：https://carbondata.apache.org/configuration-parameters.html
• CarbonData 属性配置文件说明：https://carbondata.apache.org/installation-on-pseudo-distributed-hadoop-cluster.html
• CarbonData 数据管理（Compaction）：https://carbondata.apache.org/data-management-on-carbondata.html
• CarbonCli 工具使用说明：https://carbondata.apache.org/carbon-cli-tool-guide.html