查询 V2 HTTP 响应Query V2 HTTP response

如果状态代码为 200，则响应正文为 JSON 数组。If the status code is 200, then the response body is a JSON array. 数组中的每个 JSON 对象称为“帧”。Each JSON object in the array is called a frame.

有多种类型的帧：There are several types of frames:

DataSetHeaderDataSetHeader

DataSetHeader 帧始终是数据集中的第一个帧，并且只出现一次。The DataSetHeader frame is always the first in the data set and appears exactly once.

{
    "Version": string,
    "IsProgressive": Boolean
}

其中：Where:

  • Version 是协议版本。Version is the protocol version. 当前版本为 v2.0。The current version is v2.0.

  • IsProgressive 是一个布尔标志，指示此数据集是否包含渐进式帧。IsProgressive is a boolean flag that indicates whether this data set contains progressive frames. 渐进式帧是下列项之一：A progressive frame is one of:

    FrameFrame 说明Description
    TableHeader 包含有关表的常规信息Contains general information about the table
    TableFragment 包含表的矩形数据分片Contains a rectangular data shard of the table
    TableProgress 包含以百分比表示的进度 (0-100)Contains the progress in percent (0-100)
    TableCompletion 指示此帧是最后一帧Indicates that this frame is the last one

    上述帧描述了一个表。The frames above describe a table. 如果 IsProgressive 标志未设置为 true，则将使用单个帧对集中的每个表进行序列化：If the IsProgressive flag isn't set to true, then every table in the set will be serialized using a single frame:

  • DataTable：包含客户端所需的有关数据集中的单个表的所有信息。DataTable: Contains all the information that the client needs about a single table in the data set.

TableHeaderTableHeader

如果将 results_progressive_enabled 选项设置为 true，则进行的查询可能包含此帧。Queries that are made with the results_progressive_enabled option set to true may include this frame. 根据此表，客户端可以期望得到一个包含 TableFragment 和 TableProgress 帧的交织序列。Following this table, clients can expect an interleaving sequence of TableFragment and TableProgress frames. 表的最后一帧是 TableCompletion。The final frame of the table is TableCompletion.

{
    "TableId": Number,
    "TableKind": string,
    "TableName": string,
    "Columns": Array,
}

其中：Where:

  • TableId 是表的唯一 ID。TableId is the table's unique ID.

  • TableKind 是下列项之一：TableKind is one of:

    • PrimaryResultPrimaryResult
    • QueryCompletionInformationQueryCompletionInformation
    • QueryTraceLogQueryTraceLog
    • QueryPerfLogQueryPerfLog
    • TableOfContentsTableOfContents
    • QueryPropertiesQueryProperties
    • QueryPlanQueryPlan
    • 未知Unknown

  • TableName 是表的名称。TableName is the table's name.

  • Columns 是描述表的架构的数组。Columns is an array describing the table's schema.

{
    "ColumnName": string,
    "ColumnType": string,
}

此处介绍了支持的列类型。Supported column types are described here.

TableFragmentTableFragment

TableFragment 帧包含表的矩形数据片段。The TableFragment frame contains a rectangular data fragment of the table. 除了实际数据之外，此帧还包含一个 TableFragmentType 属性，该属性告知客户端应如何处理此片段。In addition to the actual data, this frame also contains a TableFragmentType property that tells the client what to do with the fragment. 此片段将追加到现有片段，或替换它们。The fragment appended to existing fragments, or replace them.

{
    "TableId": Number,
    "FieldCount": Number,
    "TableFragmentType": string,
    "Rows": Array
}

其中：Where:

  • TableId 是表的唯一 ID。TableId is the table's unique ID.

  • FieldCount 是表中的列数。FieldCount is the number of columns in the table.

  • TableFragmentType 描述客户端应如何处理此片段。TableFragmentType describes what the client should do with this fragment. TableFragmentType 是下列项之一：TableFragmentType is one of:

    • DataAppendDataAppend
    • DataReplaceDataReplace

  • Rows 是包含片段数据的二维数组。Rows is a two-dimensional array that contains the fragment data.

TableProgressTableProgress

TableProgress 帧可以与上面所述的 TableFragment 帧交织出现。The TableProgress frame can interleave with the TableFragment frame described above. 其唯一用途是告知客户端查询进度。Its sole purpose is to notify the client of the query's progress.

{
    "TableId": Number,
    "TableProgress": Number,
}

其中：Where:

  • TableId 是表的唯一 ID。TableId is the table's unique ID.
  • TableProgress 是以百分比表示的进度 (0-100)。TableProgress is the progress in percent (0--100).

TableCompletionTableCompletion

TableCompletion 帧标记表传输的结束。The TableCompletion frame marks the end of the table transmission. 不会再发送与该表相关的帧。No more frames related to that table will be sent.

{
    "TableId": Number,
    "RowCount": Number,
}

其中：Where:

  • TableId 是表的唯一 ID。TableId is the table's unique ID.
  • RowCount 是表中的总行数。RowCount is the total number of rows in the table.

DataTableDataTable

当 EnableProgressiveQuery 标志设置为 false 时，发出的查询将不包括任何帧（TableHeader、TableFragment、TableProgress 和 TableCompletion）。Queries that are issued with the EnableProgressiveQuery flag set to false won't include any of the frames (TableHeader, TableFragment, TableProgress, and TableCompletion). 相反，数据集中的每个表都将使用 DataTable 帧进行传输，该帧包含客户端读取该表需要的所有信息。Instead, each table in the data set will be transmitted using the DataTable frame that contains all the information that the client needs, to read the table.

{
    "TableId": Number,
    "TableKind": string,
    "TableName": string,
    "Columns": Array,
    "Rows": Array,
}

其中：Where:

  • TableId 是表的唯一 ID。TableId is the table's unique ID.

  • TableKind 是下列项之一：TableKind is one of:

    • PrimaryResultPrimaryResult
    • QueryCompletionInformationQueryCompletionInformation
    • QueryTraceLogQueryTraceLog
    • QueryPerfLogQueryPerfLog
    • QueryPropertiesQueryProperties
    • QueryPlanQueryPlan
    • 未知Unknown

  • TableName 是表的名称。TableName is the table's name.

  • Columns 是描述表的架构的数组，并且包括：Columns is an array describing the table's schema, and includes:

{
    "ColumnName": string,
    "ColumnType": string,
}
  • Rows 是包含表的数据的二维数组。Rows is a two-dimensional array that contains the table's data.

响应中的表的含义The meaning of tables in the response

  • PrimaryResult - 查询的主要表格结果。PrimaryResult - The main tabular result of the query. 对于每个表格表达式语句，将按顺序生成一个或多个表，表示该语句产生的结果。For each tabular expression statement, one or more tables are generated in-order, representing the results produced by the statement. 由于存在批次和分支运算符，可能会有多个这样的表。There can be multiple such tables because of batches and fork operators.
  • QueryCompletionInformation - 提供有关查询本身的执行的附加信息（例如，它是否已成功完成）以及查询使用的资源（类似于 v1 响应中的 QueryStatus 表）。QueryCompletionInformation - Provides additional information about the execution of the query itself, such as whether it completed successfully or not, and what were the resources consumed by the query (similar to the QueryStatus table in the v1 response).
  • QueryProperties - 提供附加值，例如客户端可视化效果说明（发出这些说明是有目的的，例如，反映 render 运算符中的信息和数据库游标信息）。QueryProperties - Provides additional values such as client visualization instructions (emitted, for example, to reflect the information in the render operator) and database cursor information).
  • QueryTraceLog - 性能跟踪日志信息（当客户端请求属性中的 perftrace 设置为 true 时返回）。QueryTraceLog - The performance trace log information (returned when perftrace in client request properties is set to true).

DataSetCompletionDataSetCompletion

DataSetCompletion 帧是数据集中的最后一帧。The DataSetCompletion frame is the final one in the data set.

{
    "HasErrors": Boolean,
    "Cancelled": Boolean,
    "OneApiErrors": Array,
}

其中：Where:

  • 如果生成数据集时出现错误，则 HasErrors 为 true。HasErrors is true if there were errors while generating the data set.
  • 如果导致生成数据集的请求在完成前被取消，则 Cancelled 为 true。Cancelled is true if the request that led to the generation of the data set was canceled before completion.
  • 只有 HasErrors 为 true 时才会返回 OneApiErrors。OneApiErrors is only returned if HasErrors is true. 有关 OneApiErrors 格式的说明，请参阅此处的 7.10.2 部分。For a description of the OneApiErrors format, see section 7.10.2 here.