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

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

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

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

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

制限事項

Cloud Storage バケットから BigQuery にデータを読み込む際には、次の制限があります。

データセットのロケーションが US マルチリージョン以外の値に設定されている場合、Cloud Storage バケットはデータセットと同じリージョンに存在するか、同じマルチリージョンに含まれている必要があります。
BigQuery では外部データソースに対して整合性が保証されません。クエリの実行中に基になるデータを変更すると、予期しない動作が発生する可能性があります。
BigQuery では、Cloud Storage オブジェクトのバージョニングはサポートされていません。Cloud Storage URI に世代番号を含めると、読み込みジョブは失敗します。

入力ファイルの要件

Avro ファイルを BigQuery に読み込むときに resourcesExceeded エラーを回避するには、次のガイドラインに従ってください。

行のサイズは 50 MB 以下にします。
行に多数の配列フィールドや、または非常に長い配列フィールドがある場合は、配列値を別々のフィールドに分割します。

始める前に

このドキュメントの各タスクを行うのに必要な権限をユーザーに与える 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 データセットを作成し、そのデータセット内に 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

bq コマンドラインツールでこのコマンドを実行すると、すべてのファイルが（カンマ区切りのリストとして）読み込まれ、mybucket/01/b.avro からスキーマが取得されます。

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

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

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

外部テーブルを作成するためのテーブルスキーマを提供するには、参照ファイルの URL に BigQuery API の referenceFileSchemaUri プロパティを設定するか、bq コマンドラインツールの --reference_file_schema_uri パラメータを設定します。

例: --reference_file_schema_uri="gs://mybucket/schema.avro"

Avro 圧縮

BigQuery は、Avro ファイルの内容に対して次の圧縮コーデックをサポートしています。

Snappy
DEFLATE

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

Avro データを Cloud Storage から新しい BigQuery テーブルに読み込むには、次のいずれかのオプションを選択します。

コンソール

Google Cloud コンソールで、[BigQuery] ページを開きます。

[BigQuery] に移動
[エクスプローラ] パネルでプロジェクトを開いて、データセットを選択します。
アクション オプションを開いて、[開く] をクリックします。
詳細パネルで [テーブルを作成] をクリックします。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
- [テーブルの作成元] で [Google Cloud Storage] を選択します。
- ソースフィールドで、Cloud Storage URI を参照するか入力します。Google Cloud コンソールで複数の URI は指定できませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在する必要があります。
- [ファイル形式] で [Avro] を選択します。
[テーブルの作成] ページの [送信先] セクションで、次の操作を行います。
- [データセット名] で、該当するデータセットを選択します。
- [テーブルタイプ] が [ネイティブテーブル] に設定されていることを確認します。
- [テーブル名] フィールドに、BigQuery で作成するテーブルの名前を入力します。
[スキーマ] セクションでは、何もする必要はありません。Avro ファイルの中にスキーマが自己記述されているからです。
（省略可）テーブルをパーティショニングするには、[パーティションとクラスタの設定] で次のオプションを選択します。詳細については、パーティション分割テーブルの作成をご覧ください。
（省略可）クエリを実行するパーティションを指定する WHERE 句の使用を必須にするには、[パーティショニングフィルタ] で [パーティションフィルタを要求] ボックスをクリックします。パーティションフィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。[パーティショニングなし] を選択している場合、このオプションは使用できません。
（省略可）テーブルをクラスタ化するには、[クラスタリング順序] ボックスに 1～4 個のフィールド名を入力します。
（省略可）[詳細オプション] をクリックします。
- [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
- [不明な値] で [不明な値を無視する] をオフのままにします。このオプションは、CSV ファイルと JSON ファイルにのみ適用されます。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] をクリックします。[Google が管理する鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
[テーブルを作成] をクリックします。

SQL

LOAD DATA DDL ステートメントを使用します。次の例では、Avro ファイルを新しいテーブル mytable に読み込みます。

Google Cloud コンソールで [BigQuery] ページに移動します。

[BigQuery] に移動

クエリエディタで次のステートメントを入力します。

LOAD DATA OVERWRITE mydataset.mytable
FROM FILES (
  format = 'avro',
  uris = ['gs://bucket/path/file.avro']);

[実行] をクリックします。

クエリの実行方法については、インタラクティブクエリを実行するをご覧ください。

bq

bq load コマンドを使用します。--source_format フラグを使用して AVRO を指定し、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 鍵。

パーティション分割テーブルの詳細については、以下をご覧ください。
- パーティション分割テーブルの作成
クラスタ化テーブルの詳細については、以下をご覧ください。
- クラスタ化テーブルの作成と使用
テーブルの暗号化の詳細については、以下をご覧ください。
- 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/ の複数のファイルから mydataset 内の mytable という名前のテーブルにデータを読み込みます。Cloud Storage URI ではワイルドカードを使用しています。

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

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

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

API

Cloud Storage のソースデータを参照する load ジョブを作成します。
（省略可）ジョブリソースの jobReference セクションにある location プロパティでロケーションを指定します。
source URIs プロパティは、完全修飾の gs://bucket/object の形式にする必要があります。各 URI にワイルドカード文字「*」を 1 つ含めることができます。
sourceFormat プロパティを AVRO に設定して、Avro データ形式を指定します。
ジョブのステータスを確認するには、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 に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証を設定するをご覧ください。

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importAvro demonstrates loading Apache Avro data from Cloud Storage into a table.
func importAvro(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.avro")
	gcsRef.SourceFormat = bigquery.Avro
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to load Avro data from Cloud Storage into a new BigQuery table
public class LoadAvroFromGCS {

  public static void runLoadAvroFromGCS() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro";
    loadAvroFromGCS(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCS(String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.of(tableId, sourceUri, FormatOptions.avro());

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Avro from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Node.js の設定手順を完了してください。詳細については、BigQuery Node.js API のリファレンスドキュメントをご覧ください。

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

async function loadTableGCSAvro() {
  // Imports a GCS file into a table with Avro source format.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'us_states';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {sourceFormat: 'AVRO'},
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), jobConfigurationLoad);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(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_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

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

Avro データから JSON データを抽出する

Avro データが JSON データとして BigQuery に読み込まれるようにする方法には、次の 2 つがあります。

sqlType を JSON に設定した Avro スキーマにアノテーションを付ける。たとえば、次の Avro スキーマでデータを読み込むと、json_field 列は JSON 型として読み取られます。
```
{
    "type": {"type": "string", "sqlType": "JSON"},
    "name": "json_field"
}
```
BigQuery 宛先テーブルスキーマを明示的に指定し、列の型を JSON に設定する。詳細については、スキーマの指定をご覧ください。

JSON を Avro スキーマまたは BigQuery テーブルスキーマにおける型に指定しなかった場合、データは STRING として読み取られます。

Avro データをテーブルに追加、または Avro データでテーブルを上書きする

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

Google Cloud コンソールでは、[書き込み設定] オプションを使用して、ソースファイルやクエリ結果からデータを読み込むときに行う操作を指定します。

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

コンソールのオプション	bq ツールフラグ	BigQuery API のプロパティ	説明
空の場合に書き込む	非対応	`WRITE_EMPTY`	テーブルが空の場合にのみデータを書き込みます。
テーブルに追加する	`--noreplace` または `--replace=false`（`--[no]replace` を指定しない場合、デフォルトは追加）	`WRITE_APPEND`	（デフォルト）テーブルの末尾にデータを追加します。
テーブルを上書きする	`--replace` または `--replace=true`	`WRITE_TRUNCATE`	新しいデータを書き込む前に、テーブル内の既存のデータをすべて消去します。この操作を行うと、テーブルスキーマ、行レベルのセキュリティ、Cloud KMS 鍵も削除されます。

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

Avro データをテーブルに追加または上書きするには:

コンソール

Google Cloud コンソールで、[BigQuery] ページを開きます。

[BigQuery] に移動
[エクスプローラ] パネルでプロジェクトを開いて、データセットを選択します。
アクション オプションを開いて、[開く] をクリックします。
詳細パネルで [テーブルを作成] をクリックします。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
- [テーブルの作成元] で [Cloud Storage] を選択します。
- ソースフィールドで、Cloud Storage URI を参照するか入力します。Google Cloud コンソールで複数の URI は指定できませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、データを追加または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
- [ファイル形式] で [Avro] を選択します。
[テーブルの作成] ページの [送信先] セクションで、次の操作を行います。
- [データセット名] で、該当するデータセットを選択します。
- [テーブル名] フィールドに、BigQuery で追加または上書きするテーブルの名前を入力します。
- [テーブルタイプ] が [ネイティブテーブル] に設定されていることを確認します。
[スキーマ] セクションでは、何もする必要はありません。Avro ファイルの中にスキーマが自己記述されているからです。

注: テーブルを追加または上書きするときに、テーブルのスキーマを変更できます。読み込みオペレーション中にサポートされるスキーマの変更については、テーブルスキーマの変更をご覧ください。
[パーティションとクラスタの設定] はデフォルト値のままにします。追加や上書きではテーブルをパーティション分割テーブルまたはクラスタ化テーブルに変換できません。Google Cloud コンソールでは、読み込みジョブでパーティション分割テーブルやクラスタ化テーブルの追加または上書きを行うことはできません。
[詳細オプション] をクリックします。
- [書き込み設定] で、[テーブルに追加する] または [テーブルを上書きする] を選択します。
- [不明な値] で [不明な値を無視する] をオフのままにします。このオプションは、CSV ファイルと JSON ファイルにのみ適用されます。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] をクリックします。[Google が管理する鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
[テーブルを作成] をクリックします。

SQL

LOAD DATA DDL ステートメントを使用します。次の例では、Avro ファイルをテーブル mytable に追加します。

Google Cloud コンソールで [BigQuery] ページに移動します。

[BigQuery] に移動

クエリエディタで次のステートメントを入力します。

LOAD DATA INTO mydataset.mytable
FROM FILES (
  format = 'avro',
  uris = ['gs://bucket/path/file.avro']);

[実行] をクリックします。

クエリの実行方法については、インタラクティブクエリを実行するをご覧ください。

bq

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

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

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

--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

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

API

Cloud Storage のソースデータを参照する load ジョブを作成します。
（省略可）ジョブリソースの jobReference セクションにある location プロパティでロケーションを指定します。
source URIs プロパティは、完全修飾の gs://bucket/object の形式にする必要があります。複数の URI をカンマ区切りのリストとして含めることができます。ワイルドカードも使用できます。
configuration.load.sourceFormat プロパティを AVRO に設定して、データ形式を指定します。
configuration.load.writeDisposition プロパティを WRITE_TRUNCATE または WRITE_APPEND に設定して、書き込み設定を指定します。

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importAvroTruncate demonstrates loading Apache Avro data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importAvroTruncate(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.avro")
	gcsRef.SourceFormat = bigquery.Avro
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	// Default for import jobs is to append data to a table.  WriteTruncate
	// specifies that existing data should instead be replaced/overwritten.
	loader.WriteDisposition = bigquery.WriteTruncate

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to overwrite the BigQuery table data by loading a AVRO file from GCS
public class LoadAvroFromGCSTruncate {

  public static void runLoadAvroFromGCSTruncate() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro";
    loadAvroFromGCSTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCSTruncate(
      String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.avro())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Table is successfully overwritten by AVRO file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

async function loadTableGCSAvroTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'us_states';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {
      sourceFormat: 'AVRO',
      writeDisposition: 'WRITE_TRUNCATE',
    },
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), jobConfigurationLoad);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

import io

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = io.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    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_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

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

Hive パーティション分割 Avro データの読み込み

BigQuery では、Cloud Storage に保管されている Hive パーティション分割 Avro データを読み取り可能であり、宛先 BigQuery マネージドテーブルの列として Hive パーティショニング列を取り込みます。詳しくは、Cloud Storage からの外部パーティション分割データの読み取りをご覧ください。

Avro の変換

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

プリミティブ型

logicalType 属性のない Avro データ型	BigQuery のデータ型	メモ
null	BigQuery はこれらの値を無視します
boolean	BOOLEAN
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
bytes	BYTES
string	STRING	UTF-8 のみ

論理型

デフォルトでは、BigQuery はほとんどの型の logicalType 属性を無視し、代わりに元の Avro の型を使用します。Avro の論理型から対応する BigQuery データ型に変換するには、bq コマンドラインツールを使用して --use_avro_logical_types フラグを true に設定するか、jobs.insert メソッドを呼び出して読み込みジョブを作成する際にジョブリソースの useAvroLogicalTypes プロパティを設定します。

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

Avro の論理型	BigQuery のデータ型: 論理型が無効	BigQuery のデータ型: 論理型が有効
date	INTEGER	DATE
time-millis	INTEGER	TIME
time-micros	INTEGER（LONG から変換）	TIME
timestamp-millis	INTEGER（LONG から変換）	TIMESTAMP
timestamp-micros	INTEGER（LONG から変換）	TIMESTAMP
local-timestamp-millis	INTEGER（LONG から変換）	DATETIME
local-timestamp-micros	INTEGER（LONG から変換）	DATETIME
duration	BYTES（サイズ 12 の `fixed` 型から変換）	BYTES（サイズ 12 の `fixed` 型から変換）
decimal	NUMERIC、BIGNUMERIC、STRING（decimal 論理型を参照）	NUMERIC、BIGNUMERIC、STRING（decimal 論理型を参照）

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

日付論理型

読み込む Avro ファイルでは、日付論理型を次の形式で指定する必要があります。

{
       "type": {"logicalType": "date", "type": "int"},
       "name": "date_field"
}

decimal 論理型

Decimal の論理型は、NUMERIC、BIGNUMERIC、STRING の型に変換できます。変換される型は、decimal 論理型の精度とスケールのパラメータ、また指定されたターゲットの固定小数点型によって異なります。ターゲットの固定小数点型は次のように指定します。

jobs.insert API を使用する読み込みジョブの場合: JobConfigurationLoad.decimalTargetTypes フィールドを使用します。
bq コマンドラインツールで bq load コマンドを使用する読み込みジョブの場合: --decimal_target_types フラグを使用します。
外部ソースを含むテーブルに対するクエリの場合: ExternalDataConfiguration.decimalTargetTypes フィールドを使用します。
DDL で作成した永続外部テーブルの場合: decimal_target_types オプションを使用します。

下位互換性を維持するため、固定小数点型のターゲットが指定されていない場合、decimal 論理型の bytes 列を含む既存の Avro ファイルを既存のテーブルの BYTES 列に読み込むことができます。この場合、Avro ファイル内の列に設定された decimal 論理型は無視されます。このコンバージョンモードはサポートが終了しており、今後削除される可能性があります。

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

時間論理型

読み込む Avro ファイルでは、時間論理型を次のいずれかの形式で指定する必要があります。

ミリ秒の精度の場合:

{
       "type": {"logicalType": "time-millis", "type": "int"},
       "name": "time_millis_field"
}

マイクロ秒の精度の場合:

{
       "type": {"logicalType": "time-micros", "type": "int"},
       "name": "time_micros_field"
}

タイムスタンプ論理型

読み込む Avro ファイルでは、タイムスタンプ論理型を次のいずれかの形式で指定する必要があります。

ミリ秒の精度の場合:

{
       "type": {"logicalType": "timestamp-millis", "type": "long"},
       "name": "timestamp_millis_field"
}

マイクロ秒の精度の場合:

{
       "type": {"logicalType": "timestamp-micros", "type": "long"},
       "name": "timestamp_micros_field"
}

ローカルタイムスタンプ論理型

読み込む Avro ファイルではローカルタイムスタンプ論理型を次のいずれかの形式で指定する必要があります。

ミリ秒の精度の場合:

{
       "type": {"logicalType": "local-timestamp-millis", "type": "long"},
       "name": "local_timestamp_millis_field"
}

マイクロ秒の精度の場合:

{
       "type": {"logicalType": "local-timestamp-micros", "type": "long"},
       "name": "local_timestamp_micros_field"
}

複合型

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 では、ネストされた配列形式はサポートされていません。この形式を使用する Avro ファイルは、インポートする前に変換する必要があります。
Avro ファイルでは、フルネームの名前と名前空間に使用できるのは、英数字とアンダースコア文字 _ のみです。次の正規表現は、使用可能な文字を示しています。[A-Za-z_][A-Za-z0-9_]*

詳細については、BigQuery 読み込みジョブの制限をご覧ください。

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

制限事項

入力ファイルの要件

始める前に

必要な権限

BigQuery にデータを読み込む権限

Cloud Storage からデータを読み込む権限

必要な権限

データセットとテーブルを作成する

Avro の利点

Avro スキーマ

Avro 圧縮

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

コンソール

SQL

bq

API

Go

Java

Node.js

Python

Avro データから JSON データを抽出する

Avro データをテーブルに追加、または Avro データでテーブルを上書きする

コンソール

SQL

bq

API

Go

Java

Node.js

Python

Hive パーティション分割 Avro データの読み込み

Avro の変換

プリミティブ型

論理型

日付論理型

decimal 論理型

時間論理型

タイムスタンプ論理型

ローカル タイムスタンプ論理型

複合型

制限事項

ローカルタイムスタンプ論理型