tencent cloud

大数据智能体工作台 DataBuddy

文档大数据智能体工作台 DataBuddy数据工程Studio Notebook开发辅助工具（DLCUtils、魔法命令）

辅助工具（DLCUtils、魔法命令）

下载
聚焦模式
字号
最后更新时间： 2026-10-09 16:22:43
DataBuddy 在 Notebook 中提供 DLCUtils 函数库与 魔法命令（Magic Commands） 两类辅助工具，用于参数化、文件交互、密钥管理与多语法切换。本节给出常用模块、典型示例与使用规范。

概述

类型
说明
适用范围
DLCUtils 函数库
与 Notebook 配套的 Python 工具库，简化参数、密钥、任务通信等操作。
所有 Notebook 文件。
魔法命令
Jupyter 提供的特殊指令，用于切换语法、引用其他 Notebook、安装依赖等。
所有 Notebook 文件。

前提条件

Notebook 已连接 Kernel。
您具备当前 Notebook 的「运行」「编辑」或「管理」权限。

DLCUtils 模块速查

常用模块概览

模块
主要函数
用途
dlcutils.widgets
text(name, defaultValue, label)、get(name)、remove(name)、removeAll()、getAll()
定义与获取动态参数。
dlcutils.notebook
exit(value)、run(path, timeout, parameters)
Notebook 间退出参数传递与跨文件执行。
dlcutils.jobs.taskValues
set(key, value)、get(taskKey, key, debugValue)
Workflow 任务间通过 taskValues 传递结果。
dlcutils.secrets
get(secretName, secretVersion, region)
从腾讯云 SSM 凭据管理服务获取加密凭据。

参数化示例

1. 在文件内定义并获取参数

# 定义文本参数
dlcutils.widgets.text(name='your_name', defaultValue='Ricky', label='Your name')

# 获取参数
print(dlcutils.widgets.get('your_name'))
# 输出: Ricky

2. 在 Workflow 任务中获取上层参数（带容错）

# 获取任务参数
try:
    task_value = dlcutils.widgets.get('task_param')
    if not task_value:
        task_value = 'default_value'
except Exception:
    task_value = 'default_value'
print(task_value)

# 获取工作流参数
try:
    workflow_value = dlcutils.widgets.get('workflow_param')
    if not workflow_value:
        workflow_value = 'default_value'
except Exception:
    workflow_value = 'default_value'
print(workflow_value)

Notebook 间参数传递

上游 Notebook 退出并输出参数

# upstream.ipynb
dlcutils.notebook.exit('12345')

下游 Notebook 接收参数

# downstream.ipynb
result = dlcutils.notebook.run('/folder/upstream.ipynb', 60)
print(result)
# 输出: 12345

Workflow 任务间通过 taskValues 传递

# 上游任务 notebook_upstream
dlcutils.jobs.taskValues.set(key='favorite_food', value='apple')
# 下游任务 notebook_downstream（已配置上游为 notebook_upstream）
value = dlcutils.jobs.taskValues.get(
    taskKey='notebook_upstream',
    key='favorite_food',
    debugValue='banana'
)
print(value)
# Studio 调试时输出: banana
# Workflow 调度时输出: apple
说明：
taskValues.get 仅在 Workflow 调度运行场景下能取到上游 set 的值；在 Studio 调试运行时取的是 debugValue。

通过 SSM 获取密钥

避免在代码中明文写入 AK/SK、数据库密码：
1. 前往 腾讯云 SSM 控制台 创建凭据，记录凭据名称、版本与地域。
2. 在 Notebook 中获取：
secret = dlcutils.secrets.get('my_secret', 'v1', 'ap-guangzhou')
print(secret)
3. 使用密钥后续调用 SDK 或访问数据库。

魔法命令清单

单元格语法切换

命令
作用
%sql
将当前单元格切换为 Spark SQL 语法。
%md
将当前单元格切换为 Markdown，仅作展示用。
%scala
将当前单元格切换为 Scala 语法（依赖引擎）。
%sql
SELECT count(*) FROM your_catalog.your_schema.your_table;

跨文件运行

%run /path/to/another_notebook.ipynb
执行另一个 Notebook 的所有单元格，等价于将其内容内联到当前单元格。常用于公共变量与函数定义共享。

依赖安装

%pip install pandas==2.2.0 jieba
在当前 Spark 会话中安装依赖。新建会话或重置环境后失效，需要重新安装。

操作步骤

步骤 1：在 Notebook 中调用 DLCUtils

1. 确认当前 Notebook 已连接 Kernel。
2. 直接在 Python 单元格中调用 dlcutils.widgets.text(...)、dlcutils.notebook.exit(...) 等函数，无需额外 import。

步骤 2：使用魔法命令切换语法

1. 在 Python 单元格的首行输入 %sql / %md / %scala。
2. 之后的代码按对应语法解释执行。

步骤 3：调试参数

1. 单击操作栏 参数 按钮，弹窗显示当前 Notebook 已识别的参数（含通过 dlcutils.widgets.text 定义的与可视化定义的）。
2. 在弹窗中调整参数值用于本次调试运行。

使用限制

dlcutils.notebook.run / dlcutils.jobs.taskValues 在 Studio 调试运行时返回 debugValue；只有在 Workflow 调度运行场景下能取到真实上下游传递值。
%pip install 安装的依赖不持久化；新建会话或重置环境后失效。
Notebook 中获取参数请统一使用 dlcutils.widgets.get；不支持 ${param_key} 占位符语法（该语法仅适用于 SQL）。

常见问题

Q1：调用 dlcutils.widgets.get('xxx') 返回 NameError？ 通常是该参数名称未被定义，可以使用dlcutils.widgets.widgets() 函数进行参数名和参数值的定义，或者在界面上点击参数 按钮，在弹窗中定义参数名称和取值。
Q2：%run 引用的 Notebook 路径怎么写？
使用绝对路径：/workspace_1/your_username/folder/upstream.ipynb。
使用相对路径：folder/upstream.ipynb（相对当前文件）。
在目录中右键 复制路径 直接粘贴。
Q3：SSM 密钥的地域参数如何确定？ SSM 凭据按地域隔离，需要传入凭据创建时所在地域，例如 ap-guangzhou / ap-shanghai。可在 SSM 控制台查看凭据归属地域。

相关文档

Notebook IDE 基础操作
Notebook 运行
参数化实现
腾讯云官方文档：使用 dlcutils 函数库和魔法命令
上一篇: Notebook 运行（内核配置、环境管理、运行结果处理）下一篇: SQL 脚本运行（数据源、资源组配置、运行日志处理、结果查看）

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈

搜索
    请输入关键词搜索文档