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

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

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

ndJSON 形式は、JSON Lines と同じ形式です。

制限事項

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

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

JSON ファイルを BigQuery に読み込む場合は、次の点に注意してください。

• JSON データは改行区切り（ndJSON）である必要があります。各 JSON オブジェクトはファイル内でそれぞれ別の行に配置されている必要があります。
• gzip 圧縮を使用した場合、BigQuery はデータを並列で読み取ることはできません。圧縮された JSON データを BigQuery に読み込む場合は、圧縮されていないデータを読み込むよりも時間がかかります。
• 同じ読み込みジョブに圧縮ファイルと非圧縮ファイルの両方を含めることはできません。
• gzip ファイルの最大サイズは 4 GB です。

• 取り込み時にスキーマ情報が不明な場合でも、BigQuery は JSON 型をサポートします。JSON 型として宣言されたフィールドは、未加工の JSON 値とともに読み込まれます。

• BigQuery API を使用して [-2⁵³+1, 2⁵³-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（年-月-日）または YYYY/MM/DD（年/月/日）のいずれかの形式にする必要があります。タイムスタンプの時間部分 hh:mm:ss（時-分-秒）には、区切りとしてコロン（:）を使用します。

• ファイルは、読み込みジョブの上限で説明されている JSON ファイルサイズの上限を満たしている必要があります。

始める前に

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

JSON 圧縮

gzip ユーティリティを使用して JSON ファイルを圧縮できます。gzip は、Avro などの他のファイル形式の圧縮コーデックによって実行されるファイル コンテンツ圧縮とは異なり、ファイルの完全な圧縮を実行します。gzip を使用して JSON ファイルを圧縮すると、パフォーマンスに影響する可能性があります。このトレードオフの詳細については、圧縮データと非圧縮データの読み込みをご覧ください。

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

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

コンソール

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

   [BigQuery] に移動

2. [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
3. [データセット情報] セクションで、[ テーブルを作成] をクリックします。
4. [テーブルを作成] パネルで、次の詳細を指定します。
1. [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
   1. Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
   2. [ファイル形式] で [JSONL（改行区切り JSON）] を選択します。
2. [送信先] セクションで、次の詳細を指定します。
   1. [データセット] で、テーブルを作成するデータセットを選択します。
   2. [テーブル] フィールドに、作成するテーブルの名前を入力します。
   3. [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
3. [スキーマ] セクションでスキーマ定義を入力します。スキーマの自動検出を有効にするには、[自動検出] を選択します。スキーマ情報は、次のいずれかの方法で手動で入力できます。
   • オプション 1: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。既存のテーブルのスキーマを JSON 形式で表示するには、次のコマンドを入力します。

         bq show --format=prettyjson dataset.table
         

   • オプション 2: [フィールドを追加] をクリックして、テーブル スキーマを入力します。各フィールドの名前、型、モードを指定します。
4. 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。
5. [詳細オプション] をクリックして、次の操作を行います。
   • [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
   • [許可されているエラー数] で、デフォルト値の 0 を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブは invalid メッセージとなり、失敗します。このオプションは、CSV ファイルと JSON ファイルにのみ適用されます。
   • テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
   • Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
6. [テーブルを作成] をクリックします。

注: Google Cloud コンソールを使用して空のテーブルにデータを読み込むときに、ラベル、説明、テーブルの有効期限、パーティションの有効期限を追加することはできません。

テーブルの作成後、テーブルの有効期限、説明、ラベルを更新できますが、Google Cloud コンソールでテーブルを作成した後にパーティションの有効期限を追加することはできません。詳細は、テーブルの管理をご覧ください。

SQL

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

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

   [BigQuery] に移動

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

   LOAD DATA OVERWRITE mydataset.mytable
   (x INT64,y STRING)
   FROM FILES (
     format = 'JSON',
     uris = ['gs://bucket/path/file.json']);

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

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

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 データのスキーマ自動検出が有効になります。
• --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 鍵によるデータの保護

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 という名前のローカル スキーマ ファイルで定義されています。

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

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

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

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

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

次のコマンドは、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

注: bq ツールでスキーマを指定する場合は、RECORD（STRUCT）型やフィールド記述を含めることはできず、フィールド モードも指定できません。すべてのフィールド モードはデフォルトの NULLABLE になります。フィールドの説明、モード、RECORD 型を含めるには、代わりに JSON スキーマ ファイルを指定します。

次のコマンドは、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 という名前のローカル スキーマ ファイルで定義されています。

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

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

BigQueryClient.CreateLoadJob() メソッドを使用して、Cloud Storage からの読み込みジョブを開始します。JSONL を使用するには、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 = loadJob.PollUntilCompleted().ThrowOnAnyError();  // 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 のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

Client.load_table_from_uri() メソッドを使用して、Cloud Storage から読み込みジョブを開始します。JSONL を使用するには、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 のリファレンス ドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

Dataset.load_job() メソッドを使用して、Cloud Storage からの読み込みジョブを開始します。JSONL を使用するには、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 データの読み込み

BigQuery では、フィールドが異なる型の値を取ることができる半構造化データの読み込みがサポートされています。以下の例は、上記のネストされた JSON データと繰り返し JSON データ例と似ています。ただし、address フィールドは、STRING、STRUCT、または ARRAY になり得ます。

{"id":"1","first_name":"John","last_name":"Doe","dob":"1968-01-22","address":"123 First Avenue, Seattle WA 11111"}

{"id":"2","first_name":"Jane","last_name":"Doe","dob":"1980-10-16","address":{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"}}

{"id":"3","first_name":"Bob","last_name":"Doe","dob":"1982-01-10","address":[{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"}, "321 Main Street Hoboken NJ 44444"]}

このデータは、次のスキーマを使用することで BigQuery に読み込めます。

[
    {
        "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": "address",
        "type": "JSON",
        "mode": "NULLABLE"
    }
]

address フィールドは JSON 型の列に読み込まれます。これにより、この例では混合型を保持できます。種類が混在しているかどうかにかかわらず、データは JSON として取り込むことができます。たとえば、first_name フィールドのタイプとして STRING ではなく JSON を指定できます。詳細については、GoogleSQL での JSON データの操作をご覧ください。

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

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

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

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

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

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

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

• Google Cloud コンソール
• bq コマンドライン ツールの bq load コマンドの使用
• jobs.insert API メソッドと load ジョブの構成
• クライアント ライブラリ

注: このページでは、パーティション分割テーブルの追加または上書きについては説明しません。パーティション分割テーブルの追加と上書きの詳細については、パーティション分割テーブルデータの追加と上書きをご覧ください。

コンソール

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

   [BigQuery] に移動

2. [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
3. [データセット情報] セクションで、[ テーブルを作成] をクリックします。
4. [テーブルを作成] パネルで、次の詳細を指定します。
1. [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
   1. Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
   2. [ファイル形式] で [JSONL（改行区切り JSON）] を選択します。
注: テーブルを追加または上書きするときに、テーブルのスキーマを変更できます。読み込みオペレーション中にサポートされるスキーマの変更については、テーブル スキーマの変更をご覧ください。
2. [宛先] セクションで、次の詳細を指定します。
   1. [データセット] で、テーブルを作成するデータセットを選択します。
   2. [テーブル] フィールドに、作成するテーブルの名前を入力します。
   3. [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
3. [スキーマ] セクションでスキーマ定義を入力します。スキーマの自動検出を有効にするには、[自動検出] を選択します。スキーマ情報は、次のいずれかの方法で手動で入力できます。
   • オプション 1: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマ ファイルの作成と同じプロセスを使用してスキーマを生成します。既存のテーブルのスキーマを JSON 形式で表示するには、次のコマンドを入力します。

         bq show --format=prettyjson dataset.table
         

   • オプション 2: [フィールドを追加] をクリックして、テーブル スキーマを入力します。各フィールドの名前、型、モードを指定します。
   注: テーブルを追加または上書きするときに、テーブルのスキーマを変更できます。読み込みオペレーション中にサポートされるスキーマの変更については、テーブル スキーマの変更をご覧ください。
4. 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。追加や上書きではテーブルをパーティション分割テーブルまたはクラスタ化テーブルに変換できません。Google Cloud コンソールでは、読み込みジョブでパーティション分割テーブルやクラスタ化テーブルの追加または上書きを行うことはできません。
5. [詳細オプション] をクリックして、次の操作を行います。
   • [書き込み設定] で、[テーブルに追加する] または [テーブルを上書きする] を選択します。
   • [許可されているエラー数] で、デフォルト値の 0 を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブは invalid メッセージとなり、失敗します。このオプションは、CSV ファイルと JSON ファイルにのみ適用されます。
   • テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
   • Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
6. [テーブルを作成] をクリックします。

SQL

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

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

   [BigQuery] に移動

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

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

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

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

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 を使用して定義されます。

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

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

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 以外を自動的に検出します。

Bytes。BYTES 型の列は Base64 としてエンコードする必要があります。

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

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

Geography。GEOGRAPHY 型の列は、次のいずれかの形式の文字列にする必要があります。

• Well-known text（WKT）
• Well-known binary（WKB）
• GeoJSON

WKB を使用する場合は、値を 16 進コードにする必要があります。

有効なデータの例を以下に示します。

• WKT: POINT(1 2)
• GeoJSON: { "type": "Point", "coordinates": [1, 2] }
• 16 進数でエンコードされた WKB: 0101000000feffffffffffef3f0000000000000040

GEOGRAPHY データを読み込む際は、事前に地理空間データの読み込みもご覧ください。

Interval。INTERVAL 型の列は以下に示す ISO 8601 形式 PYMDTHMS にする必要があります。

• P = 値が期間を示す指定子。これは常に含める必要があります。
• Y = 年
• M = 月
• D = 日
• T = 期間の時間部分を示す指定子。これは常に含める必要があります。
• H = 時
• M = 分
• S = 秒。秒は、マイクロ秒の精度で、全体値または最大 6 桁の小数値として表すことができます。

負の値を指定するには、先頭にダッシュ（-）を追加します。

有効なデータの例を以下に示します。

• P-10000Y0M-3660000DT-87840000H0M0S
• P0Y0M0DT0H0M0.000001S
• P10000Y0M3660000DT87840000H0M0S

INTERVAL データを読み込むには、--schema フラグを使用してスキーマを指定し bq load コマンドを使用する必要があります。コンソールを使用して INTERVAL データをアップロードすることはできません。

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

Array（繰り返しフィールド）。値は JSON 配列または null にする必要があります。JSON の null は SQL の NULL に変換されます。配列自体に null 値を含めることはできません。

スキーマの自動検出

このセクションでは、JSON ファイルを読み込むときのスキーマの自動検出の動作について説明します。

JSON のネストされたフィールドと繰り返しフィールド

BigQuery は、JSON ファイルのネストされたフィールドと繰り返しフィールドを推測します。フィールド値が JSON オブジェクトの場合、BigQuery は RECORD 型としてその列を読み込みます。フィールド値が配列の場合、BigQuery はこの列を繰り返し列として読み込みます。ネストされたデータと繰り返しデータを含む JSON データの例については、ネストされた JSON データと繰り返し JSON データの読み込みをご覧ください。

文字列変換

スキーマの自動検出を有効にすると、BigQuery は可能であれば文字列をブール値、数値、日時型に変換します。たとえば、次の JSON データを使用すると、スキーマの自動検出によって id フィールドが INTEGER 列に変換されます。

{ "name":"Alice","id":"12"}
{ "name":"Bob","id":"34"}
{ "name":"Charles","id":"45"}

エンコードのタイプ

BigQuery に読み込む JSON データは UTF-8 でエンコードされている必要があります。サポートされている他のエンコード タイプの JSON ファイルがある場合は、BigQuery がデータを UTF-8 に変換できるように、--encoding フラグを使用してエンコードを明示的に指定する必要があります。

BigQuery は、JSON ファイルに対して次のエンコード タイプをサポートしています。

• UTF-8
• ISO-8859-1
• UTF-16BE（UTF-16 ビッグ エンディアン）
• UTF-16LE（UTF-16 リトル エンディアン）
• UTF-32BE（UTF-32 ビッグ エンディアン）
• UTF-32LE（UTF-32 リトル エンディアン）

JSON のオプション

BigQuery による JSON データの解析方法を変更するには、Google Cloud コンソール、bq コマンドライン ツール、API、またはクライアント ライブラリで追加のオプションを指定します。

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

次のステップ

• ローカル ファイルから JSON データを読み込む方法については、ローカル ファイルからのデータの読み込みをご覧ください。
• JSON データの作成、取り込み、クエリの詳細については、GoogleSQL での JSON データの操作をご覧ください。