このドキュメントでは、BigQuery REST API を使用してテーブルデータとクエリ結果のページ分割を行う方法について説明します。
API を使用した結果のページ分割
すべての *collection*.list
メソッドから返される結果は、特定の状況においてページ分けされます。ページあたりの結果の数は、maxResults
プロパティによって制御されます。
メソッド | ページ分け基準 | maxResults のデフォルト値 |
maxResults の最大値 |
maxFieldValues の最大値 |
---|---|---|---|---|
Tabledata.list |
レスポンス サイズが 10 MB1 を超えるデータ、または maxResults 行を超える場合は、ページ分割された結果を返します。 |
100,000 | 無制限 | 無制限 |
その他すべての *collection*.list メソッド |
レスポンスが maxResults 行を超え、かつ上限を下回っている場合、ページ分けされた結果を返します。 |
10,000 | 無制限 | 300,000 |
結果がバイトまたはフィールドの上限を超えると、結果は上限に合わせてカットされます。1 行がバイトまたはフィールドの上限より大きい場合、tabledata.list
は最大 100 MB のデータ 1 を返すことができます。これは、クエリ結果の最大行数制限に準拠しています。
1 行サイズは行データの内部表現に基づくため、概算値です。行の最大サイズに対する上限は、クエリジョブ実行の特定の段階で適用されます。
jobs.getQueryResult
は、サポートを通じてより大きなデータサイズを明示的にリクエストした場合を除いて、20 MB のデータを返すことができます。
ページは全行数のサブセットです。結果が 1 ページ分のデータを超える場合、結果データには pageToken プロパティが追加されます。次のページの結果を取得するには、別の list
呼び出しを行い、トークン値を pageToken という名前の URL パラメータとして指定します。
テーブルデータのページ分けに使用する tabledata.list メソッドでは、行オフセット値またはページトークンを使用します。詳細については、テーブルデータの閲覧をご覧ください。
BigQuery テーブルデータをページ分割するサンプルを以下に示します。
C#
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、BigQuery C# API のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
Go 用の Cloud クライアント ライブラリでは、デフォルトで自動的にページ分けされるため、ページ分けを自分で実装する必要はありません。次に例を示します。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
Node.js 用の Cloud クライアント ライブラリでは、デフォルトで自動的にページ分けされるため、ページ分けを自分で実装する必要はありません。次に例を示します
PHP
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用にある PHP 向けの手順に従って設定を行ってください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。
PHP 用の Cloud クライアント ライブラリでジェネレータ関数 rows
を使用すると、ページ分けが自動的に行われます。この関数はイテレーション中に結果の次のページをフェッチします。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
Python 用の Cloud クライアント ライブラリでは、デフォルトで自動的にページ分けされるため、ページ分けを自分で実装する必要はありません。次に例を示します。
Ruby
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用で説明している Ruby 向けの手順に沿って設定を行ってください。詳細については、BigQuery Ruby API のリファレンス ドキュメントをご覧ください。
Ruby 用 Cloud クライアント ライブラリで Table#data
と Data#next
を使用すると、ページ分けが自動的に行われます。
任意のページのリクエストと、冗長リスト呼び出しの回避
前のページに戻る場合、またはキャッシュされた pageToken の値を使用して任意のページにジャンプする場合、ページのデータが最後に表示された後で変更されている可能性がありますが、データが変更されたことは明確には示されません。これを確認するには、ETag プロパティを使用できます。
すべての collection.list メソッド(Tabledata 用を除く)は、結果で Etag プロパティを返します。このプロパティは、ページが最後のリクエスト以降に変更されているかどうかを確認するために使用できるページ結果のハッシュです。ETag 値を使用して BigQuery にリクエストを行うと、BigQuery はその ETag 値と API によって返された ETag 値を比較し、ETag 値が一致しているかどうかに基づいて応答します。次の方法で、冗長なリスト呼び出しを回避するために ETag を使用できます。
値が変更されている場合にのみリスト値を返す場合:
値が変更されている場合にのみリスト値のページを返す場合は、HTTP の If-None-Match ヘッダーを使用し、保存しておいた ETag を指定してリスト呼び出しを行うことができます。指定した ETag がサーバー上の ETag と一致しない場合、BigQuery は、新しいリスト値のページを返します。ETag が一致する場合、BigQuery は HTTP 304「Not Modified」という結果を返し、値を返しません。この例として、ユーザーが BigQuery に格納されている情報を定期的に入力するウェブページがあります。ETag と If-None-Match ヘッダーを使用することにより、データに変更がない場合に冗長なリスト呼び出しを避けることができます。
値が変更されていない場合にのみリスト値を返す場合:
リストの値が変更されていない場合にのみリスト値のページを返す場合は、HTTP の If-Match ヘッダーを使用できます。BigQuery は ETag 値を比較し、結果が変更されていない場合は結果のページを返します。ページが変更されている場合は、412「Precondition Failed」という結果を返します。
クエリ結果のページ分け
各クエリは宛先テーブルに書き込みます。宛先テーブルが指定されていない場合、BigQuery API は宛先テーブル プロパティに一時匿名テーブルへの参照を自動的に挿入します。
API
jobs.config.query.destinationTable
フィールドを読み取り、クエリ結果が書き込まれたテーブルを確認します。クエリ結果を読み取るには、tabledata.list を呼び出します。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
Python
QueryJob.result
メソッドは、クエリ結果のイテラブルを返します。または
QueryJob.destination
プロパティを読み取ります。構成されていない場合、API がこのプロパティに一時匿名テーブルへの参照を設定します。Client.get_table
メソッドでテーブル スキーマを取得します。Client.list_rows
メソッドを使用して、宛先テーブルのすべての行に対するイテラブルを作成します。
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順で設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。