配置 Databricks 数据源
Databricks 数据源用于通过离线同步在 Databricks 与平台预置仓之间传输表数据。本文介绍 Databricks-JDBC 连接配置、来源与去向设置、支持的字段类型,以及同步验证和任务流调度。
使用限制与准备事项
开始配置前,请确认以下事项:
- 支持 Databricks → 预置仓 和 预置仓 → Databricks,不支持在本方案中将 Databricks 与其他外部数据源直接互传。
- 在 Databricks 中准备可用于 JDBC 连接的计算资源,取得对应的 JDBC URL 和 Personal Access Token。连接信息需与实际使用的计算资源、工作区和驱动配置一致,可参见 Databricks JDBC 连接说明。
- Token 所属账号需有权使用相应计算资源、访问 Catalog 和数据库(Schema),并查看表的元数据。读取来源表需有读取权限,写入目标表需有相应写入权限;由 Databricks 管理员按实际使用范围授权。
- 平台运行环境需能访问 JDBC URL 对应的服务。若 Databricks 设置了网络访问限制,请核对平台服务器的实际出口地址与允许访问范围。
- 提前准备目标表,并核对字段类型及分区定义。预置仓目标表的创建方式参见 空间表的创建与管理;Databricks 目标表需在目标 Catalog 和数据库中预先准备。
| 环境配置方式 | 配置要求 |
|---|---|
| 不区分环境 | 开发环境与生产环境共用一套连接及凭据配置 |
| 独立环境配置 | 分别配置开发环境与生产环境;两套配置均需能够访问方案所选的表 |
数据预览使用开发环境配置,手动执行使用生产环境配置。请分别核对两套配置的计算资源、表权限和网络访问。
获取 Databricks 连接信息
- 登录 Databricks 工作区,打开要连接的计算资源。集群可在 Compute > 目标集群 > Configuration > Advanced options > JDBC/ODBC 中查看连接信息;SQL 仓库可在 SQL Warehouses > 目标仓库 > Connection details 中查看。
- 获取 JDBC URL,并核对其中的服务主机、端口和 HTTP Path,确保指向预期计算资源。具体入口参见 Databricks JDBC 连接说明。
- 准备该工作区可用的 PAT。需要新建时,在 Settings > Developer > Access tokens > Manage 中生成,并设置合适的有效期;无法创建或使用时,请联系工作区管理员。操作说明参见 创建 Databricks 个人访问令牌。
请通过安全方式交接 Token,避免将凭据写入截图、日志或公开文档。更换 Token 或调整权限后,应重新验证数据源连接及同步方案。
创建 Databricks 数据源
- 进入 数据开发平台 > 集成 > 数据源,点击 + 数据源。
- 选择 Databricks-JDBC,点击 下一步,填写数据源名称和备注。
- 选择 不区分环境 或 独立环境配置。独立环境配置需分别填写开发环境和生产环境的信息。
- 填写以下连接参数。在 连通性测试 中点击 测试,确认测试通过后,点击 完成。
| 配置项 | 说明 |
|---|---|
| JDBC URL | Databricks 计算资源对应的 JDBC 连接地址,请向管理员确认服务地址及连接参数 |
| 认证机制 | 选择 PAT |
| Personal Access Token | 填写接入账号的有效 Token,需具备本次读取或写入所需权限 |
| 高级配置 | 按需填写 JSON 格式的扩展配置;没有额外配置要求时可留空 |
连通性测试通过后,还需在同步方案中加载表、预览来源数据并执行验证,确认实际表权限及读写结果。
配置 Databricks 数据来源
- 进入 数据开发平台 > 集成 > 离线同步,点击 + 集成方案。
- 在 数据来源 中选择 Databricks-JDBC 和已创建的数据源。
- 选择 取数方式,按整表读取或自定义查询配置来源。
- 点击 数据预览,核对来源字段、实际值和读取范围。
- 如需调整批次大小,展开 高级配置 进行设置。
图为已有方案的配置示例,不能替代当前连接和数据读取验证。完成配置后,请使用数据预览核对实际结果。
| 取数方式 | 配置方法 |
|---|---|
| 整表 | 依次选择 Catalog、数据库(Schema)和数据表;如只读取部分数据,开启 数据过滤 并填写过滤条件 |
| 自定义查询 | 填写返回待同步字段的只读查询 SQL,将筛选条件写在查询中;此方式不单独配置整表的 Catalog、数据库、数据表选择项或数据过滤 |
整表方式的数据过滤用于限定读取范围,请按编辑器中的 WHERE 语句填写,例如 WHERE status = 'active',不填写完整的 SELECT 查询。自定义查询需确保 SQL 能访问正确的 Catalog 和数据库,返回的字段名称明确、类型可识别。
批次大小 的默认值为 1000,可设置范围为 1000–10000。切换数据源、取数方式、Catalog、数据库或数据表后,请重新核对读取范围、预览结果和字段映射。来源结构或查询结果发生变化后,也需重新解析并检查映射。
配置数据去向
Databricks 读取到预置仓
在 数据去向 中选择平台 预置仓,再选择目标空间表。若目标表尚未创建,请先前往 库表 按所需字段和分区定义创建,参见 空间表的创建与管理。
| 配置项 | 说明 |
|---|---|
| 目标表 | 接收本次数据的预置仓空间表 |
| 分区信息 | 目标为分区表时,按目标表要求填写各分区值;可结合 空间参数 配置执行时的分区 |
| 写入模式 | 按目标数据保留要求选择 插入新数据 或 覆盖写入,执行前再次核对目标表和目标分区 |
预置仓写入 Databricks
在 数据来源 中配置预置仓来源表,在 数据去向 中选择 Databricks-JDBC 和已创建的数据源,依次选择目标 Catalog、数据库(Schema)及数据表。
| 配置项 | 说明 |
|---|---|
| 写入表 | 已在 Databricks 中准备、且接入账号有权写入的目标表 |
| 分区信息 | 界面显示目标分区字段时,每个分区值都需填写,并核对执行时的实际值 |
| 写入模式 | 仅支持 插入新数据,向目标表追加数据;重复执行前需评估是否会产生重复记录 |
| 前置语句 | 按需填写在同步开始前执行的目标端 SQL;没有使用需求时可留空 |
| 批次大小 | 位于 高级配置 中,默认值为 5000,可设置范围为 1–10000 |
前置语句会在目标端真实执行,执行失败时不会继续提交本次同步。前置语句与后续数据写入不保证处于同一事务中,后续同步失败也不保证自动撤销已经执行的前置语句。填写或重试前,请核对目标环境、SQL 的数据影响及重复执行结果。
Databricks 去向的写入模式为追加,不提供原生覆盖或更新插入模式。不要将前置删除语句与追加写入视为具有整体回滚能力的覆盖操作。
字段映射与支持的字段类型
完成来源和去向配置后,在 字段映射 中建立源字段与目标字段的对应关系。可以逐项选择,也可以使用 同名映射 或 同行映射 后逐项核对;一个目标字段只能对应一个来源字段。
图中展示的是已有方案的字段对应关系,不表示已通过实时连通性或本次执行验证。
读取支持的字段类型
Databricks 作为数据来源时,支持以下字段类型。类型名称不区分大小写,带参数或嵌套结构的字段还需核对完整定义。
| 类型类别 | 支持的 Databricks 字段类型 |
|---|---|
| 布尔 | boolean |
| 整数 | tinyint、smallint、int、integer、bigint |
| 浮点与定点数 | float、double、decimal |
| 字符串 | string、varchar、char |
| 日期时间 | date、timestamp、timestamp_ntz |
| 复杂类型 | array、map、struct,需核对完整结构 |
不支持 binary,以及 interval、void、variant 等未列出的类型和其他未识别的类型。
写入支持的字段类型
Databricks 作为数据去向时,支持的 Databricks 字段类型与上表相同;不支持 binary、未列出的类型及其他未识别的类型。
目标表需预先创建。字段类型受支持,不代表任意数据均符合目标字段的完整定义和空值约束。
字段类型使用限制
decimal(p,s)、varchar(n)、char(n)需核对完整精度、小数位数及长度要求。timestamp、timestamp_ntz需核对实际时间含义、时区和精度要求,不能仅凭类型名称判断结果符合预期。array<T>、map<K,V>、struct<...>需核对元素、键值或字段定义,包括字段名称和顺序、空值约束及嵌套层级。顶层类型受支持不表示任意内部结构均受支持,例如不能仅凭array受支持就认定array<binary>受支持。- 来源或目标表结构变化后,请重新解析字段并检查字段对应关系。数据预览能够显示字段,不等于该字段类型已支持同步。
保存、验证与任务流调度
保存并验证同步结果
- 核对来源表或查询、过滤范围、目标表及分区、写入模式、前置语句和字段映射。先使用来源 数据预览 检查字段与样例值。
- 填写方案名称、负责人和备注,点击 保存。
- 点击 手动执行,按弹窗要求选择执行模式,并核对本次参数值后开始执行。手动执行使用生产环境配置;执行模式不用于切换开发环境与生产环境。
- 在 手动执行记录 中查看状态和日志。任务成功后,到目标表核对数据量、字段对应关系,以及数值、时间、复杂类型和空值等样例。
独立环境配置下,开发环境能够加载或预览数据,不代表生产环境凭据和读写权限也已具备。首次执行前,请分别核对两套配置及目标环境中的表、分区和参数。向 Databricks 追加写入或配置前置语句时,还需评估重试对已有数据的影响。
挂载到任务流
手动验证通过后,可将方案挂载到任务流,按调度周期执行。
- 打开已保存的方案,点击 挂载到任务流,选择目标任务流;尚未创建时,参见 创建任务流。
- 填写节点名、执行模式、负责人等信息,点击 创建节点并挂载。
- 点击 前往任务流,检查节点及上下游依赖,核对调度所用的表、分区和空间参数。
- 完成 任务流调度设置,保存并 发布任务流。挂载成功不等于节点已经发布上线。
方案挂载到任务流后,不再通过方案详情页手动执行,请从任务流中执行和验证该节点。
常见问题
| 现象 | 检查项 |
|---|---|
| 连通性测试失败 | 核对 JDBC URL、PAT 是否有效、计算资源访问权限及平台服务器的网络访问范围 |
| 连接通过,但找不到表或无法预览 | 核对 Catalog、数据库及表名、元数据与读取权限;自定义查询还需检查 SQL 及其访问范围 |
| 预览正常,但执行失败 | 核对生产环境凭据、目标写入权限、表及分区、参数和前置语句,并查看执行日志 |
| 重复执行后出现重复数据 | 检查追加写入范围及历史执行结果,确认是否重复读取并写入了同一批数据 |

