数据墙DBW 文档

Appearance

SQL MCP 服务器中的数据操作语言（DML）工具 ​

IMPORTANT

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

SQL Model Context Protocol（MCP）Server 会向 AI 代理公开七个数据操作语言（DML）工具。这些工具为数据库操作提供了类型化的 CRUD 表面，包括：创建、读取、更新、删除记录，执行聚合查询，以及运行存储过程。所有工具都会遵守你配置中定义的基于角色的访问控制（RBAC）、实体权限和策略。

什么是 DML 工具？ ​

DML（Data Manipulation Language）工具用于处理数据操作：创建、读取、更新和删除记录，执行聚合查询，以及运行存储过程。与修改 schema 的 DDL（Data Definition Language）不同，DML 只作用于现有表和视图的数据平面。

这七个 DML 工具包括：

  • describe_entities - 发现可用实体和操作
  • create_record - 插入新行
  • read_records - 查询表和视图
  • update_record - 修改已有行
  • delete_record - 删除行
  • execute_entity - 运行存储过程
  • aggregate_records - 执行聚合查询

NOTE

SQL MCP Server 2.0 预览相关说明页可在对应专题中查看。

当全局启用 DML 工具，且某个实体也允许 DML 工具时，SQL MCP 服务器就会通过 MCP 协议把它们公开出来。代理永远不会直接与数据库 schema 交互，而是通过数据墙DBW的抽象层工作。

这些工具 ​

list_tools 响应 ​

当代理调用 list_tools 时，SQL MCP 服务器返回：

json
{
  "tools": [
    { "name": "describe_entities" },
    { "name": "create_record" },
    { "name": "read_records" },
    { "name": "update_record" },
    { "name": "delete_record" },
    { "name": "execute_entity" },
    { "name": "aggregate_records" }
  ]
}

describe_entities ​

返回当前角色可见的实体。每个条目都包含字段名、说明和允许的操作。该工具不会查询数据库，而是从基于配置文件构建出的内存配置中读取信息。

IMPORTANT

describe_entities 中的 fields 信息来自你在配置中提供的 fields 数据。由于字段元数据是可选的，如果你没有提供它，代理只能看到实体名，而 fields 数组会是空的。最佳实践是在配置中同时提供字段名称和字段说明，这些元数据能让代理在生成查询和更新时拥有更多上下文。字段说明专题页可在对应专题中查看。

NOTE

当前响应中只包含来自配置的字段 name 和 description。数据类型和主键标志暂不会出现在响应中，存储过程参数也不会列出。代理需要依靠实体与字段说明，以及错误反馈，来推断正确用法。

参数 ​

参数类型必需说明
nameOnlybooleanNo当为 true 时，仅返回实体名和说明，不返回字段元数据。
entitiesstring 数组No仅限制返回指定实体。省略时，返回全部启用 MCP 的实体。

请求示例 ​

json
{
  "method": "tools/call",
  "params": {
    "name": "describe_entities",
    "arguments": {
      "entities": ["Products"]
    }
  }
}

响应示例 ​

json
{
  "entities": [
    {
      "name": "Products",
      "description": "Product catalog with pricing and inventory",
      "fields": [
        {
          "name": "ProductId",
          "description": "Unique product identifier"
        },
        {
          "name": "ProductName",
          "description": "Display name of the product"
        },
        {
          "name": "Price",
          "description": "Retail price in USD"
        }
      ],
      "operations": [
        "read_records",
        "update_record"
      ]
    }
  ]
}

NOTE

任何 CRUD 或 execute DML 工具所使用的实体选项，都直接来自 describe_entities。附加在每个工具上的内部语义说明也会强制代理遵循这种“两步式”流程。

create_record ​

在表中创建一条新记录。要求当前角色对该实体拥有 create 权限。该工具会根据实体 schema 校验输入，执行字段级权限检查，应用 create 策略，并返回包含自动生成值在内的创建结果。

参数 ​

参数类型必需说明
entitystringYes要创建记录的实体名。
dataobjectYes新记录的字段名 / 值对。

read_records ​

查询表或视图。支持筛选、排序、分页和字段选择。该工具会根据结构化参数构建确定性的 SQL，应用读取权限和字段投影，并执行行级安全策略。

参数 ​

参数类型必需说明
entitystringYes要读取的实体名。
selectstringNo以逗号分隔的字段列表（例如 "id,title,price"）。
filterstringNoOData 风格的筛选表达式（例如 "Price gt 10 and Category eq 'Books'"）。
orderbystring 数组No排序表达式数组，例如 ["Price desc", "Name asc"]。
firstintegerNo返回的最大记录数。
afterstringNo来自上一响应的 continuation cursor，用于分页。

WARNING

orderby 参数必须是字符串数组，而不是单个字符串。传入字符串值会触发 UnexpectedError。请使用 ["Name asc"]，不要使用 "Name asc"。

分页响应 ​

当后续还有更多结果时，响应中会包含 after 游标。你可以在下一次请求中把这个值作为 after 参数传回，以继续获取下一页。

json
{
  "value": [ ... ],
  "after": "W3siRW50aXR5TmFtZ..."
}

只要存在 after 字段，就表示还有后续页；当 after 缺失时，说明已经到达最后一页。

IMPORTANT

read_records 的结果会自动使用数据墙DBW的缓存系统进行缓存。你可以全局或按实体配置缓存 TTL，以降低数据库压力。缓存专题页已在当前中文站中提供。

JOIN 操作 ​

read_records 工具是为单表或单视图设计的，因此它不支持 JOIN 操作。这种设计有助于隔离职责、提升性能，并降低会话上下文窗口的消耗。

不过，JOIN 并不是边缘需求，而且数据墙DBW已经通过 GraphQL 终结点支持更复杂的查询。对于复杂查询，推荐使用视图替代表。你也可以使用 execute_entity 工具执行存储过程，把参数化查询封装起来。

update_record ​

修改一条现有记录。需要提供主键和值得更新的字段。该工具会校验主键是否存在，执行更新权限与策略检查，并且只更新当前角色可修改的字段。

参数 ​

参数类型必需说明
entitystringYes要更新的实体名。
keysobjectYes标识记录的键值对，例如 {"id": 42}。
fieldsobjectYes要更新的字段名 / 新值对。

delete_record ​

删除一条现有记录。需要提供主键。该工具会校验主键存在性，执行删除权限与策略检查，并在事务支持下安全删除目标数据。

参数 ​

参数类型必需说明
entitystringYes要删除记录所在的实体名。
keysobjectYes标识记录的键值对，例如 {"id": 42}。

NOTE

某些生产场景会在全局层面禁用这个工具，以对模型施加更强的约束。是否这么做取决于你的需求，但仍需记住：实体级权限才是控制访问最重要的方式。即便启用了 delete-record，如果角色没有该实体的删除权限，也依然不能使用此工具删除该实体的数据。

execute_entity ​

执行一个存储过程。支持输入参数和输出结果。该工具会根据过程签名校验输入参数、执行 execute 权限检查，并安全传递参数。

参数 ​

参数类型必需说明
entitystringYes存储过程实体名称。
parametersobjectNo输入参数名称 / 值对。

aggregate_records ​

对表和视图执行聚合查询。支持常见聚合函数，例如 count、sum、average、minimum 和 maximum。该工具会根据结构化参数构建确定性的 SQL，应用读取权限与字段投影，并执行行级安全策略。

参数 ​

参数类型必需说明
entitystringYes要聚合的实体名。
functionstringYes聚合函数：count、sum、avg、min 或 max。
fieldstringYes要聚合的字段。对 count 可使用 "*"。
filterstringNo聚合前应用的 OData 风格筛选。
distinctbooleanNo当为 true 时，聚合前会先去重。
groupbystring 数组No分组字段，例如 ["Category", "Status"]。
havingobjectNo对聚合结果分组后的过滤。支持 eq、neq、gt、gte、lt、lte、in。
orderbystring 数组No对分组结果排序，例如 ["count desc"]。
firstintegerNo返回的最大分组结果数。
afterstringNo用于分页分组结果的 continuation cursor。

示例：带 groupby 和 having 的 count ​

json
{
  "method": "tools/call",
  "params": {
    "name": "aggregate_records",
    "arguments": {
      "entity": "Todo",
      "function": "count",
      "field": "*",
      "groupby": ["UserId"],
      "having": { "gt": 2 }
    }
  }
}

aggregate-records 工具既可以配置为布尔值，也可以配置为带更多设置的对象：

json
{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

其中 query-timeout 指定最大执行时长（单位秒，范围 1–600）。此设置有助于防止长时间运行的聚合查询消耗过多资源。

运行时配置 ​

在 dab-config.json 的运行时部分全局配置 DML 工具：

json
{
  "runtime": {
    "mcp": {
      "enabled": true,
      "path": "/mcp",
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": true
      }
    }
  }
}

runtime.mcp.dml-tools 下每个工具属性都接受 true 或 false。其中 aggregate-records 还支持对象形式，包含 enabled 和 query-timeout：

json
{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

若要一次性启用或禁用全部 DML 工具，可将 "dml-tools" 直接设为 true 或 false。

使用 CLI ​

你也可以通过数据墙DBW CLI 单独设置这些属性：

bash
dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true
dab configure --runtime.mcp.dml-tools.aggregate-records.query-timeout 30

禁用工具 ​

当你在运行时层面禁用某个工具时，它就永远不会出现在代理视野中，无论实体权限或角色配置如何。这个设定适合那些需要严格操作边界的场景。

常见场景 ​

  • 禁用 delete-record，防止生产环境数据误删
  • 对只读报表终结点禁用 create-record
  • 若不使用存储过程，则禁用 execute-entity
  • 若不需要聚合查询，则禁用 aggregate-records

当某个工具在全局被禁用时，它会从 list_tools 响应中消失，也无法被调用。

实体级设置 ​

默认情况下，只要全局启用了 MCP，实体就会自动参与 MCP，除非你显式限制它。实体上的 mcp 属性用于控制该实体是否参与 MCP。若需要精细控制，请使用对象格式。

对象格式 ​

json
{
  "entities": {
    "Products": {
      "mcp": {
        "dml-tools": true
      }
    },
    "SensitiveData": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

如果实体上未显式指定 mcp，那么在全局启用 MCP 时，DML 工具会默认开启。

面向存储过程的自定义工具 ​

对于存储过程实体，可使用 custom-tool 属性将其注册为命名 MCP 工具：

json
{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id"
      },
      "mcp": {
        "custom-tool": true
      }
    }
  }
}

IMPORTANT

custom-tool 属性仅适用于存储过程实体。若把它设置在表或视图实体上，会导致配置错误。

每个工具的控制范围 ​

每个工具的开关仅在全局运行时级别（runtime.mcp.dml-tools）进行配置。

在实体级别，mcp 只是一个布尔门控，或一个包含 dml-tools 与 custom-tool 的对象。

json
{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}
json
{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": false,
        "execute-entity": true,
        "aggregate-records": true
      }
    }
  }
}

一个工具只有在全局启用且实体允许 DML 工具时才可用。

RBAC 集成 ​

每个 DML 工具操作都会严格执行你的基于角色的访问控制规则。代理角色决定：

  • 哪些实体可见
  • 哪些操作可执行
  • 哪些字段会被包含
  • 是否应用行级策略

如果 anonymous 角色仅允许对 Products 执行读取：

  • describe_entities 中只会显示 read_records
  • create_record、update_record 和 delete_record 不可用
  • schema 中只会出现 anonymous 可见的字段

在 dab-config.json 中配置角色： ​

json
{
  "entities": {
    "Products": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["ProductId", "ProductName", "Price"],
                "exclude": ["Cost"]
              }
            }
          ]
        },
        {
          "role": "admin",
          "actions": [
            {
              "action": "*"
            }
          ]
        }
      ]
    }
  }
}

相关内容 ​

  • SQL MCP 服务器概述
  • 语义描述专题页可在对应专题中查看
  • 配置参考页可在对应专题中查看
  • 实体级 MCP 配置参考页可在对应专题中查看
  • 运行时 MCP 配置参考页可在对应专题中查看

数据墙DBW 产品文档与开发指南。

Copyright © 2026 北京金数信安科技有限公司