## 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`

通用响应格式
```json
{
  "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 | 否 | 是否降序（默认升序） |

示例请求
```json
{
  "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
}
```

异步查询示例
```json
{
  "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
}
```

成功响应
```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
        },
        {
          "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": "abc123def456"
}
```

成功响应（任务完成）
```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 状态才会返回执行结果。
- 建议轮询获取任务结果，失败或取消状态会返回错误信息。