跳到主要内容

配置 Databricks 数据源

最近更新 2026/11/03

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 连接信息​

  1. 登录 Databricks 工作区,打开要连接的计算资源。集群可在 Compute > 目标集群 > Configuration > Advanced options > JDBC/ODBC 中查看连接信息;SQL 仓库可在 SQL Warehouses > 目标仓库 > Connection details 中查看。
  2. 获取 JDBC URL,并核对其中的服务主机、端口和 HTTP Path,确保指向预期计算资源。具体入口参见 Databricks JDBC 连接说明。
  3. 准备该工作区可用的 PAT。需要新建时,在 Settings > Developer > Access tokens > Manage 中生成,并设置合适的有效期;无法创建或使用时,请联系工作区管理员。操作说明参见 创建 Databricks 个人访问令牌。

请通过安全方式交接 Token,避免将凭据写入截图、日志或公开文档。更换 Token 或调整权限后,应重新验证数据源连接及同步方案。

创建 Databricks 数据源​

  1. 进入 数据开发平台 > 集成 > 数据源,点击 + 数据源。
  2. 选择 Databricks-JDBC,点击 下一步,填写数据源名称和备注。
  3. 选择 不区分环境 或 独立环境配置。独立环境配置需分别填写开发环境和生产环境的信息。
  4. 填写以下连接参数。在 连通性测试 中点击 测试,确认测试通过后,点击 完成。
配置 Databricks JDBC URL、PAT 认证及高级配置
配置项说明
JDBC URLDatabricks 计算资源对应的 JDBC 连接地址,请向管理员确认服务地址及连接参数
认证机制选择 PAT
Personal Access Token填写接入账号的有效 Token,需具备本次读取或写入所需权限
高级配置按需填写 JSON 格式的扩展配置;没有额外配置要求时可留空

连通性测试通过后,还需在同步方案中加载表、预览来源数据并执行验证,确认实际表权限及读写结果。

配置 Databricks 数据来源​

  1. 进入 数据开发平台 > 集成 > 离线同步,点击 + 集成方案。
  2. 在 数据来源 中选择 Databricks-JDBC 和已创建的数据源。
  3. 选择 取数方式,按整表读取或自定义查询配置来源。
  4. 点击 数据预览,核对来源字段、实际值和读取范围。
  5. 如需调整批次大小,展开 高级配置 进行设置。
已有方案配置中的 Databricks 来源表与批次示例

图为已有方案的配置示例,不能替代当前连接和数据读取验证。完成配置后,请使用数据预览核对实际结果。

取数方式配置方法
整表依次选择 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 作为数据来源时,支持以下字段类型。类型名称不区分大小写,带参数或嵌套结构的字段还需核对完整定义。

类型类别支持的 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> 受支持。
  • 来源或目标表结构变化后,请重新解析字段并检查字段对应关系。数据预览能够显示字段,不等于该字段类型已支持同步。

保存、验证与任务流调度​

保存并验证同步结果​

  1. 核对来源表或查询、过滤范围、目标表及分区、写入模式、前置语句和字段映射。先使用来源 数据预览 检查字段与样例值。
  2. 填写方案名称、负责人和备注,点击 保存。
  3. 点击 手动执行,按弹窗要求选择执行模式,并核对本次参数值后开始执行。手动执行使用生产环境配置;执行模式不用于切换开发环境与生产环境。
  4. 在 手动执行记录 中查看状态和日志。任务成功后,到目标表核对数据量、字段对应关系,以及数值、时间、复杂类型和空值等样例。

独立环境配置下,开发环境能够加载或预览数据,不代表生产环境凭据和读写权限也已具备。首次执行前,请分别核对两套配置及目标环境中的表、分区和参数。向 Databricks 追加写入或配置前置语句时,还需评估重试对已有数据的影响。

挂载到任务流​

手动验证通过后,可将方案挂载到任务流,按调度周期执行。

  1. 打开已保存的方案,点击 挂载到任务流,选择目标任务流;尚未创建时,参见 创建任务流。
  2. 填写节点名、执行模式、负责人等信息,点击 创建节点并挂载。
  3. 点击 前往任务流,检查节点及上下游依赖,核对调度所用的表、分区和空间参数。
  4. 完成 任务流调度设置,保存并 发布任务流。挂载成功不等于节点已经发布上线。

方案挂载到任务流后,不再通过方案详情页手动执行,请从任务流中执行和验证该节点。

常见问题​

现象检查项
连通性测试失败核对 JDBC URL、PAT 是否有效、计算资源访问权限及平台服务器的网络访问范围
连接通过,但找不到表或无法预览核对 Catalog、数据库及表名、元数据与读取权限;自定义查询还需检查 SQL 及其访问范围
预览正常,但执行失败核对生产环境凭据、目标写入权限、表及分区、参数和前置语句,并查看执行日志
重复执行后出现重复数据检查追加写入范围及历史执行结果,确认是否重复读取并写入了同一批数据
这篇文档对你有帮助吗?