Cloud Storage からの Parquet データの読み込み
このページでは、Cloud Storage から BigQuery への Parquet データの読み込みの概要を説明します。
Parquet は、Apache Hadoop エコシステムで広く使用されているオープンソースの列指向のデータ形式です。
Parquet データを Cloud Storage から読み込む際に、新しいテーブルまたはパーティションにデータを読み込むことも、既存のテーブルまたはパーティションにデータを追加したり、上書きしたりすることもできます。BigQuery に読み込まれたデータは Capacitor の列型(BigQuery のストレージ形式)に変換されます。
Cloud Storage から BigQuery テーブルにデータを読み込むとき、テーブルを含むデータセットが Cloud Storage バケットと同じリージョンまたはマルチリージョンのロケーションに存在している必要があります。
ローカル ファイルから Parquet データを読み込む方法については、ローカル ファイルからのデータの読み込みをご覧ください。
制限事項
Cloud Storage バケットから BigQuery にデータを読み込む際には、次の制限があります。
- データセットのロケーションが
US
マルチリージョン以外の値に設定されている場合、Cloud Storage バケットはデータセットと同じリージョンに存在するか、同じマルチリージョンに含まれている必要があります。 - BigQuery では外部データソースに対して整合性が保証されません。クエリの実行中に基になるデータを変更すると、予期しない動作が発生する可能性があります。
BigQuery では、Cloud Storage オブジェクトのバージョニングはサポートされていません。Cloud Storage URI に世代番号を含めると、読み込みジョブは失敗します。
Parquet データの読み込みは、列名の命名規則に従い、デフォルトでは柔軟な列名をサポートしていません。このプレビューに参加するには、登録フォームにご記入ください。
読み込むファイルのスキーマが異なる場合は、Cloud Storage URI でワイルドカードを使用することはできません。列修飾子の位置に違いがある場合は、別のスキーマと見なされます。
入力ファイルの要件
Parquet ファイルを BigQuery に読み込むときに resourcesExceeded
エラーを回避するには、次のガイドラインに従ってください。
- 行のサイズは 50 MB 以下にします。
- 入力データの列が 100 を超える場合は、ページサイズをデフォルトのページサイズ(1 × 1,024 × 1,024 バイト)より小さくすることを検討してください。これは、大幅に圧縮している場合に特に便利です。
- パフォーマンスを最適化するには、行グループのサイズを 16 MiB 以上にします。行グループのサイズが小さいほど、I/O が増加し、読み込みとクエリの速度が低下します。
始める前に
このドキュメントの各タスクを行うのに必要な権限をユーザーに与える Identity and Access Management(IAM)ロールを付与し、データを保存するためのデータセットを作成します。
必要な権限
BigQuery にデータを読み込むには、読み込みジョブを実行してデータを BigQuery のテーブルとパーティションに読み込む IAM 権限が必要です。Cloud Storage からデータを読み込む場合は、データを含むバケットに対する IAM アクセス権限も必要です。
BigQuery にデータを読み込む権限
新しい BigQuery テーブルやパーティションにデータを読み込む場合、または既存のテーブルやパーティションにデータの追加や上書きを行う場合は、次の IAM 権限が必要です。
bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.update
bigquery.jobs.create
以下の各事前定義 IAM ロールには、BigQuery テーブルやパーティションにデータを読み込むために必要な権限が含まれています。
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin
(bigquery.jobs.create
権限を含む)bigquery.user
(bigquery.jobs.create
権限を含む)bigquery.jobUser
(bigquery.jobs.create
権限を含む)
また、bigquery.datasets.create
権限がある場合は、作成するデータセットで読み込みジョブを使用してテーブルの作成と更新を行えます。
BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。
Cloud Storage からデータを読み込む権限
Cloud Storage バケットからデータを読み込むために必要な権限を取得するには、バケットに対するストレージ管理者(roles/storage.admin
)IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
この事前定義ロールには、Cloud Storage バケットからデータを読み込むために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
Cloud Storage バケットからデータを読み込むには、次の権限が必要です。
-
storage.buckets.get
-
storage.objects.get
-
storage.objects.list (required if you are using a URI wildcard)
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
データセットを作成する
データを保存する BigQuery データセットを作成します。
Parquet のスキーマ
Parquet ファイルを BigQuery に読み込むと、自己記述型ソースデータから自動的にテーブル スキーマが取得されます。BigQuery がソースデータからスキーマを取得する際は、アルファベット順で最後のファイルが使用されます。
たとえば、Cloud Storage に次の Parquet ファイルがあるとします。
gs://mybucket/00/ a.parquet z.parquet gs://mybucket/01/ b.parquet
bq コマンドライン ツールでこのコマンドを実行すると、すべてのファイルが(カンマ区切りのリストとして)読み込まれ、mybucket/01/b.parquet
からスキーマが取得されます。
bq load \ --source_format=PARQUET \ dataset.table \ "gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"
異なるスキーマを持つ複数の Parquet ファイルを読み込む場合、複数のスキーマで指定された同一の列は、各スキーマ定義内で同じモードである必要があります。
BigQuery がスキーマを検出すると、一部の Parquet データ型は、GoogleSQL 構文に対応するように BigQuery データ型に変換されます。詳細については、Parquet の変換をご覧ください。
外部テーブルを作成するためのテーブル スキーマを提供するには、参照ファイルの URL に BigQuery API のreferenceFileSchemaUri
プロパティを設定するか、bq コマンドライン ツールの
--reference_file_schema_uri
パラメータを設定します。
例: --reference_file_schema_uri="gs://mybucket/schema.parquet"
Parquet 圧縮
BigQuery は、Parquet ファイルの内容に対して次の圧縮コーデックをサポートしています。
GZip
LZO_1C
LZO_1X
LZ4_RAW
Snappy
ZSTD
Parquet データを新しいテーブルに読み込む
次のいずれかの方法で、Parquet データを新しいテーブルに読み込むことができます。
- Google Cloud コンソール
- bq コマンドライン ツールの
bq load
コマンド jobs.insert
API メソッドとload
ジョブの構成- クライアント ライブラリ
Parquet データを Cloud Storage から新しい BigQuery テーブルに読み込むには:
コンソール
Google Cloud コンソールで [BigQuery] ページに移動します。
- [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
- [データセット情報] セクションで、[ テーブルを作成] をクリックします。
- [テーブルを作成] パネルで、次の詳細を指定します。
- [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
- Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
- [ファイル形式] で、[Parquet] を選択します。
- [送信先] セクションで、次の詳細を指定します。
- [データセット] で、テーブルを作成するデータセットを選択します。
- [テーブル] フィールドに、作成するテーブルの名前を入力します。
- [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
- [スキーマ] セクションでは、何もする必要はありません。スキーマは、Parquet ファイルで自己記述されます。
- 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。
- [詳細オプション] をクリックして、次の操作を行います。
- [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
- テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
- [テーブルを作成] をクリックします。
SQL
LOAD DATA
DDL ステートメントを使用します。次の例では、Parquet ファイルを新しいテーブル mytable
に読み込みます。
Google Cloud コンソールで [BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
LOAD DATA OVERWRITE mydataset.mytable FROM FILES ( format = 'PARQUET', uris = ['gs://bucket/path/file.parquet']);
[
実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。
bq
bq load
コマンドを使用します。--source_format
フラグを使用して PARQUET
を指定し、Cloud Storage URI を設定します。単一の URI、URI のカンマ区切りのリスト、ワイルドカードを含む URI を指定できます。
(省略可)--location
フラグを指定して、その値をロケーションに設定します。
次のフラグを使用することもできます。
--time_partitioning_type
: テーブルでの時間ベースのパーティショニングを有効にし、パーティション タイプを設定します。有効な値はHOUR
、DAY
、MONTH
、YEAR
です。DATE
、DATETIME
、TIMESTAMP
列でパーティション分割されたテーブルを作成する場合、このフラグは省略可能です。時間ベースのパーティショニングのデフォルト パーティション タイプはDAY
です。既存のテーブルのパーティショニング仕様を変更することはできません。--time_partitioning_expiration
: 時間ベースのパーティションを削除する必要があるタイミングを指定する整数(秒単位)。パーティションの日付(UTC)に、この整数値を足した値が有効期限になります。--time_partitioning_field
: パーティション分割テーブルの作成に使用されるDATE
またはTIMESTAMP
の列。この値を指定せずに時間ベースのパーティショニングを有効にすると、取り込み時間パーティション分割テーブルが作成されます。--require_partition_filter
: 有効にすると、クエリの実行時にWHERE
句でパーティションを指定するようユーザーに求めます。パーティション フィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、クエリでパーティション フィルタを要求するをご覧ください。--clustering_fields
: クラスタ化テーブルの作成に使用する列名のカンマ区切りのリスト。最大 4 個の列名を指定できます。--destination_kms_key
: テーブルデータの暗号化に使用される Cloud KMS 鍵。--column_name_character_map
: 柔軟な列名を有効にするオプションを使用して、列名の文字のスコープと処理を定義します。詳細については、load_option_list
をご覧ください。パーティション分割テーブルの詳細については、以下をご覧ください。
クラスタ化テーブルの詳細については、以下をご覧ください。
テーブルの暗号化の詳細については、以下をご覧ください。
Parquet データを BigQuery に読み込むには、次のコマンドを入力します。
bq --location=LOCATION load \ --source_format=FORMAT \ DATASET.TABLE \ PATH_TO_SOURCE
次のように置き換えます。
LOCATION
: ロケーション。--location
フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1
に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。FORMAT
:PARQUET
DATASET
: 既存のデータセット。TABLE
: データの読み込み先のテーブル名。PATH_TO_SOURCE
: 完全修飾の Cloud Storage URI または URI のカンマ区切りのリスト。ワイルドカードも使用できます。
例:
次のコマンドは、gs://mybucket/mydata.parquet
から、mydataset
内の mytable
というテーブルにデータを読み込みます。
bq load \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata.parquet
次のコマンドは、gs://mybucket/mydata.parquet
からデータを読み込んで mydataset
内の mytable
という新しい取り込み時間パーティション分割テーブルに追加します。
bq load \
--source_format=PARQUET \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.parquet
次のコマンドは、gs://mybucket/mydata.parquet
からデータを読み込んで mydataset
内の mytable
というパーティション分割テーブルに追加します。テーブルは mytimestamp
列でパーティション分割されます。
bq load \
--source_format=PARQUET \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.parquet
次のコマンドは、gs://mybucket/
の複数のファイルから mydataset
内の mytable
という名前のテーブルにデータを読み込みます。Cloud Storage の URI ではワイルドカードを使用しています。
bq load \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata*.parquet
次のコマンドは、gs://mybucket/
の複数のファイルから mydataset
内の mytable
という名前のテーブルにデータを読み込みます。このコマンドでは、Cloud Storage の URI のカンマ区切りのリストをワイルドカード付きで使用しています。
bq load \
--source_format=PARQUET \
mydataset.mytable \
"gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"
API
Cloud Storage のソースデータを参照する
load
ジョブを作成します。(省略可)ジョブリソースの
jobReference
セクションにあるlocation
プロパティでロケーションを指定します。source URIs
プロパティは、完全修飾のgs://BUCKET/OBJECT
の形式にする必要があります。各 URI にワイルドカード文字(*)を 1 つ含めることができます。sourceFormat
プロパティをPARQUET
に設定して、Parquet データ形式を指定します。ジョブのステータスを確認するには、
jobs.get(JOB_ID*)
を呼び出します。JOB_ID は、最初のリクエストで返されるジョブの ID で置き換えます。status.state = DONE
である場合、ジョブは正常に完了しています。status.errorResult
プロパティが存在する場合は、リクエストが失敗したことを意味し、該当するオブジェクトにエラーを説明する情報が格納されます。リクエストが失敗した場合、テーブルは作成されず、データは読み込まれません。status.errorResult
が存在しない場合、ジョブは正常に完了していますが、一部の行のインポートで問題があったなど、致命的でないエラーが発生した可能性があります。致命的でないエラーは、返されたジョブ オブジェクトのstatus.errors
プロパティに格納されています。
API に関する注記:
読み込みジョブはアトミックで整合性があります。読み込みジョブが失敗した場合、データは一切利用できず、読み込みジョブが成功した場合はすべてのデータが利用可能になります。
おすすめの方法として、
jobs.insert
を呼び出して読み込みジョブを作成する際に、一意の ID を生成して、その ID をjobReference.jobId
として渡すようにします。この手法を使用すると、ネットワーク障害時にクライアントは既知のジョブ ID を使ってポーリングまたは再試行できるので、頑健性が向上します。同じジョブ ID に対して
jobs.insert
を呼び出しても結果は同じになります。同じジョブ ID で何回でも再試行できますが、成功するのは、その中で 1 回だけです。
Go
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Go の設定手順を完了してください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Java
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Node.js
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Node.js の設定手順を完了してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
PHP
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある PHP の設定手順を完了してください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Python
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Client.load_table_from_uri() メソッドを使用して、Cloud Storage から読み込みジョブを開始します。Parquet を使用するには、LoadJobConfig.source_format プロパティを文字列PARQUET
に構成し、ジョブ構成を load_table_from_uri()
メソッドの job_config
引数として渡します。
Parquet データでのテーブルの追加または上書き
テーブルに追加のデータを読み込むには、ソースファイルを使用するか、クエリ結果を追加します。
Google Cloud コンソールでは、[書き込み設定] オプションを使用して、ソースファイルやクエリ結果からデータを読み込むときに行う操作を指定します。
追加のデータをテーブルに読み込む場合、以下のオプションがあります。
Console のオプション | bq ツールフラグ | BigQuery API のプロパティ | 説明 |
---|---|---|---|
空の場合に書き込む | 非対応 | WRITE_EMPTY |
テーブルが空の場合にのみデータを書き込みます。 |
テーブルに追加する | --noreplace または --replace=false (--[no]replace を指定しない場合、デフォルトは追加) |
WRITE_APPEND |
(デフォルト)テーブルの末尾にデータを追加します。 |
テーブルを上書きする | --replace または --replace=true |
WRITE_TRUNCATE |
新しいデータを書き込む前に、テーブル内の既存のデータをすべて消去します。この操作を行うと、テーブル スキーマ、行レベルのセキュリティ、Cloud KMS 鍵も削除されます。 |
既存のテーブルにデータを読み込む場合、読み込みジョブでデータの追加やテーブルの上書きを行うことができます。
次のいずれかの方法で、テーブルを追加または上書きできます。
- Google Cloud コンソール
- bq コマンドライン ツールの
bq load
コマンド jobs.insert
API メソッドとload
ジョブの構成- クライアント ライブラリ
Parquet データをテーブルに追加または上書きするには、次の手順を行います。
コンソール
Google Cloud コンソールで [BigQuery] ページに移動します。
- [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
- [データセット情報] セクションで、[ テーブルを作成] をクリックします。
- [テーブルを作成] パネルで、次の詳細を指定します。
- [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
- Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
- [ファイル形式] で、[Parquet] を選択します。
- [送信先] セクションで、次の詳細を指定します。
- [データセット] で、テーブルを作成するデータセットを選択します。
- [テーブル] フィールドに、作成するテーブルの名前を入力します。
- [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
- [スキーマ] セクションでは、何もする必要はありません。スキーマは、Parquet ファイルで自己記述されます。
- 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。追加や上書きではテーブルをパーティション分割テーブルまたはクラスタ化テーブルに変換できません。Google Cloud コンソールでは、読み込みジョブでパーティション分割テーブルやクラスタ化テーブルの追加または上書きを行うことはできません。
- [詳細オプション] をクリックして、次の操作を行います。
- [書き込み設定] で、[テーブルに追加する] または [テーブルを上書きする] を選択します。
- テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
- [テーブルを作成] をクリックします。
SQL
LOAD DATA
DDL ステートメントを使用します。次の例では、Parquet ファイルをテーブル mytable
に追加します。
Google Cloud コンソールで [BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
LOAD DATA INTO mydataset.mytable FROM FILES ( format = 'PARQUET', uris = ['gs://bucket/path/file.parquet']);
[
実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。
bq
テーブルを上書きするには、--replace
フラグを指定して bq load
コマンドを入力します。テーブルにデータを追加するには、--noreplace
フラグを使用します。フラグを指定しない場合、デフォルトではデータが追加されます。--source_format
フラグを指定し、PARQUET
に設定します。Parquet スキーマは自己記述型ソースデータから自動的に取得されるため、スキーマ定義を指定する必要はありません。
(省略可)--location
フラグを指定して、その値をロケーションに設定します。
次のフラグを使用することもできます。
--destination_kms_key
: テーブルデータの暗号化に使用される Cloud KMS 鍵。
bq --location=LOCATION load \ --[no]replace \ --source_format=FORMAT \ DATASET.TABLE \ PATH_TO_SOURCE
次のように置き換えます。
location
: ロケーション。--location
フラグは省略可能です。ロケーションのデフォルト値は、.bigqueryrc ファイルを使用して設定できます。format
:PARQUET
dataset
: 既存のデータセット。table
: データの読み込み先のテーブル名。path_to_source
: 完全修飾の Cloud Storage URI または URI のカンマ区切りのリスト。ワイルドカードも使用できます。
例:
次のコマンドは、gs://mybucket/mydata.parquet
からデータを読み込んで mydataset
内の mytable
というテーブルを上書きします。
bq load \
--replace \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata.parquet
次のコマンドは、gs://mybucket/mydata.parquet
からデータを読み込んで mydataset
内の mytable
というテーブルに追加します。
bq load \
--noreplace \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata.parquet
bq コマンドライン ツールでパーティション分割テーブルへの追加や上書きを行う方法については、パーティション分割テーブルデータの追加と上書きをご覧ください。
API
Cloud Storage のソースデータを参照する
load
ジョブを作成します。(省略可)ジョブリソースの
jobReference
セクションにあるlocation
プロパティでロケーションを指定します。source URIs
プロパティは、完全修飾のgs://BUCKET/OBJECT
の形式にする必要があります。複数の URI をカンマ区切りのリストとして含めることができます。ワイルドカードも使用できます。configuration.load.sourceFormat
プロパティをPARQUET
に設定して、データ形式を指定します。configuration.load.writeDisposition
プロパティをWRITE_TRUNCATE
またはWRITE_APPEND
に設定して、書き込み設定を指定します。
Go
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Go の設定手順を完了してください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Java
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Node.js
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Node.js の設定手順を完了してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
PHP
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある PHP の設定手順を完了してください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Python
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
既存のテーブルに行を追加するには、LoadJobConfig.write_disposition
プロパティを WRITE_APPEND
に設定します。
既存のテーブルの行を置換するには、LoadJobConfig.write_disposition
プロパティを WRITE_TRUNCATE
に設定します。
Hive パーティション分割 Parquet データの読み込み
BigQuery では、Cloud Storage に保管されている Hive パーティション分割 Parquet データを読み取り可能であり、宛先 BigQuery マネージド テーブルの列として Hive パーティショニング列を取り込みます。詳細については、外部パーティション分割データの読み込みをご覧ください。
Parquet の変換
このセクションでは、Parquet データを読み込むときに BigQuery がさまざまなデータ型を解析する方法について説明します。
一部の Parquet データ型(INT32
、INT64
、BYTE_ARRAY
、FIXED_LEN_BYTE_ARRAY
など)は、複数の BigQuery データ型に変換できます。BigQuery が Parquet データ型を正しく変換できるようにするには、Parquet ファイルで適切なデータ型を指定します。
たとえば、Parquet INT32
データ型を BigQuery DATE
データ型に変換するには、次のように指定します。
optional int32 date_col (DATE);
BigQuery は、Parquet データ型を以下のセクションで説明する BigQuery データ型に変換します。
型変換
BigQuery のデータ型 | ||
---|---|---|
BOOLEAN |
なし | BOOLEAN |
INT32 | なし、INTEGER (UINT_8 、UINT_16 、UINT_32 、INT_8 、INT_16 、INT_32 ) |
INT64 |
INT32 | DECIMAL | NUMERIC、BIGNUMERIC、または STRING |
INT32 |
DATE |
DATE |
INT64 |
なし、INTEGER (UINT_64 、INT_64 ) |
INT64 |
INT64 | DECIMAL | NUMERIC、BIGNUMERIC、または STRING |
INT64 |
TIMESTAMP 、precision=MILLIS (TIMESTAMP_MILLIS ) |
TIMESTAMP |
INT64 |
TIMESTAMP 、precision=MICROS (TIMESTAMP_MICROS ) |
TIMESTAMP |
INT96 |
なし | TIMESTAMP |
FLOAT |
なし | FLOAT64 |
DOUBLE |
なし | FLOAT64 |
BYTE_ARRAY |
なし | BYTES |
BYTE_ARRAY |
STRING (UTF8 ) |
STRING |
FIXED_LEN_BYTE_ARRAY | DECIMAL | NUMERIC、BIGNUMERIC、または STRING |
FIXED_LEN_BYTE_ARRAY |
なし | BYTES |
ネストされたグループは、STRUCT
型に変換されます。Parquet の型と変換される型の他の組み合わせはサポートされていません。
未署名の論理型
Parquet UINT_8
、UINT_16
、UINT_32
、UINT_64
型は符号なしです。
BigQuery は、BigQuery の符号付き INTEGER
列に読み込むときに、これらの型の値を符号なしとして扱います。UINT_64
の場合、符号なし値が INTEGER
の最大値 9,223,372,036,854,775,807 を超えるとエラーが返されます。
decimal 論理型
Decimal
の論理型は、NUMERIC
、BIGNUMERIC
、STRING
の型に変換できます。変換される型は、decimal
論理型の精度とスケールのパラメータ、また指定されたターゲットの固定小数点型によって異なります。ターゲットの固定小数点型は次のように指定します。
jobs.insert
API を使用する読み込みジョブの場合:JobConfigurationLoad.decimalTargetTypes
フィールドを使用します。- bq コマンドライン ツールで
bq load
コマンドを使用する読み込みジョブの場合:--decimal_target_types
フラグを使用します。 - 外部ソースを含むテーブルに対するクエリの場合:
ExternalDataConfiguration.decimalTargetTypes
フィールドを使用します。 - DDL で作成した永続外部テーブルの場合:
decimal_target_types
オプションを使用します。
Enum の論理型
Enum
の論理型は、STRING
または BYTES
に変換できます。ターゲットの変換された型は次のように指定します。
jobs.insert
API を使用する読み込みジョブの場合:JobConfigurationLoad.parquetOptions
フィールドを使用します。- bq コマンドライン ツールで
bq load
コマンドを使用する読み込みジョブの場合:--parquet_enum_as_string
フラグを使用します。 bq mk
で作成した永続外部テーブルの場合:--parquet_enum_as_string
フラグを使用します。
LIST の論理型
Parquet の LIST
論理型でスキーマ推定を有効にできます。BigQuery は、LIST
ノードが標準形式か、下位互換性ルールに記載されている形式かをチェックします。
// standard form
<optional | required> group <name> (LIST) {
repeated group list {
<optional | required> <element-type> element;
}
}
標準形式である場合、変換されたスキーマの LIST
ノードに対応するフィールドは、ノードに次のスキーマがあるものとして処理されます。
repeated <element-type> <name>
ノード「list」と「element」は省略されます。
jobs.insert
API を使用する読み込みジョブの場合は、JobConfigurationLoad.parquetOptions
フィールドを使用します。- bq コマンドライン ツールで
bq load
コマンドを使用する読み込みジョブの場合は、--parquet_enable_list_inference
フラグを使用します。 bq mk
で作成した永続外部テーブルの場合は、--parquet_enable_list_inference
フラグ を使用します。CREATE EXTERNAL TABLE
ステートメントで作成した永続外部テーブルの場合は、enable_list_inference
オプションを使用します。
地理空間データ
Parquet ファイルを読み込むには、WKT、WKB(16 進数でエンコード)、または GeoJSON の STRING
列、または WKB の BYTE_ARRAY
列で BigQuery スキーマをタイプ GEOGRAPHY
で指定します。詳細については、地理空間データの読み込みをご覧ください。
GeoParquet ファイルを読み込むこともできます。この場合、GeoParquet メタデータで記述されている列は、デフォルトで GEOGRAPHY
型として解釈されます。明示的なスキーマを指定して、未加工の WKB データを BYTES
列に読み込むこともできます。詳細については、GeoParquet ファイルの読み込みをご覧ください。
列名の変換
列名には、英字(a~z、A~Z)、数字(0~9)、アンダースコア(_)を使用できます。列名の先頭は英字またはアンダースコアにする必要があります。柔軟な列名を使用する場合、BigQuery では列名の先頭に数字を使用できます。BigQuery Storage Read API または BigQuery Storage Write API で柔軟な列名を使用するには、特別な処理が必要となるため、数字で列を開始する場合は注意してください。柔軟な列名のサポートについて詳しくは、柔軟な列名をご覧ください。
列名の最大文字数は 300 文字です。列名には、次のいずれの接頭辞も使用できません。
_TABLE_
_FILE_
_PARTITION
_ROW_TIMESTAMP
__ROOT__
_COLIDENTIFIER
大文字と小文字が異なっている場合でも、重複する列名は使用できません。たとえば、Column1
という列は column1
という列と同じとみなされます。列の命名規則の詳細については、GoogleSQL リファレンスの列名をご覧ください。
テーブル名(test
など)が列名(test
など)のいずれかと同一である場合、SELECT
式は、他のすべてのテーブル列を含む STRUCT
として test
列を解釈します。この競合を回避するには、次のいずれかの方法を使用します。
テーブルとその列に同じ名前を使用しない。
テーブルに別のエイリアスを割り当てる。たとえば、次のクエリでは、テーブル エイリアス
t
をテーブルproject1.dataset.test
に割り当てます。SELECT test FROM project1.dataset.test AS t;
列を参照する際にテーブル名を含める。次に例を示します。
SELECT test.test FROM project1.dataset.test;
柔軟な列名
英語以外の言語の文字へのアクセスの拡張、記号の追加など、列名の柔軟性が向上しました。
柔軟な列名では、次の文字がサポートされています。
- Unicode 正規表現
\p{L}
で表される任意の言語の任意の文字。 - Unicode 正規表現
\p{N}
で表される任意の言語の任意の数字。 - Unicode 正規表現
\p{Pc}
で表される任意の連結用句読記号文字(アンダースコアを含む)。 - Unicode 正規表現
\p{Pd}
で表されるハイフンまたはダッシュ。 - Unicode 正規表現
\p{M}
で表される、別の文字に付随して使用するための任意のマーク(アクセント記号、傘、囲み記号など)。 - 次の特殊文字:
- Unicode 正規表現
\u0026
で表されるアンパサンド(&
)。 - Unicode 正規表現
\u0025
で表されるパーセント記号(%
)。 - Unicode 正規表現
\u003D
で表される等号(=
)。 - Unicode 正規表現
\u002B
で表されるプラス記号(+
)。 - Unicode 正規表現
\u003A
で表されるコロン(:
)。 - Unicode 正規表現
\u0027
で表されるアポストロフィ('
)。 - Unicode 正規表現
\u003C
で表される小なり記号(<
)。 - Unicode 正規表現
\u003E
で表される大なり記号(>
)。 - Unicode 正規表現
\u0023
で表されるナンバー記号(#
)。 - Unicode 正規表現
\u007c
で表される縦線(|
)。 - 空白文字。
- Unicode 正規表現
柔軟な列名は、次の特殊文字をサポートしていません。
- Unicode 正規表現
\u0021
で表される感嘆符(!
)。 - Unicode 正規表現
\u0022
で表される引用符("
)。 - Unicode 正規表現
\u0024
で表されるドル記号($
)。 - Unicode 正規表現
\u0028
で表される左かっこ((
)。 - Unicode 正規表現
\u0029
で表される右かっこ()
)。 - Unicode 正規表現
\u002A
で表されるアスタリスク(*
)。 - Unicode 正規表現
\u002C
で表されるカンマ(,
)。 - Unicode 正規表現
\u002E
で表されるピリオド(.
)。 - Unicode 正規表現
\u002F
で表されるスラッシュ(/
)。 - Unicode 正規表現
\u003B
で表されるセミコロン(;
)。 - Unicode 正規表現
\u003F
で表される疑問符(?
)。 - Unicode 正規表現
\u0040
で表されるアットマーク(@
)。 - Unicode 正規表現
\u005B
で表される左角かっこ([
)。 - Unicode 正規表現
\u005C
で表されるバックスラッシュ(\
)。 - Unicode 正規表現
\u005D
で表される、右角かっこ(]
)。 - Unicode 正規表現
\u005E
で表される曲折アクセント(^
)。 - Unicode 正規表現
\u0060
で表される抑音アクセント(`
)。 - Unicode 正規表現
\u007B
で表される左波かっこ({
)。 - Unicode 正規表現
\u007D
で表される右波かっこ(}
)。 - Unicode 正規表現
\u007E
で表されるチルダ(~
)。
追加のガイドラインについては、列名をご覧ください。
拡張された列の文字は、BigQuery Storage Read API と BigQuery Storage Write API の両方でサポートされています。BigQuery Storage Read API で Unicode 文字の拡張リストを使用するには、フラグを設定する必要があります。displayName
属性を使用すると列名を取得できます。次の例では、Python クライアントでフラグを設定する方法を示します。
from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()
#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options
BigQuery Storage Write API で Unicode 文字の拡張リストを使用するには、JsonStreamWriter
ライター オブジェクトを使用している場合を除き、column_name
表記でスキーマを指定する必要があります。次の例では、スキーマの指定方法を示します。
syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";
message FlexibleSchema {
optional string item_name_column = 1
[(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
optional string item_description_column = 2
[(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}
この例では、item_name_column
と item_description_column
はプレースホルダ名で、プロトコル バッファの命名規則に準拠する必要があります。column_name
アノテーションは、常にプレースホルダ名よりも優先されます。
制限事項
柔軟な列名は、外部テーブルではサポートされていません。
列名にピリオド(.)を持つ列を含む Parquet ファイルを読み込むことはできません。
Parquet の列名に他の文字(ピリオド以外)が含まれている場合、その文字はアンダースコアに置き換えられます。列名の末尾のアンダースコアを追加すると、競合を回避できます。たとえば、Parquet ファイルに Column1
と column1
の 2 つの列が含まれている場合、それらの列はそれぞれ Column1
と column1_
として読み込まれます。
Parquet ファイルのデバッグ
読み込みジョブがデータエラーで失敗した場合は、PyArrow を使用して Parquet データファイルが破損しているかどうかを確認できます。PyArrow でファイルを読み取ることができない場合、BigQuery の読み込みジョブによってファイルが拒否されている可能性があります。次の例は、PyArrow を使用して Parquet ファイルの内容を読み取る方法を示しています。
from pyarrow import parquet as pq
# Read the entire file
pq.read_table('your_sample_file.parquet')
# Read specific columns
pq.read_table('your_sample_file.parquet',columns=['some_column', 'another_column'])
# Read the metadata of specific columns
file_metadata=pq.read_metadata('your_sample_file.parquet')
for col in file_metadata.row_group(0).to_dict()['columns']:
print col['column_path_in_schema']
print col['num_values']
詳細については、PyArrow ドキュメントをご覧ください。