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

在工作区中计划笔记本¶

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

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

NPOs 的权限和共享¶

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

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

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

• 计算： 仓库和计算池（用于容器运行时）的 USAGE 权限。

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

• External access integrations: USAGE on any EAIs used by the notebook.

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

Using an NPO to schedule a notebook¶

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

For detailed workflows for each scenario, see 按场景调度工作流程.

查看已计划的笔记本运行¶

You can view scheduled tasks in three places:

通过笔记本

To view or interact with scheduled runs, you must use a role with access to the database and schema where the schedule and project object were created.

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

2. 打开计划的笔记本。

3. At the top of the notebook editor, select Scheduled runs . A popover displays the following information:

• All scheduled runs for this notebook.

• 下次计划运行时间。

• 历史运行状态。将鼠标悬停在状态指示器上，可查看详细信息，例如查询 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 工作区中笔记本的可观察性和日志记录. opens the executed notebook with its output.

通过数据库资源管理器

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

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

2. Select the database and schema that contain the Notebook Project Object (NPO).

3. 选择 NPO。

4. Select Run history.

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

Manage scheduled tasks¶

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

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

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

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

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

After editing a notebook, you must deploy your changes before scheduled runs use the updated version. Deployment ensures reproducibility and prevents scheduled tasks from running code that differs from what was last deployed. If this is the notebook's first task and a notebook has changes that require deployment, the Schedule (calendar) icon displays a clock indicator. If a schedule already exists, the icon is a calendar with a clock.

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

• Select Deploy Changes.

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

Find a notebook project object (NPO) in the Object Explorer¶

Each scheduled notebook automatically creates an NPO that stores its deployed code, execution history, and artifacts. You can locate these objects in the Object Explorer in Snowsight.

To locate an NPO in Snowsight, follow these steps:

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

2. Navigate to Database » Schema » Notebook Project Objects to view all NPOs in that schema.

或者，您可以：

1. 打开相关笔记本。

2. At the top of the notebook editor, select Scheduled runs .

3. Select Open run history to open the associated NPO.

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

This section describes how to view execution details and troubleshoot notebook runs after a schedule has been created. If any step fails during execution, Snowflake stops the run to prevent partial or inconsistent downstream results.

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

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

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

3. At the top of the notebook editor, select 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 = 'snow://workspace/<workspace_hash>/path/to/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')

Copy

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

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

Copy

If a task fails because your active role lacks the required privileges, Snowsight displays the relevant error messages so you can address missing permissions.

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