用途
Cortex Analyst 在将自然语言查询匹配到列中的字面值时，如果维度带有提示（hints），匹配效果会更好。本技能通过丰富语义模型 YAML 或语义视图来改善字面值搜索，适用于以下场景：Cortex Analyst 无法将自然语言短语匹配到字面列值（例如“iced tea”找不到“Ice Tea”），或希望增强语义模型的字面值匹配能力。
主要能力
本技能对语义模型进行两类增强：
- 对低基数维度（不同值不超过 10 个）添加
is_enum: true以及全部不同值。 - 对高基数维度（不同值超过 10 个）创建 Cortex Search Service，并添加 3 个
sample_values。
支持三种来源：本地 YAML、暂存区（staged）YAML 和语义视图（semantic view）。
使用方式
工作流分为六个步骤：
步骤 1：确认连接与来源。 验证 Snowflake 连接：
SELECT CURRENT_ACCOUNT(), CURRENT_USER(), CURRENT_ROLE();
向用户询问来源（本地 YAML / 暂存区 YAML / 语义视图 FQN）以及用于搜索服务的仓库（XSMALL 即可）。对于语义视图，列出并读取：
SHOW SEMANTIC VIEWS IN <db>.<schema>;
SELECT SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW('<DB.SCHEMA.VIEW>');
对于暂存区 YAML，将文件作为单个值读取以避免记录被拆分：
CREATE TEMP FILE FORMAT IF NOT EXISTS _yaml_fmt
TYPE = 'CSV' FIELD_DELIMITER = NONE RECORD_DELIMITER = NONE;
SELECT $1 FROM @<stage>/<path>/model.yaml (FILE_FORMAT => '_yaml_fmt');
步骤 2：分析维度。 对每个缺少配置的文本维度，查询基数和样本值：
SELECT COUNT(DISTINCT <col>) AS distinct_count
FROM <base_table> WHERE <col> IS NOT NULL;
SELECT DISTINCT <col> FROM <base_table>
WHERE <col> IS NOT NULL ORDER BY <col> LIMIT <N>;
将每个维度归类为 enum、search-service 或已配置。
步骤 3：展示建议。 显示维度 → 不同值数量 → 建议的表格，并询问 TARGET_LAG（默认 '1 day'）。
⚠️ 停止点：在执行任何 DDL 之前，获得用户对要配置哪些维度的明确批准。
步骤 4：应用枚举维度（低基数）。 编辑 YAML / 视图以包含：
dimensions:
- name: region
expr: region_column
is_enum: true
sample_values: ["North America", "Europe", "Asia Pacific"]
步骤 5：创建搜索服务并更新模型（高基数）。
⚠️ 停止点：在运行 CREATE OR REPLACE 之前，确认服务名称和仓库。
CREATE OR REPLACE CORTEX SEARCH SERVICE <db>.<schema>.<table>_<col>_ss
ON <col>
WAREHOUSE = <wh>
TARGET_LAG = '<lag>'
AS (SELECT DISTINCT <col> FROM <db>.<schema>.<table>);
对于 YAML 模型，添加：
- name: product_name
expr: product_name_column
cortex_search_service:
service: <table>_<col>_ss
literal_column: <col>
database: <db>
schema: <schema>
sample_values: ["Example A", "Example B"]
对于语义视图，通过 DDL 重建。所需语法：
WITH CORTEX SEARCH SERVICE必须位于COMMENT之前。WITH EXTENSION (CA = '<json>')携带 is_enum / sample_values。- 在
TABLES中使用完全限定表名。 - 使用
COPY GRANTS。
CREATE OR REPLACE SEMANTIC VIEW DB.SCHEMA.MY_VIEW
TABLES (DB.SCHEMA.ORDERS COMMENT = 'Orders')
DIMENSIONS (
ORDERS.PRODUCT_NAME AS PRODUCT_NAME
WITH CORTEX SEARCH SERVICE DB.SCHEMA.ORDERS_PRODUCT_NAME_SS
COMMENT = 'Product',
ORDERS.REGION AS REGION COMMENT = 'Region'
)
WITH EXTENSION (CA = '{"tables":[{"name":"ORDERS","dimensions":[{"name":"REGION","is_enum":true,"sample_values":["NA","EU","APAC"]}]}]}')
COPY GRANTS;
验证：
SHOW CORTEX SEARCH SERVICES IN <schema>;
步骤 6：验证。
cortex analyst query "<question with a literal value>" --view=<view>
确认匹配能够正确解析。
脚本
对于语义视图，随附脚本可自动化步骤 2 和步骤 5。依赖项位于 pyproject.toml / uv.lock；使用 uv 运行。<SKILL_DIR> 是本技能所在目录。--connection 默认为 SNOWFLAKE_CONNECTION_NAME，否则使用连接器的默认连接。
scripts/analyze_table.py（只读）：读取语义视图 YAML，查找字符串维度，查询每个基表的基数和样本值，并将建议（不同值不超过 10 个为 enum，否则为 search_service）写入 JSON 文件。
uv run --project <SKILL_DIR> python <SKILL_DIR>/scripts/analyze_table.py \
--semantic-view DB.SCHEMA.VIEW --warehouse <wh> --output analysis.json [--connection <name>]
scripts/apply_changes.py（破坏性）：根据 analysis.json，为高基数维度运行 CREATE OR REPLACE CORTEX SEARCH SERVICE，并通过 SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML（会复制现有授权）重建语义视图，包含 is_enum、sample_values 和搜索服务引用。它会打印计划执行的语句，仅在交互式输入 y 或使用 --yes 后才执行。
uv run --project <SKILL_DIR> python <SKILL_DIR>/scripts/apply_changes.py \
--analysis analysis.json [--update-lag '1 day'] [--connection <name>] [--yes]
⚠️ 停止点：在运行 apply_changes.py 之前，向用户展示计划变更（来自 analysis.json，或不带 --yes 运行以打印语句并中止），并获得明确批准。仅在批准后才传入 --yes。
常见错误
COMMENT位于WITH CORTEX SEARCH SERVICE之前——DDL 会失败。搜索子句应放在前面。TABLES (...)子句中使用未限定的表名——应使用 DB.SCHEMA.TABLE。WITH EXTENSION (CA = '...')中的 JSON 格式错误——运行前先验证。- 缺少 SNOWFLAKE.CORTEX_USER 角色——搜索服务创建会失败。
- 在超大列上采样不同值时跳过 LIMIT——查询会变慢。
- 为仓库设置过于激进的 TARGET_LAG——会增加成本而无精度收益。建议从 '1 day' 开始。
- 测试前未等待索引完成——初始索引构建需要时间。
停止点
- 步骤 3——在任何 DDL 之前，批准维度建议和 TARGET_LAG。
- 步骤 5——在 CREATE OR REPLACE 之前，确认服务名称、仓库和视图 DDL。
故障排除
- 搜索服务创建被拒绝：向角色授予 schema 上的 CREATE CORTEX SEARCH SERVICE 以及 SNOWFLAKE.CORTEX_USER。
- 找不到语义视图名称：先运行 SHOW SEMANTIC VIEWS；用户输入通常略有差异。
- 没有匹配改善：通过 SHOW CORTEX SEARCH SERVICES 确认服务处于 READY 状态，并确认自创建以来 TARGET_LAG 已过。