BigLake テーブルの Cloud Storage データにクエリを行う

このドキュメントでは、Cloud Storage BigLake テーブルに保存されているデータに対してクエリを行う方法について説明します。

始める前に

Cloud Storage BigLake テーブルがあることを確認します。

必要なロール

Cloud Storage BigLake テーブルに対してクエリを行うには、次のロールがあることを確認してください。

BigQuery データ閲覧者（roles/bigquery.dataViewer）
BigQuery ユーザー（roles/bigquery.user）

権限に応じて、これらのロールを自身に付与するか、これらのロールを付与するよう管理者に依頼します。ロールの付与の詳細については、リソースに対して付与可能なロールの表示をご覧ください。

Cloud Storage BigLake テーブルのクエリに必要な権限を正確に確認するには、[必要な権限] セクションを展開します。

必要な権限

bigquery.jobs.create
bigquery.readsessions.create（BigQuery Storage Read API を使用してデータを読み取る場合にのみ必要）
bigquery.tables.get
bigquery.tables.getData

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

BigLake テーブルに対してクエリを行う

Cloud Storage BigLake テーブルを作成すると、標準の BigQuery テーブルの場合と同じように GoogleSQL 構文を使用してクエリを行うことができます。例: SELECT field1, field2 FROM mydataset.my_cloud_storage_table;

外部データ処理ツールを使用して BigLake テーブルにクエリを行う

BigQuery コネクタと他のデータ処理ツールを使用して、Cloud Storage 上の BigLake テーブルにアクセスできます。詳細については、コネクタをご覧ください。

Apache Spark

次の例では Dataproc を使用していますが、Spark-BigQuery コネクタを使用する Spark デプロイメントでも動作します。

この例では、クラスタを作成するときに、初期化アクションとして Spark-BigQuery コネクタを指定します。このアクションでは、Zeppelin ノートブックを使用して、データアナリストユーザーの行動を実行できます。

Spark-BigQuery コネクタのバージョンは、GitHub の GoogleCloudDataproc/spark-bigquery-connector リポジトリに記載されています。

Spark-BigQuery コネクタの初期化アクションを使用して、単一ノードのクラスタを作成します。

gcloud dataproc clusters create biglake-demo-cluster \
    --optional-components=ZEPPELIN \
    --region=REGION \
    --enable-component-gateway \
    --single-node \
    --initialization-actions gs://goog-dataproc-initialization-actions-REGION/connectors/connectors.sh \
    --metadata spark-bigquery-connector-url= gs://spark-lib/bigquery/spark-bigquery-with-dependencies_SCALA_VERSION-CONNECTOR_VERSION.jar

Apache Hive

次の例では Dataproc を使用していますが、Hive-BigQuery コネクタを使用するすべての Hive デプロイメントでも使用できます。

この例では、クラスタを作成するときに、初期化アクションとして Hive-BigQuery コネクタを指定します。

Hive-BigQuery コネクタのバージョンは、GitHub の GoogleCloudDataproc/hive-bigquery-connector リポジトリにあります。

Hive-BigQuery コネクタの初期化アクションを使用して、単一ノードのクラスタを作成します。

gcloud dataproc clusters create biglake-hive-demo-cluster \
    --region=REGION \
    --single-node \
    --initialization-actions gs://goog-dataproc-initialization-actions-REGION/connectors/connectors.sh \
    --metadata hive-bigquery-connector-url=gs://goog-dataproc-artifacts-REGION/hive-bigquery/hive-bigquery-connector-CONNECTOR_VERSION.jar

Hive-BigQuery コネクタの詳細については、Hive-BigQuery コネクタを使用するをご覧ください。

Dataflow

Dataflow から BigLake テーブルを読み取るには、DIRECT_READ モードで Dataflow コネクタを使用して、BigQuery Storage API を使います。クエリ文字列からの読み取りもサポートされています。Apache Beam ドキュメントの BigQuery I/O をご覧ください。

一時的な BigLake テーブルに対してクエリを行う

外部データに対する 1 回限りのアドホッククエリを行う場合、または抽出、変換、読み込み（ETL）プロセスを行う場合は、一時テーブルを使用して外部データソースのクエリを行うと便利です。

永続テーブルを作成せずに外部データソースに対してクエリを実行するには、一時テーブルに対してテーブル定義を指定し、コマンドまたは呼び出しでそのテーブル定義を使用して一時テーブルに対してクエリを実行します。テーブル定義は次のいずれかの方法で指定できます。

テーブル定義ファイル
インラインスキーマの定義
JSON スキーマファイル

テーブル定義ファイルまたは指定したスキーマを使用して一時外部テーブルが作成され、そのテーブルに対してクエリが実行されます。

外部の一時テーブルを使用する場合は、BigQuery データセット内にテーブルが作成されません。テーブルはデータセットに永続的に保存されないため、このテーブルを他のユーザーと共有することはできません。

bq コマンドラインツール、API、クライアントライブラリを使用して、外部データソースにリンクされた一時テーブルを作成してクエリを実行できます。

bq

--external_table_definition フラグを指定して bq query コマンドを使用します。

（省略可）--location フラグを指定して、その値をロケーションに設定します。

テーブル定義ファイルを使用して、外部データソースにリンクする一時テーブルに対してクエリを実行するには、次のコマンドを入力します。

bq --location=LOCATION query \
--external_table_definition=TABLE::DEFINITION_FILE \
'QUERY'

次のように置き換えます。

LOCATION: ロケーションの名前。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
TABLE: 作成する一時テーブルの名前。
DEFINITION_FILE: ローカルマシン上のテーブル定義ファイルへのパス。
QUERY: 一時テーブルに送信するクエリ。

たとえば、次のコマンドを実行すると、sales_def というテーブル定義ファイルを使用して sales という一時テーブルが作成され、クエリが実行されます。

bq query \
--external_table_definition=sales::sales_def@us.myconnection \
'SELECT
  Region,
  Total_sales
FROM
  sales'

インラインスキーマ定義を使用して、外部データソースにリンクする一時テーブルに対してクエリを実行するには、次のコマンドを入力します。

bq --location=LOCATION query \
--external_table_definition=TABLE::SCHEMA@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
'query'

次のように置き換えます。

LOCATION: ロケーションの名前。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
TABLE: 作成する一時テーブルの名前。
SCHEMA: field:data_type,field:data_type という形式のインラインスキーマの定義。
SOURCE_FORMAT は、外部データソースの形式です（例: CSV）。
BUCKET_PATH: テーブルのデータを含む Cloud Storage バケットへのパス（gs://bucket_name/[folder_name/]file_pattern 形式）。

file_pattern にワイルドカードとしてアスタリスク（*）を 1 つ指定して、バケットから複数のファイルを選択することもできます。たとえば、gs://mybucket/file00*.parquet のようにします。詳細については、Cloud Storage の URI でのワイルドカードのサポートをご覧ください。

複数のパスを指定して、uris オプションに複数のバケットを指定できます。

次の例に、有効な uris 値を示します。
- gs://bucket/path1/myfile.csv
- gs://bucket/path1/*.parquet
- gs://bucket/path1/file1*、gs://bucket1/path1/*
複数のファイルをターゲットとする uris 値を指定する場合、それらのファイルはすべて互換性のあるスキーマを共有する必要があります。

BigQuery での Cloud Storage URI の使用方法については、Cloud Storage リソースパスをご覧ください。
PROJECT_ID: 接続を含むプロジェクト。
REGION: 接続を含むリージョン（例: us）。
CONNECTION_ID: 接続の名前（例: myconnection）。
QUERY: 一時テーブルに送信するクエリ。

たとえば、次のコマンドを実行すると、スキーマ定義 Region:STRING,Quarter:STRING,Total_sales:INTEGER を使用して、Cloud Storage に保存された CSV ファイルにリンクする一時テーブルが sales という名前で作成され、クエリが実行されます。

bq query \
--external_table_definition=sales::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv@us.myconnection \
'SELECT
  Region,
  Total_sales
FROM
  sales'

JSON スキーマファイルを使用して、外部のデータソースにリンクする一時テーブルに対してクエリを実行するには、次のコマンドを入力します。

bq --location=LOCATION query \
--external_table_definition=SCHEMA_FILE@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
'QUERY'

次のように置き換えます。

LOCATION: ロケーションの名前。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
SCHEMA_FILE: ローカルマシン上の JSON スキーマファイルへのパス
SOURCE_FORMAT は、外部データソースの形式です（例: CSV）。
BUCKET_PATH: テーブルのデータを含む Cloud Storage バケットへのパス（gs://bucket_name/[folder_name/]file_pattern 形式）。

file_pattern にワイルドカードとしてアスタリスク（*）を 1 つ指定して、バケットから複数のファイルを選択することもできます。たとえば、gs://mybucket/file00*.parquet のようにします。詳細については、Cloud Storage の URI でのワイルドカードのサポートをご覧ください。

複数のパスを指定して、uris オプションに複数のバケットを指定できます。

次の例に、有効な uris 値を示します。
- gs://bucket/path1/myfile.csv
- gs://bucket/path1/*.parquet
- gs://bucket/path1/file1*、gs://bucket1/path1/*
複数のファイルをターゲットとする uris 値を指定する場合、それらのファイルはすべて互換性のあるスキーマを共有する必要があります。

BigQuery での Cloud Storage URI の使用方法については、Cloud Storage リソースパスをご覧ください。
PROJECT_ID: 接続を含むプロジェクト。
REGION: 接続を含むリージョン（例: us）。
CONNECTION_ID: 接続の名前（例: myconnection）。
QUERY: 一時テーブルに送信するクエリ。

たとえば、次のコマンドを実行すると、/tmp/sales_schema.json というスキーマファイルを使用して、Cloud Storage に保存された CSV ファイルにリンクするテーブルが sales という名前で作成されます。

  bq query \
  --external_table_definition=sales::/tmp/sales_schema.json@CSV=gs://mybucket/sales.csv@us.myconnection \
  'SELECT
      Region,
      Total_sales
    FROM
      sales'

API

API を使用してクエリを実行する手順は次のとおりです。

Job オブジェクトを作成します。
Job オブジェクトの configuration セクションに JobConfiguration オブジェクトを入力します。
JobConfiguration オブジェクトの query セクションに JobConfigurationQuery オブジェクトを入力します。
JobConfigurationQuery オブジェクトの tableDefinitions セクションに ExternalDataConfiguration オブジェクトを入力します。connectionId フィールドに、Cloud Storage への接続に使用する接続を指定します。
クエリを非同期で実行するには jobs.insert メソッドを呼び出し、同期的にクエリを実行するには jobs.query メソッドを呼び出して、Job オブジェクトで渡します。

次のステップ

BigQuery での SQL の使用について確認する。
BigLake テーブルについて確認する。
BigQuery の割り当てについて確認する。