@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/Migrate_Spark_DataEngineeringBestPractices_Project_to_Lakehouse.md

@@ -0,0 +1,292 @@
+# 将Spark数据工程最佳实践项目迁移到云器Lakehouse
+
+## 新方案亮点
+
+* **全面云化，聚焦数据**：将线下管理的环境全部迁移到云上，免去资源准备、系统运维等非数据相关的工作。
+* **易于迁移**：云器 Lakehouse SQL、Zettapark 与 Spark SQL、pySpark 分别具有高度兼容性，代码迁移的难度与成本极低。
+* **降低总体成本与复杂度**：云器 Lakehouse 内置工作流服务与数据质量控制服务，无需单独的 Airflow 和 Great Expectations。极大程度简化了系统架构，降低了总体成本与复杂度。
+* **具备开放性**：同时能够在架构中保留 Airflow 和 Greate Expectations，借助 Airflow 调度 Python 任务，并在 Python 代码中持续调用 Great Expectations 开展数据质量检测。
+* **资源管理与任务队列管理**：分别运用不同的 Virtual Cluster 处理 ETL、BI 以及数据质量的作业，达成资源隔离与任务队列管理。
+
+## Spark数据工程最佳实践项目介绍
+
+### Spark数据工程最佳实践项目背景
+
+在缺乏充分指导的情形下构建数据管道，可能会令人感到无所适从，难以判定自身是否遵循了最佳实践。倘若您身为一名数据工程师，期望明晰自身技术技能在构建数据管道方面的发展状况，但对是否遵循了行业标准存疑，也不确定能否与大型科技公司的数据工程师相较，那么 GitHub 上的 [Spark数据工程最佳实践](https://github.com/josephmachado/data_engineering_best_practices/tree/main) 项目便是为您量身定制的。本文将对设计数据管道、洞悉行业标准、考量数据质量以及编写可维护且易于操作的代码的最佳实践予以回顾。完成此项目后，您将洞悉设计数据管道的关键组件及其需求，并且能够迅速熟悉任何新的代码库。
+
+### Spark数据工程最佳实践项目场景
+
+假设我们从上游来源提取客户和订单信息，并创建订单数量的每小时报告。
+
+:-: ![](.topwrite/assets/image_1737530842475.png =405)
+
+使用的组件和环境如下：
+
+* 数据存储：MinIO with Delta Table Format
+* 数据处理：Spark
+* 代码语言：PySpark + Spark SQL
+* 数据质量：Great Expectations
+* 工作流：Airflow
+* 运行环境：本地Docker（Spark、Airflow）
+
+### Spark数据工程最佳实践项目最佳实践
+
+#### 使用标准模式逐步转换数据
+
+遵循既定的数据处理流程有助于处理常见的潜在问题，并且您可参考大量的资料。大多数行业标准模式均遵循三层数仓架构，具体如下：
+
+1. **原始层**：按上游源端的原始状态存储数据。此层有时会涉及数据类型的更改和列名的标准化。
+2. **转换层**：依据所选的建模原则对原始层的数据进行转换，从而形成一组表。常见的建模原则包括维度建模（Kimball）、Data Vault 模型、实体关系数据模型等。
+3. **消费层**：将来自转换层的数据加以组合，形成直接与最终用户用例相对应的数据集。消费层通常涉及连接和聚合转换层表，以方便最终用户对历史性能进行分析。**业务特定的指标**通常在此层定义。我们应确保**一个指标仅在一个位置定义**。
+4. **接口层（可选）**：消费层中的数据通常会遵循数据仓库的命名/数据类型等。然而，呈现给最终用户的数据应具备易用性和易理解性。接口层通常是作为仓库表与其消费者之间接口的**视图**。
+
+:-: ![](.topwrite/assets/image_1737530923177.png =808)
+
+^
+
+上图中的青铜层（Bronze Layer）、白银层（Silver Layer）、黄金层（Gold Layer）和接口层（User Interface）分别与上述的原始层、转换层、消费层和接口层相对应。我们针对白银层采用了维度建模的方法。对于管道/转换函数/表而言，输入被称为“上游”，输出则被称为“下游”消费者。在规模较大的公司中，多个团队在不同的层级上开展工作。数据采集团队或许会将数据导入青铜层，而其他团队能够依据自身需求构建属于自己的白银层和黄金层的表。
+
+^
+
+#### 在将数据提供给消费者之前确保数据有效（又称为数据质量检查）
+
+在构建数据集时，明确对数据的期望至关重要。对数据集的期望可以简单到列值符合要求，也可以复杂到满足更复杂的业务需求。若下游消费者使用了不良数据，其后果可能是灾难性的。例如，向客户发送错误的数据或基于不正确的数据进行资金支出。纠正不良数据使用的过程通常需要耗费大量时间，并重新运行所有受影响的流程！
+
+为防止消费者意外使用不良数据，我们应当在提供数据以供使用之前对其进行检查。
+
+本项目使用[Great Expectations](https://www.startdataengineering.com/post/ensuring-data-quality-with-great-expectations/) 库来定义和运行数据检查。
+
+#### 使用幂等的数据管道避免数据重复
+
+重跑，即重新运行数据管道，是一种常见操作。在重新运行数据管道时，我们必须确保输出不包含重复的行。系统在给定相同输入的情况下始终产生相同输出的特性称为幂等性。
+
+以下展示了重新运行数据管道时避免数据重复的两种技术：
+
+1. **基于运行 ID 的覆盖**：用于仅附加输出数据。请确保您的输出数据具有运行 ID 作为分区列（例如，我们的黄金表中的分区列）。运行 ID 表示创建的数据所属的时间范围。当重新处理数据时，依据给定的运行 ID 进行覆盖。
+2. **基于自然键的 UPSERTS**：在管道使用自然键对输出数据执行插入和更新时使用。当需要更新现有行的维度数据时（例如 SCD2 采用此方法）。重新运行管道产生的重复会致使现有行的更新（而非在输出中创建新行）。我们使用此方法来填充 dim\_customer 表。
+
+^
+
+## 迁移方案
+
+### 基于云器Lakehouse的新架构
+
+:-: ![](.topwrite/assets/image_1737601829558.png =828)
+
+### 两种方案的组件对比
+
+:-: ![](.topwrite/assets/image_1737537672374.png =828)
+
+^
+
+| **组件**   | **Spark方案**                   | **云器Lakehouse服务**                                |
+| -------- | ----------------------------- | ------------------------------------------------ |
+| **数据存储** | MinIO with Delta Table Format | 阿里云OSS(or AWS S3, etc) with Iceberg Table Format |
+| **数据处理** | Spark                         | 云器Lakehouse                                      |
+| **代码语言** | PySpark + Spark SQL           | ZettaPark + Lakehouse SQL                       |
+| **数据质量** | Great Expectations           | 云器Lakehouse DQC(数据质量)                            |
+| **工作流**  | Airflow                       | 云器Lakehouse Workflow                             |
+| **运行环境** | 本地Docker（Spark、Airflow）       | 云上Serverless服务                                   |
+
+### 语法差异
+
+| **功能**        | **Spark语法**                                                 | **云器Lakehouse语法**                                        |
+| ------------- | ----------------------------------------------------------- | -------------------------------------------------------- |
+| **建表DDL**     | CREATE TABLE ... USING DELTA ... LOCATION '{path}/customer' | CREATE TABLE, 不需要USING DELTA和LOCATION '{path}/customer'  |
+| **创建Session** | SparkSession.builder.appName                                | Session.builder.configs(connection\_parameters).create() |
+
+### 新方案的特点
+
+* **全面云化，聚焦数据**：将线下管理的环境全部迁移到云上，免去资源准备、系统运维等非数据相关的工作。
+* **易于迁移**：云器 Lakehouse SQL、Zettapark 与 Spark SQL、pySpark 分别具有高度兼容性，代码迁移的难度与成本极低。
+* **降低总体成本与复杂度**：云器 Lakehouse 内置工作流服务与数据质量控制服务，无需单独的 Airflow 和 Great Expectations。极大程度简化了系统架构，降低了总体成本与复杂度。
+* **具备开放性**：同时能够在架构中保留 Airflow 和 Greate Expectations，借助 Airflow 调度 Python 任务，并在 Python 代码中持续调用 Great Expectations 开展数据质量检测。
+* **资源管理与任务队列管理**：分别运用不同的 Virtual Cluster 处理 ETL、BI 以及数据质量的作业，达成资源隔离与任务队列管理。
+
+## 迁移步骤
+
+### 任务代码开发
+
+导航到[Lakehouse Studio](studio_overview.md)的开发->任务，构建如下任务树：
+
+^
+
+:-: ![](.topwrite/assets/image_1737533356377.png =827)
+
+^
+
+单击“+”新建如下目录：
+
+* 01\_QuickStarts\_data\_engineering\_best\_practices
+
+单击“+”新建如下SQL任务：
+
+* 00\_setup\_env
+
+单击“+”新建如下Python任务：
+
+* 01\_DDL
+  * create\_bronze\_tables.py
+  * create\_gold\_tables.py
+  * create\_interface\_views.py
+  * create\_silver\_tables.py
+* 02\_Pipeline
+  * sales\_mart.py
+
+访问本迁移项目的 [Github代码库](https://github.com/yunqiqiliang/clickzetta_quickstart/tree/main/data_engineering_best_practices)，将代码分别复制到对应的任务里。
+
+^
+
+### 资源管理和任务队列管理
+
+在set\_env任务里，通过创建三个Virtual Cluster（虚拟集群）来运行不同的任务：
+
+```SQL
+-- virtual cluster
+CREATE VCLUSTER IF NOT EXISTS data_engineering_best_practices_vc_etl
+   VCLUSTER_SIZE = XSMALL
+   VCLUSTER_TYPE = GENERAL
+   AUTO_SUSPEND_IN_SECOND = 10
+   AUTO_RESUME = TRUE
+   COMMENT  'data_engineering_best_practices_vc_etl';
+
+CREATE VCLUSTER IF NOT EXISTS data_engineering_best_practices_vc_bi
+   VCLUSTER_SIZE = XSMALL
+   VCLUSTER_TYPE = ANALYTICS
+   AUTO_SUSPEND_IN_SECOND = 300
+   AUTO_RESUME = TRUE
+   COMMENT  'data_engineering_best_practices_vc_bi';
+
+CREATE VCLUSTER IF NOT EXISTS data_engineering_best_practices_vc_dqc
+   VCLUSTER_SIZE = XSMALL
+   VCLUSTER_TYPE = GENERAL
+   AUTO_SUSPEND_IN_SECOND = 10
+   AUTO_RESUME = TRUE
+   COMMENT  'data_engineering_best_practices_vc_dqc';
+```
+
+### 任务参数配置
+
+#### 01\_DDL任务参数配置
+
+分别给如下四个任务配置参数：
+
+* create\_bronze\_tables.py
+* create\_gold\_tables.py
+* create\_interface\_views.py
+* create\_silver\_tables.py
+
+打开任务，点击“调度”：
+
+![](.topwrite/assets/image_1737534509318.png =474)
+
+在弹出页面点击“加载代码中参数”：
+
+:-: ![](.topwrite/assets/image_1737534572480.png =567)
+
+设定每个参数的取值：
+
+:-: ![](.topwrite/assets/image_1737534633567.png =562)
+
+如何获得参数值请参考 [这篇文章](https://uat-doc.clickzetta.com/JDBC-Driver)。
+
+^
+
+#### 02\_Pipeline ETL任务参数配置
+
+给如下任务配置参数，参数配置的方法同上。
+
+* sales\_mart.py
+
+### 创建环境
+
+运行 setup_env 和 DDL 临时任务，创建运行所需要的虚拟计算集群、数据库 Schema 以及 Tables。
+创建运行所需要的虚拟计算集群、数据库Schema：
+
+:-: ![](.topwrite/assets/image_1737534798871.png =599)
+
+创建Tables:
+
+:-: ![](.topwrite/assets/image_1737534852030.png =594)
+
+### 配置数据质量监控规则
+
+导航到[Lakehouse Studio](studio_overview.md)的数据->数据质量->质量规则，新建如下规则：
+
+:-: ![](.topwrite/assets/image_1737534933748.png =597)
+
+以expectation\_suite\_name是customer为例
+
+:-: ![](.topwrite/assets/image_1737535012940.png =594)
+
+配置如下规则：
+
+:-: ![](.topwrite/assets/image_1737535163110.png =615)
+
+### 工作流调度
+
+导航到[Lakehouse Studio](studio_overview.md)的开发->任务，
+对sales\_mart.py ETL任务进行调度配置：
+
+:-: ![](.topwrite/assets/image_1737535319989.png =578)
+
+从而实现1小时为周期的报表数据刷新。
+
+然后点击“提交”，按周期执行该ETL任务：
+
+![](.topwrite/assets/image_1737535401895.png =723)
+
+### 任务运维
+
+#### ETL任务运维
+
+导航到[Lakehouse Studio](studio_overview.md)的运维监控->任务运维，查看任务状态，执行日志、实例管理等。
+
+:-: ![](.topwrite/assets/image_1737535489873.png =712)
+
+#### 数据质量控制
+
+导航到[Lakehouse Studio](studio_overview.md)的数据->数据质量，在数据质量中可以配置质量规则来监控数据表的产出是否正常。
+
+查看校验对象：
+
+:-: ![](.topwrite/assets/image_1737535653201.png =729)
+
+查看校验结果：
+
+:-: ![](.topwrite/assets/image_1737535687027.png =720)
+
+^
+^
+
+#### 监控告警配置
+
+下一步可以导航到运维监控->监控告警，增加告警规则，实现对ETL任务和数据质量控制的实时告警。
+
+^
+
+**使用内置的监控告警规则**：
+
+在系统内部，内置了如下通用的监控告警规则，在数据质量校验失败时，会按照规则中的具体配置来触发邮件、短信、电话等告警。
+
+:-: ![](.topwrite/assets/image_1737600310887.png =720)
+
+^
+
+**使用自定义监控告警规则**：
+
+上述内置的监控告警规则，是对全局所有的质量监控规则的校验结果都生效。如果想进一步精细化控制告警的监测范围和告警策略，也可以自定义的新建规则，如下图所示，选择“质量规则校验失败”的监控事项，并给定限制范围的过滤条件。监控告警配置的详细指南，可以参考 [监控告警](monitoring_and_alerting.md) 使用指南。
+
+:-: ![](.topwrite/assets/image_1737600502785.png =720)
+
+^
+
+## 参考资料
+
+* [任务开发与调度](taskdevelop.md)
+* [Python任务开发与调度、工作流编排](Python_Task.md)
+* [Zettapark快速上手](ZettaparkQuickStart.md)
+* [任务参数](task_param.md)
+* [监控告警](monitoring_and_alerting.md)
+
+^

package/bin/skills/lakehouse-doc/references/ModernDataStackWithEcosystemTools.md

@@ -0,0 +1 @@
+^

package/bin/skills/lakehouse-doc/references/N8N_AI_Workflow_Integration.md

@@ -0,0 +1 @@
+^

package/bin/skills/lakehouse-doc/references/N8N_Integrated_with_LakehouseMCPServer.md

@@ -0,0 +1,128 @@
+# N8N中集成Lakehouse MCP Server
+
+N8N 的 Agent 节点支持直接集成来自外部 [MCP](https://modelcontextprotocol.io/introduction) 服务器的[工具](https://modelcontextprotocol.io/docs/concepts/tools)。这为 Lakehouse 与您的 N8N AI 工作流集成提供了新方式。
+Lakehouse MCP Server 通过这种方式实现与 N8N 的集成，来自 Lakehouse MCP Server 的丰富工具可以在 N8N 的 Agent 节点中轻松调用。
+
+首先，您需要部署支持 [SSE协议的Lakehouse MCP Server](LakehouseMCPServer_intro.md)。
+
+## 在 N8N 工作流 AI Agent 节点中增加 MCP Client
+
+N8N MCP 客户端工具节点是一个[模型上下文协议 (MCP)](https://modelcontextprotocol.io/introduction)客户端，允许您使用外部 MCP 服务器公开的工具。您可以将 MCP 客户端工具节点连接到您的模型，以便使用 N8N 代理调用外部工具。**目前 N8N 仅支持 SSE 协议，还不支持通过 HTTP 协议与 MCP Server 互通**。
+
+:-: ![](.topwrite/assets/image_1756887369109.png =795)
+
+在 Agent 节点的 System Message 中填写：
+您是 ClickZetta Lakehouse 资深产品专家，擅长借助 MCP Server Tools 帮助用户回答和解决问题，避免编造。对于 ClickZetta Lakehouse 相关的问题，如果没有合适的 MCP Tool，您需要先通过 `get_product_knowledge` 这个 MCP Tool 查询产品知识库获得知识，然后再通过合适的 Tool 执行获得结果。
+
+## 配置AI Agent节点的MCP
+
+使用以下参数配置节点。
+
+* **SSE 端点**：您要连接的 MCP 服务器的 SSE 端点。
+
+* **身份验证**：用于向 MCP 服务器进行身份验证的身份验证方法。选择 **“无”** 则无需身份验证即可尝试连接。
+
+* **要包含的工具**：选择要向 AI 代理公开的工具：
+
+  * **全部**：公开 MCP 服务器提供的所有工具。
+  * **已选择**：激活 **要包含的工具** 参数，您可以在其中选择要向 AI 代理公开的工具。
+  * **除以下所有**：激活 **要排除的工具** 参数，您可以在其中选择要避免与 AI 代理共享的工具。AI 代理将可以访问所有未选中的 MCP 服务器工具。
+
+:-: ![](.topwrite/assets/image_1756887446000.png =614)
+
+选择 **已选择**，即可看到 Tools 列表：
+
+\:-:
+![](.topwrite/assets/image_1756887497226.png =611)
+
+## 测试Agent流程
+
+在对话框中输入您的问题来操作 Lakehouse：
+
+**问题1：我有哪些 Lakehouse 环境？**
+
+:-: ![](.topwrite/assets/image_1756887670661.png =629)
+
+^
+
+**答复1**：
+
+您当前有以下4个Lakehouse环境配置：
+
+1. **aliyun\_shanghai\_prod**
+
+   * **工作空间**: quick\_start
+   * **Schema**: mcp\_demo
+   * **虚拟集群**: default\_ap
+   * **状态**: 已连接（当前活跃且默认）
+
+2. **tencent\_shanghai\_prod**
+
+   * **工作空间**: quick\_start
+   * **Schema**: mcp\_demo
+   * **虚拟集群**: default\_ap
+   * **状态**: 已连接
+
+3. **tencent\_beijing\_prod**
+
+   * **工作空间**: quick\_start
+   * **Schema**: public
+   * **虚拟集群**: default\_ap
+   * **状态**: 已连接
+
+4. **tencent\_guangzhou\_prod**
+
+   * **工作空间**: quick\_start
+   * **Schema**: public
+   * **虚拟集群**: default\_ap
+   * **状态**: 已连接
+
+当前活跃的环境是 **aliyun\_shanghai\_prod**。如果需要切换环境，请告诉我具体需求！
+
+**问题2：帮我切换到 tencent_shanghai_prod**
+
+**答复2**：
+
+已成功将Lakehouse环境切换到 **tencent\_shanghai\_prod**，以下是验证信息：
+
+* **新连接状态**：
+
+  * **服务端点**: `ap-shanghai-tencentcloud.api.clickzetta.com`
+  * **工作空间**: `quick_start`
+  * **Schema**: `mcp_demo`
+  * **实例ID**: `270738` (内部标识)
+
+* **切换详情**：
+
+  * 物理连接已重建，无配置漂移。
+  * 处理耗时：2.83秒。
+
+如需进一步验证当前上下文，可执行 `get_current_context`。
+请继续告知后续操作需求！
+
+**问题3：当前上下文是？**
+
+**答复3：**
+
+当前上下文信息如下：
+
+* **实例ID**: `270738`
+* **Schema**: `mcp_demo`
+* **用户名**: `qiliang` (ID: `2162115`)
+* **虚拟集群**: `default_ap`
+* **工作空间**: `quick_start`
+* **连接时间**: `2025-09-03 16:25:45` (UTC+8)
+
+当前环境为 **tencent\_shanghai\_prod**（腾讯云上海生产环境），状态正常。如需其他操作请随时告知！
+
+^
+
+同样，您也可以在对话框中输入问题，进行 Lakehouse 相关的知识问答：
+
+^
+
+:-: ![](.topwrite/assets/image_1756888912810.png =813)
+
+^
+
+可以看到，通过 N8N 流程可以便捷地访问 Lakehouse 了！

package/bin/skills/lakehouse-doc/references/Notebook.md

@@ -0,0 +1,109 @@
+# Notebook
+
+> 【预览发布】本功能当前处于受邀预览发布阶段。如果需要使用，请联系我们的技术支持同学协助处理。
+
+Notebook 是一个基于 Web 的代码编辑器，可用于编写代码并查看交互式数据分析的结果。本文介绍如何在产品中使用 Notebook 的基础知识，包括如何导航工具栏以及如何执行各种单元格操作。
+
+^
+
+## 创建Notebook
+
+点击侧边栏「分析」→「新建 Notebook」。
+
+![](.topwrite/assets/011388d678/27c707b51a3829432947bf879bdc28e3665d6b89.png =600)
+
+A：左侧目录树和数据树
+B：Notebook 功能操作区
+C：Notebook 单元格
+
+^
+
+## 左侧目录树和数据树
+
+* **Notebook**：目录树用于有序管理工作空间下的 Notebook 任务代码。当前暂不支持创建文件夹。
+* **数据**：Notebook 下方呈现的是用户所在 Region 下的所有数据目录树，按照工作空间-schema-表/视图的层级进行呈现。
+
+## 功能操作区
+
+| 序号 | 图标 | 描述 |
+| -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| 1  | ![](.topwrite/assets/011388d678/d16321d9b457ef7518d8d06790b0dac50b471a41.png =100)                                                                                     | 当前 Notebook 的全局参数。若下方有引用自定义参数（参数格式为 ${自定义参数}），则需要用户在此处输入参数值。注意：参数是针对全局的，若不同单元格中引用了相同的自定义参数名，则在执行时，会被替换为相同的参数值。 |
+| 2  | ![](.topwrite/assets/011388d678/d8ed39230535fca0269d918237100caa5ca43ab6.png =100) ![](.topwrite/assets/011388d678/3f584bbce433d2989fcdd20dab2a64fa7702ffec.png =100) | 运行所有单元格或停止执行。此按钮的名称会根据 Notebook 的状态而变化。用户点击“全部运行”后，会按照单元格的顺序依次执行所有单元格。 |
+| 3  | ![](.topwrite/assets/image_1751961573864.png =100) | 执行 SQL 单元的集群信息。 |
+| 4  | ![](.topwrite/assets/011388d678/5f64010035df28f6497b0c1721262d3c603098cb.png =100) | 更多操作：支持重命名 Notebook、复制、删除。 |
+
+^
+
+## Notebook单元格
+
+### 创建单元格
+
+新建一个 Notebook 任务后，在操作区域点击不同单元格类型以创建具体的单元格。
+
+![](.topwrite/assets/011388d678/687592cc8aef988fdd9f3b8530dc90d0e5d0a990.png =573)
+
+### 单元格类型
+
+Notebook 包含两种类型的单元格：**代码单元格**和 **Markdown 单元格**。
+
+#### 代码单元格
+
+代码单元格包含可执行代码，支持：
+
+**SQL单元格**: 执行ClickZetta SQL查询。
+
+若选择的是 SQL 单元格，需要用户选择需要访问云器数据的具体 schema 信息。筛选后，在该单元格中，可直接输入表名，系统会根据 schema 和当前 workspace 信息自动补全具体的三段式代码。
+
+![](.topwrite/assets/011388d678/67cd9f5c72eb094aed95ea9b640b1f44f2e83ee5.png =223)
+
+**Python 单元格**：执行 Python 数据分析代码。
+**Markdown 单元格**：Markdown 单元格包含可呈现为文本和图形的 Markdown 代码。使用 Markdown 来记录或说明您的代码。
+
+您可以在 Notebook 中添加或删除任一类型的单元格来组织您的工作。
+
+**限制**：单元格的输出大小限制为最大 10MB。
+
+### 单元格操作
+
+| 序号 | 图标 | 描述 |
+| -- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1  | ![](.topwrite/assets/011388d678/82fe986dd8bdc6d14931a490b9c42461e0ff875e.png =150) | 单元格类型。不同单元格类型支持的语言不同。                                                                                                                            |
+| 2  | ![](.topwrite/assets/011388d678/04a9470cabe9b435bad48723a08d020e78eebae9.png =200) | 单元格名称。当用户新创建一个单元格时，系统会默认填写一个单元格名称。双击该区域支持用户重命名该单元格名称。Notebook 允许用户在 Python 脚本中直接引用单元格的输出值。这需要用户明确输出信息的单元格名称，并通过单元格名称进行数据定位。单元格名称只支持英文大小写字母、数字和下划线（_）。 |
+| 3  | ![](.topwrite/assets/011388d678/3624b860938372cc54731d55b56f33830815ca1b.png =150) | 单元格代码、展示结果的展开/收起。当 Notebook 代码信息过长时，支持用户点击左侧箭头，分别对代码和结果区域进行展开和收起。 |
+| 4  | ![](.topwrite/assets/011388d678/05bb1679bb297efe3ffc6cdc8a3d931cfe317ae3.png =150) | 移动单元格。Notebook 的执行有严格的顺序。若用户需要调整单元格的位置，可将鼠标悬停在单元格上方，选中移动区域后，即可上下拖动单元格。 |
+| 5  | ![](.topwrite/assets/011388d678/b42720011c5a781da12e42c3c6f123f12b39b72d.png =200) | 快捷添加单元格。鼠标悬停在当前单元格中间区域的上方或下方时，可快速在对应位置添加新的单元格。 |
+| 6  | ![](.topwrite/assets/011388d678/3fb0299e2f3ea40f0c233f10e43965ae81e1ac0d.png =83) | 运行单元格。 |
+| 7  | ![](.topwrite/assets/011388d678/6dc56eab8288e3a88583d61d352095e2b157665c.png =150) | 单元格更多操作：
+- 重命名：点击后可为单元格重新命名。
+- 清除输出：清除当前单元格的执行结果。若有其他单元格依赖该单元格的输出，则可能导致其他单元格执行失败。
+- 删除：删除该单元格。 |
+
+## 运行单元格
+
+### 基本操作
+
+要运行代码单元格，请单击代码单元格左上角的运行按钮，或整个 Notebook 区域左上角的「全部运行」按钮。
+
+单个运行：只会运行当前的单元格。
+
+若当前单元格中引用了其他单元格的输出结果，请确保所引用的单元格已成功运行。单个单元格的执行时间建议不要超过 30 分钟。若超过 30 分钟，可能会存在 Pod 被清空的风险。
+
+全部运行：点击后，会按照单元格顺序自上而下执行。若其中一个单元格执行失败或暂停，则下方所有单元格的执行会被阻断，状态会变更为暂停。
+
+![](.topwrite/assets/011388d678/c4675e355e9e871a79ecfef355b544355e257e01.png =319)
+
+点击运行后，在单元格内可看到执行的结果。
+
+![](.topwrite/assets/image_1751969653572.png =600)
+
+### 单元格之间上下文通信
+
+云器 Notebook 采用基于**单元格命名**的通信机制，每个单元格都有唯一的名称（如 cell1、cell2 等），可以直接在其他单元格中引用。
+
+**SQL 单元格输出**：多段 SQL 中只有最后一段作为该单元格的输出结果。
+
+**直接引用**：SQL 单元格的结果可直接作为 pandas DataFrame 使用。
+
+**无需转换**：不需要 `to_pandas()` 等额外操作。
+
+**命名引用**：通过 cell 名称直接访问结果。