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

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

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

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

使ってみる

Google Cloud を初めて使用される方は、アカウントを作成して、実際のシナリオでの BigQuery のパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイに充当できる無料クレジット $300 分を差し上げます。

BigQuery の無料トライアル

制限事項

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

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

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

CSV ファイルはネストされたデータや繰り返しデータに対応していません。
バイトオーダーマーク（BOM）文字を削除します。予期しない問題が発生する可能性があります。
gzip 圧縮を使用した場合、BigQuery はデータを並列で読み取ることができません。圧縮された CSV データを BigQuery に読み込む場合は、圧縮されていないデータを読み込むよりも時間がかかります。圧縮データと非圧縮データを読み込むをご覧ください。
同じ読み込みジョブに圧縮ファイルと非圧縮ファイルの両方を含めることはできません。
gzip ファイルの最大サイズは 4 GB です。
スキーマの自動検出を使用して CSV データを読み込む際、すべての列が文字列型の場合、ヘッダーは自動的に検出されません。この場合、数値列を入力に追加するか、スキーマを明示的に宣言します。
CSV データまたは JSON データを読み込む場合、DATE 列の値に区切りとしてダッシュ（-）を使用し、YYYY-MM-DD（年-月-日）の形式にする必要があります。
JSON または CSV データを読み込む場合、TIMESTAMP 列のタイムスタンプ値の日付部分の区切りにはダッシュ（-）またはスラッシュ（/）を使用し、日付は、YYYY-MM-DD（年-月-日）または YYYY/MM/DD（年/月/日）のいずれかの形式にする必要があります。タイムスタンプの時間部分 hh:mm:ss（時-分-秒）には、区切りとしてコロン（:）を使用します。
ファイルは、読み込みジョブの上限で説明されている CSV ファイルサイズの上限を満たしている必要があります。

始める前に

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

CSV 圧縮

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

CSV データをテーブルに読み込む

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

コンソール

このタスクを Cloud Shell エディタで直接行う際のガイダンスについては、「ガイドを表示」をクリックしてください。

ガイドを表示

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

[BigQuery] に移動
[エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
[データセット情報] セクションで、[ テーブルを作成] をクリックします。
[テーブルを作成] パネルで、次の詳細を指定します。

[ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
1. Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
2. [ファイル形式] で [CSV] を選択します。
[宛先] セクションで、次の詳細を指定します。
1. [データセット] で、テーブルを作成するデータセットを選択します。
2. [テーブル] フィールドに、作成するテーブルの名前を入力します。
3. [テーブルタイプ] フィールドが [ネイティブテーブル] に設定されていることを確認します。
[スキーマ] セクションでスキーマ定義を入力します。スキーマの自動検出を有効にするには、[自動検出] を選択します。スキーマ情報は、次のいずれかの方法で手動で入力できます。
- オプション 1: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマファイルの作成と同じプロセスを使用してスキーマを生成します。既存のテーブルのスキーマを JSON 形式で表示するには、次のコマンドを入力します。
```
    bq show --format=prettyjson dataset.table
    
```
- オプション 2: [フィールドを追加] をクリックして、テーブルスキーマを入力します。各フィールドの名前、型、モードを指定します。
省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。
[詳細オプション] をクリックして、次の操作を行います。
- [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
- [許可されているエラー数] で、デフォルト値の 0 を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブは invalid メッセージとなり、失敗します。このオプションは、CSV ファイルと JSON ファイルにのみ適用されます。
- テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
- [フィールド区切り文字] で、CSV ファイル内のセルの区切り文字を選択します。[カンマ]、[タブ]、[パイプ]、[カスタム] のいずれかを選択します。[カスタム] を選択した場合、[カスタムのフィールド区切り文字] ボックスに区切り文字を入力します。デフォルト値はカンマです。
- [スキップするヘッダー行] で、CSV ファイルの先頭でスキップするヘッダーの行数を入力します。デフォルト値は 0 です。
- 引用符で囲まれた改行を使用する場合は、[引用符で囲まれた改行を許可する] をオンにして、改行文字を含む引用符で囲まれたデータセクションを CSV ファイルで許可します。デフォルト値は false です。
- ジャグ行を使用する場合、[ジャグ行を許可する] をオンにして、CSV ファイルで末尾のオプションの列が欠落している行を許可します。欠損値は null として扱われます。オフの場合、末尾の列が欠落しているレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値は false です。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。Google-managed key の設定をそのままにすると、BigQuery は保存データを暗号化します。
[テーブルを作成] をクリックします。

SQL

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

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

[BigQuery Studio] に移動

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

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

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

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

bq

bq load コマンドを使用します。--source_format フラグを使用して CSV を指定し、Cloud Storage URI を設定します。単一の URI、URI のカンマ区切りのリスト、ワイルドカードを含む URI を指定できます。スキーマをインラインまたはスキーマ定義ファイルで指定するか、スキーマ自動検出を使用します。スキーマを指定せず、--autodetect が false であり、宛先テーブルが存在する場合は、宛先テーブルのスキーマが使用されます。

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

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

--allow_jagged_rows: 指定すると、CSV ファイルで末尾のオプションの列が欠落している行を受け入れます。欠損値は null として扱われます。オフの場合、末尾の列が欠落しているレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値は false です。
--allow_quoted_newlines: 指定すると、改行文字を含む引用符で囲まれたデータセクションが CSV ファイルで許可されます。デフォルト値は false です。
--field_delimiter: データ内の列間の境界を示す文字。タブ区切り文字には \t と tab の両方を使用できます。デフォルト値は , です。
--null_marker: CSV データの NULL 値を表すオプションのカスタム文字列。
--skip_leading_rows: CSV ファイルの先頭でスキップするヘッダーの行数を指定します。デフォルト値は 0 です。
--quote: レコードを囲むために使用する引用符。デフォルト値は " です。引用符を使用しない場合は、空の文字列を使用します。
--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 鍵。
--column_name_character_map: 柔軟な列名を有効にするオプションを使用して、列名の文字のスコープと処理を定義します。CSV ファイルには --autodetect オプションが必要です。詳細については、load_option_list をご覧ください。

bq load コマンドについて詳しくは、以下をご覧ください。
- コマンドラインリファレンス
パーティション分割テーブルの詳細については、以下をご覧ください。
- パーティション分割テーブルの作成
クラスタ化テーブルの詳細については、以下をご覧ください。
- クラスタ化テーブルの作成と使用
テーブルの暗号化の詳細については、以下をご覧ください。
- Cloud KMS 鍵によるデータの保護

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

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

ここで

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

例:

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

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

次のコマンドは、gs://mybucket/mydata.csv から mydataset 内の mytable というテーブルにデータを読み込みます。スキーマは、myschema.json という名前のローカルスキーマファイルで定義されています。CSV ファイルには、2 行のヘッダーが含まれています。--skip_leading_rows を指定していない場合、ファイルにヘッダーが含まれていないと想定されます。

    bq load \
    --source_format=CSV \
    --skip_leading_rows=2
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

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

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

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

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

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

    bq load \
    --autodetect \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv

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

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

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

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

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

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

API

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


using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsCsv
{
    public void LoadTableGcsCsv(
        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.csv";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        var destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            // The source format defaults to CSV; line below is optional.
            SourceFormat = FileFormat.Csv,
            SkipLeadingRows = 1
        };
        // Create and run job
        var 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 のリファレンスドキュメントをご覧ください。

import (
	"context"
	"fmt"

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

// importCSVExplicitSchema demonstrates loading CSV data from Cloud Storage into a BigQuery
// table and providing an explicit schema for the data.
func importCSVExplicitSchema(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.csv")
	gcsRef.SkipLeadingRows = 1
	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 のリファレンスドキュメントをご覧ください。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.Field;
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 CSV data from Cloud Storage into a new BigQuery table
public class LoadCsvFromGcs {

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

  public static void loadCsvFromGcs(
      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();

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri, csvOptions).setSchema(schema).build();

      // Load data from a GCS CSV 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("CSV from GCS successfully added during load append job");
      } 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 CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.csv';

async function loadCSVFromGCS() {
  // 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: 'CSV',
    skipLeadingRows: 1,
    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.csv';
$schema = [
    'fields' => [
        ['name' => 'name', 'type' => 'string'],
        ['name' => 'post_abbr', 'type' => 'string']
    ]
];
$loadConfig = $table->loadFromStorage($gcsUri)->schema($schema)->skipLeadingRows(1);
$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 にある CSV ファイルからデータを読み込みます。LoadJobConfig.schema プロパティの値を SchemaField オブジェクトのリストに設定することで、スキーマ定義を明示的に指定します。

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"),
    ],
    skip_leading_rows=1,
    # The source format defaults to CSV, so the line below is optional.
    source_format=bigquery.SourceFormat.CSV,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"

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)  # Make an API request.
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

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

require "google/cloud/bigquery"

def load_table_gcs_csv 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.csv"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, skip_leading: 1 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

CSV データを列ベースの時間パーティショニングを使用するテーブルに読み込む

CSV データを Cloud Storage から列ベースの時間パーティショニングを使用する BigQuery テーブルに読み込むには:

Go


import (
	"context"
	"fmt"
	"time"

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

// importPartitionedTable demonstrates specifing time partitioning for a BigQuery table when loading
// CSV data from Cloud Storage.
func importPartitionedTable(projectID, destDatasetID, destTableID 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-by-date.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
		{Name: "date", Type: bigquery.DateFieldType},
	}
	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
	loader.TimePartitioning = &bigquery.TimePartitioning{
		Field:      "date",
		Expiration: 90 * 24 * time.Hour,
	}
	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

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.JobId;
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;
import com.google.cloud.bigquery.TimePartitioning;
import java.time.Duration;
import java.time.temporal.ChronoUnit;
import java.util.UUID;

public class LoadPartitionedTable {

  public static void runLoadPartitionedTable() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    loadPartitionedTable(datasetName, tableName, sourceUri);
  }

  public static void loadPartitionedTable(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      // Configure time partitioning. For full list of options, see:
      // https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#TimePartitioning
      TimePartitioning partitioning =
          TimePartitioning.newBuilder(TimePartitioning.Type.DAY)
              .setField("date")
              .setExpirationMs(Duration.of(90, ChronoUnit.DAYS).toMillis())
              .build();

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .build();

      // Create a job ID so that we can safely retry.
      JobId jobId = JobId.of(UUID.randomUUID().toString());
      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).setJobId(jobId).build());

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Data successfully loaded into time partitioned table during load job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println(
          "Data not loaded into time partitioned table during load job \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 CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states-by-date.csv';

async function loadTablePartitioned() {
  // Load data into a table that uses column-based time partitioning.

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const partitionConfig = {
    type: 'DAY',
    expirationMs: '7776000000', // 90 days
    field: 'date',
  };

  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
        {name: 'date', type: 'DATE'},
      ],
    },
    location: 'US',
    timePartitioning: partitionConfig,
  };

  // 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.`);
}

Python

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"),
        bigquery.SchemaField("date", "DATE"),
    ],
    skip_leading_rows=1,
    time_partitioning=bigquery.TimePartitioning(
        type_=bigquery.TimePartitioningType.DAY,
        field="date",  # Name of the column to use for partitioning.
        expiration_ms=7776000000,  # 90 days.
    ),
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

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

table = client.get_table(table_id)
print("Loaded {} rows to table {}".format(table.num_rows, table_id))

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

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

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

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

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

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

コンソール

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

[BigQuery] に移動
[エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
[データセット情報] セクションで、[ テーブルを作成] をクリックします。
[テーブルを作成] パネルで、次の詳細を指定します。

[ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
1. Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
2. [ファイル形式] で [CSV] を選択します。

[宛先] セクションで、次の詳細を指定します。
1. [データセット] で、テーブルを作成するデータセットを選択します。
2. [テーブル] フィールドに、作成するテーブルの名前を入力します。
3. [テーブルタイプ] フィールドが [ネイティブテーブル] に設定されていることを確認します。
[スキーマ] セクションでスキーマ定義を入力します。スキーマの自動検出を有効にするには、[自動検出] を選択します。スキーマ情報は、次のいずれかの方法で手動で入力できます。
- オプション 1: [テキストとして編集] をクリックし、スキーマを JSON 配列の形式で貼り付けます。JSON 配列を使用する場合は、JSON スキーマファイルの作成と同じプロセスを使用してスキーマを生成します。既存のテーブルのスキーマを JSON 形式で表示するには、次のコマンドを入力します。
```
    bq show --format=prettyjson dataset.table
    
```
- オプション 2: [フィールドを追加] をクリックして、テーブルスキーマを入力します。各フィールドの名前、型、モードを指定します。
省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。追加や上書きではテーブルをパーティション分割テーブルまたはクラスタ化テーブルに変換できません。Google Cloud コンソールでは、読み込みジョブでパーティション分割テーブルやクラスタ化テーブルの追加または上書きを行うことはできません。
[詳細オプション] をクリックして、次の操作を行います。
- [書き込み設定] で、[テーブルに追加する] または [テーブルを上書きする] を選択します。
- [許可されているエラー数] で、デフォルト値の 0 を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブは invalid メッセージとなり、失敗します。このオプションは、CSV ファイルと JSON ファイルにのみ適用されます。
- テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
- [フィールド区切り文字] で、CSV ファイル内のセルの区切り文字を選択します。[カンマ]、[タブ]、[パイプ]、[カスタム] のいずれかを選択します。[カスタム] を選択した場合、[カスタムのフィールド区切り文字] ボックスに区切り文字を入力します。デフォルト値はカンマです。
- [スキップするヘッダー行] で、CSV ファイルの先頭でスキップするヘッダーの行数を入力します。デフォルト値は 0 です。
- 引用符で囲まれた改行を使用する場合は、[引用符で囲まれた改行を許可する] をオンにして、改行文字を含む引用符で囲まれたデータセクションを CSV ファイルで許可します。デフォルト値は false です。
- ジャグ行を使用する場合、[ジャグ行を許可する] をオンにして、CSV ファイルで末尾のオプションの列が欠落している行を許可します。欠損値は null として扱われます。オフの場合、末尾の列が欠落しているレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値は false です。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。Google-managed key の設定をそのままにすると、BigQuery は保存データを暗号化します。
[テーブルを作成] をクリックします。

SQL

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

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

[BigQuery Studio] に移動

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

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

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

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

bq

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

スキーマをインラインまたはスキーマ定義ファイルで指定するか、スキーマ自動検出を使用します。スキーマを指定せず、--autodetect が false であり、宛先テーブルが存在する場合は、宛先テーブルのスキーマが使用されます。

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

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

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

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

--allow_jagged_rows: 指定すると、CSV ファイルで末尾のオプションの列が欠落している行を受け入れます。欠損値は null として扱われます。オフの場合、末尾の列が欠落しているレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値は false です。
--allow_quoted_newlines: 指定すると、改行文字を含む引用符で囲まれたデータセクションが CSV ファイルで許可されます。デフォルト値は false です。
--field_delimiter: データ内の列間の境界を示す文字。タブ区切り文字には \t と tab の両方を使用できます。デフォルト値は , です。
--null_marker: CSV データの NULL 値を表すオプションのカスタム文字列。
--skip_leading_rows: CSV ファイルの先頭でスキップするヘッダーの行数を指定します。デフォルト値は 0 です。
--quote: レコードを囲むために使用する引用符。デフォルト値は " です。引用符を使用しない場合は、空の文字列を使用します。
--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 は CSV です。
dataset は既存のデータセットです。
table は、データの読み込み先のテーブル名です。
path_to_source は、完全修飾の Cloud Storage URI または URI のカンマ区切りのリストです。ワイルドカードもサポートされます。
schema は有効なスキーマです。スキーマはローカルの JSON ファイルにすることも、コマンドの一部としてインラインで入力することもできます。また、スキーマ定義を指定する代わりに、--autodetect フラグを使用することもできます。

例:

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

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

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

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

API

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

Go

import (
	"context"
	"fmt"

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

// importCSVTruncate demonstrates loading data from CSV data in Cloud Storage and overwriting/truncating
// data in the existing table.
func importCSVTruncate(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.csv")
	gcsRef.SourceFormat = bigquery.CSV
	gcsRef.AutoDetect = true
	gcsRef.SkipLeadingRows = 1
	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.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

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

  public static void runLoadCsvFromGcsTruncate() throws Exception {
    // 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.csv";
    loadCsvFromGcsTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadCsvFromGcsTruncate(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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 configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(WriteDisposition.WRITE_TRUNCATE)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job loadJob = bigquery.create(JobInfo.of(configuration));

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Table is successfully overwritten by CSV file loaded from GCS");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

既存のテーブルの行を置換するには、metadata パラメータの writeDisposition 値を 'WRITE_TRUNCATE' に設定します。

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

async function loadCSVFromGCSTruncate() {
  /**
   * 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: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    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;
  }
}

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.csv';
$loadConfig = $table->loadFromStorage($gcsUri)->skipLeadingRows(1)->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 プロパティを SourceFormat の定数 WRITE_TRUNCATE に設定します。

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.CSV,
    skip_leading_rows=1,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
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 パーティション分割 CSV データの読み込み

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

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

このセクションでは、BigQuery によりさまざまな CSV のフォーマットのオプションを処理する方法について説明します。

エンコード

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

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

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

エンコードを指定しない場合、または CSV ファイルが UTF-8 でエンコードされていないときに UTF-8 エンコードを指定した場合、BigQuery はデータを UTF-8 に変換しようとします。通常、CSV ファイルが ISO-8859-1 でエンコードされている場合、データは正常に読み込まれますが、予期されるものと完全には一致しないことがあります。CSV ファイルが UTF-16BE、UTF-16LE、UTF-32BE、UTF-32LE でエンコードされている場合、読み込みが失敗する可能性があります。予期しないエラーを回避するには、--encoding フラグを使用して正しいエンコードを指定します。

BigQuery が ASCII 0 文字以外の文字を変換できない場合、BigQuery は文字を標準の Unicode 置換文字 � に変換します。

フィールド区切り文字

CSV ファイル内の区切り文字には、任意の 1 バイト文字を使用できます。ソースファイルが ISO-8859-1 エンコードを使用する場合、任意の文字を区切り文字に使用できます。ソースファイルが UTF-8 エンコードを使用している場合、10 進数の範囲 1～127（U+0001～U+007F）の任意の文字を変更せずに使用できます。この範囲外の ISO-8859-1 文字を区切り文字として挿入すると、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 型の列は Y-M D H:M:S[.F] の形式にする必要があります。この場合、

Y = 年。サポートされる値の範囲は 0～10,000 です。
M = 月。サポートされる値の範囲は 1～12 です。
D = 日。サポートされる値の範囲は 1～[指定された月の最終日] です。
H = 時。
M = 分。
S = 秒。
[.F] = マイクロ秒の精度で、6 桁までの秒の小数部。

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

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

10-6 0 0:0:0
0-0 -5 0:0:0
0-0 0 0:0:1.25

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

JSON。引用は、2 文字のシーケンス（""）でエスケープされます。詳細については、CSV ファイルから JSON データを読み込む例をご覧ください。

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

範囲。CSV ファイルでは [LOWER_BOUND, UPPER_BOUND) の形式で表されます。ここで、LOWER_BOUND と UPPER_BOUND は有効な DATE、DATETIME、または TIMESTAMP の文字列です。NULL と UNBOUNDED は、制限のない開始値または終了値を表します。

次に RANGE<DATE> の CSV 値の例を示します。

"[2020-01-01, 2021-01-01)"
"[UNBOUNDED, 2021-01-01)"
"[2020-03-01, NULL)"
"[UNBOUNDED, UNBOUNDED)"

スキーマの自動検出

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

CSV 区切り文字

BigQuery は以下の区切り文字を検出します。

カンマ（,）
パイプ（|）
タブ（\t）

CSV ヘッダー

BigQuery は、ファイルの最初の行をファイル内の他の行と比較することでヘッダーを推測します。最初の行に文字列のみが含まれ、他の行に他のデータ型も含まれる場合、BigQuery はその最初の行がヘッダー行であると想定します。BigQuery は、ヘッダー行のフィールド名に基づいて列名を割り当てます。この名前は、BigQuery の列の命名規則を満たすように変更される場合があります。たとえば、スペースはアンダースコアに置き換えられます。

それ以外の場合、BigQuery は最初の行がデータ行であると想定し、string_field_1 などの一般的な列名を割り当てます。テーブルを作成した後は、スキーマでは列名を更新できませんが、手動で名前を変更することはできます。もう 1 つの方法は、autodetect を使用する代わりに明示的なスキーマを指定することです。

すべてのデータフィールドが文字列のヘッダー行を含む CSV ファイルがあるとします。この場合、最初の行がヘッダーであることを BigQuery は自動的に検出しません。--skip_leading_rows オプションを使用することで、ヘッダー行をスキップできます。そうしない場合、ヘッダーはデータとしてインポートされます。こうしたケースでは、明示的なスキーマを指定して列名を割り当てることも検討してください。

CSV 引用符付き改行

BigQuery は、CSV フィールド内の引用符付き改行文字を検出し、引用符付き改行文字を行境界として解釈しません。

解析エラーのトラブルシューティング

CSV ファイルの解析中に問題が発生すると、読み込みジョブの errors リソースにエラーの詳細が入力されます。

通常、こうしたエラーでは、バイトオフセットで問題のある行の先頭が特定されます。非圧縮ファイルの場合は、--recursive 引数を指定して gcloud storage を使用し、関連する行にアクセスできます。

たとえば、bq load コマンドを実行すると、エラーが発生します。

bq load
    --skip_leading_rows=1 \
    --source_format=CSV \
    mydataset.mytable \
    gs://my-bucket/mytable.csv \
    'Number:INTEGER,Name:STRING,TookOffice:STRING,LeftOffice:STRING,Party:STRING'

出力のエラーは次のようになります。

Waiting on bqjob_r5268069f5f49c9bf_0000018632e903d7_1 ... (0s)
Current status: DONE
BigQuery error in load operation: Error processing job
'myproject:bqjob_r5268069f5f49c9bf_0000018632e903d7_1': Error while reading
data, error message: Error detected while parsing row starting at position: 1405.
Error: Data between close quote character (") and field separator.
File: gs://my-bucket/mytable.csv
Failure details:
- gs://my-bucket/mytable.csv: Error while reading data,
error message: Error detected while parsing row starting at
position: 1405. Error: Data between close quote character (") and
field separator. File: gs://my-bucket/mytable.csv
- Error while reading data, error message: CSV processing encountered
too many errors, giving up. Rows: 22; errors: 1; max bad: 0; error
percent: 0

上記のエラーによれば、ファイルに形式エラーがあります。ファイルの内容を表示するには、gcloud storage cat コマンドを実行します。

gcloud storage cat 1405-1505 gs://my-bucket/mytable.csv --recursive

出力は次のようになります。

16,Abraham Lincoln,"March 4, 1861","April 15, "1865,Republican
18,Ulysses S. Grant,"March 4, 1869",
...

ファイルの出力から、"April 15, "1865 の引用符の位置がずれていることが問題であることがわかります。

圧縮 CSV ファイル

報告されるバイトオフセットは非圧縮ファイルの位置を示すため、圧縮された CSV ファイルの場合は、解析エラーのデバッグがより困難になります。次の gcloud storage cat コマンドは、Cloud Storage からファイルをストリーミングして解凍し、適切なバイトオフセットを特定して形式エラーのある行を表示します。

gcloud storage cat gs://my-bucket/mytable.csv.gz | gunzip - | tail -c +1406 | head -n 1

出力は次のようになります。

16,Abraham Lincoln,"March 4, 1861","April 15, "1865,Republican

CSV のオプション

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

CSV 形式の詳細については、RFC 4180 をご覧ください。

CSV のオプション	コンソールのオプション	bq ツールフラグ	BigQuery API のプロパティ	説明
フィールド区切り文字	フィールド区切り文字: カンマ、タブ、パイプ、カスタム	`-F` または `--field_delimiter`	`fieldDelimiter`（Java、Python）	（省略可）CSV ファイル内のフィールド区切り文字。区切り文字には、ISO-8859-1 の任意の 1 バイト文字を使用できます。BigQuery は文字列を ISO-8859-1 エンコードに変換し、エンコードされた文字列の先頭バイトを使用してデータを未加工のバイナリ状態で分割します。また、BigQuery はタブ区切りを示すエスケープシーケンス「\t」もサポートしています。デフォルト値はカンマ（,）です。
ヘッダー行	スキップするヘッダー行	`--skip_leading_rows`	`skipLeadingRows`（Java、Python）	（省略可）ソースデータ内のヘッダー行の数を示す整数。
許可されている不良レコード数	許容されるエラー数	`--max_bad_records`	`maxBadRecords`（Java、Python）	（省略可）BigQuery でジョブの実行時に無視できる不良レコードの最大数。不良レコードの数がこの値を超えると、ジョブ結果で「無効」エラーが返されます。デフォルト値は 0 で、すべてのレコードが有効である必要があります。
改行文字	引用符で囲まれた改行を許可する	`--allow_quoted_newlines`	`allowQuotedNewlines`（Java、Python）	（省略可）改行文字を含む引用符で囲まれたデータセクションを CSV ファイルで許可するかどうかを指定します。デフォルト値は false です。
カスタム Null 値	なし	`--null_marker`	`nullMarker`（Java、Python）	（省略可）CSV ファイル内で null 値を表す文字列を指定します。たとえば、「\N」を指定すると、BigQuery に CSV ファイルが読み込まれるときに「\N」が null 値として解釈されます。デフォルト値は空の文字列です。このプロパティにカスタム値を設定すると、STRING と BYTE を除くすべてのデータ型で、空の文字列がある場合にエラーがスローされます。STRING 列と BYTE 列では、空の文字列は空の値として解釈されます。
末尾のオプションの列	ジャグ行を許可する	`--allow_jagged_rows`	`allowJaggedRows`（Java、Python）	（省略可）末尾のオプションの列が欠落している行を受け入れます。欠損値は null として扱われます。false の場合、末尾の列が欠落しているレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値は false です。これは CSV のみに適用され、他の形式では無視されます。
不明な値	不明な値を無視	`--ignore_unknown_values`	`ignoreUnknownValues`（Java、Python）	（省略可）テーブルスキーマで示されていない余分な値を許可するかどうかを指定します。true の場合、余分な値は無視されます。false の場合、余分な列を含むレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値は false です。何が余分な値として扱われるかは、`sourceFormat` プロパティによって決まります。 CSV: 末尾の列 JSON: どの列名とも一致しない名前付き値
引用	引用符として使用する文字: 二重引用符、一重引用符、なし、カスタム	`--quote`	`quote`（Java、Python）	（省略可）CSV ファイル内のデータセクションを囲む引用符として使用される値。BigQuery は文字列を ISO-8859-1 エンコードに変換し、エンコードされた文字列の先頭バイトを使用してデータを未加工のバイナリ状態で分割します。デフォルト値は二重引用符（'"'）です。データに引用符で囲まれたセクションが含まれていない場合は、このプロパティの値を空の文字列に設定します。データに引用符で囲まれた改行文字が含まれている場合は、`allowQuotedNewlines` プロパティの値を `true` に設定する必要もあります。引用符で囲まれた値の中に特定の引用符を含めるには、その前に引用符を追加します。たとえば、デフォルトの「"」をエスケープするには、「""」を使用します。
エンコード	なし	`-E` または `--encoding`	`encoding`（Java、Python）	（省略可）データの文字エンコード。サポートされている値は UTF-8、ISO-8859-1、UTF-16BE、UTF-16LE、UTF-32BE、UTF-32LE です。デフォルト値は UTF-8 です。BigQuery は、`quote` プロパティと `fieldDelimiter` プロパティの値を使用して未加工のバイナリデータを分割してからデータをデコードします。
ASCII 制御文字	なし	`--preserve_ascii_control_characters`	なし	（省略可）ASCII 0 とその他の ASCII 制御文字を許可する場合は、読み込みジョブの `--preserve_ascii_control_characters` を `true` に設定します。