add-semantic-layer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

add-semantic-layer

接入语义层

Wire a semantic layer in so it becomes the canonical source of truth for metrics. The agent queries it instead of computing metrics from raw tables.

接入语义层，使其成为指标的标准可信源。Agent将查询该语义层，而非从原始表计算指标。

When to add — and when not to

何时接入——何时不接入

Only add a semantic layer after
nao test
shows the agent struggling with metric reliability. Not before.

Increases reliability and stability (one definition per metric).
Reduces the scope of answerable questions (anything outside the layer is harder, sometimes impossible).

If failures are concentrated on schema gaps or date logic, a semantic layer doesn't help — fix

RULES.md

first.

Semantic layer vs metric store: a semantic layer is a file (md/yaml) the agent reads to write its own SQL. A metric store exposes metrics through an API the agent calls (

query_metric(...)

); the framework converts to SQL. dbt MetricFlow Cloud is a metric store. Snowflake views and nao YAML are semantic layers. Bigger reliability gain with a metric store, bigger scope reduction too.

仅在
nao test
显示agent在指标可靠性方面存在问题后，才接入语义层。切勿提前操作。

提升可靠性与稳定性（每个指标仅一个定义）。
缩小可回答问题的范围（语义层之外的内容会更难处理，有时甚至无法处理）。

如果问题集中在架构缺口或日期逻辑上，语义层无法解决——应先修复

RULES.md

。

语义层 vs 指标存储： 语义层是Agent读取后用于生成SQL的文件（md/yaml格式）。指标存储通过API暴露指标，供Agent调用（

query_metric(...)

）；框架会将其转换为SQL。dbt MetricFlow Cloud属于指标存储。Snowflake视图和nao YAML属于语义层。指标存储能带来更大的可靠性提升，但也会导致更大的范围缩小。

Step 1 — Pick the tool

步骤1 — 选择工具

Option	Type	When
dbt MetricFlow	Metric store	Already running dbt Cloud with the Semantic Layer enabled.
Snowflake views / semantic	Semantic layer	Snowflake; using curated views or native semantic views.
nao semantic files	Semantic layer	No existing layer. Want a lightweight in-repo YAML.
Other	Varies	Looker/LookML, Cube, AtScale, etc.

选项	类型	使用场景
dbt MetricFlow	指标存储	已运行启用语义层的dbt Cloud。
Snowflake views / semantic	语义层	使用Snowflake；采用精心维护的视图或原生语义视图。
nao semantic files	语义层	无现有语义层；希望使用轻量的仓库内YAML文件。
Other	多种类型	Looker/LookML、Cube、AtScale等工具。

Path A — dbt MetricFlow (dbt Cloud with Semantic Layer)

路径A — dbt MetricFlow（带语义层的dbt Cloud）

Add to

.claude/mcp.json

json

{
	"mcpServers": {
		"dbt-mcp": {
			"command": "uvx",
			"args": ["dbt-mcp"],
			"env": {
				"DBT_HOST": "us1.dbt.com",
				"MULTICELL_ACCOUNT_PREFIX": "your_prefix",
				"DBT_TOKEN": "${DBT_TOKEN}",
				"DBT_PROD_ENV_ID": "your_env_id",
				"DISABLE_SEMANTIC_LAYER": "false",
				"DISABLE_DISCOVERY": "true",
				"DISABLE_SQL": "true",
				"DISABLE_ADMIN_API": "true",
				"DISABLE_REMOTE": "false"
			}
		}
	}
}

Substitute

MULTICELL_ACCOUNT_PREFIX

DBT_PROD_ENV_ID

DBT_HOST

from the user's dbt Cloud account. Set

DBT_TOKEN

in their shell, not in the file. Restart the session and verify the MCP connects (

list_metrics

dbt Core (local-only) is not supported here — no metric-store API to route through.

Hand off to

write-context-rules

: in

## Key Metrics Reference

, route each MetricFlow metric through

query_metric

(e.g.

MRR → query via dbt MCP query_metric (semantic layer)

). In

## Analysis Process

, instruct the agent to use semantic-layer tools for known metrics instead of raw tables.

在

.claude/mcp.json

中添加以下内容：

json

{
	"mcpServers": {
		"dbt-mcp": {
			"command": "uvx",
			"args": ["dbt-mcp"],
			"env": {
				"DBT_HOST": "us1.dbt.com",
				"MULTICELL_ACCOUNT_PREFIX": "your_prefix",
				"DBT_TOKEN": "${DBT_TOKEN}",
				"DBT_PROD_ENV_ID": "your_env_id",
				"DISABLE_SEMANTIC_LAYER": "false",
				"DISABLE_DISCOVERY": "true",
				"DISABLE_SQL": "true",
				"DISABLE_ADMIN_API": "true",
				"DISABLE_REMOTE": "false"
			}
		}
	}
}

从用户的dbt Cloud账户中替换

MULTICELL_ACCOUNT_PREFIX

、

DBT_PROD_ENV_ID

、

DBT_HOST

的值。在shell中设置

DBT_TOKEN

，不要写入文件。重启会话并验证MCP连接成功（执行

list_metrics

）。

此处不支持dbt Core（仅本地）——没有可路由的指标存储API。

移交至

write-context-rules

：在

## Key Metrics Reference

中，将每个MetricFlow指标通过

query_metric

路由（例如

MRR → query via dbt MCP query_metric (semantic layer)

）。在

## Analysis Process

中，指示Agent对已知指标使用语义层工具，而非原始表。

Path B — Snowflake views / semantic views

路径B — Snowflake视图/语义视图

json

{
	"mcpServers": {
		"snowflake": {
			"command": "uvx",
			"args": ["mcp-server-snowflake"],
			"env": {
				"SNOWFLAKE_ACCOUNT": "your_account",
				"SNOWFLAKE_USER": "your_user",
				"SNOWFLAKE_PASSWORD": "${SNOWFLAKE_PASSWORD}",
				"SNOWFLAKE_WAREHOUSE": "your_warehouse",
				"SNOWFLAKE_DATABASE": "your_database",
				"SNOWFLAKE_SCHEMA": "your_schema",
				"SNOWFLAKE_ROLE": "your_role"
			}
		}
	}
}

For native semantic views (Cortex Analyst), use the Cortex MCP variant with

SEMANTIC_VIEW

set. Verify package + env-var names against the latest docs — auth options (key pair / OAuth / password) vary.

Identify the semantic surface (curated views like

analytics.metrics.*

or native semantic views). Hand off to

write-context-rules

: in

## Key Metrics Reference

, route each metric to its view, never the underlying tables.

json

{
	"mcpServers": {
		"snowflake": {
			"command": "uvx",
			"args": ["mcp-server-snowflake"],
			"env": {
				"SNOWFLAKE_ACCOUNT": "your_account",
				"SNOWFLAKE_USER": "your_user",
				"SNOWFLAKE_PASSWORD": "${SNOWFLAKE_PASSWORD}",
				"SNOWFLAKE_WAREHOUSE": "your_warehouse",
				"SNOWFLAKE_DATABASE": "your_database",
				"SNOWFLAKE_SCHEMA": "your_schema",
				"SNOWFLAKE_ROLE": "your_role"
			}
		}
	}
}

对于原生语义视图（Cortex Analyst），使用设置了

SEMANTIC_VIEW

的Cortex MCP变体。根据最新文档验证包和环境变量名称——认证选项（密钥对/OAuth/密码）有所不同。

确定语义层面（如

analytics.metrics.*

这类精心维护的视图或原生语义视图）。移交至

write-context-rules

：在

## Key Metrics Reference

中，将每个指标路由至对应的视图，绝不使用底层表。

Path C — Other (no obvious MCP)

路径C — 其他（无明确MCP）

Search the MCP registry, the tool's docs, and the user's installed MCPs. If a fit exists, configure it following the pattern from paths A-B. If not: fall back to Path D (nao semantic files) or build a thin MCP wrapper.

搜索MCP注册表、工具文档以及用户已安装的MCP。如果存在适配项，按照路径A-B的模式进行配置。如果没有：回退至路径D（nao语义文件）或构建轻量MCP封装。

Path D — nao semantic files

路径D — nao语义文件

For users with no existing semantic layer. One file:
semantics/semantic.yaml
holding all dimensions and metrics together. Use

templates/semantic.yaml

Walk through dimensions first (slice axes: date, plan, country — capture

name

type

description

, and allowed

values

for categoricals), then top metrics (capture

name

definition

, source

table

column

aggregation

grain

dimensions

filters

Hand off to

write-context-rules

: in

## Key Metrics Reference

, point every metric at

semantics/semantic.yaml

适用于无现有语义层的用户。仅需一个文件：
semantics/semantic.yaml
，用于存储所有维度和指标。使用

templates/semantic.yaml

模板。

先梳理维度（切片轴：日期、套餐、国家——记录

name

、

type

、

description

，以及分类类型的允许

values

），再梳理核心指标（记录

name

、

definition

、源

table

column

aggregation

、

grain

、

dimensions

、

filters

）。

移交至

write-context-rules

：在

## Key Metrics Reference

中，将所有指标指向

semantics/semantic.yaml

。

Validate

验证

Confirm every metric the user cares about now has a routing rule in
```
RULES.md
```
.
```
nao chat
```
one of their top questions; confirm the agent uses the semantic layer.
```
nao test
```
and compare to the pre-semantic-layer baseline pass rate. Reliability is the only reason to do this — measure it.

确认用户关心的每个指标现在都在
```
RULES.md
```
中有对应的路由规则。
使用
```
nao chat
```
测试用户的核心问题之一；确认Agent使用了语义层。
执行
```
nao test
```
并与接入语义层之前的基线通过率对比。可靠性是执行此操作的唯一原因——必须进行衡量。

Recommend next step

Guardrails

约束规则

Only after tests show metric failures. Cite them when the user asks "should we add one?"
One semantic layer at a time. Two competing layers create MECE violations.
Don't write
RULES.md
directly. Hand off to
```
write-context-rules
```
.
Don't store credentials in
.claude/mcp.json
. Use
```
${ENV_VAR}
```
. Add the file to
```
.gitignore
```
if anything sensitive lands there.
Don't invent metrics for Path D. Only encode what the user defines.

仅在测试显示指标失败后操作。当用户询问"我们是否应该接入？"时，引用测试结果。
一次仅接入一个语义层。两个相互竞争的层会导致MECE违规。
不要直接编写
RULES.md
。移交至
```
write-context-rules
```
处理。
不要在
.claude/mcp.json
中存储凭证。使用
```
${ENV_VAR}
```
。如果文件中包含敏感内容，将其添加至
```
.gitignore
```
。
不要为路径D发明指标。仅编码用户定义的内容。

Templates

模板

```
templates/semantic.yaml
```
— single-file schema for Path D.

```
templates/semantic.yaml
```
— 路径D使用的单文件架构。

add-semantic-layer

Original

Translation

add-semantic-layer

接入语义层

When to add — and when not to

何时接入——何时不接入

Step 1 — Pick the tool

步骤1 — 选择工具

Path A — dbt MetricFlow (dbt Cloud with Semantic Layer)

路径A — dbt MetricFlow（带语义层的dbt Cloud）

Path B — Snowflake views / semantic views

路径B — Snowflake视图/语义视图

Path C — Other (no obvious MCP)

路径C — 其他（无明确MCP）

Path D — nao semantic files

路径D — nao语义文件

Validate

验证

Recommend next step

推荐下一步

Guardrails

约束规则

Templates

模板