Cloud Storage からの ORC データの読み込み
このページでは、Cloud Storage から BigQuery への ORC データの読み込みの概要を説明します。
ORC は、Apache Hadoop エコシステムで広く使用されているオープンソースの列指向のデータ形式です。
ORC データを Cloud Storage から読み込む際に、新しいテーブルまたはパーティションにデータを読み込むことも、既存のテーブルまたはパーティションにデータを追加したり上書きしたりすることもできます。BigQuery に読み込まれたデータは Capacitor の列型(BigQuery のストレージ形式)に変換されます。
Cloud Storage から BigQuery テーブルにデータを読み込むとき、テーブルを含むデータセットが Cloud Storage バケットと同じリージョンまたはマルチリージョンのロケーションに存在している必要があります。
ローカル ファイルから ORC データを読み込む方法については、データをローカル データソースから読み込むをご覧ください。
制限事項
Cloud Storage バケットから BigQuery にデータを読み込む際には、次の制限があります。
- データセットのロケーションが
US
マルチリージョン以外の値に設定されている場合、Cloud Storage バケットはデータセットと同じリージョンに存在するか、同じマルチリージョンに含まれている必要があります。 - BigQuery では外部データソースに対して整合性が保証されません。クエリの実行中に基になるデータを変更すると、予期しない動作が発生する可能性があります。
- BigQuery では、Cloud Storage オブジェクトのバージョニングはサポートされていません。Cloud Storage URI に世代番号を含めると、読み込みジョブは失敗します。
準備
このドキュメントの各タスクを行うのに必要な権限をユーザーに与える 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 データセットを作成します。
ORC スキーマ
ORC ファイルを BigQuery に読み込むと、自己記述型ソースデータから自動的にテーブル スキーマが取得されます。BigQuery がソースデータからスキーマを取得する際は、アルファベット順で最後のファイルが使用されます。
たとえば、Cloud Storage に次の ORC ファイルがあるとします。
gs://mybucket/00/ a.orc z.orc gs://mybucket/01/ b.orc
bq コマンドライン ツールでこのコマンドを実行すると、すべてのファイルがカンマ区切りのリストとして読み込まれ、mybucket/01/b.orc
からスキーマが取得されます。
bq load \ --source_format=ORC \ dataset.table \ "gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"
BigQuery がスキーマを検出すると、一部の ORC データ型は、GoogleSQL 構文に対応するように BigQuery データ型に変換されます。検出されたスキーマに含まれるフィールドはすべて NULLABLE
です。詳細については、ORC 変換をご覧ください。
スキーマが異なる複数の ORC ファイルを読み込む場合、複数のスキーマで指定された同一のフィールド(名前とネストレベルが同じ)は、各スキーマ定義の同じ変換済み BigQuery データ型にマッピングする必要があります。
外部テーブルを作成するためのテーブル スキーマを提供するには、参照ファイルの URL に BigQuery API のreferenceFileSchemaUri
プロパティを設定するか、bq コマンドライン ツールの
--reference_file_schema_uri
パラメータを設定します。
例: --reference_file_schema_uri="gs://mybucket/schema.orc"
ORC 圧縮
BigQuery は、ORC ファイルの内容に対して次の圧縮コーデックをサポートしています。
Zlib
Snappy
LZO
LZ4
ZSTD
ORC ファイルのデータは、BigQuery にアップロードされた後に圧縮されたままではありません。データ ストレージは、データセット ストレージの課金モデルに応じて、論理バイトまたは物理バイトで報告されます。ストレージ使用量に関する情報を取得するには、INFORMATION_SCHEMA.TABLE_STORAGE
ビューにクエリを実行します。
ORC データを新しいテーブルに読み込む
新しいテーブルに ORC データを読み込むには、次の方法を使用します。
- Google Cloud コンソールを使用する
- bq コマンドライン ツールの
bq load
コマンドを使用する jobs.insert
API メソッドを呼び出してload
ジョブを構成する- クライアント ライブラリを使用する
ORC データを Cloud Storage から新しい BigQuery テーブルに読み込むには:
コンソール
Google Cloud コンソールで [BigQuery] ページに移動します。
- [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
- [データセット情報] セクションで、[ テーブルを作成] をクリックします。
- [テーブルを作成] パネルで、次の詳細を指定します。
- [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
- Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
- [ファイル形式] で、[ORC] を選択します。
- [送信先] セクションで、次の詳細を指定します。
- [データセット] で、テーブルを作成するデータセットを選択します。
- [テーブル] フィールドに、作成するテーブルの名前を入力します。
- [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
- [Schema] セクションでは、何もする必要はありません。スキーマは ORC ファイルで自己記述されます。
- 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。
- [詳細オプション] をクリックして、次の操作を行います。
- [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
- テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
- [テーブルを作成] をクリックします。
SQL
LOAD DATA
DDL ステートメントを使用します。次の例では、ORC ファイルを新しいテーブル mytable
に読み込みます。
Google Cloud コンソールで [BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
LOAD DATA OVERWRITE mydataset.mytable FROM FILES ( format = 'ORC', uris = ['gs://bucket/path/file.orc']);
[
実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。
bq
bq load
コマンドを使用し、source_format
に ORC を指定して、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 鍵。パーティション分割テーブルの詳細については、以下をご覧ください。
クラスタ化テーブルの詳細については、以下をご覧ください。
テーブル暗号化の詳細については、以下をご覧ください。
ORC データを BigQuery に読み込むには、次のコマンドを入力します。
bq --location=location load \ --source_format=format \ dataset.table \ path_to_source
ここで
- location はロケーションです。
--location
フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1
に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。 - format は
ORC
です。 - dataset は既存のデータセットです。
- table は、データの読み込み先のテーブル名です。
- path_to_source は、完全修飾の Cloud Storage URI または URI のカンマ区切りのリストです。ワイルドカードもサポートされます。
例:
次のコマンドは、gs://mybucket/mydata.orc
から、mydataset
内の mytable
というテーブルにデータを読み込みます。
bq load \
--source_format=ORC \
mydataset.mytable \
gs://mybucket/mydata.orc
次のコマンドは、gs://mybucket/mydata.orc
からデータを読み込んで mydataset
内の mytable
という新しい取り込み時間パーティション分割テーブルに追加します。
bq load \
--source_format=ORC \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.orc
次のコマンドは、gs://mybucket/mydata.orc
からデータを読み込んで mydataset
内の mytable
というパーティション分割テーブルに追加します。テーブルは mytimestamp
列でパーティション分割されます。
bq load \
--source_format=ORC \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.orc
次のコマンドは、gs://mybucket/
の複数のファイルから mydataset
内の mytable
という名前のテーブルにデータを読み込みます。Cloud Storage の URI ではワイルドカードを使用しています。
bq load \
--source_format=ORC \
mydataset.mytable \
gs://mybucket/mydata*.orc
次のコマンドは、gs://mybucket/
の複数のファイルから mydataset
内の mytable
という名前のテーブルにデータを読み込みます。このコマンドでは、Cloud Storage の URI のカンマ区切りのリストをワイルドカード付きで使用しています。
bq load --autodetect \
--source_format=ORC \
mydataset.mytable \
"gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"
API
Cloud Storage のソースデータを参照する
load
ジョブを作成します。(省略可)ジョブリソースの
jobReference
セクションにあるlocation
プロパティでロケーションを指定します。source URIs
プロパティは、完全修飾のgs://bucket/object
の形式にする必要があります。各 URI にワイルドカード文字(*)を 1 つ含めることができます。sourceFormat
プロパティをORC
に設定して、ORC データ形式を指定します。ジョブのステータスを確認するには、
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 回だけです。
C#
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある C# の設定手順を完了してください。詳細については、BigQuery C# API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Go
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Go の設定手順を完了してください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Java
Node.js
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Node.js の設定手順を完了してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
PHP
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある PHP の設定手順を完了してください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Python
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Ruby
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Ruby の設定手順を完了してください。詳細については、BigQuery Ruby API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
ORC データをテーブルに追加または上書きする
テーブルに追加のデータを読み込むには、ソースファイルを使用するか、クエリ結果を追加します。
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
ジョブを構成する- クライアント ライブラリを使用する
ORC データをテーブルに追加または上書きするには:
コンソール
Google Cloud コンソールで [BigQuery] ページに移動します。
- [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
- [データセット情報] セクションで、[ テーブルを作成] をクリックします。
- [テーブルを作成] パネルで、次の詳細を指定します。
- [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
- Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
- [ファイル形式] で、[ORC] を選択します。
- [送信先] セクションで、次の詳細を指定します。
- [データセット] で、テーブルを作成するデータセットを選択します。
- [テーブル] フィールドに、作成するテーブルの名前を入力します。
- [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
- [Schema] セクションでは、何もする必要はありません。スキーマは ORC ファイルで自己記述されます。
- 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。追加や上書きではテーブルをパーティション分割テーブルまたはクラスタ化テーブルに変換できません。Google Cloud コンソールでは、読み込みジョブでパーティション分割テーブルやクラスタ化テーブルの追加または上書きを行うことはできません。
- [詳細オプション] をクリックして、次の操作を行います。
- [書き込み設定] で、[テーブルに追加する] または [テーブルを上書きする] を選択します。
- テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
- [テーブルを作成] をクリックします。
SQL
LOAD DATA
DDL ステートメントを使用します。次の例では、ORC ファイルをテーブル mytable
に追加します。
Google Cloud コンソールで [BigQuery] ページに移動します。
クエリエディタで次のステートメントを入力します。
LOAD DATA INTO mydataset.mytable FROM FILES ( format = 'ORC', uris = ['gs://bucket/path/file.orc']);
[
実行] をクリックします。
クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。
bq
テーブルを上書きするには、--replace
フラグを指定して bq load
コマンドを入力します。テーブルにデータを追加するには、--noreplace
フラグを使用します。フラグを指定しない場合、デフォルトではデータが追加されます。--source_format
フラグを指定し、ORC
に設定します。ORC スキーマは自己記述型ソースデータから自動的に取得されるため、スキーマ定義を指定する必要はありません。
(省略可)--location
フラグを指定して、その値をロケーションに設定します。
次のフラグを使用することもできます。
--destination_kms_key
: テーブルデータの暗号化に使用される Cloud KMS 鍵。
bq --location=location load \ --[no]replace \ --source_format=format \ dataset.table \ path_to_source
ここで
- location はロケーションです。
--location
フラグは省略可能です。ロケーションのデフォルト値は、.bigqueryrc ファイルを使用して設定できます。 - format は
ORC
です。 - dataset は既存のデータセットです。
- table は、データの読み込み先のテーブル名です。
- path_to_source は、完全修飾の Cloud Storage URI または URI のカンマ区切りのリストです。ワイルドカードもサポートされます。
例:
次のコマンドは、gs://mybucket/mydata.orc
からデータを読み込んで mydataset
内の mytable
というテーブルを上書きします。
bq load \
--replace \
--source_format=ORC \
mydataset.mytable \
gs://mybucket/mydata.orc
次のコマンドは、gs://mybucket/mydata.orc
からデータを読み込んで mydataset
内の mytable
というテーブルに追加します。
bq load \
--noreplace \
--source_format=ORC \
mydataset.mytable \
gs://mybucket/mydata.orc
bq コマンドライン ツールを使用したパーティション分割テーブルに対する追加と上書きについては、パーティション分割テーブルデータの追加と上書きをご覧ください。
API
Cloud Storage のソースデータを参照する
load
ジョブを作成します。(省略可)ジョブリソースの
jobReference
セクションにあるlocation
プロパティでロケーションを指定します。source URIs
プロパティは、完全修飾のgs://bucket/object
の形式にする必要があります。複数の URI をカンマ区切りのリストとして含めることができます。ワイルドカードも使用できます。configuration.load.sourceFormat
プロパティをORC
に設定して、データ形式を指定します。configuration.load.writeDisposition
プロパティをWRITE_TRUNCATE
またはWRITE_APPEND
に設定して、書き込み設定を指定します。
C#
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある C# の設定手順を完了してください。詳細については、BigQuery C# API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Go
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Go の設定手順を完了してください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Java
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_TRUNCATE に設定します。Ruby
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Ruby の設定手順を完了してください。詳細については、BigQuery Ruby API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証情報を設定するをご覧ください。
Hive パーティション分割 ORC データを読み込む
BigQuery では、Cloud Storage に保管されている Hive パーティション分割 ORC データを読み取り可能であり、宛先 BigQuery マネージド テーブルの列として Hive パーティショニング列を取り込みます。詳しくは、Cloud Storage からの外部パーティション分割データの読み取りをご覧ください。
ORC 変換
BigQuery は ORC のデータ型を次の BigQuery データ型に変換します。
プリミティブ型
BigQuery のデータ型 | 注 | |
---|---|---|
boolean | BOOLEAN | |
byte | INTEGER | |
short | INTEGER | |
int | INTEGER | |
long | INTEGER | |
float | FLOAT | |
double | FLOAT | |
string | STRING | UTF-8 のみ |
varchar | STRING | UTF-8 のみ |
char | STRING | UTF-8 のみ |
binary | BYTES | |
date | DATE | ORC データで -719162 日未満または 2932896 日を超える値を変換しようとすると、invalid date
value エラーが返されます。これによって影響を受ける場合は、サポートに連絡して、必要に応じて、サポートされていない値を BigQuery の最小値 0001-01-01 、または最大値 9999-12-31 に変換してください。 |
timestamp | TIMESTAMP |
ORC はナノ秒単位の精度をサポートしますが、BigQuery はデータを読み取るときにマイクロ秒未満の値をマイクロ秒に変換します。 ORC データで -719162 日未満または 2932896 日を超える値を変換しようとすると、 |
decimal | NUMERIC、BIGNUMERIC、または STRING | 固定小数点型をご覧ください。 |
Decimal 型
Decimal
の論理型は、NUMERIC
、BIGNUMERIC
、STRING
の型に変換できます。変換される型は、decimal
論理型の精度とスケールのパラメータ、また指定されたターゲットの固定小数点型によって異なります。ターゲットの固定小数点型は次のように指定します。
jobs.insert
API を使用する読み込みジョブの場合:JobConfigurationLoad.decimalTargetTypes
フィールドを使用します。- bq コマンドライン ツールで
bq load
コマンドを使用する読み込みジョブの場合:--decimal_target_types
フラグを使用します。 - 外部ソースを含むテーブルに対するクエリの場合:
ExternalDataConfiguration.decimalTargetTypes
フィールドを使用します。 - DDL で作成した永続外部テーブルの場合:
decimal_target_types
オプションを使用します。
複合型
BigQuery のデータ型 | 注 | |
---|---|---|
struct | RECORD |
|
map<K,V> | RECORD | ORC の map<K,V> フィールドは、2 つのフィールド(K と同じデータ型のキー、V と同じデータ型の値)を含む、繰り返し RECORD に変換されます。両方のフィールドが NULLABLE です。 |
list | 繰り返しフィールド | ネストされたリストとマップのリストはサポートされていません。 |
union | RECORD |
|
Column names
列名には、英字(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
アノテーションは、常にプレースホルダ名よりも優先されます。
制限事項
柔軟な列名は、外部テーブルではサポートされていません。
NULL
値
BigQuery は読み込みジョブで list
複合型の NULL
要素を無視します。理由は、無視されずに NULL
ARRAY
要素に変換されるとテーブルに存続できなくなるからです(詳細はデータ型をご覧ください)。
ORC のデータ型の詳細については、Apache ORC™ Specification v1 をご覧ください。