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 に読み込むと、自己記述型ソースデータからテーブル スキーマが自動的に取得されます。

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 load \
--source_format=AVRO \
dataset.table \
"gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

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

スキーマを検出した BigQuery は、BigQuery SQL 構文と互換を持たせるために一部の Avro データ型を BigQuery データ型に変換します。詳細については、Avro 変換をご覧ください。

Avro 圧縮

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

必要な権限

BigQuery にデータを読み込むには、読み込みジョブを実行する権限が必要です。また、新規または既存の BigQuery テーブルやパーティションにデータを読み込むための権限も必要です。Cloud Storage からデータを読み込む場合は、データを含むバケットに対するアクセス権限が必要です。

BigQuery の権限

BigQuery にデータを読み込むには、少なくとも以下の権限が必要です。これらの権限は、データを新しいテーブルまたはパーティションに読み込む場合や、既存のテーブルまたはパーティションに対してデータの追加や上書きを行う場合に必要になります。

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.jobs.create

事前定義された以下の Cloud IAM 役割には、bigquery.tables.createbigquery.tables.updateData の両方の権限が含まれています。

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

bigquery.jobs.create 権限は、以下の事前定義された Cloud IAM 役割に含まれています。

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

また、bigquery.datasets.create 権限を持つユーザーがデータセットを作成すると、作成したデータセットに対する bigquery.dataOwner アクセス権がそのユーザーに付与されます。 bigquery.dataOwner アクセス権により、読み込みジョブを使用してデータセット内のテーブルを作成または更新する権限が付与されます。

BigQuery での Cloud IAM 役割と権限については、アクセス制御をご覧ください。

Cloud Storage の権限

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

事前定義された Cloud IAM 役割 storage.objectViewer が付与されると、storage.objects.get 権限と storage.objects.list 権限が両方とも与えられます。

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

新しいテーブルに Avro データを読み込むには、次の方法を使用します。

  • GCP Console または従来のウェブ UI を使用する
  • CLI の bq load コマンドを使用する
  • jobs.insert API メソッドを呼び出して load ジョブを構成する
  • クライアント ライブラリを使用する

Avro データを Google Cloud Storage から新しい BigQuery テーブルに読み込むには、次の手順を行います。

Console

  1. GCP Console で BigQuery ウェブ UI を開きます。
    GCP Console に移動

  2. ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。

  3. ウィンドウの右側の詳細パネルで、[テーブルを作成] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。

    テーブルを作成

  4. [テーブルを作成] ページの [ソース] セクションで、次の操作を行います。

    • [テーブルの作成元] で [Cloud Storage] を選択します。

    • ソース フィールドで Cloud Storage URI を参照または入力します。GCP Console で複数の URI を指定することはできませんが、ワイルドカードは使用できます。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在している必要があります。

      ファイルを選択

    • [ファイル形式] で [Avro] を選択します。

  5. [テーブルの作成] ページの [送信先] セクションで、次の操作を行います。

    • [データセット名] で、該当するデータセットを選択します。

      データセットを表示

    • [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。

    • [テーブル名] フィールドに、BigQuery で作成するテーブルの名前を入力します。

  6. [スキーマ] セクションでは、何もする必要はありません。Avro ファイルの中にスキーマが自己記述されているからです。

  7. (省略可)テーブルを分割するには、[パーティションとクラスタの設定] で次のオプションを選択します。

    • パーティション分割テーブルを作成するには、[パーティショニングなし] をクリックして [フィールドにより分割] を選択し、DATE 列または TIMESTAMP 列を選択します。スキーマに DATE 列または TIMESTAMP 列が含まれていない場合、このオプションは使用できません。
    • 取り込み時間パーティション分割テーブルを作成するには、[パーティショニングなし] をクリックして [取り込み時間により分割] を選択します。
  8. (省略可)クエリを実行するパーティションを指定する WHERE 句の使用を必須にするには、[パーティショニング フィルタ] で [パーティション フィルタを要求] ボックスをクリックします。パーティション フィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。[パーティショニングなし] を選択している場合、このオプションは使用できません。

  9. (省略可)テーブルをクラスタ化するには、[クラスタリング順序] ボックスに 1~4 個のフィールド名を入力します。現在、クラスタリングはパーティション分割テーブルに対してのみサポートされています。

  10. (省略可)[詳細オプション] をクリックします。

    • [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
    • [許可されているエラー数] で、デフォルト値の 0 を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブは invalid メッセージとなり、失敗します。
    • [不明な値] で [不明な値を無視する] をオフのままにします。このオプションは、CSV ファイルと JSON ファイルにのみ適用されます。
    • Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] をクリックします。[Google が管理する鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
  11. [テーブルを作成] をクリックします。

従来の UI

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

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

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

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

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

  6. (省略可)[Options] セクションで、次の操作を行います。

    • [Number of errors allowed] で、デフォルト値の 0 を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブは invalid メッセージとなり、失敗します。
    • [Write preference] で、[Write if empty] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
    • テーブルを分割するには、次の手順を行います。
      • [Partitioning Type] で、[None] をクリックして [Day] を選択します。
      • [Partitioning Field] で、次の操作を行います。
      • パーティション分割テーブルを作成するには、DATE 列または TIMESTAMP 列を選択します。スキーマに DATE 列または TIMESTAMP 列が含まれていない場合、このオプションは使用できません。
      • 取り込み時間パーティション分割テーブルを作成するには、デフォルト値(_PARTITIONTIME)のままにします。
      • クエリを実行するパーティションを指定する WHERE 句の使用を必須にするには、[Require partition filter] ボックスをクリックします。パーティション フィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。[Partitioning type] を [None] に設定している場合、このオプションは使用できません。
    • テーブルをクラスタ化するには、[Clustering fields] ボックスに 1~4 個のフィールド名を入力します。
    • Cloud Key Management Service 鍵を使用してテーブルを暗号化するには、[Destination encryption] で [Customer-managed encryption] を選択します。Default 設定をそのまま使用すると、BigQuery は Google が管理する鍵を使用して保存されているデータを暗号化します。
  7. [Create Table] をクリックします。

CLI

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

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

次のフラグを使用することもできます。

  • --max_bad_records: ジョブ全体が失敗する前に許容される不良レコードの最大数を整数で指定します。デフォルト値は 0 です。--max_bad_records 値にかかわらず、最大で任意のタイプの 5 つのエラーが返されます。
  • --time_partitioning_type: テーブルで時間ベースのパーティショニングを有効にし、パーティショニング タイプを設定します。現在、唯一の有効な値は、1 日に 1 つのパーティションを生成する DAY です。DATE 列または TIMESTAMP 列でパーティション分割されたテーブルを作成する場合、このフラグは省略可能です。
  • --time_partitioning_expiration: 時間ベースのパーティションが削除されるまでの時間(秒単位)を整数で指定します。パーティションの日付(UTC)に、この整数値を足した値が有効期限になります。
  • --time_partitioning_field: パーティション分割テーブルの作成に使用される DATE 列または TIMESTAMP 列。この値を指定せずに時間ベースのパーティショニングを有効にすると、取り込み時間パーティション分割テーブルが作成されます。
  • --require_partition_filter: 有効にすると、クエリの実行時に WHERE 句でパーティションを指定するようユーザーに求めます。パーティション フィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。
  • --clustering_fields: クラスタ化テーブルの作成に使用するカンマ区切りのリスト。最大 4 個の列名を指定できます。このフラグは、パーティション分割テーブルでのみ使用できます。
  • --destination_kms_key: テーブルデータの暗号化に使用される Cloud KMS 鍵。

    パーティション分割テーブルの詳細については、以下をご覧ください。

    クラスタ化テーブルの詳細については、以下をご覧ください。

    テーブルの暗号化の詳細については、以下をご覧ください。

Avro データを BigQuery に読み込むには、次のコマンドを入力します。

bq --location=location load \
--source_format=format \
dataset.table \
path_to_source

ここで

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

例:

次のコマンドは、gs://mybucket/mydata.avro から、mydataset 内の mytable というテーブルにデータを読み込みます。

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

次のコマンドは、gs://mybucket/mydata.avro から mydataset 内の mytable という取り込み時間パーティション分割テーブルにデータを読み込みます。

    bq load \
    --source_format=AVRO \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.avro

次のコマンドは、gs://mybucket/mydata.avro から mydataset 内の mytable というパーティション分割テーブルにデータを読み込みます。テーブルは mytimestamp 列で分割されます。

    bq load \
    --source_format=AVRO \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.avro

次のコマンドは、gs://mybucket/ の複数のファイルから mydatasetmytable という名前のテーブルにデータを読み込みます。Cloud Storage の URI ではワイルドカードを使用しています。

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata*.avro

次のコマンドは、gs://mybucket/ の複数のファイルから mydatasetmytable という名前のテーブルにデータを読み込みます。このコマンドでは、Cloud Storage の URI のカンマ区切りのリストをワイルドカード付きで使用しています。

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

API

  1. Cloud Storage のソースデータを参照する load ジョブを作成します。

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

  3. source URIs プロパティは、完全修飾の gs://bucket/object の形式にする必要があります。各 URI にワイルドカード文字「*」を 1 つ含めることができます。

  4. 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 では、[書き込み設定] オプションを使用して、ソースファイルまたはクエリ結果からデータを読み込むときに行う操作を指定します。

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

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

既存のテーブルにデータを読み込む場合、読み込みジョブでデータの追加やテーブルの上書きを行うことができます。

次の方法でテーブルを追加または上書きできます。

  • GCP Console または従来のウェブ UI を使用する
  • CLI の bq load コマンドを使用する
  • jobs.insert API メソッドを呼び出して load ジョブを構成する
  • クライアント ライブラリを使用する

Avro データをテーブルに追加または上書きするには、次の手順を行います。

Console

  1. GCP Console で BigQuery ウェブ UI を開きます。
    GCP Console に移動

  2. ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。

  3. ウィンドウの右側の詳細パネルで、[テーブルを作成] をクリックします。読み込みジョブでデータを追加または上書きするプロセスは、読み込みジョブでテーブルを作成するプロセスと同じです。

    テーブルを作成

  4. [テーブルの作成] ページの [ソース] セクションで、次の操作を行います。

    • [テーブルの作成元] で [Cloud Storage] を選択します。

    • ソース フィールドで Cloud Storage URI を参照または入力します。BigQuery ウェブ UI には複数の URI を指定できませんが、ワイルドカードは使用できます。Cloud Storage バケットは、データを追加または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。

      ファイルを選択

    • [ファイル形式] で [Avro] を選択します。

  5. [テーブルの作成] ページの [送信先] セクションで、次の操作を行います。

    • [データセット名] で、該当するデータセットを選択します。

      データセットを選択

    • [テーブル名] フィールドに、BigQuery で追加または上書きするテーブルの名前を入力します。

    • [テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。

  6. [スキーマ] セクションでは、何もする必要はありません。Avro ファイルの中にスキーマが自己記述されているからです。

  7. [パーティションとクラスタの設定] はデフォルト値のままにします。追加や上書きでテーブルをパーティション分割テーブルまたはクラスタ化テーブルに変換できません。GCP Console では、読み込みジョブでパーティション分割テーブルやクラスタ化テーブルの追加または上書きを行うことはできません。

  8. [詳細オプション] をクリックします。

    • [書き込み設定] で、[テーブルに追加する] または [テーブルを上書きする] を選択します。
    • [許可されているエラー数] で、デフォルト値の 0 を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブは invalid メッセージとなり、失敗します。
    • [不明な値] で [不明な値を無視する] をオフのままにします。このオプションは、CSV ファイルと JSON ファイルにのみ適用されます。
    • Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] をクリックします。[Google が管理する鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。

      テーブルを上書きする

  9. [テーブルを作成] をクリックします。

従来の 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] セクションで、次の操作を行います。

    • [Number of errors allowed] で、デフォルト値の 0 を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブは invalid メッセージとなり、失敗します。
    • [Write preference] で、[Append to table] または [Overwrite table] を選択します。
    • [Partitioning Type]、[Partitioning Field]、[Require partition filter]、[Clustering Fields] は、デフォルト値を使用します。追加や上書きでテーブルをパーティション分割テーブルまたはクラスタ化テーブルに変換できません。ウェブ UI では、読み込みジョブでパーティション分割テーブルやクラスタ化テーブルの追加または上書きを行うことはできません。
    • Cloud Key Management Service 鍵を使用してテーブルを暗号化するには、[Destination encryption] で [Customer-managed encryption] を選択します。Default 設定をそのまま使用すると、BigQuery は Google が管理する鍵を使用して保存されているデータを暗号化します。
  7. [Create Table] をクリックします。

CLI

テーブルを上書きするには、--replace フラグを指定して bq load コマンドを入力します。テーブルにデータを追加するには、--noreplace フラグを使用します。フラグを指定しない場合、デフォルトではデータが追加されます。--source_format フラグを AVRO に設定します。Avro スキーマは自己記述型ソースデータから自動的に取得されるため、スキーマ定義を指定する必要はありません。

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

次のフラグを使用することもできます。

  • --max_bad_records: ジョブ全体が失敗する前に許容される不良レコードの最大数を整数で指定します。デフォルト値は 0 です。--max_bad_records 値にかかわらず、最大で任意のタイプの 5 つのエラーが返されます。
  • --destination_kms_key: テーブルデータの暗号化に使用される Cloud KMS 鍵。
bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source

ここで

  • location は、ロケーションです。--location フラグは省略可能です。.bigqueryrc ファイルを使用すると、ロケーションのデフォルト値を設定できます。
  • format は、AVRO です。
  • dataset は、既存のデータセットです。
  • table は、データの読み込み先のテーブル名です。
  • path_to_source は、完全修飾された Cloud Storage URI または URI のカンマ区切りのリストです。ワイルドカードもサポートされます。

例:

次のコマンドは、gs://mybucket/mydata.avro からデータを読み込んで mydataset 内の mytable というテーブルを上書きします。

    bq load \
    --replace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

次のコマンドは、gs://mybucket/mydata.avro からデータを読み込んで mydataset 内の mytable というテーブルに追加します。

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

CLI でパーティション分割テーブルへの追加や上書きを行う方法については、パーティション分割テーブルデータの追加と上書きをご覧ください。

API

  1. Cloud Storage のソースデータを参照する load ジョブを作成します。

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

  3. source URIs プロパティは、完全修飾の gs://bucket/object の形式にする必要があります。複数の URI をカンマ区切りのリストとして含めることができます。ワイルドカードも使用できます。

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

  5. configuration.load.writeDisposition プロパティを WRITE_TRUNCATE または WRITE_APPEND に設定して、書き込み設定を指定します。

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 つだけが設定されます。
fixed 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 に設定するか、jobs.insert メソッドを呼び出して読み込みジョブを作成する際にジョブリソースuseAvroLogicalTypes プロパティを設定します。

次の表に、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 の仕様をご覧ください。

decimal 論理型

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

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

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

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

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

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