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 毫秒後重試。任何 503 或 200 以外的 HTTP 狀態都表示查詢已失敗。

/v1/statement POST 請求會傳回 QueryResults 類型的 JSON 文件，以及一系列回應標頭。QueryResults 文件會包含 QueryError 類型的 error 欄位（如果查詢失敗），如果該物件不存在，則表示查詢成功。下方文件說明 QueryResults 的重要成員。

如果設定 JSON 文件的 data 欄位，它會包含資料列的清單，columns 欄位也會設定為查詢傳回的資料行名稱和類型清單。大部分回應標頭應由客戶端視為瀏覽器 Cookie 並在後續客戶端請求中作為請求標頭回傳，如下方文件所述。

若要以二進位格式請求結果，請在初始 /v1/statement POST 請求中加入 binaryResults=true 查詢參數。回應 JSON 文件將包含 binaryData 欄位，其中包含 SerializedPage 格式的 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`	提供額外的憑證給連接器。標頭是一個名稱=值字串，儲存在連線 `Identity` 物件中。名稱和值僅對連接器有意義。

用戶端回應標頭¶

此表格列出支援的用戶端回應標頭。收到回應後，用戶端必須更新後續請求中使用的請求標頭，使其與收到的回應標頭一致。

回應標頭名稱	描述
`X-Presto-Set-Catalog`	指示用戶端設定目錄，該目錄將在後續用戶端請求中的 `X-Presto-Catalog` 請求標頭中發送。
`X-Presto-Set-Schema`	指示用戶端設定綱要，該綱要將在後續用戶端請求中的 `X-Presto-Schema` 請求標頭中發送。
`X-Presto-Set-Session`	`X-Presto-Set-Session` 回應標頭的值是一個名稱=值字串，表示對 Presto 引擎或連接器有意義的連線屬性。指示用戶端將該名稱=值字串添加到 `X-Presto-Session` 請求標頭中，以便在後續用戶端請求中使用。
`X-Presto-Clear-Session`	指示用戶端從連線屬性（以逗號分隔的列表）中刪除名稱為 `X-Presto-Clear-Session` 標頭值的連線屬性，該連線屬性將在後續用戶端請求中的 `X-Presto-Session` 標頭中發送。
`X-Presto-Set-Role`	指示用戶端將 `X-Presto-Role` 請求標頭設定為 `X-Presto-Set-Role` 標頭值提供的目錄角色，以用於後續用戶端請求。
`X-Presto-Added-Prepare`	指示用戶端將名稱=值配對添加到已準備好的語句集中，該語句集將在後續用戶端請求中的 `X-Presto-Prepared-Statements` 請求標頭中發送。
`X-Presto-Deallocated-Prepare`	指示用戶端從用戶端在後續用戶端請求中於 `X-Presto-Prepared-Statements` 請求標頭中發送的準備好的語句列表中，移除名稱為 `X-Presto-Deallocated-Prepare` 標頭值的準備好的語句。
`X-Presto-Started-Transaction-Id`	提供交易 ID，用戶端應在後續請求的 `X-Presto-Transaction-Id` 請求標頭中傳回。
`X-Presto-Clear-Transaction-Id`	指示用戶端清除後續請求中使用的 `X-Presto-Transaction-Id` 請求標頭。

`QueryResults`¶

當用戶端執行查詢時，會返回一個 QueryResults 物件。QueryResults 包含很長的資料成員列表。這些資料成員可能對於追蹤問題很有用

資料成員	類型	筆記
`queryError`	`QueryError`	僅當查詢導致錯誤時才為非 Null。`QueryResults.failureInfo` 的類型為 `FailureInfo`，其中包含有關失敗原因的詳細資訊，包括堆疊追蹤和 `FailureInfo.errorLocation`，提供偵測到失敗的查詢行號和欄號。
`warnings`	`List<PrestoWarning>`	通常為空的警告列表。
`statementStats`	`StatementStats`	一個包含有關查詢執行統計資訊的類別。特別令人感興趣的是類型為 `StageStats` 的 `StatementStats.rootStage`，它提供有關查詢處理的每個階段的執行統計資訊。

`PrestoHeaders`¶

PrestoHeaders 類別列舉 Presto 用戶端 REST API 允許的所有 HTTP 請求和回應標頭。