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

在工作区中计划笔记本

When deploying notebooks to production, Snowflake provides native functionality to manage deployment, orchestration, and monitoring. You develop and iterate on notebooks interactively in Workspaces within Snowsight. Scheduling a notebook deploys its contents into a production object called a Notebook Project Object (NPO), which encapsulates the workspace contents (for example, .ipynb files, Python scripts, and SQL files). NPOs support versioned deployments and are schema-level objects (for example, db_name.schema_name.npo_name).

After deployment, you can orchestrate notebook execution using Snowflake Tasks (which run notebook code top-down using a consistent runtime and dependency set) or with any third-party orchestration tool. Snowflake captures execution telemetry that you can monitor in Snowsight or query programmatically through an event table. For more information, see Observability and logging for Notebooks in Workspaces.

笔记本项目对象 (NPOs)¶

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

• Placement: NPOs exist within a specific schema inside a database (database_name.schema_name.npo_name).
• 封装： 当您计划笔记本时，NPO 会获取整个工作区目录，以确保所有依赖项在执行期间可用。
• Execution: You execute an NPO by specifying a main .ipynb file (for example, using the MAIN_FILE parameter). The main notebook can call additional notebooks using %run.
• 计划： 您可以创建多个任务对象来执行同一 NPO，允许同一笔记本项目对象有多个计划。

发现 NPOs¶

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

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 权限。
• Tasks: When the NPO is scheduled via a task, the task owner role must be granted the USAGE privilege on all required objects (such as NPOs, warehouses, or databases). The task owner role must also have privileges to execute the USE DATABASE and USE SCHEMA commands if the notebook sets its execution context programmatically.

使用 NPO 计划笔记本¶

Currently there are two supported scenarios for deploying and scheduling notebooks. In both scenarios, notebooks must be packaged in the NPO. Scenario A is scheduling notebooks from a private workspace. Scenario B is integrating GitHub Actions (or another CI/CD system) to automate the creation of NPOs from an internal or temporary stage, manage their lifecycle through versioned updates, and orchestrate their execution using Snowflake Tasks.

For detailed workflows for each scenario, see Scheduling workflows by scenario.

查看已计划的笔记本运行

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

通过笔记本

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

1. In the navigation menu, select Projects » Workspaces.
2. 打开计划的笔记本。
3. At the top of the notebook editor, select Scheduled runs . A popover displays the following information:

• 此笔记本的所有计划运行记录。
• 下次计划运行时间。
• 历史运行状态。将鼠标悬停在状态指示器上，可查看详细信息，例如查询 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 Observability and logging for Notebooks in Workspaces.

通过数据库资源管理器

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

1. In the navigation menu, select Catalog » Database Explorer.
2. 选择包含笔记本项目对象 (NPO) 的数据库和架构。
3. 选择 NPO。
4. Select Run history.
5. Select a run to view the notebook output from that execution, along with logs and metrics (when available). For more information, see Observability and logging for Notebooks in Workspaces.

管理计划任务

From the Scheduled runs popover, you can manage your scheduled tasks by selecting the ellipsis (more actions) next to a scheduled task:

• 立即运行： 触发计划任务的立即执行。
• 暂停计划： 暂时停止计划自动运行。任务保持配置状态，但在恢复之前不会执行。
• Delete: Removes the scheduled task permanently. You can create a new schedule with different settings (such as a different role or database location) after deleting the existing schedule.

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

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

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

• Select Deploy Changes.

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

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

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. In the navigation menu, select 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.

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

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

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

1. In the navigation menu, select Projects » Workspaces.
2. 打开要查看运行历史的笔记本。
3. At the top of the notebook editor, select Scheduled runs .
4. Select View run history from the drop-down menu.

Run History shows the following information for the notebook’s project object:

• 结果： 查看笔记本及过往运行的输出。
• 任务： 查看哪些任务执行了 NPO。
• 源文件： 查看已执行的笔记本文件。
• Logs and metrics: View execution logs and performance metrics (ensure you have enabled logging and event tables). For more information, see Observability and logging for Notebooks in Workspaces.
• 运行详细信息： 开始和结束时间、运行状态和错误详细信息。

Scheduling in Shared workspaces¶

In a shared workspace, runs use the same building blocks as elsewhere in Workspaces: a Notebook Project Object (NPO) for packaged code and Snowflake tasks for scheduled execution.

The NPO and each task are separate objects. Grant explicit privileges so collaborators can work in the workspace, deploy to the NPO, execute or monitor runs, and manage tasks.

Non-interactive execution of an NPO (manual)¶

Non-interactive execution of an NPO (manual) runs the deployed project headlessly (outside the notebook editor) when you issue SQL such as EXECUTE NOTEBOOK PROJECT. Use this path for ad hoc validation and testing after you deploy to the NPO.

• Visibility: Access is tied to the individual user session.
• Requirement: You must have USAGE or OWNERSHIP on the NPO to trigger a non-interactive run (manual).
• Where to view history: In Snowsight, use Database » Schema » the NPO.

Scheduled execution (tasks)¶

To run on a cadence, execute the NPO from a Snowflake task. Create or manage the schedule from Workspaces » Notebooks (calendar icon) or with SQL in a worksheet.

• Visibility: Access follows task object privileges (owner compared with monitor or operate).

• Requirement: The executing role must have USAGE on the NPO and OWNERSHIP on the task to initiate the schedule.

• Run history:

  • With USAGE on the NPO and OWNERSHIP on the task, a user can view full run history, including results.
  • With USAGE on the NPO and MONITOR or OPERATE on the task, a user can see success or failure status but cannot view the result file.

• Result files: Accessing the notebook output file for a task run requires OWNERSHIP on the task.

General workspace permissions¶

• Creating objects: Requires VIEW permission on the workspace (or a higher privilege).
• Deploying changes: With write access to a shared workspace, you can deploy changes. For the schedule to run updated logic, the role must have OWNERSHIP on the task and USAGE on the NPO.

Permission scenarios: non-interactive manual runs and tasks¶

The following table summarizes who can view run history and results for non-interactive (manual) NPO runs versus task runs.

使用 Tasks 计划笔记本¶

1. In the navigation menu, select Projects » Workspaces.
2. 在 SQL 文件/工作表中运行以下命令：

Copy codeExpand code block

-- 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')

Show lessSee more

Scroll to top

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

Copy codeExpand code block

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

Show lessSee more

Scroll to top

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

For syntax, parameters, and examples, see EXECUTE NOTEBOOK PROJECT. For information about passing parameters to scheduled notebooks, see Running notebooks with parameters.