Presto クライアント REST API¶

Prestoクライアントを使用すると、ユーザーはPrestoクエリを送信して結果を表示できます。このノートでは、Prestoクライアントで使用されるREST APIについて説明します。

HTTPメソッド¶

POSTを/v1/statementに送信すると、POST本文のクエリ文字列が実行され、クエリ結果を含むJSONドキュメントが返されます。結果がさらに存在する場合は、JSONドキュメントにnextUri URL属性が含まれます。
nextUri属性へのGETは、次のバッチのクエリ結果を返します。
nextUriへのDELETEは、実行中のクエリを終了します。

クエリ処理の概要¶

Prestoクライアントのリクエストは、エンドポイント/v1/statementへのHTTP POSTによって開始され、SQLクエリ文字列を含むPOST本文が使用されます。呼び出し側は、セッションのユーザー名にヘッダー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ドキュメントには、SerializedPage形式のbase64でエンコードされたページのリストを含むbinaryDataフィールドが含まれます。dataフィールドは存在しません。

/v1/statementへのPOSTによって返されたJSONドキュメントにnextUriリンクが含まれていない場合、クエリは成功または失敗のいずれかで完了しており、追加のリクエストを行う必要はありません。nextUriリンクがドキュメントに存在する場合は、取得する必要があるクエリ結果がさらにあります。クライアントは、nextUriがレスポンスからなくなるまで、QueryResultsレスポンスオブジェクトで返されたnextUriへのGETリクエストを実行するループを実行する必要があります。

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`	`SET SESSION name=value`クエリを実行すると、Prestoクライアントはname=valueペアをカンマ区切りリストとしてセッションプロパティとして提供します。 `X-Set-Presto-Session`レスポンスヘッダーにはname=valueペアが返され、クライアントのセッションプロパティリストに追加されます。レスポンスヘッダー`X-Presto-Clear-Session`が返された場合、その値はクライアントの累積リストから削除されるセッションプロパティの名前です。
`X-Presto-Role`	このリクエストで使用されるカタログロールを設定します。レスポンスヘッダー`X-Presto-Set-Role`で設定されます。
`X-Presto-Prepared-Statement`	name=valueペアのカンマ区切りリスト。nameは事前に準備されたSQL文の名前、valueは名前付き準備済みステートメントの実行可能形式を識別するキーです。
`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`オブジェクトに保存されるname=value文字列です。nameとvalueはコネクタにとってのみ意味を持ちます。

クライアントレスポンスヘッダー¶

この表には、サポートされているクライアントレスポンスヘッダーが一覧表示されています。レスポンスを受信した後、クライアントは、受信したレスポンスヘッダーと一致するように、後続のリクエストで使用されるリクエストヘッダーを更新する必要があります。

レスポンスヘッダー名	説明
`X-Presto-Set-Catalog`	クライアントに、後続のクライアントリクエストで`X-Presto-Catalog`リクエストヘッダーに送信されるカタログを設定するように指示します。
`X-Presto-Set-Schema`	クライアントに、後続のクライアントリクエストで`X-Presto-Schema`リクエストヘッダーに送信されるスキーマを設定するように指示します。
`X-Presto-Set-Session`	`X-Presto-Set-Session`レスポンスヘッダーの値は、Prestoエンジンまたはコネクタにとって意味のあるセッション属性を表すname=value文字列です。クライアントに、そのname=value文字列を`X-Presto-Session`リクエストヘッダーに追加して、後続のクライアントリクエストで使用するように指示します。
`X-Presto-Clear-Session`	クライアントに、`X-Presto-Clear-Session`ヘッダーの値である名前を持つセッションプロパティを、後続のクライアントリクエストで`X-Presto-Session`ヘッダーに送信されるセッションプロパティのカンマ区切りリストから削除するように指示します。
`X-Presto-Set-Role`	クライアントに、後続のクライアントリクエストで`X-Presto-Set-Role`ヘッダーの値で指定されたカタログロールに`X-Presto-Role`リクエストヘッダーを設定するように指示します。
`X-Presto-Added-Prepare`	クライアントに、name=valueペアを、後続のクライアントリクエストで`X-Presto-Prepared-Statements`リクエストヘッダーに送信される準備済みステートメントのセットに追加するように指示します。
`X-Presto-Deallocated-Prepare`	クライアントに、`X-Presto-Deallocated-Prepare`ヘッダーの値である名前を持つ準備済みステートメントを、後続のクライアントリクエストで`X-Presto-Prepared-Statements`リクエストヘッダーに送信されるクライアントの準備済みステートメントのリストから削除するように指示します。
`X-Presto-Started-Transaction-Id`	クライアントが後続のリクエストで`X-Presto-Transaction-Id`リクエストヘッダーに渡す必要があるトランザクション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`	クエリ実行に関する統計を含むクラス。`StatementStats.rootStage`（`StageStats`型）は、クエリ処理の各ステージの実行に関する統計を提供します。

`PrestoHeaders`¶

クラスPrestoHeadersは、PrestoクライアントREST APIで許可されているすべてのHTTPリクエストヘッダーとレスポンスヘッダーを列挙します。