查询超时配置

当数据库操作执行时间超过预设超时值时，引擎会终止查询并返回超时错误。数据墙DBW 本身没有全局的 query-timeout 配置项——超时通过数据库连接字符串参数和 MCP 专用设置来控制。

IMPORTANT

调高超时值可能掩盖性能问题。在提高超时上限之前，优先优化查询（添加索引、优化 WHERE 条件）、减少单次查询数据量（分页）或评估存储过程的执行计划。

数据库连接字符串超时

超时参数在连接字符串中设置，对 REST、GraphQL 和 MCP 三种协议同时生效。不同数据库的参数名和默认值不同。

SQL Server

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=host;Database=db;User Id=user;Password=pwd;Command Timeout=120;"
  }
}

参数：Command Timeout（注意中间有空格），单位秒，默认 30 秒。

PostgreSQL

{
  "data-source": {
    "database-type": "postgresql",
    "connection-string": "Host=host;Database=db;User ID=user;Password=pwd;CommandTimeout=120"
  }
}

参数：CommandTimeout，单位秒，默认 30 秒。

MySQL

{
  "data-source": {
    "database-type": "mysql",
    "connection-string": "Server=host;Database=db;User=user;Password=pwd;DefaultCommandTimeout=120"
  }
}

参数：DefaultCommandTimeout，单位秒，默认 30 秒。

三种数据库参数对照

数据库	连接字符串参数	默认值
SQL Server	Command Timeout	30 秒
PostgreSQL	CommandTimeout	30 秒
MySQL	DefaultCommandTimeout	30 秒

注意三种数据库的参数名略有差异——SQL Server 有空格、PostgreSQL 驼峰、MySQL 带 Default 前缀。

MCP aggregate-records 独立超时

MCP 的 aggregate_records 工具有自己独立的超时设置。当同时配置了连接字符串超时和 MCP 聚合超时时，取两者中更短的值先触发：

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

字段	说明	默认值	范围
query-timeout	聚合查询超时	30 秒	1–600 秒

设置方式：

dab configure --runtime.mcp.dml-tools.aggregate-records.query-timeout 120

聚合查询涉及 count、sum、avg 等计算，在大数据量下可能比普通查询更耗时。如果聚合查询频繁超时，单独调高此值而不影响其他 CRUD 操作的超时时间。

超时值的选取建议

场景	建议超时
常规 CRUD 操作	30 秒（默认）
涉及大表查询	60–120 秒
复杂聚合计算	60–300 秒
长时间报表	300–600 秒
API 面向用户交互	不超过 30 秒，配合分页

超时错误的表现

当查询超时时，客户端会收到 HTTP 错误响应：

• REST：500 Internal Server Error，error.message 中包含超时相关信息。
• GraphQL：errors 数组中包含超时错误消息。
• MCP：工具调用返回错误。

日志中也会记录超时事件（取决于日志级别配置），可以在开发和排查阶段将日志级别临时调至 Debug 以获取更多诊断信息。

超时 vs 性能优化

调高超时只是一种临时方案。长期解决查询慢的问题应从以下几个方向入手：

优化方向	具体措施
数据库层	检查执行计划、添加缺失的索引、优化统计信息
查询层	使用筛选条件缩小结果集、避免 $select=*、使用分页
架构层	将复杂查询封装为视图或存储过程、预先聚合数据
缓存层	启用一级缓存减少重复查询、热点数据用 Redis 二级缓存
实例层	水平扩展数据墙DBW 实例分担连接压力

下一步

• 数据库连接配置 — 连接字符串完整参数说明。
• 一级缓存 — 通过缓存减少数据库查询次数。