在工作区中运行和计划笔记本

在工作区中计划笔记本

将笔记本部署到生产环境时，Snowflake 提供原生功能来管理部署、编排和监控。您可以在 Snowsight 的工作区中以交互方式对笔记本进行开发和迭代。计划笔记本会将其内容部署到称为笔记本项目对象 (NPO) 的生产对象中，该对象封装了工作区内容（例如，.ipynb 文件、Python 脚本和 SQL 文件）。NPOs 支持版本化部署，并且是架构级对象（例如，db_name.schema_name.npo_name）。

部署完成后，您可以使用 Snowflake Tasks（使用一致的运行时和依赖项集自上而下运行笔记本代码）或任何第三方编排工具来编排笔记本执行。Snowflake 获取执行遥测数据，您可以在 Snowsight 中对其进行监控，或者通过事件表以编程方式进行查询。有关更多信息，请参阅 工作区中笔记本的可观察性和日志记录。

笔记本项目对象 (NPOs)

NPO 是架构级对象，充当管道中的生产就绪“单元”。笔记本项目与工作区或暂存区关联，并且工作区中的所有文件都会被复制。NPOs 以非交互方式执行，可以嵌入到任务中进行调度。

  • 位置： NPOs 存在于数据库内的特定架构中 (database_name.schema_name.npo_name)。

  • 封装： 当您计划笔记本时，NPO 会获取整个工作区目录，以确保所有依赖项在执行期间可用。

  • 执行： 通过指定主 .ipynb 文件（例如，使用 MAIN_FILE 参数）来执行 NPO。主笔记本可以使用 %run 调用其他笔记本。

  • 计划： 您可以创建多个任务对象来执行同一 NPO，允许同一笔记本项目对象有多个计划。

发现 NPOs

NPOs 是标准数据库对象，因此您可以使用元数据命令来审计或清理计划任务

范围

命令

当前上下文

SHOW NOTEBOOK PROJECTS;

数据库级别

SHOW NOTEBOOK PROJECTS IN DATABASE <database_name>;

架构级别

SHOW NOTEBOOK PROJECTS IN SCHEMA <database_name>.<schema_name>;

账户级别

SHOW NOTEBOOK PROJECTS IN ACCOUNT;

NPOs 的权限和共享

要执行或管理 NPO，角色必须具有以下权限：

  • 位置： 包含 NPO 的数据库和架构的 USAGE 或 OWNERSHIP 权限。

  • NPO 访问权限： 特定 NPO 的 USAGE 或 OWNERSHIP 权限。

  • Compute: USAGE and MONITOR on the warehouse, and USAGE on the compute pool (for Container Runtime).

  • 计划： 如果 NPO 由任务触发，则需要账户级全局 EXECUTE TASK 权限。

  • 外部访问集成： 笔记本使用的任何 EAIs 的 USAGE 权限。

  • 任务： 当通过任务对 NPO 进行计划时，必须向任务所有者角色授予所有必需对象（例如 NPOs、仓库或数据库）的 USAGE 权限。如果笔记本以编程方式设置其执行上下文，则任务所有者角色还必须具有执行 USE DATABASE 和 USE SCHEMA 命令的权限。

备注

NPOs 使用调用方权限，其中调用方是用户（而不是角色）。当您在 Snowsight 中直接运行 EXECUTE NOTEBOOK PROJECT 时，执行使用的是调用用户的身份，而非 Snowsight 会话中的活跃角色。笔记本在其专用会话中运行（与 Snowsight 会话分开），用户的默认角色作为主要角色，并激活了所有次要角色。这意味着笔记本可以使用授予用户角色的所有权限执行操作。

使用 NPO 计划笔记本

目前支持两种部署和计划笔记本的场景。在这两种场景中，笔记本都必须打包在 NPO 中。场景 A 从专用工作区计划笔记本。场景 B 集成 GitHub Actions（或其他 CI/CD 系统），以实现从 内部暂存区或临时暂存区 自动创建 NPOs、通过版本化更新管理其生命周期，以及使用 Snowflake Tasks 编排其执行。

场景

工作区类型

计划方法

A：个人开发

专用

支持。在专用工作区中进行开发。创建 笔记本项目对象 (NPO) 和计划任务。

B：生产 (CI/CD)

Git 集成

使用 GitHub Actions（或其他 CI/CD 工具）将笔记本文件从 GitHub 部署到内部暂存区或临时暂存区，并从该暂存区创建/更新 NPO。任务在 NPO 上执行。

有关每个场景的详细工作流程，请参阅 按场景调度工作流程。

查看已计划的笔记本运行

您可以在三个位置查看计划任务：

通过笔记本

要查看计划的运行或与其交互，您必须使用对创建该计划和项目对象的数据库及架构具有访问权限的角色。

  1. 在导航菜单中，选择 Projects » Workspaces。

  2. 打开计划的笔记本。

  3. 在笔记本编辑器的顶部，选择 Scheduled runs Scheduled runs 图标。弹出窗口将显示以下信息：

  • 此笔记本的所有计划运行记录。

  • 下次计划运行时间。

  • 历史运行状态。将鼠标悬停在状态指示器上，可查看详细信息，例如查询 ID、上次运行时间、持续时间及状态。

通过“Actions”菜单

  • Open Run History: Opens the notebook's project object showing all past runs, including status, duration, results, source file, logs, and metrics. Selecting a run's result opens the executed notebook with its output. For more information, see 工作区中笔记本的可观察性和日志记录.

通过数据库资源管理器

要查看任何计划笔记本（包括通过 CI/CD 部署的笔记本）的运行历史记录，请执行以下操作：

  1. 在导航菜单中，选择 Catalog » Database Explorer。

  2. 选择包含笔记本项目对象 (NPO) 的数据库和架构。

  3. 选择 NPO。

  4. 选择 Run history。

  5. 选择一次运行以查看该执行的笔记本输出，以及日志和指标（如果可用）。有关更多信息，请参阅 工作区中笔记本的可观察性和日志记录。

备注

要查看由 Airflow 触发的笔记本运行历史记录，请使用运行 Airflow 的相同用户登录 Snowsight。

管理计划任务

从 Scheduled runs 弹出窗口中，您可以通过选择计划任务旁边的省略号（更多操作）|sf-options-button| 来管理计划任务：

  • 立即运行： 触发计划任务的立即执行。

  • 暂停计划： 暂时停止计划自动运行。任务保持配置状态，但在恢复之前不会执行。

  • 删除： 永久移除计划任务。删除现有计划后，您可以使用不同的设置（例如不同的角色或数据库位置）创建新计划。

将更新部署到计划的笔记本任务

编辑笔记本后，必须先部署更改，计划运行才会使用更新后的版本。部署可确保可重复性，并防止计划任务运行与上次部署版本不同的代码。如果这是笔记本的第一个任务，并且笔记本有需要部署的更改，则计划（日历）图标将显示时钟指示器。如果计划已存在，则图标是带时钟的日历。

修改代码或单元格后，该图标表示存在未部署的更改。

  • 选择 Deploy Changes。

    随后，Snowflake 会更新关联的笔记本项目对象，该笔记本的所有计划任务将在下一次运行中使用新部署的版本。

在对象资源管理器中查找笔记本项目对象 (NPO)

每个计划的笔记本都会自动创建一个 NPO，用于存储其部署的代码、执行历史记录和工件。您可以在 Snowsight 的对象资源管理器中找到这些对象。

要在 Snowsight 中找到 NPO，请按照以下步骤操作：

  1. 在导航菜单中，选择 Catalog » Database Explorer。

  2. 导航至 Database » Schema » Notebook Project Objects，以查看该架构中的所有 NPOs。

或者，您可以：

  1. 打开相关笔记本。

  2. 在笔记本编辑器的顶部，选择 Scheduled runs Scheduled runs 图标。

  3. 选择 Open run history 以打开关联的 NPO。

查看笔记本的运行历史记录

本节介绍如何在创建计划后查看执行详细信息和对笔记本运行进行故障排除。如果在执行过程中任何步骤出现问题，Snowflake 会停止运行，以防下游结果不完整或不一致。

要查看运行历史，请按照以下步骤操作：

  1. 在导航菜单中，选择 Projects » Workspaces。

  2. 打开要查看运行历史的笔记本。

  3. 在笔记本编辑器的顶部，选择 Scheduled runs Scheduled runs 图标。

  4. 从下拉菜单中选择 View run history。

Run History 显示笔记本项目对象的以下信息：

  • 结果： 查看笔记本及过往运行的输出。

  • 任务： 查看哪些任务执行了 NPO。

  • 源文件： 查看已执行的笔记本文件。

  • 日志和指标： 查看执行日志和性能指标（确保您已启用日志记录和事件表）。有关更多信息，请参阅 工作区中笔记本的可观察性和日志记录。

  • 运行详细信息： 开始和结束时间、运行状态和错误详细信息。

使用 Tasks 计划笔记本

  1. 在导航菜单中，选择 Projects » Workspaces。

  2. 在 SQL 文件/工作表中运行以下命令：

-- Execute a notebook project using a task
CREATE OR REPLACE TASK <database_name>.<schema_name>.<name>
  WAREHOUSE = <string>
  SCHEDULE = 'USING CRON 10 13 * * * America/Los_Angeles'
  -- CRON format: <minute> <hour> <day_of_month> <month> <day_of_week> <timezone>
AS
  -- Execute a notebook stored within a notebook project.
  EXECUTE NOTEBOOK PROJECT "<database_name>"."<schema_name>"."<project_name>"
    MAIN_FILE = 'notebook.ipynb'  -- Path to the notebook file
    COMPUTE_POOL = '<compute_pool_name>'
    RUNTIME = '<runtime_version>'  -- e.g. V2.2-CPU-PY3.11
    QUERY_WAREHOUSE = '<wh_name>'
    ARGUMENTS = '<string>'  -- Can pass a single string parsed in the notebook code
    REQUIREMENTS_FILE = '<path/to/requirements.txt>'  -- Pre-installs dependencies before the notebook runs
    EXTERNAL_ACCESS_INTEGRATIONS = ('integration_name');  -- e.g. ('http_eai', 's3_eai')

创建此任务后，运行以下命令来激活计划：

ALTER TASK <database_name>.<schema_name>.<task_name> RESUME;

如果任务因活动角色缺乏所需权限而失败，Snowsight 会显示相关错误消息，以便您解决缺少权限的问题。

有关语法、参数和示例，请参阅 EXECUTE NOTEBOOK PROJECT。有关将参数传递给计划笔记本的信息，请参阅 带参数运行笔记本。

备注

要了解有关 Credit 使用量、空闲超时行为及笔记本服务管理的更多信息，请参阅 设置计算 和 空闲超时。