Notebook 基础开发

开始前，请确保您已满足以下条件：

• 当前工作空间已开通并使用新版数据开发（Data Studio）。

• 已创建Serverless 资源组。Notebook在生产环境运行需要依赖Serverless资源组。

• 已创建个人开发环境实例。如果您使用包含Python单元格的Notebook，在开发环境调试运行时需要依赖个人开发环境实例。

  如果您尚未创建，请参见创建个人开发环境实例。

操作步骤：

1. 创建 Notebook 节点

   1. 进入 Data Studio，在数据开发的项目目录下，新建 Notebook 节点。

   2. 为 Notebook 命名（例如 hello_notebook）并提交。

2. 选择个人开发环境

   在顶部导航处单击个人开发环境，从下拉列表中选择您已创建的个人开发环境实例。

3. 编写 Python 单元格以定义参数

   添加一个Python单元格，并输入以下代码。此步骤定义一个城市变量，用于后续的 SQL 查询。

   # 定义一个变量，用于后续SQL查询
   city = 'Beijing'
   print(f"已定义城市变量 city = {city}")

4. 编写 SQL 单元格以查询数据

   1. 在第一个单元格下方，新增一个 SQL 单元格。

   2. 在单元格右下角，将 SQL 类型切换为 MaxCompute SQL。

   3. 输入以下 SQL 代码。代码通过 ${city} 语法引用了上一步 Python 单元格中定义的 city 变量。

      -- 使用Python中定义的变量进行查询  
      SELECT '${city}' AS city;

5. 运行并查看结果

   1. 单击 Notebook 上方工具栏的全部运行按钮。

   2. 观察每个单元格的运行情况：

      • Python 单元格下方会输出 已定义城市变量 city = Beijing。

      • SQL 单元格下方会显示查询结果的表格。

至此，您已成功创建并运行一个包含 Python 和 SQL 交互的 Notebook。

Notebook 模式

DataWorks Notebook 支持两种使用模式：

• 纯SQL和Markdown模式：仅包含 SQL 和 Markdown 单元格，适用于纯数据查询和文档编写场景。此模式下，无论是开发环境还是生产环境，都仅需 Serverless 资源组即可运行，不依赖个人开发环境实例。默认情况下为此模式，Notebook右上角显示为SQL内核。

• 完整模式（Python + SQL + Markdown）：支持 Python、SQL 和 Markdown 单元格的混合使用，适用于需要数据处理、分析和可视化的复杂场景。在开发环境调试运行时，需要依赖个人开发环境实例来执行 Python 代码。请您选择个人开发环境后，Notebook右上角将显示为（Python版本仅供参考）。

开发环境 vs. 生产环境

计算资源与内核

在 DataWorks Notebook 中，代码的执行由计算资源和内核两个核心概念共同决定。

• 计算资源：计算资源是负责最终执行和处理数据任务的后端计算引擎。它定义了任务运行的环境、计算能力和所遵循的执行逻辑。

  • 定义：一个独立的、可被调度的计算服务实例。例如：MaxCompute 项目、EMR Serverless Spark 集群等。

  • 作用：为 SQL 查询、Spark 作业等提供实际的算力。

  • 选择：您需要在执行任务时，明确将其绑定到一个具体的计算资源上。

• 内核：内核是 Notebook 环境中负责解析并执行用户在代码单元格内所编写代码的组件。它决定了该单元格接受的编程语言。

  • Python 内核：

    • 功能：执行 Python 语言编写的代码，支持数据处理、算法实现、任务调度等复杂逻辑。

    • 交互模式：在 Python 内核中，可以通过 Magic Command (如 %sql) 或 SDK 库，将封装好的计算任务（如一段 SQL 语句）提交给指定的计算资源执行，并能获取其返回结果用于进一步分析。

  • SQL 内核：

    • 功能：直接解释和提交 SQL 语言编写的查询。

    • 交互模式：使用 SQL 内核时，它将 SQL 语句直接转发给用户为该单元格指定的后端计算资源（例如 EMR Spark SQL 或 MaxCompute SQL Session）来执行。

  • Markdown 内核：

    • 功能：用于渲染 Markdown 格式的富文本文档，不执行任何计算逻辑。

关系总结：

• 内核是前端的语言解释器，决定“写什么”（Python 或 SQL）。

• 计算资源是后端的执行引擎，决定代码“在哪里运行”（在 MaxCompute 还是 Spark 上）。

目录类型与适用场景

您创建 Notebook 的位置决定其协作模式、权限和发布流程。

单元格管理

• 添加单元格：将鼠标悬停在现有单元格的上方或下方边缘，单击出现的+ SQL等按钮。也可以使用顶部工具栏的按钮。

• 切换单元格类型：单击单元格右下角的类型标识（如 Python），在弹出的菜单中选择新的类型，如 SQL、Markdown。切换类型时，单元格内的代码内容会保留，您需要手动修改以适应新类型。

• 移动单元格：将鼠标悬停在单元格左侧的蓝色竖线上，按住并拖动即可调整顺序。

• 运行单元格：

  • 运行单个：单击单元格左侧的运行按钮。

  • 运行全部：单击 Notebook 顶部工具栏的全部运行按钮。

参数传递

查看血缘（Beta）

当 Notebook 代码变得复杂，涉及多个数据表或文件的读写时，理解数据流向会变得困难。血缘分析功能通过静态解析Notebook 中的 Python（支持MaxFrame框架），快速理清数据的来龙去脉。

Copilot 辅助编程

DataWorks Copilot 是内置的智能编程助手，可以帮助您生成和解释代码。

唤起方式：

• 在选择的单元格左上方单击 Copilot 图标。

• 在SQL单元格内右键，选择 Copilot。

• 使用快捷键 Cmd+I (Mac) 或 Ctrl+I (Windows)。

1、配置调度参数（参数化调度）

如需每次调度运行时，Notebook 中的参数能动态变化（例如，按天处理不同分区的数据），可以设置参数化调度。

1. 标记参数单元格： 在包含核心参数定义的 Python 单元格中，单击右上角的 ... 菜单，选择 Mark Cell as Parameters。该单元格会被添加一个 parameters 标签，表明它是调度任务的参数入口。

   

2. 配置调度参数：

   1. 在 Notebook 右侧面板，单击调度配置。

   2. 在调度参数区域，为您在代码中定义的变量（如 var）赋值。

      

当任务被调度系统自动执行时，代码中 var 参数的实际值，将由在调度参数中配置的值动态替换。

2、配置运行环境与资源

1. 配置镜像：在调度配置中，选择一个包含 Notebook 运行所需全部依赖的镜像。这是确保生产环境成功运行的关键。

   重要

   如果您在个人开发环境实例中通过 pip install 等方式进行了Python包的安装，为确保生产环境具备与开发环境相同的依赖，您需将个人开发环境制作DataWorks镜像，并在调度配置中选用该自定义镜像。

2. 配置资源组：选择用于执行任务的资源组。对于 Serverless 资源组，建议配置不超过 16CU，以避免因资源不足导致任务启动失败。单个任务最大支持 64CU。

3. 配置关联角色：如需进行细粒度的权限管控，可以为节点关联一个特定的 RAM角色，使其以该角色的身份运行。详情请参见配置节点关联角色。

3、发布节点

只有项目目录下的节点才能被发布和周期性调度。

• 对于项目目录下的 Notebook：完成配置后，单击顶部工具栏的发布按钮。

• 对于个人目录下的 Notebook：需先单击保存按钮，将其提交到项目目录，然后再执行发布操作。

发布成功后，您可以在运维中心的周期任务页面监控和管理您的 Notebook 任务。