版本：26.x

用户指南

本页面向 SelectDB 的用户。管理员已经为你部署好了 SelectDB MCP 服务,你只需要知道:

如何把服务接入 AI Agent(Claude Code / Cursor / Codex)
如何通过 AI 对话查询数据

语义模型的定义与管理(管理员)请看语义模型。

接入 AI Agent（Claude Code / Cursor / Codex）

接入前，准备好以下信息：

MCP 连接地址：在控制台 Connection 页 → Connection Methods → 复制 MCP Connection URL。
SelectDB 账号密码：用于认证（格式 用户名:密码，如 admin:admin）
Workspace 名称：语义模型所在的工作区（默认 example）

接入 Claude Code

步骤 1：添加 MCP Server

claude mcp add --transport http selectdb <MCP-Connection-URL> \
  --header "Authorization: Bearer admin:admin"

步骤 2：验证连接

在 Claude Code 对话中输入：

检查服务健康状态

AI 会自动调用 check_service_health，返回 SelectDB 连接状态和所有 workspace 状态。如果看到 "selectdb": "connected" 说明接入成功。

步骤 3：开始查询

列出所有可用指标

AI 会自动按三步流程操作：list_metrics → list_dimensions_for_metric → query_metric。

接入 Cursor / VS Code

在项目根目录创建 .cursor/mcp.json 或 VS Code 的 MCP 配置：

{
  "mcpServers": {
    "selectdb": {
      "url": "<MCP-Connection-URL>",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer admin:admin"
      }
    }
  }
}

可用 Tool 一览（共 10 个）

启动 & 健康检查（Agent 对话开始时先调这里）

Tool	参数	用途
`get_query_guide`	—	第一步必调。返回完整工作流指引：何时用语义层 vs 裸 SQL、工具调用顺序、查询语法。不调此工具 Agent 会走弯路。
`check_service_health`	detail(可选)	返回 SelectDB 连通性 + 每个 workspace 的状态（healthy / no_models / not_ready）和指标数量。首次对话必调。

语义查询（推荐优先使用，自动生成正确 SQL）

Tool	参数	用途
`list_metrics`	workspace(必填), page_size, page_token	列出所有可用指标（name + description）。Agent 根据用户意图匹配指标。
`list_dimensions_for_metric`	workspace(必填), metric_name(必填)	返回指标的可用 group_by 维度（name + type + description）。确保 group_by 不报错。
`query_metric`	workspace(必填), metrics(必填), group_by, where, order_by, limit, having, database, max_rows	核心查询工具。编译 + 执行语义查询。涉及计数/求和/比率/排名/趋势都必须走这里。支持 HAVING 过滤聚合结果。database 指定目标库，max_rows 硬限制返回行数（0=默认10000）。
`reload_semantic_layer`	workspace(必填)	手动触发语义层重载。管理员修改 YAML 模型并 commit 后如需立即生效可调用，否则 60s 自动轮询。

底层元数据 & 裸 SQL（仅在以下两种场景使用）

两种裸 SQL 场景：

场景 A — 语义层不可用：check_service_health 返回所有 workspace 都不是 healthy（no_models / not_ready）。此时所有查询只能走 list_databases → list_tables → describe_table → execute_query。
**场景 B — 无匹配指标：**语义层 healthy，但 list_metrics 中没有任何指标能匹配用户意图。此时同样回退到裸 SQL 路径。

Tool	参数	用途
`list_databases`	page_size, page_token	列出所有数据库。探索阶段可用，但不能替代 `list_metrics`。
`list_tables`	database(必填), like, page_size, page_token	列出库中的表名。仅返回表名，不含列信息。想看列用 `describe_table`。
`describe_table`	database(必填), table(必填), detail_level	查看物理表结构（列名、类型）。detail_level: names/summary/full。
`execute_query`	sql(必填), database, max_rows	裸 SQL 兜底。仅允许只读（SELECT/SHOW/DESCRIBE/EXPLAIN）。如果语义层有匹配指标，优先用 `query_metric`。

Agent 推荐工作流

每次对话的标准流程：

get_query_guide() — 获取完整指引（Agent 知道何时用哪个工具）
check_service_health() — 确认 SelectDB 连通，查看可用 workspace
路由判断：

用户问"有多少"、"计算"、"趋势"、"比率" → 走语义层 4-5-6

用户问"看表结构"、"有哪些库" → 走元数据工具
语义层不可用（所有 workspace 非 healthy）→ 跳过 4-6，直接走 7
list_metrics(workspace) — 列出指标，匹配用户意图
list_dimensions_for_metric(workspace, metric_name) — 获取可用维度
query_metric(workspace, metrics, group_by, ...) — 执行查询
**兜底：**如果步骤 4 没有匹配的指标，用 list_databases → list_tables → describe_table → execute_query 走裸 SQL 路径

关键禁区：

语义层 healthy + 有匹配指标 → 绝不允许绕开 query_metric 直接用 execute_query 写 SQL。
语义层 healthy + 无匹配指标 → 先告知用户"语义层没有覆盖此查询"，再用 execute_query，并在结果中附警告。

对话示例

用户：最近一个月各渠道的订单总额是多少？

AI 思考：
  1. get_query_guide → 获取指引 ✓
  2. check_service_health → workspace "example" healthy, 5 metrics ✓
  3. 涉及"总额"、"渠道" → 走语义层
  4. list_metrics(example) → total_amount（订单总金额）✓
  5. list_dimensions_for_metric(example, total_amount) → channel ✓
  6. query_metric(example, metrics=[total_amount], group_by=[channel],
                  where="order_date >= '2026-04-30'")

AI 回复：
  渠道    订单总额
  WEB    1,096.00
  APP    2,396.00
  MINI     298.00

可用的查询能力

接入后，你在 Claude Code 对话中直接用自然语言提问，AI 会自动调用对应的 MCP Tool。

元数据发现

你想做什么	直接说	调用了哪个 Tool
看有哪些库	"列出所有数据库"	`list_databases`
看库下有哪些表	"列出 dw 库的表"	`list_tables`
看表结构	"查看 orders 表有哪些字段"	`describe_table`

SQL 查询

你想做什么	直接说	调用了哪个 Tool
查数据	"查询 top 10 订单"	`execute_query`
统计分析	"按状态统计订单数"	`execute_query`

execute_query 只允许只读 SQL（SELECT / SHOW / DESCRIBE / EXPLAIN）。

语义层查询（需要管理员配置了语义模型）

如果你的 SelectDB 集群配置了语义层，Agent 三步即可完成查询：

list_metrics — 列出所有可用指标（name + description）
list_dimensions_for_metric — 查看指标的可用维度（name + type + description）
query_metric — 执行语义查询（支持 having 过滤聚合结果）

你想做什么	直接说	调用了哪个 Tool
看有哪些指标	"列出所有指标"	`list_metrics`
查营收趋势	"查询过去 7 天的营收，按天分组"	`query_metric`
看可用维度	"total_amount 可以按哪些维度分析"	`list_dimensions_for_metric`
检查服务状态	"检查服务健康状态"	`check_service_health`

所有语义工具必传 workspace 参数（默认可用 "example"）。

查询示例

示例 1：探索数据结构

你：列出所有数据库
AI：[调用 list_databases]
    dw

你：看看 dw 库里有哪些表
AI：[调用 list_tables]
    orders, users, products, dim_date

你：看一下 orders 表的结构
AI：[调用 describe_table]
    列名        类型      注释
    order_id    BIGINT    订单ID
    user_id     BIGINT    用户ID
    amount      DECIMAL   金额
    channel     VARCHAR   渠道
    status      VARCHAR   状态
    order_date  DATE      下单日期

示例 2：数据查询

你：查一下最近一周各状态的订单数和总金额
AI：[调用 execute_query]
    status      count   total_amount
    completed   1234    567890.00
    pending     567     89012.00
    cancelled   89      12345.00

示例 3：语义指标

你：列出所有可用的指标
AI：[调用 list_metrics]
    total_amount      订单总金额
    order_count       订单数
    avg_amount        平均客单价
    unique_users      下单用户数
    user_count        用户数

你：查询最近 7 天各渠道的订单总金额
AI：[调用 list_dimensions_for_metric] → channel
    [调用 query_metric]
    渠道      总金额
    线上      12345.00
    线下      15678.00
    ...

常见问题

Q: 连不上，报 401

确认 Token 格式正确：用户名:密码（英文冒号分隔）。

Q: 语义查询报错 "workspace not found"

确认 workspace 名称正确，默认可用 "example"。登录 WebUI 查看可用 workspace。

Q: 能否执行写操作？

不能。execute_query 仅允许只读 SQL（SELECT / SHOW / DESCRIBE / EXPLAIN）。

Q: 查询很慢？

数据量大时让 AI 加 LIMIT 或缩小时间范围。

Q: 语义层能用哪些指标？

让 AI 说"列出所有指标"即可（自动调用 list_metrics）；或登录 WebUI 在对应 workspace 查看。

下一步

语义模型 — 管理员:用 YAML 定义实体、维度、度量与指标。

接入 AI Agent（Claude Code / Cursor / Codex）​

接入 Claude Code​

接入 Cursor / VS Code​

可用 Tool 一览（共 10 个）​

Agent 推荐工作流​

对话示例​

可用的查询能力​

元数据发现​

SQL 查询​

语义层查询（需要管理员配置了语义模型）​

查询示例​

示例 1：探索数据结构​

示例 2：数据查询​

示例 3：语义指标​

常见问题​

Q: 连不上，报 401​

Q: 语义查询报错 "workspace not found"​

Q: 能否执行写操作？​

Q: 查询很慢？​

Q: 语义层能用哪些指标？​

下一步​