企业官网建设流程全解析

ShardingSphere-MCP 查询结果被截断时如何缩小查询并调整返回行数

【免费下载链接】shardingsphereEmpowering Data Intelligence with Distributed SQL for Sharding, Scalability, and Security Across All Databases.项目地址: https://gitcode.com/GitHub_Trending/sh/shardingsphere

通过 AI 应用让 ShardingSphere-MCP 执行只读查询时，返回的结果可能只包含一部分行：查询本身执行成功，但受运行时保护限制，结果被截断。这是 MCP Server 的明确边界：查询默认最多返回 100 行，单次查询最多可请求 5000 行，结果被截断时处理方式是缩小查询条件、减少返回列或降低返回行数。本文按"判断保护类型 → 缩小查询并调整行数 → 验证结果"这条路径，把查询结果恢复到完整可用的状态。

前提条件

• ShardingSphere-MCP 已完成部署，且 AI 应用能连上 MCP Server（HTTP 或 STDIO），可参考快速开始和部署说明中的健康检查。
• 配置文件中runtimeDatabases至少配置了一项运行时数据库，自然语言任务中引用的数据库名称与配置一致，详见配置说明。
• 当前执行的是只读查询。database_gateway_execute_query只接受已判定为查询类的SELECT，DML、DDL、DCL、事务控制、savepoint 等 SQL 会被直接拒绝，这类拒绝不属于截断问题。

先判断触发的是哪一种保护

常见问题页面的"运行时保护"表列出了与查询相关的保护项：

区分两类现象：

• 结果被截断：SQL 正常执行，但只返回了部分行。查询工具的响应中truncated为true（表示行被max_rows或服务端限制截断），可以结合returned_row_count（本次实际返回的行数）和applied_max_rows（经默认值和边界强制执行后实际应用的行数上限）交叉判断。
• 查询超时：在超时时间内没有拿到结果。处理是缩小查询范围，或在合理范围内调整超时时间，单次最大可请求 300000 毫秒。

如果排查后问题仍不在查询保护范围内，例如出现连接错误分类或"查询被拒绝"，按常见问题的问题列表和"连接错误分类"一节另行处理，不要混到截断场景里。

缩小查询：按文档顺序执行三个动作

常见问题对"查询执行失败或结果被截断"给出的处理是：先查看表结构；缩小查询条件、减少返回列、降低返回行数；必要时调整超时时间。对应到操作：

1. 先查看表结构。在 AI 应用中执行"查看orders的字段和索引"这类任务（快速开始中即用该任务验证逻辑库可用）。确认列名和索引后，才知道哪些列上有可用的过滤条件。
2. 缩小查询条件。给原SELECT增加WHERE条件，把数据范围限制到当前任务真正需要的部分。
3. 减少返回列。SELECT中只列出实际需要的列，不返回无关列。
4. 调整返回行数。行数上限的边界是：省略max_rows或传 0 时使用服务端默认的 100 行，最多可请求 5000 行。如果按 5000 行请求仍然截断，说明单次请求取不完的判断成立，此时文档给出的处理就是继续缩小查询条件、减少返回列，或降低本次请求的行数分次获取，而不是请求超过上限的行数。

在 AI 应用里，这一步直接用自然语言表达。能力清单给出的示例任务：

• "查询orders表前 10 行。"
• "查询orders表前 100 行，不要返回更多数据。"

可选分支：自研客户端直接调用工具

如果你不是通过 AI 应用，而是自研 MCP 客户端或调试协议请求，同样的调整等价于在调用database_gateway_execute_query时显式传入max_rows与timeout_ms。工具入参定义见 mcp-descriptor-core.yaml：

• database（必填）：运行时数据库名称，仅用于选择运行时连接，不要把它当作 SQL 里的库名限定符。
• sql（必填）：一条已判定为查询类的SELECT，不要包含EXPLAIN、多语句或修改类 SQL。
• max_rows：省略或传 0 使用服务端默认的 100；minimum: 0，maximum: 5000。
• timeout_ms：默认 0 表示不显式设置超时；maximum: 300000。

HTTP 调试示例（按自研集成附录的协议调试方式，仅用于开发者调试，不是普通使用流程）：

curl -sS http://127.0.0.1:18088/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Session-Id: demo-session-id' \ -H 'MCP-Protocol-Version: 2025-11-25' \ --data '{ "jsonrpc":"2.0", "id":"tool-1", "method":"tools/call", "params":{ "name":"database_gateway_execute_query", "arguments":{ "database":"logic_db", "sql":"SELECT order_id, status FROM orders", "max_rows":100, "timeout_ms":0 } } }'

其中logic_db、SQL 语句按你的实际逻辑库和表替换；MCP-Session-Id需要替换为完成initialize后获得的会话标识（附录示例中使用demo-session-id作为占位说明）。http://127.0.0.1:18088/mcp为默认端点，如果你的transport.http.port或endpointPath有自定义，端点地址同步调整。

验证结果

重新执行缩小后的查询，从响应字段确认：

• truncated为false，说明本次结果没有被max_rows或服务端限制截断；
• returned_row_count与本次实际返回行数一致；
• applied_max_rows显示实际应用的行数上限，用于确认请求的行数确实生效；
• next_actions中终端动作是Stop（"Return the result rows to the user."），表示任务可以收尾。

工具描述符中给出了如下响应示例（文档示例，数值仅演示字段结构，实际行数取决于查询结果）：

response_mode: query summary: Executed SELECT statement and returned 0 row(s). result_kind: result_set statement_class: query status: OK returned_row_count: 0 applied_max_rows: 10 applied_timeout_ms: 0 truncated: false next_actions: - order: 1 type: terminal title: Stop reason: Return the result rows to the user.

另外，查询工具的next_actions是服务端返回的结构化下一步建议，自研客户端在收到截断或失败响应后可以直接按该字段继续处理。

边界与相邻问题

• 单次查询最多可请求 5000 行，这是保护上限，文档没有提供绕过方式；取不全时按上文顺序缩小查询条件、减少返回列或降低返回行数。
• 查询超时最大可请求 300000 毫秒；超时不是靠继续加大超时解决，文档要求先缩小查询范围。
• 会话达到工具调用次数保护限制时会返回tool_call_limit_exceeded，处理方式是结束当前会话并重新创建 MCP 会话，这与结果截断无关，但排查查询问题时会碰到。
• SHOW STORAGE UNITS、SHOW SINGLE TABLES这类控制台风格元数据 SQL 会被database_gateway_execute_query拦截，需要使用对应 MCP 资源或提示，不提供原始SHOW透传。

需要继续定位协议层面的请求与响应时，参考自研集成附录中的tools/list、resources/list和 HTTP 调试示例；连接类失败按常见问题的"连接错误分类"表逐项对照。

【免费下载链接】shardingsphereEmpowering Data Intelligence with Distributed SQL for Sharding, Scalability, and Security Across All Databases.项目地址: https://gitcode.com/GitHub_Trending/sh/shardingsphere