Notebook 开发--大数据研发治理套件-火山引擎

文档中心

大数据研发治理套件

在线开发

Notebook 开发

DataLeap New IDE 提供基于 Web 的 Notebook 交互式开发环境，支持在同一文件中混合使用 SQL、Python、Scala、Shell 和 Markdown 多种语言，适用于数据探索、原型验证和交互式 ETL 开发。

创建与配置 Notebook

创建 Notebook

在左侧文件树中右键点击目标目录。
选择新建 > Notebook。
输入文件名（如 data_exploration）。
系统自动创建两个文件：
- data_exploration.ipynb — Notebook 内容文件（包含所有 Cell）。
- .data_exploration.ipynb.metadata.yaml — 仅在用户首次保存执行设置/参数时才创建。

双文件结构

notebooks/
├── data_exploration.ipynb              # Notebook 内容文件
└── .data_exploration.ipynb.metadata.yaml # 元数据配置

内容文件（.ipynb）：存储所有 Cell 的代码与输出，是实际的开发文件
元数据文件（.metadata.yaml）：存储在线调试运行所需的引擎配置和参数值

两者通过命名约定关联：元数据文件名 = 内容文件名 + .metadata.yaml。

说明

元数据文件仅用于在线调试。当 Notebook 被 Pipeline Activity 引用时，引擎和参数配置以 Activity 定义为准，不依赖元数据文件。如使用 Git 管理代码且不需要共享调试配置，可将 .metadata.yaml加入 .gitignore。

元数据配置

Notebook 的元数据配置文件采用标准 YAML 格式，需要同时配置 SQL 引擎和通用计算引擎，分别用于 SQL Cell 和 Python Cell 的执行：

# data_exploration.ipynb.metadata.yaml
apiVersion: newide.studio.dataleap.volc/v1
kind: Script
spec:
  # SQL Cell 使用的引擎配置
  sqlEngineType: emr_serverless_spark
  sqlEngineQueue: default
  sqlComputingResourceGroupName: default_sql_group
  sqlComputingResourceGroupId: 1

  # Python / 通用 Cell 使用的引擎配置
  generalComputingResourceGroupName: default_py_group
  generalComputingResourceGroupId: 2

  # 调试时使用的参数值（仅作缓存，实际参数以代码解析为准）
  parameterValues:
    biz_date: "{{biz_date}}"

字段	类型	必填	说明
`apiVersion`	String	是	固定为 `newide.studio.dataleap.volc/v1`
`kind`	String	是	固定为 `Script`
`spec.sqlEngineType`	String	是	SQL Cell 的计算引擎（如 `emr_serverless_spark`）
`spec.sqlEngineQueue`	String	是	SQL Cell 的计算队列
`spec.sqlComputingResourceGroupName`	String	否	SQL 计算资源组名称
`spec.generalComputingResourceGroupName`	String	是	Python/通用 Cell 的计算资源组
`spec.parameterValues`	Map	否	调试时使用的参数值（键值对）

Kernel 类型

Kernel 决定了 Notebook 中代码 Cell 的执行环境。不同 Kernel 类型适用于不同的计算场景：

Kernel 类型	`kernelType` 值	适用语言	适用场景
PySpark (EMR Serverless)	`emr_serverless_spark_python`	Python、SQL、Scala	大规模分布式数据处理，直接使用 SparkSession。
Python (K8S)	`python_kubernetes`	Python	轻量级数据处理、API 调用、小数据集分析
Ray	`ray`	Python	分布式机器学习、大规模并行计算

Kernel 类型与配置要求

不同 Kernel 类型需要的配置项不同：

配置项	PySpark (`emr_serverless_spark_python`)	Python (`python_kubernetes`)
`engineQueue`	必填	不需要
`computingResourceGroupName`	不需要	必填
`sparkConf`	可选（配置 Spark 参数）	不需要

选择建议

场景	推荐 Kernel	原因
处理 TB 级数据的 ETL 开发	PySpark	Spark 分布式引擎，可弹性扩展。
小数据集的快速分析	Python (K8S)	启动快、资源消耗低。
模型训练与推理	Ray	原生支持分布式机器学习框架。
混合 SQL + Python 的交互探索	PySpark	同时支持 SQL Cell 和 Python Cell。

Cell 类型与支持的语言

Notebook 由多个 Cell 组成，每个 Cell 可以使用不同的语言。通过在 Cell 首行添加语言标记（Magic 标记）切换语言类型：

Cell 类型	语言标记	用途	示例
SQL	`%%sql`	数据查询、建表、ETL 操作	`SELECT * FROM table`
Python	无	数据处理、分析、可视化	`df = spark.sql(...)`
Scala	`%%scala`	高性能 Spark 算子开发	`val df = spark.read...`
Shell	`%%bash`	系统命令、文件操作	`ls -la /data/`
Markdown	无	文档说明、注释、标题	`# 分析报告`

多语言混合开发

Notebook 的核心优势是在同一文件中混合使用多种语言。不同语言的 Cell 通过 Spark 临时视图实现数据共享：

%sql
-- Cell 1: SQL 查询并注册为临时视图
CREATE OR REPLACE TEMP VIEW orders_summary AS
SELECT
    region,
    COUNT(*) AS order_count,
    SUM(total_amount) AS total_revenue
FROM dwd.orders
WHERE dt = '${date}'
GROUP BY region

# Cell 2: Python 读取 SQL 查询结果
df = spark.sql("SELECT * FROM orders_summary").toPandas()
df['revenue_pct'] = df['total_revenue'] / df['total_revenue'].sum() * 100
print(df.to_string(index=False))

%python
# Cell 3: 数据可视化
import matplotlib.pyplot as plt
plt.figure(figsize=(10, 6))
plt.bar(df['region'], df['total_revenue'])
plt.title('Revenue by Region')
plt.tight_layout()
plt.show()

跨语言变量共享规则

场景	共享方式
同语言跨 Cell	直接共享执行上下文，变量自动可见。
SQL → Python	SQL 创建临时视图，Python 通过 `spark.sql()` 读取。
Python → SQL	Python 将 DataFrame 注册为临时视图，SQL 直接查询。
Scala → SQL	Scala 将 DataFrame 注册为临时视图，SQL 直接查询。

Python → SQL 示例：

%python
# 在 Python Cell 中创建数据并注册为临时视图
df = spark.createDataFrame([(1, "Alice"), (2, "Bob")], ["id", "name"])
df.createOrReplaceTempView("my_table")

%sql
-- 在 SQL Cell 中直接查询 Python 注册的视图
SELECT * FROM my_table

说明

跨语言数据共享依赖 Spark 临时视图机制，因此仅在 PySpark Kernel（emr_serverless_spark_python）下可用。Python (K8S) Kernel 不支持 SQL Cell。

运行与调试

执行方式

操作	快捷键	说明
执行当前 Cell	`Shift + Enter`	执行当前 Cell 并自动跳转到下一个 Cell。
执行不跳转	`Ctrl + Enter`	执行当前 Cell 但保持光标位置不变。
全部执行	工具栏「Run All」	从上到下依次执行所有 Cell。

执行结果

Cell 类型	结果展示
SQL `SELECT`	表格形式展示查询结果（默认最多 1000 行）。
SQL DDL/DML	显示执行状态与耗时。
Python	显示 `print()` 输出和最后一个表达式的值。
可视化	内嵌图表直接渲染在 Cell 下方。

会话管理

Notebook 的执行依赖计算会话（Session）。会话管理规则如下：

操作	说明
创建会话	首次执行任意 Cell 时自动创建。
超时释放	默认 60 分钟无操作自动释放资源。
手动断开	点击工具栏「断开会话」立即释放。
重新连接	再次执行 Cell 将创建新会话，所有变量和上下文将被清空。

说明

开发完成后主动断开会话，避免空闲计算资源产生不必要的费用。

调试技巧

技巧	说明
分步执行	逐个 Cell 执行，观察中间结果是否符合预期。
小数据集	开发阶段使用 `.limit(100)` 或 `WHERE` 条件限制数据量。
Markdown 注释	使用 `%md` Cell 记录分析思路和结论。
自顶向下	确保从上到下顺序执行时结果一致，避免依赖随机执行顺序。
控制规模	单个 Notebook 建议不超过 20~30 个 Cell。

Magic 命令（%run）

Notebook 支持使用 %run Magic 命令调用其他 Notebook，实现代码复用和模块化组织。

基本语法

%run /Workspace/Users/zhang3/notebooks/common_utils.ipynb

%run 命令在当前 Notebook 的执行上下文中顺序执行目标 Notebook 的所有 Cell。执行完成后，目标 Notebook 中定义的变量和函数在当前 Notebook 中可直接使用。

典型使用场景

公共函数库： 将常用的数据处理函数封装在一个 Notebook 中，其他 Notebook 通过 %run 引用：

%python
# common_utils.ipynb — 公共函数库

def clean_string(s):
    """去除前后空格并转小写"""
    return s.strip().lower() if s else None

def format_date(dt, fmt="%Y-%m-%d"):
    """格式化日期"""
    return dt.strftime(fmt) if dt else None

%python
# analysis.ipynb — 业务分析 Notebook

# 引用公共函数库
%run /Workspace/Users/zhang3/notebooks/common_utils.ipynb

# 直接使用 common_utils 中定义的函数
result = clean_string("  Hello World  ")
print(result)  # 输出: hello world

环境初始化： 将连接配置、Spark 参数等初始化逻辑集中管理：

%python
# init_env.ipynb — 环境初始化

spark.conf.set("spark.sql.shuffle.partitions", "200")
spark.conf.set("spark.sql.adaptive.enabled", "true")
DATABASE = "dwd_production"

%python
# 业务 Notebook 首行引用初始化
%run /Workspace/Users/zhang3/notebooks/init_env.ipynb

# 使用初始化后的变量
df = spark.sql(f"SELECT * FROM {DATABASE}.orders LIMIT 10")

使用约束

约束	说明
执行方式	同步顺序执行，`%run` 所在 Cell 会等待目标 Notebook 全部执行完成。
路径格式	必须使用工作空间绝对路径（`/Workspace/...`）。
上下文共享	目标 Notebook 与当前 Notebook 共享同一执行上下文。
嵌套调用	支持嵌套 `%run`，但应避免循环引用。

参数引用

Notebook 中的参数引用方式与其他脚本类型一致，在代码中通过 {{参数名}} 按名称引用，运行时系统按 Activity → Pipeline → Project 的优先级逐层查找参数值：

%sql
SELECT *
FROM {{source_database}}.orders
WHERE dt = '${date}'
  AND region = '{{target_region}}'

import ipywidgets as widgets
from IPython.display import display

# 创建组件
sliderv2=5
slider = widgets.FloatSlider(description='数值:', min=0, max=10, value=5)
button = widgets.Button(description='提交')
output = widgets.Output()

def on_button_clicked(b):
    with output:
        # 直接获取 slider 的当前值作为参数
        current_val = slider.value
        print(f"接收到的参数是: {current_val}")
        process_data(current_val)

def process_data(val):
    print(f"正在处理数据: {val * 2}")

button.on_click(on_button_clicked)

display(slider, button, output)

系统变量 ${date}、${hour} 可在 SQL Cell 和 Python Cell 中直接使用。
更多参数变量引用说明详见：参数配置规则。

Pipeline 中引用 Notebook

当 Notebook 被 Pipeline Activity 引用时，通过 Activity 配置指定 Kernel、引擎和参数值：

activities:
  - name: data_analysis
    type: notebook
    source: WORKSPACE
    path: /Workspace/Users/zhang3/notebooks/analysis.ipynb
    kernelType: emr_serverless_spark_python
    engineQueue: default
    sqlEngineType: emr_serverless_spark
    sqlEngineQueue: default
    sqlComputingResourceGroupName: default_sql_group
    generalComputingResourceGroupName: default_py_group
    parameterValues:
      biz_date: "{{run_date}}"
      target_region: "cn-beijing"

字段	类型	必填	说明
`type`	String	是	固定为 `notebook`
`path`	String	是	Notebook 文件路径
`kernelType`	String (Enum)	是	Kernel 类型
`engineQueue`	String	条件必填	`kernelType = emr_serverless_spark_python` 时必填
`computingResourceGroupName`	String	条件必填	`kernelType = python_kubernetes` 时必填
`parameterValues`	Map	否	向 Notebook 传递的参数值
`sparkConf`	List	条件必填	Spark 配置参数，`kernelType = emr_serverless_spark_python` 时可用
`resources`	List	否	额外资源文件列表

说明

path 字段支持引用项目参数（如 {{project.parameters.code_owner}}），但不支持引用 Pipeline 参数或变量。

Widget 是 Notebook 提供的交互式参数输入机制，允许用户在 Notebook 界面中通过可视化控件（文本框、下拉列表等）动态设定参数值，无需修改代码即可调整运行参数。
Widget 的主要用途：

在交互式开发中快速切换不同的参数值进行数据探索
为非技术用户提供可视化的参数输入界面
与 %run 命令配合，实现向子 Notebook 传递参数

使用示例：

%python
# 创建 Widget
dbutils.widgets.text("biz_date", "20240101", "业务日期")
dbutils.widgets.dropdown("region", "cn-beijing", ["cn-beijing", "cn-shanghai", "cn-guangzhou"], "目标区域")

# 获取 Widget 的值
biz_date = dbutils.widgets.get("biz_date")
region = dbutils.widgets.get("region")

print(f"Processing: date={biz_date}, region={region}")

Notebook 开发最佳实践

实践	说明
结构化组织	使用 `%md` Cell 添加标题与说明，形成可读的分析文档。
自顶向下	确保从上到下顺序执行时结果一致，避免依赖随机执行顺序。
职责分离	探索性分析用 Notebook；生产逻辑抽取为独立 SQL / Python 脚本。
控制规模	单个 Notebook 建议不超过 20~30 个 Cell。
及时清理	删除调试用的临时 Cell，保持 Notebook 整洁。
代码复用	将公共函数抽取到独立 Notebook，通过 `%run` 引用。
会话管理	开发完成后主动断开会话，释放计算资源。

最近更新时间：2026.06.12 11:44:15

这个页面对您有帮助吗？

有用

无用

大数据研发治理套件

创建与配置 Notebook #

创建 Notebook #

双文件结构 #

元数据配置 #

Kernel 类型 #

Kernel 类型与配置要求 #

选择建议 #

Cell 类型与支持的语言 #

多语言混合开发 #

跨语言变量共享规则 #

运行与调试 #

执行方式 #

执行结果 #

会话管理 #

调试技巧 #

Magic 命令（%run） #

基本语法 #

典型使用场景 #

使用约束 #

Notebook 参数与 Widget #

参数引用 #

Pipeline 中引用 Notebook #

Widget #

Notebook 开发最佳实践 #