账户快照 API

接口参考 · 8811 · data_server

默认地址为 http://127.0.0.1:8811，提供账户资金、持仓、委托和成交的最新快照。服务通过表结构发现与受限只读 SQL 查询访问数据；不提供下单、撤单或改单能力。

字段含义见账户快照字段，监控与统计用法见常见应用与组合使用。结算后的历史日记录请使用历史绩效 API。

接口总览

账户快照接口
方法	路径	作用
`GET`	`/health`	检查服务与数据库状态
`GET`	`/tables`	返回可查询的表、字段、类型、可空性和索引名称
`POST`	`/query`	执行一条只读 SQL，返回列名和二维行数组

检查服务

按快速开始启用服务后，发送无参数请求：

Invoke-RestMethod "http://127.0.0.1:8811/health"

数据库可用时返回 HTTP 200 和 {"ok": true}，不可用时返回 HTTP 503 和 {"ok": false}。健康检查通过不代表每个交易账户的快照已经准备完毕。

查询表结构：`GET /tables`

无请求参数。当前主要业务表为 AccountSnap、PositionSnap、OrderSnap 和 TradeSnap，实际可查询表及字段以返回值为准。

$schema = Invoke-RestMethod "http://127.0.0.1:8811/tables"
$schema.tables | Select-Object name, columns, indexes

下面仅展示一张表的部分字段：

{
  "ok": true,
  "tables": [{
    "name": "AccountSnap",
    "columns": [{"name": "node_key", "type": "TEXT", "primary_key": true, "nullable": false}],
    "indexes": ["account_update_time_idx", "account_user_key_idx"]
  }]
}

columns 中每项给出字段的 name、SQLite type、primary_key 和 nullable；indexes 是索引名称数组。不同版本可能增加字段，程序可先发现结构再构建查询。

执行查询：`POST /query`

请求体为 JSON 对象，sql 是必填字符串：

{"sql": "SELECT user_key, currency, client_equity, available FROM AccountSnap ORDER BY user_key LIMIT 100"}

可直接在 PowerShell 中运行：

$query = @{
    sql = "SELECT user_key, currency, client_equity, available FROM AccountSnap ORDER BY user_key LIMIT 100"
} | ConvertTo-Json
$body = [System.Text.Encoding]::UTF8.GetBytes($query)
$result = Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8811/query" `
    -ContentType "application/json; charset=utf-8" -Body $body
if (-not $result.ok) { throw $result.error.message }
$result.columns
$result.rows

成功响应示例中的数据为虚构值：

{
  "ok": true,
  "columns": ["user_key", "currency", "client_equity", "available"],
  "rows": [["example-account", "CNY", 100000.0, 80000.0]],
  "row_count": 1,
  "truncated": false,
  "elapsed_ms": 2
}

查询响应
字段	含义
`columns`	列名数组，顺序与每行数值一致
`rows`	二维数组；每条记录是一个按列顺序排列的数组，并非字段名对象
`row_count`	本次实际返回的行数，不是查询条件匹配的总行数
`truncated`	结果是否因服务端限制被截断；为 `true` 时不能认为已经取齐数据
`elapsed_ms`	SQL 执行耗时，单位毫秒

查询限制

每个请求只允许一条只读 SELECT 或只读 WITH 查询，禁止写入、多语句和加载 SQLite 扩展。
最多返回 1000 行，并限制响应大小为 8 MiB；查询超时为 10 秒。
建议显式写出所需字段、筛选条件、排序和 LIMIT。需要更多记录时，在 SQL 中缩小范围或分批查询，并检查 truncated。
这里没有独立的 limit、offset 或 params JSON 参数。按账户过滤时使用快照中的 user_key；构造 SQL 字符串时应正确处理文本转义。
多次查询之间快照可能变化；该服务不会自动保留每次变化形成的盘中历史序列。日频历史分析见历史绩效分析与导出。

错误响应

{"ok": false, "error": {"code": "BAD_REQUEST", "message": "missing sql"}}

错误类型
HTTP	代码	说明
`400`	`BAD_REQUEST`	请求体无法解析或缺少 `sql`
`400`	`SQL_ERROR`	SQL 不符合只读规则、语法错误或执行失败
`500`	`DB_ERROR`	获取表结构时数据库查询失败
`503`	无独立错误码	健康检查失败，响应为 `{"ok": false}`