cortex-classify-notebook

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cortex Classify Text - Notebook Deployment Skill

Cortex Classify Text - 笔记本部署技能

You are deploying the Cortex CLASSIFY_TEXT tutorial notebook to the user's Snowflake account. This skill uploads the notebook and provides a direct link to open it in Snowsight.

您正在将Cortex CLASSIFY_TEXT教程笔记本部署到用户的Snowflake账户。本技能会上传笔记本并提供在Snowsight中打开它的直接链接。

What This Skill Does

本技能的功能

Fetches latest documentation to ensure current syntax
Detects or sets up the target environment (prefers SNOWFLAKE_LEARNING)
Creates a user-specific schema for the notebook
Uploads the tutorial notebook to a Snowflake stage
Creates the notebook in the user's account
Provides a direct link to open the notebook in Snowsight

获取最新文档以确保使用当前语法
检测或设置目标环境（优先使用SNOWFLAKE_LEARNING）
为笔记本创建用户专属的schema
将教程笔记本上传到Snowflake stage
在用户账户中创建笔记本
提供在Snowsight中打开笔记本的直接链接

Deployment Flow

部署流程

Welcome the user briefly, then proceed through the steps efficiently while keeping them informed. Do NOT ask for confirmation at each step - deploy smoothly and report results.

先向用户简要问候，然后高效执行以下步骤并及时告知用户进度。不要在每一步都请求确认——流畅完成部署并汇报结果。

Step 0: Fetch Latest Documentation (ALWAYS do this first)

步骤0：获取最新文档（必须首先执行）

Before starting deployment, use

web_fetch

to retrieve the current official documentation:

https://docs.snowflake.com/en/sql-reference/functions/classify_text-snowflake-cortex
https://docs.snowflake.com/en/user-guide/ui-snowsight/notebooks

This ensures your explanations and any troubleshooting advice are current. If the docs show new parameters or syntax, inform the user.

开始部署前，使用

web_fetch

获取当前官方文档：

https://docs.snowflake.com/en/sql-reference/functions/classify_text-snowflake-cortex
https://docs.snowflake.com/en/user-guide/ui-snowsight/notebooks

这能确保您的说明和任何故障排除建议都是最新的。如果文档中出现新参数或语法，请告知用户。

Step 1: Environment Detection and Setup

步骤1：环境检测与设置

Run these two queries in parallel:

sql

-- Query 1: Check if SNOWFLAKE_LEARNING environment exists
SHOW ROLES LIKE 'SNOWFLAKE_LEARNING_ROLE';

-- Query 2: Read the notebook file from assets/classify_unstructured_customer_reviews.ipynb

If SNOWFLAKE_LEARNING_ROLE exists (preferred):

sql

USE ROLE SNOWFLAKE_LEARNING_ROLE;
USE DATABASE SNOWFLAKE_LEARNING_DB;
USE WAREHOUSE SNOWFLAKE_LEARNING_WH;

If NOT available (fallback):

sql

USE ROLE ACCOUNTADMIN;  -- or appropriate role with CREATE DATABASE privilege
CREATE DATABASE IF NOT EXISTS CORTEX_TUTORIALS_DB;
USE DATABASE CORTEX_TUTORIALS_DB;
CREATE WAREHOUSE IF NOT EXISTS CORTEX_TUTORIALS_WH WITH WAREHOUSE_SIZE = 'XSMALL';
USE WAREHOUSE CORTEX_TUTORIALS_WH;

并行运行以下两个查询：

sql

-- Query 1: Check if SNOWFLAKE_LEARNING environment exists
SHOW ROLES LIKE 'SNOWFLAKE_LEARNING_ROLE';

-- Query 2: Read the notebook file from assets/classify_unstructured_customer_reviews.ipynb

如果SNOWFLAKE_LEARNING_ROLE存在（优先选择）：

sql

USE ROLE SNOWFLAKE_LEARNING_ROLE;
USE DATABASE SNOWFLAKE_LEARNING_DB;
USE WAREHOUSE SNOWFLAKE_LEARNING_WH;

如果不可用（备选方案）：

sql

USE ROLE ACCOUNTADMIN;  -- 或拥有CREATE DATABASE权限的合适角色
CREATE DATABASE IF NOT EXISTS CORTEX_TUTORIALS_DB;
USE DATABASE CORTEX_TUTORIALS_DB;
CREATE WAREHOUSE IF NOT EXISTS CORTEX_TUTORIALS_WH WITH WAREHOUSE_SIZE = 'XSMALL';
USE WAREHOUSE CORTEX_TUTORIALS_WH;

Step 2: Create User Schema and Stage

步骤2：创建用户Schema与Stage

sql

-- Create a schema for the notebook (named after current user)
SET schema_name = CONCAT(CURRENT_USER(), '_CORTEX_TUTORIALS');
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name);
USE SCHEMA IDENTIFIER($schema_name);

-- Create internal stage for notebook files
CREATE STAGE IF NOT EXISTS notebook_stage
    DIRECTORY = (ENABLE = TRUE)
    ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE');

sql

-- Create a schema for the notebook (named after current user)
SET schema_name = CONCAT(CURRENT_USER(), '_CORTEX_TUTORIALS');
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name);
USE SCHEMA IDENTIFIER($schema_name);

-- Create internal stage for notebook files
CREATE STAGE IF NOT EXISTS notebook_stage
    DIRECTORY = (ENABLE = TRUE)
    ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE');

Step 3: Capture Environment Info (CRITICAL)

步骤3：捕获环境信息（至关重要）

IMPORTANT: After setting up the environment, you MUST query the actual values to use in subsequent steps. Do NOT guess or assume schema names based on the local username.

sql

SELECT 
    CURRENT_USER() as current_user,
    CURRENT_SCHEMA() as current_schema, 
    CURRENT_DATABASE() as current_database,
    CURRENT_ROLE() as current_role

Store these values for use in the upload and notebook creation steps.

注意： 设置完环境后，您必须查询实际值以用于后续步骤。不要根据本地用户名猜测或假设schema名称。

sql

SELECT 
    CURRENT_USER() as current_user,
    CURRENT_SCHEMA() as current_schema, 
    CURRENT_DATABASE() as current_database,
    CURRENT_ROLE() as current_role

存储这些值以便在上传和笔记本创建步骤中使用。

Step 4: Upload Notebook File to Stage

步骤4：将笔记本文件上传到Stage

Use the
snow stage copy
CLI command with fully qualified stage path:

bash

snow stage copy <local_notebook_path> @<DATABASE>.<SCHEMA>.notebook_stage --overwrite --connection <connection_name>

Example (substitute actual values from Step 3):

bash

snow stage copy /path/to/assets/classify_unstructured_customer_reviews.ipynb @{DATABASE}.{SCHEMA}.notebook_stage --overwrite --connection {CONNECTION}

IMPORTANT:

Use the ACTUAL schema name from Step 3, NOT a guessed name based on local OS username
The local path is:
```
assets/classify_unstructured_customer_reviews.ipynb
```
relative to this skill's base directory
Always use
```
--overwrite
```
flag to handle re-deployments

使用
snow stage copy
CLI命令，并使用完全限定的stage路径：

bash

snow stage copy <local_notebook_path> @<DATABASE>.<SCHEMA>.notebook_stage --overwrite --connection <connection_name>

示例（替换步骤3中的实际值）：

bash

snow stage copy /path/to/assets/classify_unstructured_customer_reviews.ipynb @{DATABASE}.{SCHEMA}.notebook_stage --overwrite --connection {CONNECTION}

注意：

使用步骤3中查询到的实际schema名称，不要基于本地OS用户名猜测

本地路径为：相对于本技能根目录的

assets/classify_unstructured_customer_reviews.ipynb

始终使用
```
--overwrite
```
参数以支持重新部署

Step 5: Create the Notebook

步骤5：创建笔记本

Use fully qualified names for the notebook creation:

sql

CREATE OR REPLACE NOTEBOOK <DATABASE>.<SCHEMA>.CLASSIFY_CUSTOMER_REVIEWS
    FROM '@<DATABASE>.<SCHEMA>.notebook_stage'
    MAIN_FILE = 'classify_unstructured_customer_reviews.ipynb'
    COMMENT = 'Tutorial: Classify customer reviews with Cortex AI';

Example (substitute actual values from Step 3):

sql

CREATE OR REPLACE NOTEBOOK {DATABASE}.{SCHEMA}.CLASSIFY_CUSTOMER_REVIEWS
    FROM '@{DATABASE}.{SCHEMA}.notebook_stage'
    MAIN_FILE = 'classify_unstructured_customer_reviews.ipynb'
    COMMENT = 'Tutorial: Classify customer reviews with Cortex AI';

使用完全限定名称创建笔记本：

sql

CREATE OR REPLACE NOTEBOOK <DATABASE>.<SCHEMA>.CLASSIFY_CUSTOMER_REVIEWS
    FROM '@<DATABASE>.<SCHEMA>.notebook_stage'
    MAIN_FILE = 'classify_unstructured_customer_reviews.ipynb'
    COMMENT = 'Tutorial: Classify customer reviews with Cortex AI';

示例（替换步骤3中的实际值）：

sql

CREATE OR REPLACE NOTEBOOK {DATABASE}.{SCHEMA}.CLASSIFY_CUSTOMER_REVIEWS
    FROM '@{DATABASE}.{SCHEMA}.notebook_stage'
    MAIN_FILE = 'classify_unstructured_customer_reviews.ipynb'
    COMMENT = 'Tutorial: Classify customer reviews with Cortex AI';

Step 6: Generate Snowsight URL

步骤6：生成Snowsight URL

Get the account identifier for the URL:

sql

SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME() as account_identifier

Build the Snowsight URL:

https://app.snowflake.com/{ORG}/{ACCOUNT}/#/notebooks/{DATABASE}.{SCHEMA}.CLASSIFY_CUSTOMER_REVIEWS

Where

{ORG}

and

{ACCOUNT}

come from splitting the account_identifier on

获取URL所需的账户标识符：

sql

SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME() as account_identifier

构建Snowsight URL：

https://app.snowflake.com/{ORG}/{ACCOUNT}/#/notebooks/{DATABASE}.{SCHEMA}.CLASSIFY_CUSTOMER_REVIEWS

其中

{ORG}

和

{ACCOUNT}

来自将account_identifier按

拆分后的结果。

Success Message

成功提示

After successful deployment, provide this summary:

部署成功后，提供以下摘要：

Notebook Deployed Successfully!

笔记本部署成功！

Open your notebook: Click here to open in Snowsight

Location:

{DATABASE}.{SCHEMA}.CLASSIFY_CUSTOMER_REVIEWS

打开您的笔记本： 点击此处在Snowsight中打开

位置：

{DATABASE}.{SCHEMA}.CLASSIFY_CUSTOMER_REVIEWS

What the notebook covers:

本教程笔记本涵盖内容：

Load Sample Data - Customer reviews from Tasty Bytes food trucks
Classify Text with Python - Use
```
cortex.classify_text()
```
on single strings and DataFrames
Classify Text with SQL - Use
```
SNOWFLAKE.CORTEX.CLASSIFY_TEXT()
```
directly in queries
Analyze Results - Determine if customers would recommend food trucks based on reviews

加载示例数据 - 来自Tasty Bytes餐车的顾客评论数据
使用Python进行文本分类 - 在单个字符串和DataFrames上使用
```
cortex.classify_text()
```
使用SQL进行文本分类 - 在查询中直接使用
```
SNOWFLAKE.CORTEX.CLASSIFY_TEXT()
```
分析结果 - 根据评论判断顾客是否会推荐餐车

To run the tutorial:

运行教程的步骤：

Click the link above to open the notebook in Snowsight
Click Run All to execute all cells
Review the classification results showing "Likely", "Unlikely", or "Unsure" recommendations

点击上方链接在Snowsight中打开笔记本
点击Run All执行所有单元格
查看分类结果，结果分为“Likely”（可能推荐）、“Unlikely”（不太可能推荐）或“Unsure”（不确定）

Handling Issues

问题处理

Schema Name Mismatch Errors

Schema名称不匹配错误

If you get "Schema does not exist" errors:

Always query
CURRENT_SCHEMA()
after setup to get the actual schema name
Do NOT assume the schema name matches the local OS username
Use the queried values in all subsequent commands

如果出现“Schema不存在”错误：

**务必在设置后查询
```
CURRENT_SCHEMA()
```
**以获取实际的schema名称
不要假设schema名称与本地OS用户名一致
在所有后续命令中使用查询到的实际值

Stage Copy Failures

Stage复制失败

snow stage copy

fails:

Verify the stage path uses fully qualified names:
```
@DATABASE.SCHEMA.stage_name
```
Ensure the connection parameter matches the user's active connection
Check that the role has WRITE privileges on the stage

如果

snow stage copy

失败：

验证stage路径使用完全限定名称：
```
@DATABASE.SCHEMA.stage_name
```
确保connection参数与用户的活跃连接匹配
检查角色是否拥有该stage的WRITE权限

Notebook Already Exists

笔记本已存在

The skill uses

CREATE OR REPLACE NOTEBOOK

by default, which handles existing notebooks automatically.

本技能默认使用

CREATE OR REPLACE NOTEBOOK

，可自动处理已存在的笔记本。

Insufficient Privileges

权限不足

If user can't create notebooks:

Check if they have CREATE NOTEBOOK privilege on the schema
Suggest using SNOWFLAKE_LEARNING_ROLE if available
Fall back to ACCOUNTADMIN if necessary

如果用户无法创建笔记本：

检查用户是否拥有该schema的CREATE NOTEBOOK权限
建议使用SNOWFLAKE_LEARNING_ROLE（如果可用）
必要时切换到ACCOUNTADMIN角色

Cortex Not Available

Cortex不可用

If Cortex functions aren't available in the region:

Check Cortex region availability
Verify account has Cortex enabled

如果Cortex功能在当前区域不可用：

查看Cortex区域可用性
验证账户是否已启用Cortex

Reference Materials

参考资料

assets/classify_unstructured_customer_reviews.ipynb

- The notebook file to deploy

Notebook teaches classification of customer reviews into "Likely", "Unlikely", "Unsure" categories

assets/classify_unstructured_customer_reviews.ipynb

- 待部署的笔记本文件

本笔记本教授将顾客评论分类为“Likely”、“Unlikely”、“Unsure”三个类别的方法