为 SQL MCP 服务器实体添加说明

IMPORTANT

SQL Model Context Protocol（MCP）Server 自 数据墙DBW 1.7 及以上版本开始提供。

说明（Descriptions）是一种语义元数据，可帮助 AI 代理理解 SQL Model Context Protocol（MCP）Server 的数据库 schema。当你为实体、字段和参数添加说明时，语言模型就能更准确地判断要查询哪些数据，以及如何正确使用它们。本文将展示如何通过数据墙DBW CLI 在各个层级添加说明，从而提升 AI 代理准确性和工具发现效果。

为什么要添加说明？

AI 代理依赖上下文来理解你的数据。如果没有说明，代理看到的只是类似 ProductID 或 dbo.Orders 这样的技术名称。有了说明后，代理就能理解 ProductID 是“产品目录中每个产品的唯一标识符”，而 dbo.Orders 存放的是“包含行项目和物流信息的客户采购订单”。

说明可以改进：

• 工具发现 - 代理能更快找到正确实体
• 查询准确性 - 代理在具备上下文后能构造更准确的查询
• 参数使用 - 代理能为存储过程提供正确参数值
• 字段选择 - 代理只返回真正相关的字段

TIP

这些说明会通过 describe_entities MCP 工具暴露给代理，有助于语言模型在不猜测的情况下做出更合理的决策。

实体说明

实体说明用于解释表、视图或存储过程代表什么。你可以在创建实体或更新实体时添加它们。

使用 dab add 添加说明

在新增实体时，可使用 --description 标志：

dab add Products \
  --source dbo.Products \
  --permissions "anonymous:*" \
  --description "Product catalog with pricing, inventory, and supplier information"

使用 dab update 添加说明

你也可以为现有实体添加或修改说明：

dab update Products \
  --description "Product catalog with pricing, inventory, and supplier information"

示例

表说明：

dab add Orders \
  --source dbo.Orders \
  --permissions "authenticated:read" \
  --description "Customer purchase orders with line items, shipping details, and payment status"

视图说明：

dab add ActiveProducts \
  --source dbo.vw_ActiveProducts \
  --source.type view \
  --fields.name "ProductID" \
  --fields.primary-key "true" \
  --permissions "anonymous:read" \
  --description "Currently available products with positive inventory and active status"

存储过程说明：

dab add GetOrderHistory \
  --source dbo.usp_GetOrderHistory \
  --source.type stored-procedure \
  --permissions "authenticated:execute" \
  --description "Retrieves complete order history for a customer including items, totals, and shipping tracking"

字段说明

字段说明用于解释每一列代表什么。它们帮助代理理解单个数据点的用途和业务含义。

使用 dab update 添加字段说明

请结合使用 --fields.name 和 --fields.description：

dab update Products \
  --fields.name ProductID \
  --fields.description "Unique identifier for each product" \
  --fields.primary-key true

添加多个字段说明

你可以通过多次调用 dab update 为多个字段添加说明：

dab update Products \
  --fields.name ProductID \
  --fields.description "Unique identifier for each product" \
  --fields.primary-key true

dab update Products \
  --fields.name ProductName \
  --fields.description "Display name of the product"

dab update Products \
  --fields.name UnitPrice \
  --fields.description "Retail price per unit in USD"

dab update Products \
  --fields.name UnitsInStock \
  --fields.description "Current inventory count available for purchase"

dab update Products \
  --fields.name Discontinued \
  --fields.description "True if product is no longer available for sale"

字段说明最佳实践

请使用清晰、简洁的说明，并尽量包含以下内容：

• Purpose - 字段表示什么
• Units - 货币、计量单位、时区等
• Format - 日期格式、字符串模式等
• Business rules - 有效范围、约束等

好的示例：

# 包含单位
dab update Products \
  --fields.name Weight \
  --fields.description "Product weight in kilograms"

# 包含格式细节
dab update Orders \
  --fields.name OrderDate \
  --fields.description "Order placement date in UTC (ISO 8601 format)"

# 包含业务上下文
dab update Employees \
  --fields.name HireDate \
  --fields.description "Date employee was hired, used for calculating benefits eligibility"

# 包含约束
dab update Products \
  --fields.name ReorderLevel \
  --fields.description "Minimum stock level that triggers automatic reorder (must be positive integer)"

参数说明

参数说明帮助代理理解在执行存储过程时应提供什么值。对于调用存储过程的 MCP 工具来说，这一点尤其重要。

使用 dab add 添加参数说明

在新增存储过程时，使用逗号分隔的参数元数据列表：

dab add GetOrdersByDateRange \
  --source dbo.usp_GetOrdersByDateRange \
  --source.type stored-procedure \
  --permissions "authenticated:execute" \
  --description "Retrieves all orders placed within a specified date range" \
  --parameters.name "StartDate,EndDate,CustomerID" \
  --parameters.description "Beginning of date range (inclusive),End of date range (inclusive),Optional customer ID filter (null returns all customers)" \
  --parameters.required "true,true,false" \
  --parameters.default ",,null"

使用 dab update 添加参数说明

你也可以在已有存储过程上更新参数说明：

dab update GetOrdersByDateRange \
  --parameters.name "StartDate,EndDate,CustomerID" \
  --parameters.description "Beginning of date range (inclusive),End of date range (inclusive),Optional customer ID filter (null returns all customers)" \
  --parameters.required "true,true,false"

参数说明格式

参数元数据使用多个逗号分隔列表，规则如下：

• --parameters.name - 按顺序列出参数名
• --parameters.description - 与之对应的说明列表
• --parameters.required - 每个参数是否必填（true / false）
• --parameters.default - 默认值（必填参数可用空字符串）

带详细参数说明的示例：

dab add SearchProducts \
  --source dbo.usp_SearchProducts \
  --source.type stored-procedure \
  --permissions "anonymous:execute" \
  --description "Searches products by keyword, category, and price range" \
  --parameters.name "SearchTerm,CategoryID,MinPrice,MaxPrice,PageSize,PageNumber" \
  --parameters.description "Keyword to search in product names and descriptions,Product category ID (null searches all categories),Minimum price filter in USD (null removes lower bound),Maximum price filter in USD (null removes upper bound),Number of results per page (default 20, max 100),Page number for pagination (1-based)" \
  --parameters.required "true,false,false,false,false,false" \
  --parameters.default ",null,null,null,20,1"

完整工作流示例

下面展示一个在所有层级都添加说明的完整示例：

1. 创建带说明的实体

dab add Customers \
  --source dbo.Customers \
  --permissions "authenticated:read,update" \
  --description "Customer master records including contact information, billing preferences, and account status"

2. 添加字段说明

dab update Customers \
  --fields.name CustomerID \
  --fields.description "Unique customer identifier (auto-generated)" \
  --fields.primary-key true

dab update Customers \
  --fields.name CompanyName \
  --fields.description "Customer company or organization name"

dab update Customers \
  --fields.name ContactEmail \
  --fields.description "Primary contact email address for order notifications"

dab update Customers \
  --fields.name Phone \
  --fields.description "Primary phone number in E.164 format (+1234567890)"

dab update Customers \
  --fields.name AccountBalance \
  --fields.description "Current account balance in USD (negative indicates credit)"

dab update Customers \
  --fields.name PreferredCurrency \
  --fields.description "Customer's preferred billing currency (ISO 4217 code)"

dab update Customers \
  --fields.name IsActive \
  --fields.description "Account status flag (false indicates suspended or closed account)"

dab update Customers \
  --fields.name CreatedDate \
  --fields.description "Account creation timestamp in UTC"

dab update Customers \
  --fields.name LastOrderDate \
  --fields.description "Date of most recent order (null for customers with no orders)"

3. 添加带参数说明的相关存储过程

dab add UpdateCustomerPreferences \
  --source dbo.usp_UpdateCustomerPreferences \
  --source.type stored-procedure \
  --permissions "authenticated:execute" \
  --description "Updates customer communication and billing preferences" \
  --parameters.name "CustomerID,EmailNotifications,SMSNotifications,PreferredCurrency,MarketingOptIn" \
  --parameters.description "Customer ID to update,Enable email notifications for orders and promotions,Enable SMS notifications for shipping updates,Preferred billing currency (ISO 4217 code),Opt in to marketing communications" \
  --parameters.required "true,false,false,false,false" \
  --parameters.default ",true,false,USD,false"

在配置中查看说明

这些说明会被存储到你的 dab-config.json 中。示例如下：

{
  "entities": {
    "Products": {
      "description": "Product catalog with pricing, inventory, and supplier information",
      "source": {
        "object": "dbo.Products",
        "type": "table"
      },
      "fields": [
        {
          "name": "ProductID",
          "description": "Unique identifier for each product",
          "primary-key": true
        },
        {
          "name": "ProductName",
          "description": "Display name of the product",
          "primary-key": false
        },
        {
          "name": "UnitPrice",
          "description": "Retail price per unit in USD",
          "primary-key": false
        }
      ],
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Products",
          "plural": "Products"
        }
      },
      "rest": {
        "enabled": true
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "*"
            }
          ]
        }
      ]
    },
    "GetOrdersByDateRange": {
      "description": "Retrieves all orders placed within a specified date range",
      "source": {
        "object": "dbo.usp_GetOrdersByDateRange",
        "type": "stored-procedure",
        "parameters": [
          {
            "name": "StartDate",
            "description": "Beginning of date range (inclusive)",
            "required": true,
            "default": ""
          },
          {
            "name": "EndDate",
            "description": "End of date range (inclusive)",
            "required": true,
            "default": ""
          },
          {
            "name": "CustomerID",
            "description": "Optional customer ID filter (null returns all customers)",
            "required": false,
            "default": "null"
          }
        ]
      },
      "graphql": {
        "enabled": true,
        "operation": "mutation",
        "type": {
          "singular": "GetOrdersByDateRange",
          "plural": "GetOrdersByDateRanges"
        }
      },
      "rest": {
        "enabled": true,
        "methods": [
          "post"
        ]
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ]
    }
  }
}

代理如何使用这些说明

当 AI 代理调用 describe_entities MCP 工具时，它会连同 schema 信息一起收到你的说明：

{
  "entities": [
    {
      "name": "Products",
      "description": "Product catalog with pricing, inventory, and supplier information",
      "fields": [
        {
          "name": "ProductID",
          "type": "int",
          "description": "Unique identifier for each product",
          "isKey": true
        },
        {
          "name": "UnitPrice",
          "type": "decimal",
          "description": "Retail price per unit in USD"
        }
      ],
      "operations": ["read_records", "create_record", "update_record"]
    }
  ]
}

代理会利用这些信息：

• 选择正确实体 - 将用户意图与实体说明进行匹配
• 选择相关字段 - 根据说明只返回需要的字段
• 构造准确查询 - 理解关系和约束
• 提供正确参数 - 为存储过程传递合适的值

最佳实践

应该做

• 写得具体 - “Customer shipping address” 比 “Address” 更好
• 包含单位 - “Price in USD”、"Weight in kilograms"
• 说明格式 - “ISO 8601 date format”、"E.164 phone format"
• 解释业务规则 - “Negative values indicate credit balance”
• 注明可选字段 - “Optional; null returns all results”
• 保持说明最新 - schema 变化时同步更新说明

不应该做

• 不要只写技术术语 - 需要把业务上下文一起写出来
• 不要重复字段名 - 例如 “ProductID is the product ID” 没有任何增益
• 不要写成长篇小说 - 建议控制在一到两句话
• 不要忽略参数顺序 - 确保逗号分隔列表严格对齐
• 不要忽视可空字段 - 需要指出 null 值是否有特殊含义

脚本化批量更新说明

对于大 schema，你可以通过脚本循环批量添加字段说明：

#!/bin/bash

# Products 表的字段说明数组
declare -a fields=(
  "ProductID:Unique identifier for each product:true"
  "ProductName:Display name of the product:false"
  "SupplierID:ID of the supplier providing this product:false"
  "CategoryID:Product category classification:false"
  "QuantityPerUnit:Standard packaging quantity (e.g., '12 bottles per case'):false"
  "UnitPrice:Retail price per unit in USD:false"
  "UnitsInStock:Current inventory count available for purchase:false"
  "UnitsOnOrder:Quantity ordered from supplier but not yet received:false"
  "ReorderLevel:Minimum stock level that triggers automatic reorder:false"
  "Discontinued:True if product is no longer available for sale:false"
)

# 循环添加说明
for field in "${fields[@]}"; do
  IFS=':' read -r name desc is_pk <<< "$field"
  if [ "$is_pk" = "true" ]; then
    dab update Products --fields.name "$name" --fields.description "$desc" --fields.primary-key true
  else
    dab update Products --fields.name "$name" --fields.description "$desc"
  fi
done

相关内容

• SQL MCP 服务器概述
• SQL MCP 数据操作工具
• entities 配置参考页可在对应专题中查看
• dab add 命令参考页：/data-api-builder/reference/cli/dab-add
• dab update 命令参考页：/data-api-builder/reference/cli/dab-update