Spark Catalog 与 OceanBase 集成最佳实践

更新时间：2026-07-28

适用产品：OceanBase 数据库

适用场景：开发

背景与架构概述

Spark Catalog 核心价值

Apache Spark 3.0 引入的 Spark Catalog 作为标准化元数据管理接口，通过统一元数据视图、动态 Schema 发现和标准化 API 三大核心能力，实现了跨异构数据源的元数据一致性管理。相较于传统 Hive Metastore，其显著优势体现在：

核心特性	技术实现说明
统一元数据视图	支持 OceanBase、HDFS、Iceberg 等异构数据源的元数据协同管理
动态 Schema 发现	自动推断外部数据源表结构，无需预定义 Schema
标准化操作接口	通过统一 API 执行 DDL/DML

OceanBase Connector 适配方案

OceanBase Spark Connector 自 V1.1 版本起深度集成 Spark Catalog：

无缝接入：项目完全开源，开源地址GitHub。
零代码接入：零代码，支持全 SQL 交互。
性能增强：自适应分区、并行读写、谓词下推等优化策略。
跨租户访问：通过 Catalog 映射多租户数据源，实现跨业务单元联合查询。
分区表优化：自动识别 OceanBase 数据库分区表，优化分区表读取性能。
自动 Schema 推断：自动发现推断 OceanBase 数据库表结构。

Spark 集群资源配置优化

硬件资源规划策略

以 128 核/1TB 内存服务器为例，建议采用以下资源配置策略：

硬件组件	物理规格	Spark 资源配置策略	计算示例
CPU	128核	Worker 核数 = 物理核数 × 2.5	128×2.5=320 核
内存	1024GB	预留 24GB 系统内存，全量分配给 Spark 使用	1000GB 可用

关键配置参数调整

系统级配置（spark-env.sh）：规划硬件资源。

# 内存资源配置
export SPARK_WORKER_MEMORY=1000G
# CPU 资源配置
export SPARK_WORKER_CORES=320

作业级配置（spark-defaults.conf）：调整 Spark Job 相关参数。

# Driver资源配置
spark.driver.cores=2
spark.driver.memory=4g

# Executor资源配置
spark.executor.memory=16g
spark.executor.cores=4

# 序列化优化
spark.serializer=org.apache.spark.serializer.KryoSerializer

调优目标验证

通过压力测试验证以下指标：

集群资源利用率 ≥95%
线性扩展能力验证（任务并行度与吞吐量呈正相关）
稳定性测试（72 小时持续负载）

OceanBase Catalog 配置实践

基础连接配置

参数名称 参数解释

参数名称	参数解释
`spark.sql.catalog.your_catalog_name.driver`	用于指定 Spark 连接 OceanBase 数据库时使用的 JDBC 驱动类。根据使用的驱动程序，你需要配置不同的驱动程序类名：如果使用 MySQL 驱动程序连接到 OceanBase 数据库，则应配置为 `com.mysql.cj.jdbc.Driver`。如果使用 OceanBase 驱动程序连接到OceanBase，则应配置为 `com.oceanbase.jdbc.Driver`。虽然该参数非必选项，但推荐配置，通过正确配置该参数，可以避免 Spark 找不到对应的驱动程序，从而确保连接过程的顺利进行。

spark.sql.catalog.your_catalog_name.driver

用于指定 Spark 连接 OceanBase 数据库时使用的 JDBC 驱动类。根据使用的驱动程序，你需要配置不同的驱动程序类名：

如果使用 MySQL 驱动程序连接到 OceanBase 数据库，则应配置为 com.mysql.cj.jdbc.Driver。

如果使用 OceanBase 驱动程序连接到OceanBase，则应配置为 com.oceanbase.jdbc.Driver。

虽然该参数非必选项，但推荐配置，通过正确配置该参数，可以避免 Spark 找不到对应的驱动程序，从而确保连接过程的顺利进行。

读操作优化

根据您实际的硬件规格与资源条件，通过调整以下参数，提升 Spark 从 OceanBase 数据库的读取性能：

参数名称	默认值	参数解释	调优建议
`spark.sql.catalog.your_catalog_name.fetch-size`	100	设置 JDBC 驱动每次从 OceanBase 数据库获取的行数。	可以适当调大此值，减少网络交互次数，提高 Spark 每个 Task 读取 OceanBase 的性能。
`spark.sql.catalog.your_catalog_name.max_records_per_partition`		控制 Spark 读取 OceanBase 数据库时，最多多少条数据作为一个分区。默认为空，此时 Spark 根据数据量自动推算出该值。	一般不建议手动设置此值。
`spark.sql.catalog.your_catalog_name.parallel_hint_degree`	1	Spark 读取 OceanBase 数据库时，Spark 下发到 OceanBase 数据库的 SQL 会自动带上 PARALLEL Hint。通过该参数可以设置 /+ PARALLEL(n) / Hint 中的 n。	根据 OceanBase 数据库计算资源调为 `4-8`，提升并行度。

写操作优化

通过调整以下参数，提升 Spark 从 OceanBase 数据库的写入性能：

JDBC 写入优化

参数名称	参数说明	调优建议
`spark.sql.catalog.your_catalog_name.batch-size`	该参数控制 Spark 每个 Task 每积累 batch-size 条数据，进行一次写入。	调大该值可提高写入效率。

旁路导入优化

参数名称参数说明调优建议

spark.sql.catalog.your_catalog_name.direct-load.batch-size 该参数控制 Spark 每个 Task 每积累 batch-size 条数据，进行一次写入。适当调大该参数，可以提高写入性能。

spark.sql.catalog.your_catalog_name.direct-load.parallel 旁路导入服务端的并发度。该参数决定了服务端使用多少 cpu 资源来处理本次导入任务。默认为 8。对于大数据量的旁路导入写入，通过适当调大该值，可以大幅缩减旁路导入 commit 阶段的耗时，从而提高整体性能。

参数名称	参数说明	调优建议
`spark.sql.catalog.your_catalog_name.direct-load.batch-size`	该参数控制 Spark 每个 Task 每积累 batch-size 条数据，进行一次写入。	适当调大该参数，可以提高写入性能。
`spark.sql.catalog.your_catalog_name.direct-load.parallel`	旁路导入服务端的并发度。该参数决定了服务端使用多少 cpu 资源来处理本次导入任务。默认为 8。	对于大数据量的旁路导入写入，通过适当调大该值，可以大幅缩减旁路导入 commit 阶段的耗时，从而提高整体性能。
`spark.sql.catalog.your_catalog_name.direct-load.load-method`	旁路导入导入模式: `full`、`inc`、`inc_replace`。 `full`：全量旁路导入，默认值。 `inc`：普通增量旁路导入，会进行主键冲突检查，observer-4.3.2 及以上版本支持，暂时不支持 `direct-load.dup-action` 为 `REPLACE` 。 `inc_replace`: 特殊 replace 模式的增量旁路导入，不会进行主键冲突检查，直接覆盖旧数据（相当于replace的效果），`direct-load.dup-action` 参数会被忽略，observer-4.3.2 及以上支持。	full模式：只适合用于空表（或者含有少量数据的表）。导入的数据直接写到 major sstable 中。对于列存表，写完就是列存格式，查询性能好。 inc_replace、inc 模式：增量旁路导入。适合空表和非空表。数据写到转储里面，转储目前不支持列存。所以对于列存表来说，导入以后查询性能是行存的性能，需要合并一次才能达到列存的查询性能。 inc_replace 和 inc 的区别，inc_replace不检测主键冲突，直接覆盖原有的主键。

spark.sql.catalog.your_catalog_name.direct-load.load-method

旁路导入导入模式: full、inc、inc_replace。

full：全量旁路导入，默认值。

inc：普通增量旁路导入，会进行主键冲突检查，observer-4.3.2 及以上版本支持，暂时不支持 direct-load.dup-action 为 REPLACE 。

inc_replace: 特殊 replace 模式的增量旁路导入，不会进行主键冲突检查，直接覆盖旧数据（相当于replace的效果），direct-load.dup-action 参数会被忽略，observer-4.3.2 及以上支持。

full模式：只适合用于空表（或者含有少量数据的表）。导入的数据直接写到 major sstable 中。对于列存表，写完就是列存格式，查询性能好。

inc_replace、inc 模式：增量旁路导入。适合空表和非空表。数据写到转储里面，转储目前不支持列存。所以对于列存表来说，导入以后查询性能是行存的性能，需要合并一次才能达到列存的查询性能。

inc_replace 和 inc 的区别，inc_replace不检测主键冲突，直接覆盖原有的主键。

表管理规范

非分区表

限制：
1. 不支持创建索引。
2. 不能设置列默认值。

分区表

兼容性限制：

Spark 仅支持 BUCKET 分区，对应 OceanBase 数据库的 KEY 分区。例如：

CREATE TABLE test.test1 (
  user_id BIGINT COMMENT 'test_for_key',
  name VARCHAR(255)
)
PARTITIONED BY (bucket(16, user_id))
COMMENT 'test_for_table_create'
TBLPROPERTIES('replica_num' = 2, COMPRESSION = 'zstd_1.0');

不支持多级分区，仅允许一级分区。

推荐实践：

复杂分区表应在 OceanBase 数据库侧直接创建，Spark Catalog 可自动识别现有表结构。

生产环境建议

参数调优

根据业务负载动态调整 Spark 资源配置和 OceanBase 数据连接参数，关注线程并发、批量大小等关键指标。
管理分区

为提升查询效率，考虑根据业务需求对表进行合理的分区。
管理权限

确保在 OceanBase 数据库和 Spark 中妥善管理用户权限，防止未经授权的数据访问。
管理版本

定期检查更新版本，建议升级到最新版 spark-connector-oceanbase，集成性能优化和新功能。