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

Cloud Storage から JSON ファイルを読み込む

Cloud Storage から改行区切りの JSON データを読み込むとき、データを新しいテーブルまたはパーティションに読み込むか、データを既存のテーブルまたはパーティションに追加するか、それらに上書きできます。BigQuery に読み込まれたデータは Capacitor のカラム型(BigQuery のストレージ形式)に変換されます。

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

改行で区切られた JSON 形式は、JSON Lines と同じ形式になります。

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

制限事項

Cloud Storage から BigQuery に JSON データを読み込む際は、以下の点に注意してください。

  • JSON データは改行区切りである必要があります。各 JSON オブジェクトはファイル内でそれぞれ別の行に配置されている必要があります。
  • gzip 圧縮を使用した場合、BigQuery はデータを並列で読み取ることができません。圧縮された JSON データを BigQuery に読み込む場合は、圧縮されていないデータを読み込むよりも時間がかかります。
  • 同じ読み込みジョブに圧縮ファイルと非圧縮ファイルの両方を含めることはできません。
  • BigQuery では JSON のマップや辞書がサポートされません。これは、純粋な JSON 辞書にスキーマ情報がない可能性があるためです。たとえば、カート内の商品のリストを表す場合、"products": {"my_product": 40.0, "product2" : 16.5} は無効ですが、"products": [{"product_name": "my_product", "amount": 40.0}, {"product_name": "product2", "amount": 16.5}] は有効です。

    JSON オブジェクト全体を保持する必要がある場合は、JSON 関数のクエリで取得できる string 列で保持します。

  • BigQuery API を使用して [-253+1, 253-1] の範囲外の整数(ほとんどの場合 9,007,199,254,740,991 を超える数)を整数(INT64)の列に読み込む場合は、データの破損を避けるため、文字列として渡す必要があります。この問題は、JSON/ECMAScript の整数のサイズ制限が原因で発生します。詳細については、RFC 7159 の Numbers のセクションをご覧ください。

  • CSV データまたは JSON データを読み込む場合、DATE 列の値に区切りとしてダッシュ(-)を使用し、YYYY-MM-DD(年-月-日)の形式にする必要があります。
  • JSON または CSV データを読み込む場合、TIMESTAMP 列のタイムスタンプ値の日付部分の区切りにはダッシュ(-)を使用し、日付は YYYY-MM-DD(年-月-日)の形式にする必要があります。タイムスタンプの時間部分 hh:mm:ss(時-分-秒)には、区切りとしてコロン(:)を使用します。

必要な権限

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

BigQuery の権限

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

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

bigquery.tables.create 権限および bigquery.tables.updateData 権限はいずれも、事前定義された以下の IAM ロールに含まれています。

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

次の事前定義済みの IAM ロールには bigquery.jobs.create 権限が含まれています。

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

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

BigQuery での IAM のロールと権限の詳細については、アクセス制御をご覧ください。

Cloud Storage の権限

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

事前定義済みの IAM ロール storage.objectViewer が付与されると、storage.objects.get 権限と storage.objects.list 権限の両方が与えられます。

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

次のいずれかの方法で、改行区切りの JSON データを Cloud Storage から新しい BigQuery テーブルに読み込むことができます。

  • Cloud Console または従来のウェブ UI
  • bq コマンドライン ツールの bq load コマンド
  • jobs.insert API メソッドと load ジョブの構成
  • クライアント ライブラリ

Cloud Storage から新しい BigQuery テーブルに JSON データを読み込むには:

コンソール

  1. Cloud Console で [BigQuery] ページを開きます。

    BigQuery ページに移動

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

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

    テーブルの作成。

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

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

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

      ファイルを選択

    • [ファイル形式] で [JSON(改行区切り)] を選択します。

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

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

      データセットを表示

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

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

  6. [Schema] セクションの [Auto detect] で、[Schema and input parameters] をオンにしてスキーマの自動検出を有効にします。次の方法でスキーマ定義を手動で入力することもできます。

    • [テキストとして編集] を有効にし、テーブル スキーマを JSON 配列として入力します。

      スキーマを JSON 配列として追加する

    • [フィールドを追加] を使用して、スキーマを手動で入力します。

      [フィールドを追加] ボタンを使用してスキーマ定義を追加する

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

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

  9. (省略可)テーブルをクラスタ化するには、[クラスタリング順序] ボックスに 1~4 個のフィールド名を入力します。

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

    • [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
    • [許可されているエラー数] で、デフォルト値の 0 を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブは invalid メッセージを出して失敗します。
    • 行の値でテーブルのスキーマに存在しないものを無視するには、[不明な値] で [不明な値を無視する] をオンにします。
    • 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] で [Google Cloud Storage] を選択し、ソース フィールドに Cloud Storage URI を入力します。BigQuery ウェブ UI では URI の複数指定はできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在している必要があります。
    • [File format] で [JSON(Newline Delimited)] を選択します。
  4. [Destination Table] セクションで、次の操作を行います。

    • [Table name] で適切なデータセットを選択し、BigQuery で作成するテーブルの名前をテーブル名のフィールドに入力します。
    • [Table type] が [Native table] に設定されていることを確認します。
  5. [Schema] セクションの [Auto detect] で、[Schema and input parameters] をオンにしてスキーマの自動検出を有効にします。次の方法でスキーマ定義を手動で入力することもできます。

    • [Edit as Text] をクリックし、テーブル スキーマを JSON 配列として入力します。

      スキーマを JSON 配列として追加する

    • [Add Field] を使用して、スキーマを手動で入力します。

      追加フィールドを使用してスキーマを追加する

  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] をクリックします。

bq

bq load コマンドを使用します。--source_format フラグを使用して NEWLINE_DELIMITED_JSON を指定し、Cloud Storage URI を設定します。単一の URI、URI のカンマ区切りのリスト、ワイルドカードを含む URI を指定できます。スキーマをインラインまたはスキーマ定義ファイルで指定するか、スキーマ自動検出を使用します。

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

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

  • --max_bad_records: ジョブ全体が失敗する前に許容される不良レコードの最大数を指定する整数。デフォルト値は 0 です。--max_bad_records の値にかかわらず、最大で 5 つの任意のタイプのエラーが返されます。
  • --ignore_unknown_values: 指定すると、CSV または JSON データで認識されない余分な値が許可され、無視されます。
  • --autodetect: 指定すると、CSV および JSON データのスキーマ自動検出が有効になります。
  • --quote: レコードを囲むために使用する引用符。デフォルト値は " です。引用符を使用しない場合は、空の文字列を使用します。
  • --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 鍵。

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

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

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

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

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

次のように置き換えます。

  • LOCATION: ロケーション。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
  • FORMAT: NEWLINE_DELIMITED_JSON
  • DATASET: 既存のデータセット。
  • TABLE: データの読み込み先のテーブル名。
  • PATH_TO_SOURCE: 完全修飾の Cloud Storage URI または URI のカンマ区切りのリスト。ワイルドカードも使用できます。
  • SCHEMA: 有効なスキーマ。スキーマはローカルの JSON ファイルにすることも、コマンドの一部としてインラインで入力することもできます。また、スキーマ定義を指定する代わりに、--autodetect フラグを使用することもできます。

例:

次のコマンドは、gs://mybucket/mydata.json から mydataset 内の mytable というテーブルにデータを読み込みます。スキーマは、myschema.json という名前のローカル スキーマ ファイルで定義されています。

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema.json

次のコマンドは、gs://mybucket/mydata.json から mydataset 内の mytable という取り込み時間パーティション分割テーブルにデータを読み込みます。スキーマは、myschema.json という名前のローカル スキーマ ファイルで定義されています。

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema.json

次のコマンドは、gs://mybucket/mydata.json からデータを読み込んで mydataset 内の mytable というパーティション分割テーブルに追加します。テーブルは mytimestamp 列で分割されます。スキーマは、myschema.json という名前のローカル スキーマ ファイルで定義されています。

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema.json

次のコマンドは、gs://mybucket/mydata.json から mydataset 内の mytable というテーブルにデータを読み込みます。スキーマは自動検出されます。

    bq load \
    --autodetect \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json

次のコマンドは、gs://mybucket/mydata.json から mydataset 内の mytable というテーブルにデータを読み込みます。スキーマは、FIELD:DATA_TYPE, FIELD:DATA_TYPE の形式でインラインで定義されます。

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    qtr:STRING,sales:FLOAT,year:STRING

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

    bq load \
    --autodetect \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata*.json

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

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    "gs://mybucket/00/*.json","gs://mybucket/01/*.json" \
    ./myschema.json

API

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

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

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

  4. sourceFormat プロパティを NEWLINE_DELIMITED_JSON に設定して、JSON データ形式を指定します。

  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 回だけです。

C#

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

BigQueryClient.CreateLoadJob() メソッドを使用して、Cloud Storage からの読み込みジョブを開始します。改行区切りの JSON を使用するには、CreateLoadJobOptions オブジェクトを作成し、その SourceFormat プロパティを FileFormat.NewlineDelimitedJson に設定します。


using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsJson
{
    public void LoadTableGcsJson(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.NewlineDelimitedJson
        };
        // Create and run job
        BigQueryJob loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Go

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

import (
	"context"
	"fmt"

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

// importJSONExplicitSchema demonstrates loading newline-delimited JSON data from Cloud Storage
// into a BigQuery table and providing an explicit schema for the data.
func importJSONExplicitSchema(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.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
	}
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty

	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 のリファレンス ドキュメントをご覧ください。

LoadJobConfiguration.builder(tableId, sourceUri) メソッドを使用して、Cloud Storage からの読み込みジョブを開始します。改行区切りの JSON を使用するには、LoadJobConfiguration.setFormatOptions(FormatOptions.json()) を使用します。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
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.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

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

  public static void runLoadJsonFromGCS() {
    // 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.json";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCS(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    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.json())
              .setSchema(schema)
              .build();

      // Load data from a GCS JSON 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("Json 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 json file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.json
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.json';

async function loadJSONFromGCS() {
  // Imports a GCS file into a table with manually defined schema.

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'NEWLINE_DELIMITED_JSON',
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    location: 'US',
  };

  // 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), metadata);
  // 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;
  }
}

PHP

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.json';
$schema = [
    'fields' => [
        ['name' => 'name', 'type' => 'string'],
        ['name' => 'post_abbr', 'type' => 'string']
    ]
];
$loadConfig = $table->loadFromStorage($gcsUri)->schema($schema)->sourceFormat('NEWLINE_DELIMITED_JSON');
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

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

Client.load_table_from_uri() メソッドを使用して、Cloud Storage から読み込みジョブを開始します。改行区切りの JSON を使用するには、LoadJobConfig.source_format プロパティを文字列 NEWLINE_DELIMITED_JSON に設定し、ジョブ構成を load_table_from_uri() メソッドの job_config 引数として渡します。

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"),
    ],
    source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

load_job = client.load_table_from_uri(
    uri,
    table_id,
    location="US",  # Must match the destination dataset location.
    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))

Ruby

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

Dataset.load_job() メソッドを使用して、Cloud Storage からの読み込みジョブを開始します。改行区切りの JSON を使用するには、format パラメータを "json" に設定します。

require "google/cloud/bigquery"

def load_table_gcs_json dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.json"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, format: "json" do |schema|
    schema.string "name"
    schema.string "post_abbr"
  end
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done!  # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table(table_id)
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

ネストされた JSON データと繰り返し JSON データの読み込み

BigQuery は、JSON、Avro、ORC、Parquet、Firestore、Datastore など、オブジェクト ベースのスキーマをサポートするソース形式からネストされたデータや繰り返しデータを読み込むことができます。

各行に、ネストされたフィールド / 繰り返しフィールドを含む 1 つの JSON オブジェクトが必要です。

次の例は、ネストされたデータ / 繰り返しデータの例を示します。このテーブルには人に関する情報が含まれています。このテーブルは、次のフィールドで構成されています。

  • id
  • first_name
  • last_name
  • dob(生年月日)
  • addresses(ネストと繰り返しのあるフィールド)
    • addresses.status(現在または以前)
    • addresses.address
    • addresses.city
    • addresses.state
    • addresses.zip
    • addresses.numberOfYears(居住年数)

JSON データファイルは次のようになります。address フィールドには([ ] によって示される)値の配列が含まれています。

{"id":"1","first_name":"John","last_name":"Doe","dob":"1968-01-22","addresses":[{"status":"current","address":"123 First Avenue","city":"Seattle","state":"WA","zip":"11111","numberOfYears":"1"},{"status":"previous","address":"456 Main Street","city":"Portland","state":"OR","zip":"22222","numberOfYears":"5"}]}
{"id":"2","first_name":"Jane","last_name":"Doe","dob":"1980-10-16","addresses":[{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"},{"status":"previous","address":"321 Main Street","city":"Hoboken","state":"NJ","zip":"44444","numberOfYears":"3"}]}

この表のスキーマは次のようになります。

[
    {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "first_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "last_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "dob",
        "type": "DATE",
        "mode": "NULLABLE"
    },
    {
        "name": "addresses",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
            {
                "name": "status",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "address",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "city",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "state",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "zip",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "numberOfYears",
                "type": "STRING",
                "mode": "NULLABLE"
            }
        ]
    }
]

ネストされたスキーマと繰り返しスキーマを指定する方法については、ネストされたフィールドと繰り返しフィールドの指定をご覧ください。

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

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

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

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

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

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

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

  • Cloud Console または従来のウェブ UI
  • bq コマンドライン ツールの bq load コマンド
  • jobs.insert API メソッドと load ジョブの構成
  • クライアント ライブラリ

コンソール

  1. Cloud Console で [BigQuery] ページを開きます。

    BigQuery ページに移動

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

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

    テーブルの作成

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

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

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

      ファイルを選択

    • [ファイル形式] で [JSON(改行区切り)] を選択します。

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

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

      データセットの選択

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

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

  6. [Schema] セクションの [Auto detect] で、[Schema and input parameters] をオンにしてスキーマの自動検出を有効にします。次の方法でスキーマ定義を手動で入力することもできます。

    • [テキストとして編集] を有効にし、テーブル スキーマを JSON 配列として入力します。

      スキーマを JSON 配列として追加する

    • [フィールドを追加] を使用して、スキーマを手動で入力します。

      [フィールドを追加] ボタンを使用してスキーマ定義を追加する

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

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

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

      テーブルを上書きする

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

従来の UI

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

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

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

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

    • [Table name] で適切なデータセットを選択し、追加または上書きするテーブルの名前をテーブル名のフィールドに入力します。
    • [Table type] が [Native table] に設定されていることを確認します。
  5. [Schema] セクションでスキーマ定義を入力します。

    • JSON ファイルの場合、[Automatically detect] オプションをオンにしてスキーマの自動検出を有効にできます。

      自動検出リンク

    • 次の方法でスキーマ情報を手動で入力することもできます。

      • [Edit as Text] をクリックし、テーブル スキーマを JSON 配列として入力します。

        スキーマを JSON 配列として追加する

      • [Add Field] を使用して、スキーマを手動で入力します。

        追加フィールドを使用してスキーマを追加する

  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] をクリックします。

bq

bq load コマンドを使用します。--source_format フラグを使用して NEWLINE_DELIMITED_JSON を指定し、Cloud Storage URI を設定します。単一の URI、URI のカンマ区切りのリスト、ワイルドカードを含む URI を指定できます。

スキーマをインラインまたはスキーマ定義ファイルで指定するか、スキーマ自動検出を使用します。

テーブルを上書きするには、--replace フラグを指定します。テーブルにデータを追加するには、--noreplace フラグを使用します。フラグを指定しない場合、デフォルトではデータが追加されます。

テーブルを追加または上書きするときに、テーブルのスキーマを変更できます。読み込みオペレーションでサポートされるスキーマの変更については、テーブル スキーマの変更をご覧ください。

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

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

  • --max_bad_records: ジョブ全体が失敗する前に許容される不良レコードの最大数を指定する整数。デフォルト値は 0 です。--max_bad_records の値にかかわらず、最大で 5 つの任意のタイプのエラーが返されます。
  • --ignore_unknown_values: 指定すると、CSV または JSON データで認識されない余分な値が許可され、無視されます。
  • --autodetect: 指定すると、CSV および JSON データのスキーマ自動検出が有効になります。
  • --destination_kms_key: テーブルデータの暗号化に使用される Cloud KMS 鍵。
bq --location=LOCATION load \
--[no]replace \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

次のように置き換えます。

  • LOCATION: ロケーション--location フラグは省略可能です。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
  • FORMAT: NEWLINE_DELIMITED_JSON
  • DATASET: 既存のデータセット。
  • TABLE: データの読み込み先のテーブル名。
  • PATH_TO_SOURCE: 完全修飾の Cloud Storage URI または URI のカンマ区切りのリスト。ワイルドカードも使用できます。
  • SCHEMA: 有効なスキーマ。スキーマはローカルの JSON ファイルにすることも、コマンドの一部としてインラインで入力することもできます。また、スキーマ定義を指定する代わりに、--autodetect フラグを使用することもできます。

例:

次のコマンドは、gs://mybucket/mydata.json からデータを読み込んで mydataset 内の mytable というテーブルを上書きします。スキーマはスキーマ自動検出を使用して定義されます。

    bq load \
    --autodetect \
    --replace \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json

次のコマンドは、gs://mybucket/mydata.json からデータを読み込んで mydataset 内の mytable というテーブルに追加します。スキーマは、JSON スキーマ ファイル myschema.json を使用して定義されます。

    bq load \
    --noreplace \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema.json

API

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

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

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

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

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

Go

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

import (
	"context"
	"fmt"

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

// importJSONTruncate demonstrates loading data from newline-delimeted JSON data in Cloud Storage
// and overwriting/truncating data in the existing table.
func importJSONTruncate(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.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	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.Field;
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.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

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

  public static void runLoadJsonFromGCSTruncate() {
    // 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.json";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCSTruncate(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCSTruncate(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    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.json())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .setSchema(schema)
              .build();

      // Load data from a GCS JSON 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 JSON 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

このサンプルを試す前に、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 JSON file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.json
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.json';

async function loadJSONFromGCSTruncate() {
  /**
   * 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 = "my_table";

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'NEWLINE_DELIMITED_JSON',
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    // Set the write disposition to overwrite existing table data.
    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), metadata);
  // 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;
  }
}

PHP

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableID = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.json';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('NEWLINE_DELIMITED_JSON')->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

既存のテーブルの行を置換するには、LoadJobConfig.write_disposition プロパティを文字列 WRITE_TRUNCATE に設定します。

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

import six

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 = six.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.NEWLINE_DELIMITED_JSON,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"
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))

Ruby

既存のテーブルの行を置換するには、Table.load_job()write パラメータを "WRITE_TRUNCATE" に設定します。

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

require "google/cloud/bigquery"

def load_table_gcs_json_truncate(
    dataset_id = "your_dataset_id",
    table_id   = "your_table_id"
  )
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

  load_job = dataset.load_job table_id,
                              gcs_uri,
                              format: "json",
                              write:  "truncate"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done!  # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table(table_id)
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

Hive パーティション分割 JSON データを読み込む

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

JSON データの読み込みの詳細

このセクションでは、JSON データを読み込むときに BigQuery がさまざまなデータ型を解析する方法について説明します。

Boolean。BigQuery は、ブール値データとして 1 または 0、true または false、t または f、yes または no、y または n(すべて大文字と小文字の区別なし)の任意のペアを解析できます。スキーマ autodetection は、これらのうち 0 と 1 以外を自動的に検出します。

Date。DATE 型の列は YYYY-MM-DD の形式にする必要があります。

Datetime。DATETIME 型の列は YYYY-MM-DD HH:MM:SS[.SSSSSS] の形式にする必要があります。

Time。TIME 型の列は HH:MM:SS[.SSSSSS] の形式にする必要があります。

Timestamp。BigQuery はさまざまなタイムスタンプ形式に対応しています。タイムスタンプには日付の部分と時刻の部分を含める必要があります。

  • 日付の部分は YYYY-MM-DD 型または YYYY/MM/DD 型にできます。

  • タイムスタンプ部分は、HH:MM[:SS[.SSSSSS]] 型にする必要があります(秒数と 1 秒未満の秒数は省略可能です)。

  • 日付と時刻はスペースまたは「T」で区切る必要があります。

  • 必要に応じて、日付と時刻の後に UTC オフセットまたは UTC ゾーン指定子(Z)を追加できます。詳細については、タイムゾーンをご覧ください。

有効なタイムスタンプ値の例は次のとおりです。

  • 2018-08-19 12:11
  • 2018-08-19 12:11:35
  • 2018-08-19 12:11:35.22
  • 2018/08/19 12:11
  • 2018-07-05 12:54:00 UTC
  • 2018-08-19 07:11:35.220 -05:00
  • 2018-08-19T12:11:35.220Z

スキーマを指定すると、BigQuery はタイムスタンプ値として Unix エポック時間も指定できます。ただし、スキーマの自動検出ではこのケースは検出されず、値は数値型または文字列型として扱われます。

Unix エポック タイムスタンプ値の例:

  • 1534680695
  • 1.534680695e11

JSON のオプション

BigQuery による JSON データの解析方法を変更するには、Console、従来の UI、コマンドライン インターフェース、API、またはクライアント ライブラリで追加のオプションを指定します。

JSON のオプション Console のオプション 従来の UI のオプション コマンドライン フラグ BigQuery API のプロパティ 説明
許可されている不良レコード数 許容されるエラー数 許容されるエラー数 --max_bad_records maxBadRecords (省略可)BigQuery がジョブの実行時に無視できる不良レコードの最大数。不良レコードの数がこの値を超えると、ジョブ結果で「無効」エラーが返されます。デフォルト値は 0、つまりすべてのレコードが有効である必要があります。
不明な値 不明な値を無視する 不明な値を無視する --ignore_unknown_values ignoreUnknownValues (省略可)テーブル スキーマで示されていない余分な値を許可するかどうかを指定します。true の場合、余分な値は無視されます。false の場合、余分な列を含むレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値は false です。なにが余分な値として扱われるかは、sourceFormat プロパティによって決まります。CSV: 末尾の列。JSON: 列名と一致しない名前付きの値。