元数据工具

元数据工具用于获取语义层模型和字段的定义信息，是查询前了解数据结构的重要工具。

list_models

首选的模型发现工具。它返回当前 namespace 中可用于路由的模型概览；需要字段、度量、权限或查询能力详情时，再调用 dataset.describe_model_internal。返回字段以运行实例 tools/list 暴露的 schema 为准，不要把模型列表缓存跨 namespace 复用。

基本信息

• 工具名称: dataset.list_models
• 分类: 元数据
• 权限: 以当前 MCP endpoint 和 namespace 的工具策略为准

推荐调用顺序

dataset.list_models
  → dataset.describe_model_internal
  → dataset.query_model 或 dataset.compose_script

get_metadata

兼容性说明：dataset.get_metadata 是旧元数据入口。新集成应使用 dataset.list_models；保留本节是为了迁移旧客户端。

获取用户可访问的所有语义层模型列表。

基本信息

• 工具名称: dataset.get_metadata
• 分类: 元数据
• 权限: Admin, Analyst

参数说明

此工具无需参数。

调用示例

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "dataset.get_metadata",
    "arguments": {}
  }
}

响应格式

{
  "success": true,
  "data": {
    "models": [
      {
        "name": "FactSalesQueryModel",
        "caption": "销售分析",
        "description": "销售订单明细数据"
      },
      {
        "name": "FactOrderQueryModel",
        "caption": "订单分析",
        "description": "订单信息查询"
      }
    ],
    "fieldIndex": {
      "customerName": ["FactSalesQueryModel", "FactOrderQueryModel"],
      "totalAmount": ["FactSalesQueryModel"]
    },
    "dictionaries": {
      "customerType": {
        "10": "个人客户",
        "20": "企业客户",
        "30": "VIP客户"
      }
    }
  }
}

返回内容

使用场景

• 用户询问"有哪些可用的语义层模型"
• 查询前需要了解数据范围
• 探索不同模型间的字段关联

describe_model_internal

获取指定模型的详细字段定义。

基本信息

• 工具名称: dataset.describe_model_internal
• 分类: 元数据
• 权限: Admin, Analyst

参数说明

调用示例

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "dataset.describe_model_internal",
    "arguments": {
      "model": "FactSalesQueryModel"
    }
  }
}

响应格式

{
  "success": true,
  "data": {
    "model": "FactSalesQueryModel",
    "caption": "销售分析",
    "description": "销售订单明细数据分析",
    "fields": [
      {
        "name": "customer$id",
        "type": "DIMENSION",
        "caption": "客户ID",
        "description": "用于精确查询"
      },
      {
        "name": "customer$caption",
        "type": "DIMENSION",
        "caption": "客户名称",
        "description": "用于展示"
      },
      {
        "name": "totalAmount",
        "type": "MEASURE",
        "caption": "销售金额",
        "dataType": "MONEY",
        "aggregation": "SUM"
      },
      {
        "name": "orderStatus",
        "type": "ATTRIBUTE",
        "caption": "订单状态",
        "dictionary": "orderStatus"
      }
    ],
    "dictionaries": {
      "orderStatus": {
        "1": "待支付",
        "2": "已支付",
        "3": "已发货",
        "4": "已完成",
        "5": "已取消"
      }
    }
  }
}

字段类型

维度字段变体

维度字段会返回两个变体：

示例：

{
  "columns": ["customer$caption"],  // 展示客户名称
  "slice": [
    {"field": "customer$id", "op": "=", "value": 1001}  // 按ID过滤
  ]
}

父子维度

层级结构维度额外支持 $hierarchy$ 视角：

示例： 查询总公司及所有子部门

{
  "slice": [
    {"field": "team$hierarchy$id", "op": "=", "value": "T001"}
  ]
}

使用场景

• 查询前确认字段名和类型
• 了解字典字段的可选值
• 确认维度的 $id / $caption 用法

典型工作流

1. get_metadata
   → 获取所有可用模型列表

2. describe_model_internal
   → 选择目标模型，获取详细字段

3. query_model
   → 使用正确的字段名执行查询

下一步

• 查询工具 - 执行数据查询
• 自然语言查询 - 智能查询
• 工具概述 - 返回工具列表