Cloud Storage からの Avro データの読み込み

Cloud Storage からの Avro ファイルの読み込み

Avro は、そのファイル内にあるデータのスキーマを使用してシリアル化されたデータをバンドルする、オープンソースのデータ形式です。

Avro データを Cloud Storage から読み込む際に、新しいテーブルまたはパーティションにデータを読み込むか、既存のテーブルまたはパーティションに追加または上書きできます。BigQuery に読み込まれたデータは Capacitor の列型(BigQuery のストレージ形式)に変換されます。

Cloud Storage から BigQuery のテーブルにデータを読み込むとき、読み込み先のテーブルを含むデータセットは Cloud Storage バケットと同じリージョンまたはマルチリージョン ロケーションに存在する必要があります。

ローカル ファイルから Avro データを読み込む方法については、ローカル データソースから BigQuery にデータを読み込むをご覧ください。

Avro の利点

Avro は、BigQuery にデータを読み込むのに適した形式です。Avro ファイルの読み込みには、CSV や JSON(改行区切り)と比べて次のようなメリットがあります。

  • Avro バイナリ形式:
    • 読み込みが速い。データブロックが圧縮されていても、データを並列に読み取ることができます。
    • 型指定やシリアル化は不要。
    • ASCII などの他の形式で見られるエンコードの問題がないため、解析が簡単。
  • Avro ファイルを BigQuery に読み込むと、自己記述型ソースデータからテーブル スキーマが自動的に取得されます。

必要な権限

BigQuery にデータを読み込む場合は、新規または既存の BigQuery のテーブルやパーティションにデータを読み込むためのプロジェクト レベルまたはデータセット レベルの権限が必要です。Cloud Storage からデータを読み込む場合は、データが格納されているバケットへのアクセス権も必要です。

BigQuery の権限

Cloud Storage から BigQuery にデータを読み込む場合は、プロジェクト レベルまたはデータセット レベルで bigquery.dataOwner または bigquery.dataEditor の役割が付与されている必要があります。どちらの役割もユーザーとグループに、新しいテーブルへのデータの読み込みや、既存のテーブルへのデータの追加または上書きを行う権限を付与します。

プロジェクト レベルで役割を付与した場合、プロジェクト内のすべてのデータセットのテーブルにデータを読み込む権限がユーザーまたはグループに与えられます。データセット レベルでユーザーまたはグループに役割を付与した場合、そのデータセット内のテーブルにのみデータを読み込むことができます。

データセット アクセスの構成方法の詳細については、データセットへのアクセスの制御をご覧ください。BigQuery での IAM 役割の詳細については、アクセス制御をご覧ください。

Cloud Storage の権限

Cloud Storage バケットからデータを読み込むには、プロジェクト レベルまたはその個々のバケットの storage.objects.get 権限が付与されている必要があります。URI のワイルドカードを使用する場合は、storage.objects.list 権限も必要です。

事前定義された IAM 役割 storage.objectViewer が割り当てられると、storage.objects.get 権限と storage.objects.list 権限が付与されます。

Avro のスキーマ

Avro ファイルを BigQuery に読み込むと、ソースデータを使用して自動的にテーブル スキーマが取得されます。BigQuery がソースデータからスキーマを取得する際は、アルファベット順で最後のファイルが使用されます。

たとえば、Cloud Storage に次の Avro ファイルがあるとします。

gs://mybucket/00/
  a.avro
  z.avro
gs://mybucket/01/
  b.avro

次のコマンドでは、単一の CLI コマンドですべてのファイルが(カンマ区切りリストとして)読み込まれ、mybucket/01/b.avro からスキーマが取得されます。

bq --location=US load --source_format=AVRO [DATASET].[TABLE_NAME] "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

Avro スキーマが異なる複数の Avro ファイルをインポートする場合は、すべてのスキーマが Avro のスキーマ解決に対応している必要があります。

BigQuery がスキーマを検出すると、一部の Avro データ型が BigQuery データ型に変換され、BigQuery SQL 構文に対応するようになります。詳細については、Avro 変換をご覧ください。

Avro 圧縮

圧縮 Avro ファイルはサポートされていませんが、圧縮データブロックはサポートされています。BigQuery では DEFLATE および Snappy のコーデックがサポートされています。

Avro データを新しいテーブルに読み込む

Cloud Storage から新しい BigQuery テーブルに Avro データを読み込む場合、または既存のテーブルに Avro データを追加する場合は、次の手順に従います。

従来の UI

  1. BigQuery ウェブ UI に移動します。
    BigQuery ウェブ UI に移動

  2. ナビゲーション パネルで、データセットにカーソルを合わせて下矢印アイコン 下矢印アイコン画像 をクリックし、[Create new table] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。

  3. [Create Table] ページの [Source Data] セクションで、次の操作を行います。

    • [Location] で [Cloud Storage] を選択し、ソース フィールドに Cloud Storage URI を入力します。BigQuery ウェブ UI では URI の複数指定はできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在している必要があります。
    • [File format] で [Avro] を選択します。
  4. [Create Table] ページの [Destination Table] セクションで、次の操作を行います。

    • [Table name] で適切なデータセットを選択し、BigQuery で作成するテーブルの名前をテーブル名のフィールドに入力します。
    • [Table type] が [Native table] に設定されていることを確認します。
  5. [Schema] セクションでは、何もする必要はありません。スキーマは Avro ファイルから推論されます。

  6. [Create Table] をクリックします。

コマンドライン

bq load コマンドを使用し、source_format の値として AVRO を指定して、Cloud Storage URI を含めます。単一の URI、URI のカンマ区切りリスト、またはワイルドカードを使用した URI を含めることができます。

--location フラグを指定し、その値を該当するロケーションに設定します。

bq --location=[LOCATION] load --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE]

ここで

  • [LOCATION] はロケーションです。データが US または EU のマルチリージョン ロケーションにある場合は、--location フラグを省略できます。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
  • [FORMAT] は AVRO です。
  • [DATASET] は既存のデータセットです。
  • [TABLE] は、データの読み込み先のテーブル名です。
  • [PATH_TO_SOURCE] は、完全修飾された Cloud Storage URI または URI のカンマ区切りリストです。ワイルドカードもサポートされます。

例:

  • 次のコマンドは、gs://mybucket/mydata.avro から、mydataset 内の mytable というテーブルにデータを読み込みます。mybucketmydataset は、US マルチリージョン ロケーションに作成されています。

    bq --location=US load --source_format=AVRO mydataset.mytable gs://mybucket/mydata.avro
    
  • 次のコマンドは、gs://mybucket/ の複数のファイルから mydatasetmytable という名前のテーブルにデータを読み込みます。Cloud Storage の URI ではワイルドカードを使用しています。 mybucketmydatasetUS マルチリージョン ロケーションに存在します。

    bq --location=US load --source_format=AVRO mydataset.mytable gs://mybucket/mydata*.avro
    
  • 次のコマンドは、gs://mybucket/ の複数のファイルから mydatasetmytable という名前のテーブルにデータを読み込みます。このコマンドでは、Cloud Storage の URI のカンマ区切りのリストをワイルドカード付きで使用しています。mybucketmydatasetasia-northeast1 リージョンに存在します。

    bq --location=asia-northeast1 load --autodetect --source_format=AVRO mydataset.mytable "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"
    

API

API を使用して Avro データを読み込むには、次のプロパティを設定します。

  1. Cloud Storage のソースデータを指す読み込みジョブを作成します。

  2. ジョブリソースjobReference セクションにある location プロパティでロケーションを指定します。

  3. ソース URI は、gs://[BUCKET]/[OBJECT] の形式で完全修飾する必要があります。各 URI に「*」ワイルドカード文字を 1 つ含めることができます。

  4. configuration.load.sourceFormat プロパティの値を AVRO に設定して、Avro データ形式を指定します。

  5. ジョブ ステータスをチェックするには、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 回だけです。

Python

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の設定手順に従ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.source_format = bigquery.SourceFormat.AVRO
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.avro'

load_job = client.load_table_from_uri(
    uri,
    dataset_ref.table('us_states'),
    job_config=job_config)  # API request
print('Starting job {}'.format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print('Job finished.')

destination_table = client.get_table(dataset_ref.table('us_states'))
print('Loaded {} rows.'.format(destination_table.num_rows))

Avro データでテーブルを上書きする

テーブルに追加のデータを読み込むには、ソースファイルを使用するか、クエリ結果を追加します。

Console および従来の BigQuery ウェブ UI では、[Write preference] オプションを使用して、ソースファイルまたはクエリ結果からデータを読み込むときに行う操作を指定します。

追加のデータをテーブルに読み込む場合、以下のオプションがあります。

Console のオプション 従来の UI のオプション CLI のフラグ BigQuery API のプロパティ 説明
空の場合に書き込む 空の場合に書き込む なし WRITE_EMPTY テーブルが空の場合にのみデータを書き込みます。
テーブルに追加する テーブルに追加する --noreplace または --replace=false--[no]replace が指定されていない場合、デフォルトは追加です。 WRITE_APPEND (デフォルト)テーブルの末尾にデータを追加します。
テーブルを上書きする テーブルを上書きする --replace または --replace=true WRITE_TRUNCATE 新しいデータを書き込む前に、テーブル内の既存のデータをすべて消去します。

デフォルトでは、読み込みジョブでデータがテーブルに追加されます。読み込みジョブを使用してテーブルのデータを上書きするには、以下の手順に従います。

従来の UI

  1. BigQuery ウェブ UI に移動します。
    BigQuery ウェブ UI に移動

  2. ナビゲーション パネルで、データセットにカーソルを合わせて下矢印アイコン 下矢印アイコン画像 をクリックし、[Create new table] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。

  3. [Create Table] ページの [Source Data] セクションで、次の操作を行います。

    • [Location] で [Cloud Storage] を選択し、ソース フィールドに Cloud Storage URI を入力します。UI では複数の URI を指定できませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、データを追加または上書きするテーブルを含むデータセットと同じ場所に存在している必要があります。
    • [File format] で [Avro] を選択します。
  4. [Create Table] ページの [Destination Table] セクションで、次の操作を行います。

    • [Table name] で適切なデータセットを選択し、追加または上書きするテーブルの名前をテーブル名のフィールドに入力します。
    • [Table type] が [Native table] に設定されていることを確認します。
  5. [Schema] セクションでは、何もする必要はありません。スキーマ情報は Avro ファイルから推論されます。

  6. [Options] セクションにある [Write preference] で、[Write if empty]、[Append to table]、[Overwrite table] のいずれかを選択します。

    [Add Field] を使用してスキーマを追加する

  7. [Create Table] をクリックします。

コマンドライン

テーブルを上書きするには、--replace フラグを指定して bq load コマンドを入力します。--location フラグを指定し、その値を該当するロケーションに設定します。テーブルにデータを追加するには、--noreplace フラグを使用します。フラグを指定しない場合、デフォルトではデータが追加されます。

bq --location=[LOCATION] load --[no]replace [DATASET].[TABLE] [PATH_TO_SOURCE]

ここで

  • [LOCATION]ロケーションです。データが US または EU のマルチリージョン ロケーションにある場合は、--location フラグを省略できます。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
  • [DATASET] は既存のデータセットです。
  • [TABLE] は、データの読み込み先のテーブル名です。
  • [PATH_TO_SOURCE] は、完全修飾された Cloud Storage URI または URI のカンマ区切りリストです。ワイルドカードもサポートされます。

例:

  • 次のコマンドは、gs://mybucket/mydata.avro からデータを読み込んで mydataset 内の mytable というテーブルを上書きします。mybucketmydataset は、US マルチリージョン ロケーション作成されています。

    bq --location=US load --replace --source_format=AVRO mydataset.mytable gs://mybucket/mydata.avro
    
  • 次のコマンドは、gs://mybucket/mydata.avro からデータを読み込んで mydataset 内の mytable というテーブルに追加します。mybucketmydataset は、asia-northeast1 リージョンに作成されています。

    bq --location=asia-northeast1 load --noreplace --source_format=AVRO mydataset.mytable gs://mybucket/mydata.avro
    

API

API を使用して CSV データを読み込むには、次のプロパティを設定します。

  1. Cloud Storage のソースデータを指す読み込みジョブを作成します。

  2. ジョブリソースjobReference セクションにある location プロパティでロケーションを指定します。

  3. ソース URI は、gs://[BUCKET]/[OBJECT] の形式で完全修飾する必要があります。複数の URI をカンマ区切りのリストとして含めることができます。Cloud Storage から CSV データを読み込む場合、ワイルドカードを使用することもできます。

  4. configuration.load.sourceFormat プロパティの値を AVRO に設定して、AVRO データ形式を指定します。

  5. configuration.load.writeDisposition プロパティの値を WRITE_TRUNCATEWRITE_APPEND、または WRITE_EMPTY に設定して、目的の書き込み設定を指定します。

Python

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の設定手順に従ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.source_format = bigquery.SourceFormat.AVRO
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"
load_job = client.load_table_from_uri(
    uri, table_ref, job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(table_ref)
print("Loaded {} rows.".format(destination_table.num_rows))

Avro の変換

BigQuery は、次のように Avro のデータ型を BigQuery のデータ型に変換します。

プリミティブ型

Avro のデータ型 BigQuery のデータ型 メモ
null BigQuery はこれらの値を無視します
boolean BOOLEAN
int INTEGER
long INTEGER
float FLOAT
double FLOAT
bytes BYTES
decimal 論理型を使用した bytes NUMERIC
string STRING UTF-8 のみ

複合型

Avro のデータ型 BigQuery のデータ型 メモ
record RECORD
  • エイリアスは無視されます
  • Doc はフィールド記述に変換されます
  • デフォルト値は読み取り時に設定されます
  • 順序は無視されます
  • 再帰フィールドは削除されます - 再帰フィールドに対しては、最初のネストレベルのみが維持されます
enum STRING
  • 文字列は enum のシンボリック値です
  • エイリアスは無視されます
  • Doc はフィールド記述に変換されます
array 繰り返しフィールド 配列の配列はサポートされていません。NULL 型のみが含まれている配列は無視されます。
map<T> RECORD BigQuery は Avro の map<T> フィールドを、キーと値の 2 つのフィールドを含む繰り返し RECORD に変換します。BigQuery は、キーを STRING として格納し、値を BigQuery における対応データに変換します。
union
  • null 値を指定できるフィールド
  • null 値を指定できるフィールドのリストを含む RECORD
  • union に非 null 型が 1 つしかない場合、null 値を指定できるフィールドに変換されます。
  • それ以外の場合は、null 値を指定できるフィールドのリストを含む RECORD に変換されます。読み取り時には、これらのフィールドのいずれか 1 つだけが設定されます。
固定 BYTES
  • エイリアスは無視されます
  • サイズは無視されます

論理型

デフォルトでは、BigQuery は logicalType 属性を無視し、代わりに基礎となる Avro の型を使用します。

Avro の論理型 BigQuery のデータ型
date INTEGER
time-millis INTEGER
time-micros INTEGER(LONG から変換)
timestamp-millis INTEGER(LONG から変換)
timestamp-micros INTEGER(LONG から変換)
duration BYTES(サイズ 12 の fixed 型から変換)
decimal NUMERIC(decimal 論理型を参照)

Avro の論理型から対応する BigQuery データ型への変換を可能にするには、コマンドライン ツールを使用して --use_avro_logical_types フラグの値を True に設定するか、useAvroLogicalTypes メソッドを呼び出して読み込みジョブを作成する際にジョブリソースjobs.insert プロパティを設定します。

次の表に、Avro の論理型から BigQuery データ型への変換を示します。

Avro の論理型 変換後の BigQuery データ型
date DATE
time-millis TIME
time-micros TIME
timestamp-millis TIMESTAMP
timestamp-micros TIMESTAMP
duration BYTES(サイズ 12 の fixed 型から変換)
decimal NUMERIC(decimal 論理型を参照)

Avro のデータ型の詳細については、Apache Avro™ 1.8.2 Specification をご覧ください。

decimal 論理型

decimal 論理型を使用した Avro の bytes 型での precision(合計桁数)は最大 38、scale(小数点以下の桁数)は最大 9 です。整数の桁数は precision から scale を引いた数なので、最大で 29 になります。たとえば、precision が 38 で、scale が 9 の decimal は、整数の桁数が 29 であるためサポートされます。precision が 38 で、scale が 5 の decimal は、整数の桁数が 33 であるためサポートされません。

既存のテーブルに、decimal 論理型を使用した bytes 列が含まれる Avro ファイルを読み込むと、その列のデータ型はテーブルのスキーマ定義内で BYTES または NUMERIC になります。列のデータ型が BYTES の場合、Avro ファイル内の列に設定された decimal 論理型は無視されます。

Avro の decimal 論理型について詳しくは、Apache Avro™ 1.8.2 仕様をご覧ください。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。