root/db_view @ 77ba2d1c54e0d5753ba3997545fede5ac499df71

Database Data Query API（详细）

本文档描述数据查询模块的 API 接口，用于执行数据库表/视图的数据查询操作。

📋 最新更新 (2025-11-11)

统一响应结构：ExecuteSQLResponse 和 QueryDataResponse 已合并为 DataOperationResponse
明确统计字段：ExecuteResult.Stats 字段已替换为明确的 RowsReturned 字段
行ID字段：DataMeta 新增 rowId 字段用于唯一标识数据行；MySQL等无内置ROWID的数据库该字段为空字符串
API兼容性：所有现有功能保持不变，只是响应结构更加统一和清晰

基本信息

前缀：/database/data
协议：HTTP POST，Content-Type: application/json
公共响应包装：service/internal/common/response.Response

通用响应格式

{
  "code": 0,       // 0=成功，非0为失败
  "msg": "ok",   // 简短中文提示
  "data": {},      // 成功时的业务数据
  "error": ""    // 失败时的底层错误信息（便于排查）
}

通用字段说明

connId (string, required)：连接池查找键，后端用此 key 调用 ConnectionPool.GetConnection(connId)。
connInfo (string, optional)：展示/日志用的连接信息（可选），不会用于建立连接。
path (array of {type,name}, required)：结构化路径，表示从根到目标对象的层级。例如数据库下的表 users 的 path 为 [{"type":"database","name":"mydb"},{"type":"table","name":"users"}]。
query (object, required)：查询参数对象，详见下文 DataQueryRequest。

通用数据结构

meta.DataMeta 字段：
- name string：名称（列名、行标识等）
- type string：类型（"column"、"row"、"value"等）
- fieldType string：表单类型（可选）
- dbType string：数据库类型（如 "VARCHAR(255)"、"INT"）
- nullable bool：是否可空
- valueType string：值的类型（用于前端识别，如 "string"、"int"、"bool"）
- rowId string：行ID（仅对Type="row"有效，用于唯一标识数据行；MySQL等无内置ROWID的数据库为空字符串）
- attrs object：额外属性
- meta object：元数据
- children []DataMeta：子项
DataOperationResponse 统一响应结构（用于查询和SQL执行）：
- success bool：操作是否成功
- data QueryResult：查询结果数据（SELECT语句或数据查询）
- sqlType string：SQL类型（ExecuteSQL独有：SELECT/INSERT/UPDATE/DELETE/CREATE/DROP等）
- affectedRows int64：影响行数（ExecuteSQL独有：INSERT/UPDATE/DELETE）
- lastInsertId interface{}：最后插入ID（ExecuteSQL独有：INSERT语句）
- errorMessage string：错误信息（ExecuteSQL独有）
- executionTime int64：执行时间（ExecuteSQL独有，毫秒）
- rowsReturned int：返回行数（ExecuteSQL独有，SELECT语句）
- message string：提示信息

1) 数据查询 — POST /database/data/query

用途

对指定路径的数据库对象（通常为表或视图）执行数据查询，支持列选择、过滤、排序、分页等。
支持同步和异步执行模式。

请求字段 | 字段 | 类型 | 必需 | 说明 | |---|---:|:---:|---| | connId | string | 是 | 连接池查找键（必须） | | connInfo | string | 否 | 展示/日志用的连接备注 | | path | []ObjectPathEntry | 是 | 目标对象的结构化路径（见通用字段说明） | | query | DataQueryRequest | 是 | 查询参数对象 | | async | bool | 否 | 是否异步执行查询（通过任务队列） |

DataQueryRequest 结构 | 字段 | 类型 | 必需 | 说明 | |---|---:|:---:|---| | columns | []string | 否 | 需要返回的列名列表；为空表示返回全部列 | | filters | object | 否 | 简单等值过滤：列名 -> 字符串值 | | order | []SortField | 否 | 排序字段列表 | | offset | int | 否 | 起始偏移（分页用） | | limit | int | 否 | 返回最大行数；0 表示使用默认 | | includeTotal | bool | 否 | 是否计算总行数（影响性能） | | stream | bool | 否 | 是否流式读取（暂未实现） | | args | []string | 否 | 参数化查询占位符参数 | | queryId | string | 否 | 查询唯一标识（用于跟踪） | | timeoutMs | int | 否 | 查询超时时间（毫秒） | | fetch | bool | 否 | 是否执行查询（false 只返回 SQL，不返回数据） |

SortField 结构 | 字段 | 类型 | 必需 | 说明 | |---|---:|:---:|---| | column | string | 是 | 排序列名 | | desc | bool | 否 | 是否降序（默认升序） |

示例请求

{
  "connId": "conn-123",
  "connInfo": "mysql-prod-01",
  "path": [
    {"type": "database", "name": "mydb"},
    {"type": "table", "name": "users"}
  ],
  "query": {
    "columns": ["id", "name", "email"],
    "filters": {"status": "active"},
    "order": [{"column": "id", "desc": false}],
    "offset": 0,
    "limit": 10,
    "includeTotal": true,
    "fetch": true
  },
  "async": false
}

异步查询示例

{
  "connId": "conn-123",
  "connInfo": "mysql-prod-01",
  "path": [
    {"type": "database", "name": "mydb"},
    {"type": "table", "name": "users"}
  ],
  "query": {
    "columns": ["id", "name", "email"],
    "filters": {"status": "active"},
    "order": [{"column": "id", "desc": false}],
    "offset": 0,
    "limit": 1000,
    "includeTotal": true,
    "fetch": true
  },
  "async": true
}

成功响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "success": true,
    "data": {
      "columns": [
        {
          "name": "id",
          "type": "column",
          "dbType": "INT",
          "nullable": false
        },
        {
          "name": "name",
          "type": "column",
          "dbType": "VARCHAR(100)",
          "nullable": true
        },
        {
          "name": "email",
          "type": "column",
          "dbType": "VARCHAR(255)",
          "nullable": true
        }
      ],
      "rows": [
        {
          "type": "row",
          "rowId": "",
          "children": [
            {"name": "id", "type": "value", "value": 1, "valueType": "int"},
            {"name": "name", "type": "value", "value": "Alice", "valueType": "string"},
            {"name": "email", "type": "value", "value": "alice@example.com", "valueType": "string"}
          ]
        },
        {
          "type": "row",
          "rowId": "",
          "children": [
            {"name": "id", "type": "value", "value": 2, "valueType": "int"},
            {"name": "name", "type": "value", "value": "Bob", "valueType": "string"},
            {"name": "email", "type": "value", "value": "bob@example.com", "valueType": "string"}
          ]
        }
      ],
      "total": 100,
      "returned": 2,
      "truncated": false
    },
    "message": "查询完成"
  }
异步查询成功响应

json { "code": 0, "msg": "ok", "data": {

"success": true,
"data": {
  "taskId": "task-abc-123-def-456",
  "status": "running",
  "message": "异步查询已提交，正在执行中"
}

} }

json { "connId": "conn-123", "path": [

{"type": "database", "name": "mydb"},
{"type": "table", "name": "users"}

], "query": {

"fetch": false

} }


响应：

json { "code": 0, "msg": "ok", "data": {

"success": true,
"data": {
  "columns": [
    {
      "name": "id",
      "type": "column",
      "dbType": "INT",
      "nullable": false
    },
    {
      "name": "name",
      "type": "column",
      "dbType": "VARCHAR(100)",
      "nullable": true
    }
  ],
  "rows": [],
  "total": 100,
  "returned": 100,
  "truncated": false,
  "stats": {
    "sql": "SELECT * FROM `users`"
  }
},
"message": "查询完成"

} }


Async=true 示例（异步执行查询）

json { "connId": "conn-123", "path": [

{"type": "database", "name": "mydb"},
{"type": "table", "name": "users"}

], "query": {}, "async": true }


响应：

json { "code": 0, "msg": "ok", "data": {

"success": true,
"taskId": "abc123def456",
"message": "查询已提交到任务队列"

} }


常见错误
- code != 0 且 `error` 包含底层信息。例如路径无效：code=2, error="invalid path: need at least database and table"。
- 连接不存在：code=2, error="从连接池获取连接失败"。
- 查询失败：code=2, error="failed to execute query"。

注意事项
- 路径必须至少包含数据库和表两级。
- 过滤条件当前使用简单等值，复杂条件可后续扩展。
- 值类型根据数据库列类型自动映射（string/int/float/bool/[]byte/nil），前端可直接使用 JSON 原生类型。
- includeTotal=true 时会额外执行 COUNT 查询，可能影响性能。
- fetch=false 时只构建并返回 SQL，不执行查询（适合预览）。
- async=true 时查询将通过任务队列异步执行，返回任务ID；需通过任务接口获取结果。
- 当前实现未使用参数化查询，生产环境建议升级以防 SQL 注入。
-------------------------------------------------------------------------------

## 2) 获取异步任务结果 — POST /database/data/task/result

用途
- 获取异步数据查询任务的执行结果和状态。

请求字段
| 字段 | 类型 | 必需 | 说明 |
|---|---:|:---:|---|
| taskId | string | 是 | 异步查询任务的ID |

示例请求

json { "taskId": "abc123def4" }


成功响应（任务完成）

json { "code": 0, "msg": "ok", "data": {

"success": true,
"data": {
  "columns": [
    {
      "name": "id",
      "type": "column",
      "dbType": "INT",
      "nullable": false
    }
  ],
  "rows": [
    {
      "type": "row",
      "rowId": "",
      "children": [
        {"name": "id", "type": "value", "value": 1, "valueType": "int"}
      ]
    }
  ],
  "total": 1,
  "returned": 1,
  "truncated": false,
  "stats": {
    "query": "SELECT * FROM `users`"
  }
},
"status": "completed",
"message": "获取任务结果成功"

} }


成功响应（任务进行中）

json { "code": 0, "msg": "ok", "data": {

"success": true,
"status": "running",
"message": "获取任务结果成功"

} }


常见错误
- code != 0 且 `error` 包含底层信息。例如任务不存在：code=2, error="获取任务状态失败: 任务不存在"。
- 任务管理器未配置：code=2, error="任务管理器未配置"。

注意事项
- 任务状态包括：pending（等待中）、running（运行中）、completed（已完成）、failed（失败）、cancelled（已取消）。
- 只有 completed 状态才会返回查询数据。
- 建议轮询获取任务结果，失败或取消状态会返回错误信息。

-------------------------------------------------------------------------------

## 3) SQL 执行 — POST /database/data/execute

用途
- 执行各种类型的 SQL 语句（SELECT、INSERT、UPDATE、DELETE、CREATE、DROP 等）。
- 支持同步和异步执行模式。

请求字段
| 字段 | 类型 | 必需 | 说明 |
|---|---:|:---:|---|
| connId | string | 是 | 连接池查找键（必须） |
| connInfo | string | 否 | 展示/日志用的连接备注 |
| path | []ObjectPathEntry | 是 | 目标对象的结构化路径（用于确定数据库连接） |
| sql | string | 是 | 要执行的 SQL 语句 |
| params | []interface{} | 否 | 参数化查询的参数列表 |
| async | bool | 否 | 是否异步执行 SQL |

ExecuteSQLRequest 结构
| 字段 | 类型 | 必需 | 说明 |
|---|---:|:---:|---|
| connId | string | 是 | 连接池查找键 |
| connInfo | string | 否 | 展示/日志用的连接备注 |
| path | []ObjectPathEntry | 是 | 目标对象的结构化路径 |
| sql | string | 是 | SQL 语句 |
| params | []interface{} | 否 | 参数列表 |
| async | bool | 否 | 是否异步执行 |

示例请求

json { "connId": "conn-123", "connInfo": "mysql-prod-01", "path": [

{"type": "database", "name": "mydb"}

], "sql": "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(100))", "params": [], "async": false }


异步执行示例

json { "connId": "conn-123", "connInfo": "mysql-prod-01", "path": [

{"type": "database", "name": "mydb"}

], "sql": "INSERT INTO users (name) SELECT name FROM temp_users", "async": true }


成功响应

json { "code": 0, "msg": "ok", "data": {

"success": true,
"sqlType": "CREATE TABLE",
"affectedRows": 0,
"executionTime": 15,
"message": "SQL执行完成"

} }

"message": "SQL执行完成"

} }


异步响应

json { "code": 0, "msg": "ok", "data": {

"success": true,
"taskId": "task-abc-123",
"message": "SQL已提交到任务队列"

} }


ExecuteResult 结构（已合并为 DataOperationResponse）
| 字段 | 类型 | 说明 |
|---|---|---|
| success | bool | 执行是否成功 |
| sqlType | string | SQL 类型（SELECT/INSERT/UPDATE/DELETE/CREATE/DROP 等） |
| affectedRows | int64 | 影响行数（INSERT/UPDATE/DELETE） |
| lastInsertId | interface{} | 最后插入 ID（INSERT 语句） |
| data | QueryResult | 查询结果（SELECT 语句） |
| errorMessage | string | 错误信息 |
| executionTime | int64 | 执行时间（毫秒） |
| rowsReturned | int | 返回的行数（SELECT 语句） |

**注意**：API 响应现在统一使用 `DataOperationResponse` 结构，包含了所有执行相关的字段。

-------------------------------------------------------------------------------

## 4) 获取 SQL 执行任务结果 — POST /database/data/execute/task/result

用途
- 获取异步 SQL 执行任务的执行结果。

请求字段
| 字段 | 类型 | 必需 | 说明 |
|---|---:|:---:|---|
| taskId | string | 是 | 异步任务 ID |

示例请求

json { "taskId": "task-abc-123" }


成功响应

json { "code": 0, "msg": "ok", "data": {

"success": true,
"status": "completed",
"data": {
  "success": true,
  "sqlType": "INSERT",
  "affectedRows": 1000,
  "executionTime": 250,
  "message": "SQL执行完成"
},
"message": "获取任务结果成功"

} }


运行中响应

json { "code": 0, "msg": "ok", "data": {

"success": true,
"status": "running",
"message": "获取任务结果成功"

} } ```

常见错误

code != 0 且 error 包含底层信息。例如任务不存在：code=2, error="获取任务状态失败: 任务不存在"。
任务管理器未配置：code=2, error="任务管理器未配置"。

注意事项

任务状态包括：pending（等待中）、running（运行中）、completed（已完成）、failed（失败）、cancelled（已取消）。
只有 completed 状态才会返回执行结果。
建议轮询获取任务结果，失败或取消状态会返回错误信息。

API.md 15 KB Cronologia Originale

Database Data Query API（详细）

📋 最新更新 (2025-11-11)

1) 数据查询 — POST /database/data/query

API.md 15 KB

Cronologia Originale