Presto 客户端 REST API¶

Presto 客户端允许用户提交 Presto 查询并查看结果。此说明文档记录 Presto 客户端使用的 REST API。

HTTP 方法¶

对 /v1/statement 的 POST 请求在 POST 主体中运行查询字符串，并返回包含查询结果的 JSON 文档。如果存在更多结果，JSON 文档将包含一个 nextUri URL 属性。
对 nextUri 属性的 GET 请求返回下一批查询结果。
对 nextUri 的 DELETE 请求终止正在运行的查询。

查询处理概述¶

Presto 客户端请求通过对端点 /v1/statement 执行 HTTP POST 请求发起，POST 主体包含 SQL 查询字符串。调用者可以将头 X-Presto-User 设置为会话用户的用户名，以及下面列出的其他头。

如果客户端请求返回 HTTP 503，则表示服务器繁忙，客户端应在 50-100 毫秒后重试。任何 HTTP 状态码，除了 503 或 200 之外，都表示查询已失败。

/v1/statement POST 请求返回类型为 QueryResults 的 JSON 文档，以及响应头的集合。如果查询失败，则 QueryResults 文档将包含类型为 QueryError 的 error 字段，如果该对象不存在，则查询成功。下面记录了 QueryResults 中的重要成员。

如果 JSON 文档的 data 字段已设置，则它包含数据行的列表，而 columns 字段也将设置为查询返回的列的名称和类型的列表。大多数响应头应由客户端像浏览器 cookie 一样处理，并在后续客户端请求中回显为请求头，如下所述。

要在二进制格式中请求结果，请在初始 /v1/statement POST 请求中包含 binaryResults=true 查询参数。响应 JSON 文档将包含 binaryData 字段，其中包含序列化页面格式的 Base64 编码页面的列表。 data 字段将不存在。

如果对 /v1/statement 执行 POST 请求返回的 JSON 文档不包含 nextUri 链接，则查询已完成，无论成功还是失败，都不需要再进行额外的请求。如果文档中存在 nextUri 链接，则还有更多查询结果需要获取。客户端应循环执行对 QueryResults 响应对象中返回的 nextUri 的 GET 请求，直到响应中不存在 nextUri。

JSON 文档的 status 字段仅供人类阅读，并提供关于服务器上查询状态的提示。它与服务器的查询状态不同步，不应用于判断查询是否已完成。

重要 `QueryResults` 属性¶

此表列出了 REST API 端点返回的 QueryResults JSON 文档中最重要的属性。有关更多详细信息，请参考类 QueryResults。

属性	描述
`id`	查询的 ID。
`nextUri`	如果存在，则表示后续 `GET` 或 `DELETE` 请求应使用的 URL。如果不存在，则表示查询已完成或以错误结束。
`columns`	查询返回的列的名称和类型的列表。
`data`	`data` 属性包含查询请求返回的行列表。每行本身是一个列表，其中包含该行中列的值，顺序由 `columns` 属性指定。
`updateType`	表示操作的人类可读字符串。对于 `CREATE TABLE` 请求， `updateType` 将为“CREATE TABLE”；对于 `SET SESSION`，它将为“SET SESSION”；等等。
`error`	如果查询失败，则 `error` 属性将包含 `QueryError` 对象的 JSON。该对象包含一个 `message`、一个 `errorCode` 以及有关错误的其他信息。有关更多详细信息，请参阅 `QueryError` 类。

客户端请求头¶

此表列出了所有支持的客户端请求头。许多头可以在响应头中更新，并在后续请求中提供，就像浏览器 cookie 一样。

请求头名称	描述
`X-Presto-User`	指定会话用户；必须随对 `/v1/statement` 的每次请求提供。
`X-Presto-Source`	出于报告目的，这提供提交查询的软件的名称。
`X-Presto-Catalog`	运行查询时要使用的目录。由响应头 `X-Presto-Set-Catalog` 设置。
`X-Presto-Schema`	运行查询时要使用的模式。由响应头 `X-Presto-Set-Schema` 设置。
`X-Presto-Time-Zone`	运行查询时要使用的时区，默认情况下是 Presto 引擎的时区。
`X-Presto-Language`	运行查询和格式化结果时要使用的语言。会话语言可以通过 `X-Presto-Language` HTTP 头在每个查询的基础上设置，也可以通过 JDBC 驱动程序中的 `PrestoConnection.setLocale(Locale)` 方法设置。
`X-Presto-Trace-Token`	向 Presto 引擎提供跟踪令牌，以帮助识别源自此查询请求的日志行。
`X-Presto-Session`	提供逗号分隔的名称=值对列表作为会话属性。当 Presto 客户端运行 `SET SESSION name=value` 查询时，名称=值对将在响应头 `X-Set-Presto-Session` 中返回，并添加到客户端的会话属性列表中。如果响应头 `X-Presto-Clear-Session` 已返回，则它的值将是将从客户端的累积列表中删除的会话属性的名称。
`X-Presto-Role`	设置此请求中将使用的目录角色。由响应头 `X-Presto-Set-Role` 设置。
`X-Presto-Prepared-Statement`	一个逗号分隔的名称-值对列表，其中名称是先前准备好的 SQL 语句的名称，而值是标识已命名准备语句的可执行形式的键。
`X-Presto-Transaction-Id`	运行查询时要使用的交易 ID。由响应头 `X-Presto-Started-Transaction-Id` 设置，并由 `X-Presto-Clear-Transaction-Id` 清除。
`X-Presto-Client-Info`	包含有关提交查询的客户端程序的任意信息。
`X-Presto-Client-Tags`	一个逗号分隔的“标签”字符串列表，用于标识 Presto 资源组。
`X-Presto-Resource-Estimate`	一个逗号分隔的 `resource=value` 类型分配列表。可能的 `resource` 选择是“EXECUTION_TIME”、“CPU_TIME”、“PEAK_MEMORY”和“PEAK_TASK_MEMORY”。“EXECUTION_TIME”和“CPU_TIME”的值以 airlift `Duration` 字符串指定，其格式为双精度数字后跟 `TimeUnit` 字符串，例如，`s` 表示秒，`m` 表示分钟，`h` 表示小时，等等。“PEAK_MEMORY”和“PEAK_TASK_MEMORY”以 airlift `DataSize` 字符串指定，其格式为整数后跟 `B` 表示字节；`kB` 表示千字节；`mB` 表示兆字节，`gB` 表示吉字节，等等。
`X-Presto-Extra-Credential`	向连接器提供额外的凭据。该标头是一个 name=value 字符串，保存在会话 `Identity` 对象中。名称和值仅对连接器有意义。

客户端响应标头¶

此表列出了支持的客户端响应标头。在收到响应后，客户端必须更新将在后续请求中使用的请求标头，使其与收到的响应标头一致。

响应标头名称	描述
`X-Presto-Set-Catalog`	指示客户端设置将在后续客户端请求的 `X-Presto-Catalog` 请求标头中发送的目录。
`X-Presto-Set-Schema`	指示客户端设置将在后续客户端请求的 `X-Presto-Schema` 请求标头中发送的模式。
`X-Presto-Set-Session`	`X-Presto-Set-Session` 响应标头的值为 name=value 字符串，表示对 Presto 引擎或连接器有意义的会话属性。指示客户端将该 name=value 字符串添加到 `X-Presto-Session` 请求标头中，以在后续客户端请求中使用。
`X-Presto-Clear-Session`	指示客户端从将在后续客户端请求的 `X-Presto-Session` 标头中发送的会话属性的逗号分隔列表中删除名称为 `X-Presto-Clear-Session` 标头值的会话属性。
`X-Presto-Set-Role`	指示客户端在后续客户端请求中将 `X-Presto-Role` 请求标头设置为 `X-Presto-Set-Role` 标头值给出的目录角色。
`X-Presto-Added-Prepare`	指示客户端将 name=value 对添加到将在后续客户端请求的 `X-Presto-Prepared-Statements` 请求标头中发送的准备语句集中。
`X-Presto-Deallocated-Prepare`	指示客户端从客户端在后续客户端请求的 `X-Presto-Prepared-Statements` 请求标头中发送的准备语句列表中删除名称为 `X-Presto-Deallocated-Prepare` 标头值的准备语句。
`X-Presto-Started-Transaction-Id`	提供客户端应在后续请求的 `X-Presto-Transaction-Id` 请求标头中传递回的交易 ID。
`X-Presto-Clear-Transaction-Id`	指示客户端清除在后续请求中使用的 `X-Presto-Transaction-Id` 请求标头。

`QueryResults`¶

当客户端执行查询时，将返回一个 QueryResults 对象。 QueryResults 包含一个很长的数据成员列表。这些数据成员可能在跟踪问题时很有用。

数据成员	类型	说明
`queryError`	`QueryError`	仅当查询导致错误时才为非空。 `QueryResults.failureInfo` 类型为 `FailureInfo`，包含有关失败原因的详细信息，包括堆栈跟踪，以及 `FailureInfo.errorLocation`，提供检测到失败的查询行号和列号。
`warnings`	`List<PrestoWarning>`	通常为空的警告列表。
`statementStats`	`StatementStats`	一个包含有关查询执行的统计信息的类。特别值得注意的是 `StatementStats.rootStage`，类型为 `StageStats`，提供有关查询处理各个阶段执行的统计信息。

`PrestoHeaders`¶

类 PrestoHeaders 枚举了 Presto 客户端 REST API 允许的所有 HTTP 请求和响应标头。