Studio JDBC 任务开发指南

Studio JDBC 任务通过 JDBC 协议连接外部数据库,在外部库里执行 SQL。适合两类场景:

  • 数据同步前探索:在配置同步任务之前,先用 JDBC 任务摸清源库的表结构、数据量、字段分布,判断是否适合同步
  • 数据源问题调查:同步任务报错或数据异常时,直接在源库里执行诊断 SQL,定位空值、异常值、重复数据等问题

核心机制

一个 JDBC 任务文件里可以写多条 SQL,按顺序依次执行,每条 SQL 以

;
;
结尾。执行结果(SELECT 返回的行)在 Studio 任务日志里可见。

数据源配置:JDBC 任务需要预先在 Studio 管理 → 数据源 里配置好外部数据库连接,执行时通过

--datasource
--datasource
指定数据源名称,
--database
--database
指定库名。


场景一:数据同步前探索

在配置批量同步任务之前,先用 JDBC 任务了解源库的基本情况。

SQL 脚本

-- 查看目标表的字段结构 SELECT column_name, column_type, is_nullable, column_key, column_default FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = 'orders' ORDER BY ordinal_position; -- 查看数据量和时间范围 SELECT COUNT(*) AS total_rows, MIN(order_date) AS earliest_date, MAX(order_date) AS latest_date, COUNT(DISTINCT user_id) AS unique_users FROM orders; -- 查看各状态分布 SELECT status, COUNT(*) AS cnt FROM orders GROUP BY status ORDER BY cnt DESC; -- 抽样查看数据 SELECT * FROM orders ORDER BY order_id DESC LIMIT 10;

创建并执行任务

Studio UI

  1. 进入 数据开发 → 新建任务,选择 JDBC 类型,填写任务名称
  2. 数据源 下拉框选择已配置的外部数据库连接,再选择对应的库名
  3. 粘贴上方 SQL 脚本
  4. 点击 运行,在任务日志里查看结果

cz-cli(详见 Studio 任务开发与运维

cz-cli task create explore_orders --type jdbc --profile <your-profile> cz-cli task save-content explore_orders --file explore.sql --profile <your-profile> cz-cli task save-config explore_orders --retry-count 1 --profile <your-profile> cz-cli task online explore_orders -y --profile <your-profile> cz-cli task execute explore_orders \ --datasource <datasource_name> \ --database <database_name> \ --profile <your-profile>


场景二:数据源问题调查

同步任务报错或数据异常时,用 JDBC 任务在源库里直接诊断。以下 SQL 覆盖最常见的几类问题。

测试数据准备

-- 建测试表 CREATE TABLE IF NOT EXISTS doc_orders_raw ( order_id INT PRIMARY KEY, user_id INT, product VARCHAR(50), amount DECIMAL(10,2), status VARCHAR(20), order_date DATE ); -- 插入正常数据 INSERT INTO doc_orders_raw VALUES (1001, 101, 'iPhone', 7999.00, 'paid', '2024-12-01'), (1002, 102, 'MacBook', 14999.00,'paid', '2024-12-01'), (1003, 101, 'AirPods', 1799.00, 'pending', '2024-12-01'), (1004, 103, 'iPad', 8999.00, 'paid', '2024-12-01'), (1005, 102, 'Watch', 3299.00, 'cancelled', '2024-12-01'); -- 插入有问题的数据(模拟真实场景) INSERT INTO doc_orders_raw VALUES (2001, NULL, 'iPhone', 7999.00, 'paid', '2024-12-03'), -- user_id 为 null (2002, 106, NULL, 5999.00, 'paid', '2024-12-03'), -- product 为 null (2003, 107, 'MacBook', -100.00, 'paid', '2024-12-03'), -- 负数金额 (2004, 108, 'iPad', 8999.00, 'unknown', '2024-12-03'), -- 非法状态值 (2005, 109, 'Watch', 3299.00, 'paid', '2024-12-03'), -- 重复行 (2006, 109, 'Watch', 3299.00, 'paid', '2024-12-03'); -- 重复行

诊断 SQL 脚本

-- ── 1. 整体数据质量概览 ────────────────────────────────────────────────── SELECT COUNT(*) AS total_rows, COUNT(DISTINCT order_id) AS unique_orders, COUNT(*) - COUNT(DISTINCT order_id) AS duplicate_pks, SUM(CASE WHEN user_id IS NULL OR user_id = 0 THEN 1 END) AS null_user_id, SUM(CASE WHEN product IS NULL OR product = '' THEN 1 END) AS null_product, SUM(CASE WHEN amount <= 0 THEN 1 END) AS invalid_amount, SUM(CASE WHEN status NOT IN ('paid','pending','cancelled') THEN 1 END) AS invalid_status FROM doc_orders_raw; -- ── 2. 列出所有异常记录 ────────────────────────────────────────────────── SELECT order_id, user_id, product, amount, status, order_date, CASE WHEN user_id IS NULL OR user_id = 0 THEN 'null_user_id' WHEN product IS NULL OR product = '' THEN 'null_product' WHEN amount <= 0 THEN 'invalid_amount' WHEN status NOT IN ('paid','pending','cancelled') THEN 'invalid_status' END AS issue_type FROM doc_orders_raw WHERE user_id IS NULL OR user_id = 0 OR product IS NULL OR product = '' OR amount <= 0 OR status NOT IN ('paid','pending','cancelled') ORDER BY order_id; -- ── 3. 重复数据检查(同一用户同一商品同一天) ──────────────────────────── SELECT user_id, product, order_date, COUNT(*) AS cnt FROM doc_orders_raw GROUP BY user_id, product, order_date HAVING COUNT(*) > 1 ORDER BY cnt DESC; -- ── 4. 数据分布检查(用于判断同步范围) ───────────────────────────────── SELECT order_date, COUNT(*) AS total, SUM(CASE WHEN status = 'paid' THEN 1 END) AS paid, SUM(CASE WHEN status = 'pending' THEN 1 END) AS pending, ROUND(SUM(amount), 2) AS total_amount FROM doc_orders_raw GROUP BY order_date ORDER BY order_date;

创建并执行任务

Studio UI

  1. 进入 数据开发 → 新建任务,选择 JDBC 类型
  2. 选择数据源和库名
  3. 粘贴诊断 SQL,点击 运行
  4. 在任务日志里查看每条 SQL 的结果,定位问题

cz-cli

cz-cli task create diagnose_orders --type jdbc --profile <your-profile> cz-cli task save-content diagnose_orders --file diagnose.sql --profile <your-profile> cz-cli task online diagnose_orders -y --profile <your-profile> cz-cli task execute diagnose_orders \ --datasource <datasource_name> \ --database <database_name> \ --profile <your-profile>

执行结果

整体数据质量概览(SQL 1):

total_rows unique_orders duplicate_pks null_user_id null_product invalid_amount invalid_status 11 10 1 1 1 1 1

异常记录明细(SQL 2):

order_id user_id product amount status order_date issue_type 2001 null iPhone 7999.00 paid 2024-12-03 null_user_id 2002 106 null 5999.00 paid 2024-12-03 null_product 2003 107 MacBook -100.00 paid 2024-12-03 invalid_amount 2004 108 iPad 8999.00 unknown 2024-12-03 invalid_status

重复数据(SQL 3):

user_id product order_date cnt 109 Watch 2024-12-03 2

数据分布(SQL 4):

order_date total paid pending total_amount 2024-12-01 5 3 1 36095.00 2024-12-03 6 5 0 30494.00


注意事项

  • JDBC 任务的 SQL 在外部数据库里执行,不经过 Lakehouse 引擎,语法遵循外部数据库的方言
  • 查询结果只显示在任务日志里,不会写入 Lakehouse
  • 不支持在 JDBC 任务里引用 Lakehouse 的表(不支持跨库联邦查询)
  • 诊断完成后,根据发现的问题决定是否需要在源库修复数据,再配置同步任务

相关文档

联系我们
预约咨询
微信咨询
电话咨询