.. _qpro_trading_data_api:

.. rst-class:: qpro-docs-page

================================================================
账户快照 API
================================================================

.. container:: qpro-docs-meta

   接口参考 · 8811 · data_server

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

字段含义见 :ref:`qpro_httpserver_schema`，监控与统计用法见 :ref:`qpro_examples`。结算后的历史日记录请使用 :ref:`qpro_performance_api`。

接口总览
================================================================

.. list-table:: 账户快照接口
   :class: qpro-api-table
   :header-rows: 1
   :widths: 15 24 61

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

检查服务
================================================================

按 :ref:`qpro_httpserver` 启用服务后，发送无参数请求：

.. code-block:: powershell

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

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

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

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

.. code-block:: powershell

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

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

.. code-block:: json

    {
      "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`` 是必填字符串：

.. code-block:: json

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

可直接在 PowerShell 中运行：

.. code-block:: 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

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

.. code-block:: json

    {
      "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
    }

.. list-table:: 查询响应
   :class: qpro-api-table
   :header-rows: 1
   :widths: 26 74

   * - 字段
     - 含义
   * - ``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 字符串时应正确处理文本转义。
* 多次查询之间快照可能变化；该服务不会自动保留每次变化形成的盘中历史序列。日频历史分析见 :ref:`qpro_performance_guide`。

错误响应
================================================================

.. code-block:: json

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

.. list-table:: 错误类型
   :class: qpro-api-table
   :header-rows: 1
   :widths: 16 25 59

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