Apache CarbonData 2.3.0 快速入门与集成示例

Apache CarbonData 2.3.0 快速入门与 Spark 集成示例，含依赖引入、SparkSession 扩展配置、建表写入查询、段管理与 Compaction 完整流程，附实测回显与集成链限制说明。

Apache CarbonDataCarbonData2026/10/14

Apache CarbonData 2.3.0 快速入门与集成示例

目标：以最快路径体验 Apache CarbonData 2.3.0，覆盖 Maven 依赖引入、SparkSession 扩展配置、建表、写入、查询、段管理与 Compaction，全部命令附实测回显，并如实说明本环境下的 Spark 集成链限制。

一、CarbonData 是什么

Apache CarbonData 是 Apache 软件基金会的索引列式存储格式，与 Spark SQL 深度集成，一张 CarbonData 表对应一批 .carbondata 列式数据文件、carbonindexmerge 索引文件与段（Segment）元数据。核心特点：

  • 列式布局 + 多重索引：Blocklet/Page 级 min-max 索引、倒排索引、布隆索引，过滤条件可下推到文件与块级
  • 段（Segment）模型：每次写入产生一个段，Compaction 将多个段合并，兼顾写入效率与查询性能
  • 增量更新支持：支持 UPDATE/DELETE（依赖增量文件与合并）
  • 统一 SQL：通过 Spark SQL 扩展接入，语法与 Spark 表一致

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

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

二、环境与依赖引入

本机实测环境：CentOS 8.4（JDK 1.8.0_312）、Spark 3.1.3、CarbonData 2.3.0、Maven 3.5.4，数据目录 /opt/carbondata。

在 pom.xml 中引入三个依赖包，snappy-java 固定为 1.1.2.6：

<dependency>
  <groupId>org.apache.spark</groupId>
  <artifactId>spark-sql_2.12</artifactId>
  <version>3.1.3</version>
</dependency>
<dependency>
  <groupId>org.apache.spark</groupId>
  <artifactId>spark-hive_2.12</artifactId>
  <version>3.1.3</version>
</dependency>
<dependency>
  <groupId>org.apache.carbondata</groupId>
  <artifactId>carbondata-spark_3.1</artifactId>
  <version>2.3.0</version>
  <exclusions>
    <exclusion>
      <groupId>org.apache.spark</groupId>
      <artifactId>*</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>org.xerial.snappy</groupId>
  <artifactId>snappy-java</artifactId>
  <version>1.1.2.6</version>
</dependency>

三、SparkSession 集成配置

创建 SparkSession 时必须声明 CarbonData 扩展，否则 USING carbondata 建表不可用：

SparkSession spark = SparkSession.builder()
        .master("local[2]")
        .appName("CarbonDemo")
        .config("spark.sql.extensions", "org.apache.spark.sql.CarbonExtensions")
        .config("spark.sql.warehouse.dir", "file:///opt/carbondata/warehouse")
        .config("spark.driver.host", "localhost")
        .getOrCreate();

关键配置项：

配置项值作用
spark.sql.extensionsorg.apache.spark.sql.CarbonExtensions注册 CarbonData SQL 扩展（必须）
spark.sql.warehouse.dirfile:///opt/carbondata/warehouse表元数据目录
spark.driver.hostlocalhostlocal 模式下 driver 绑定地址

四、建表

4.1 建表语句

CREATE TABLE IF NOT EXISTS carbon_table (id INT, name STRING, city STRING)
USING carbondata
OPTIONS('PATH'='file:///opt/carbondata/data/carbon_table')

实测回显（审计日志）：

AUDIT {"opName":"CREATE TABLE","opStatus":"SUCCESS","opTime":"343 ms","table":"NA","extraInfo":{}}

建表时可指定排序列、字典等属性，例如 OPTIONS 追加 'sort_columns'='city'。未指定时按全局默认值生效。

4.2 验证建表结果

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/Fact/Part0/Segment_0/part-0-1_batchno0-0-0-1791908380958.snappy.carbondata
/opt/carbondata/data/carbon_table/Fact/Part0/Segment_0/0_1791908380958.carbonindexmerge

五、写入数据

5.1 INSERT INTO VALUES

INSERT INTO carbon_table VALUES
(1,'Jack','Beijing'),(2,'Lucy','Shanghai'),(3,'Tom','Beijing')

实测回显：

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

每次写入产生一个独立段（Segment），段内文件按 batchno 组织。生产环境大批量数据建议使用 LOAD DATA（CSV）或 COPY INTO，两者均以段为单位落盘。

5.2 段文件落盘

ls -l /opt/carbondata/data/carbon_table/Fact/Part0/Segment_0/

实测回显：

part-0-0_batchno0-0-0-1791908380958.snappy.carbondata
part-0-1_batchno0-0-0-1791908380958.snappy.carbondata
0_1791908380958.carbonindexmerge

六、查询

6.1 全表查询

SELECT * FROM carbon_table ORDER BY id

实测回显：

+---+----+--------+
| id|name|    city|
+---+----+--------+
|  1|Jack| Beijing|
|  2|Lucy|Shanghai|
|  3| Tom| Beijing|
+---+----+--------+

6.2 过滤查询（索引下推）

SELECT * FROM carbon_table WHERE city = 'Beijing'

实测回显：

+---+----+-------+
| id|name|   city|
+---+----+-------+
|  3| Tom|Beijing|
|  1|Jack|Beijing|
+---+----+-------+

city 列在写入时已生成 min-max 与局部字典索引，过滤在扫描阶段直接裁剪不匹配的块。

6.3 分组聚合

SELECT city, COUNT(*) AS cnt FROM carbon_table GROUP BY city

实测回显：

+--------+---+
|    city|cnt|
+--------+---+
| Beijing|  2|
|Shanghai|  1|
+--------+---+

七、段管理与 Compaction

7.1 查看段信息

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|
+---+-------+--------------------+---------------+---------+---------+----------+-----------+

7.2 查看列信息

SHOW COLUMNS FROM carbon_table

实测回显：

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

7.3 Minor Compaction

ALTER TABLE carbon_table COMPACT 'MINOR'

实测回显：

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

验证结果：段信息、列信息与 Compaction 均执行成功，数据量小且仅一个段时合并仅更新段元数据，不触发物理重写。

八、集成链限制说明

本环境通过 Maven 引入 Spark 3.1.3 与 carbondata-spark_3.1 以 local 模式运行，Spark 集成链存在以下真实限制，实施前需评估：

  • 未配置 Hive Metastore 时，Spark 使用内存 Catalog，表元数据不跨会话持久化。新建 SparkSession 后 SHOW TABLES 为空，SHOW SEGMENTS 报 Table not found，建表、写入、段管理与查询必须放在同一会话内执行
  • 依赖 carbondata-spark_3.1 与 Spark 3.1.x 绑定，升级 Spark 大版本需更换对应集成包
  • snappy-java 版本必须与 CarbonData 期望版本对齐（1.1.2.6），否则压缩器初始化异常
  • 生产集群部署应接入外部 Metastore 并使用 spark-submit 提交，local 模式仅用于功能验证

九、参考链接