Google Cloud Storage から CSV データを読み込む

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

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

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

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

制限事項

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

• CSV ファイルはネストされたデータや繰り返しデータに対応していません。
• gzip 圧縮を使用した場合、BigQuery はデータを並列で読み取ることができません。圧縮された CSV データを BigQuery に読み込む場合は、圧縮されていないデータを読み込むよりも時間がかかります。
• CSV データまたは JSON データを読み込む場合、DATE 列の値に区切りとしてダッシュ（-）を使用し、YYYY-MM-DD（年-月-日）の形式にする必要があります。
• JSON データまたは CSV データを読み込む場合、TIMESTAMP 列の値の日付部分に区切りとしてダッシュ（-）を使用し、YYYY-MM-DD（年-月-日）の形式にする必要があります。タイムスタンプの時間部分 hh:mm:ss（時-分-秒）は、区切りとしてコロン（:）を使用します。

CSV のエンコード

BigQuery に読み込む CSV データは UTF-8 でエンコードされている必要があります。CSV ファイルに ISO-8859-1（Latin-1 とも呼ばれます）形式でエンコードされたデータが含まれている場合は、それらのデータを UTF-8 に変換できるように、データの読み込み時に明示的にエンコードを指定する必要があります。

CSV ファイルの区切り文字には、ISO-8859-1 の任意の 1 バイト文字を使用できます。128～255 の範囲の文字を使用するには、その文字を UTF-8 としてエンコードする必要があります。BigQuery は文字列を ISO-8859-1 エンコードに変換し、エンコードされた文字列の先頭バイトを使用してデータを生のバイナリ状態で分割します。

必要な権限

BigQuery にデータを読み込む場合は、新規または既存の BigQuery のテーブルやパーティションにデータを読み込むためのプロジェクト レベルまたはデータセット レベルの権限が必要です。Cloud Storage からデータを読み込む場合は、データが格納されているバケットへのアクセス権も必要です。

BigQuery の権限

Cloud Storage から BigQuery にデータを読み込む場合は、プロジェクト レベルまたはデータセット レベルで bigquery.dataOwner または bigquery.dataEditor の役割が付与されている必要があります。どちらの役割もユーザーとグループに、新しいテーブルへのデータの読み込みや、既存のテーブルへのデータの追加または上書きを行う権限を付与します。

プロジェクト レベルで役割を付与した場合、プロジェクト内のすべてのデータセットのテーブルにデータを読み込む権限がユーザーまたはグループに与えられます。データセット レベルで役割を付与した場合、ユーザーまたはグループは、そのデータセット内のテーブルにのみデータを読み込むことができます。

データセット アクセスの構成の詳細については、データセットへのアクセス制御の割り当てをご覧ください。BigQuery での IAM 役割の詳細については、アクセス制御をご覧ください。

Cloud Storage の権限

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

事前定義された IAM 役割 storage.objectViewer を付与すると、storage.objects.get 権限と storage.objects.list 権限が付与されます。

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

CSV データを Cloud Storage から新しい BigQuery テーブルに読み込む、あるいは既存のテーブルにデータを追加するには:

ウェブ UI

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

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

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

   • [Location] で [Google Cloud Storage] を選択し、ソース フィールドに Cloud Storage URI を入力します。BigQuery ウェブ UI では複数の URI を指定できませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在している必要があります。
   • [File format] で [Comma-separated values (CSV)] を選択します。
4. [Create Table] ページの [Destination Table] セクションで、次の操作を行います。
   • [Table name] で、適切なデータセットを選択し、BigQuery で作成するテーブルの名前をテーブル名のフィールドに入力します。
   • [Table type] が [Native table] に設定されていることを確認します。

5. [Schema] セクションに、スキーマ定義を入力します。

   • スキーマ情報を手動で入力します。

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

       

       注意： 既存のテーブルのスキーマを JSON 形式で表示するには、bq show --format=prettyjson [DATASET].[TABLE] コマンドを入力します。

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

       

6. [Options] セクションで該当する項目を選択し、[Create Table] をクリックします。使用可能なオプションの詳細については、CSV のオプションをご覧ください。

コマンドライン

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

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

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 フラグを使用することもできます。

その他に、BigQuery によるデータの解析方法を制御するために CSV のオプション フラグを追加することもできます。たとえば、--skip_leading_rows フラグを使用して CSV ファイルのヘッダー行を無視したり、--encoding フラグを使用してデータの文字エンコードを指定したりできます。

例:

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

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

• 次のコマンドは、gs://mybucket/mydata.csv から mydataset 内の mytable というテーブルにデータを読み込みます。スキーマはインラインで [FIELD]:[DATA_TYPE], [FIELD]:[DATA_TYPE] の形式で定義されています。mybucket と mydataset は US マルチリージョン ロケーションに存在します。

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

  コマンドラインでスキーマを指定する場合は、RECORD（STRUCT）型とフィールドの説明を含めることはできず、フィールド モードも指定できません。すべてのフィールド モードはデフォルトの NULLABLE に設定されます。フィールドの説明、モード、RECORD 型を含めるには、代わりに JSON スキーマ ファイルを指定します。

• 次のコマンドは、gs://mybucket/mydata.csv から mydataset 内の mytable というテーブルにデータを読み込みます。スキーマは myschema.json というローカル スキーマ ファイルで定義されています。--skip_leading_rows フラグを使用して CSV ファイルの最初の 2 行のヘッダー行を無視しています。mybucket と mydataset は asia-northeast1 リージョンに存在します。

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

API

API を使用して CSV データを読み込むには、次のプロパティを設定します。

1. Google Cloud Storage のソースデータを指す読み込みジョブを作成します。

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

3. ソース URI は、完全修飾された gs://[BUCKET]/[OBJECT] 形式にする必要があります。各 URI に '*' ワイルドカード文字を 1 つ含めることができます。

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

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 Quickstart の C# の設定手順に従ってください。詳細については、BigQuery C# API のリファレンス ドキュメントをご覧ください。

GitHub で表示 フィードバック

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 jobOptions = new CreateLoadJobOptions()
{
    // The source format defaults to CSV; line below is optional.
    SourceFormat = FileFormat.Csv,
    SkipLeadingRows = 1
};
var loadJob = client.CreateLoadJob(gcsURI, dataset.GetTableReference(tableId),
    schema, jobOptions);
loadJob.PollUntilCompleted();

Go

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

GitHub で表示 フィードバック

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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())
}

Java

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

GitHub で表示 フィードバック

Job job = table.load(FormatOptions.csv(), sourceUri);
// Wait for the job to complete
try {
  Job completedJob =
      job.waitFor(
          RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
          RetryOption.totalTimeout(Duration.ofMinutes(3)));
  if (completedJob != null && completedJob.getStatus().getError() == null) {
    // Job completed successfully
  } else {
    // Handle error case
  }
} catch (InterruptedException e) {
  // Handle interrupted wait
}

Node.js

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

GitHub で表示 フィードバック

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

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

/**
 * 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';

// Instantiates clients
const bigquery = new BigQuery({
  projectId: projectId,
});

const storage = new Storage({
  projectId: projectId,
});

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

// Loads data from a Google Cloud Storage file into the table
bigquery
  .dataset(datasetId)
  .table(tableId)
  .load(storage.bucket(bucketName).file(filename), metadata)
  .then(results => {
    const job = results[0];

    // 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;
    }
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

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

GitHub で表示 フィードバック

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 オブジェクトのリストに設定することで、スキーマ定義を明示的に指定します。

GitHub で表示 フィードバック

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.schema = [
    bigquery.SchemaField('name', 'STRING'),
    bigquery.SchemaField('post_abbr', 'STRING')
]
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.source_format = bigquery.SourceFormat.CSV
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv'

load_job = client.load_table_from_uri(
    uri,
    dataset_ref.table('us_states'),
    job_config=job_config)  # API request
print('Starting job {}'.format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print('Job finished.')

destination_table = client.get_table(dataset_ref.table('us_states'))
print('Loaded {} rows.'.format(destination_table.num_rows))

Ruby

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

GitHub で表示 フィードバック

# project_id   = "Your Google Cloud project ID"
# dataset_id   = "ID of the dataset containing table"
# table_id     = "ID of the table to import data into"
# storage_path = "Storage path to file to import, eg. gs://bucket/file.csv"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id
dataset  = bigquery.dataset dataset_id
table    = dataset.table table_id

puts "Importing data from Cloud Storage file: #{storage_path}"
load_job = table.load_job storage_path

puts "Waiting for load job to complete: #{load_job.job_id}"
load_job.wait_until_done!

puts "Data imported"

スキーマの自動検出による CSV データの読み込み

ウェブ UI

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

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

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

   • [Location] で [Google Cloud Storage] を選択し、ソース フィールドに Cloud Storage URI を入力します。BigQuery ウェブ UI では複数の URI を指定できませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在している必要があります。
   • [File format] で [Comma-separated values (CSV)] を選択します。
4. [Create Table] ページの [Destination Table] セクションで、次の操作を行います。
   • [Table name] で、適切なデータセットを選択し、BigQuery で作成するテーブルの名前をテーブル名のフィールドに入力します。
   • [Table type] が [Native table] に設定されていることを確認します。

5. [Schema] セクションで [Auto-detect] オプションをオンにして、スキーマの自動検出を有効にします。

   

6. [Options] セクションで該当する項目を選択し、[Create Table] をクリックします。使用可能なオプションの詳細については、CSV のオプションをご覧ください。

コマンドライン

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

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

bq --location=[LOCATION] load --autodetect --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE]

各項目の説明は次のとおりです。

• [LOCATION] はロケーションです。--location フラグはオプションです。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
• --autodetect フラグによってスキーマの自動検出が有効になります。
• [FORMAT] は CSV です。
• [DATASET] は既存のデータセットです。
• [TABLE] は、データの読み込み先のテーブル名です。
• [PATH_TO_SOURCE] は、完全修飾された Cloud Storage URI または URI のカンマ区切りリストです。ワイルドカードも使用できます。

その他に、BigQuery によるデータの解析方法を制御するために CSV のオプション フラグを追加することもできます。たとえば、--skip_leading_rows フラグを使用して CSV ファイルのヘッダー行を無視したり、--encoding フラグを使用してデータの文字エンコードを指定したりできます。

例:

• 次のコマンドは、gs://mybucket/mydata.csv から mydataset 内の mytable というテーブルにデータを読み込みます。スキーマはスキーマ自動検出を使用して定義されます。 mybucket と mydataset は US マルチリージョン ロケーションに存在します。

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

• 次のコマンドは、gs://mybucket/ にある複数のファイルから mydataset 内の mytable というテーブルにデータを読み込みます。Cloud Storage URI ではワイルドカードを使用しており、スキーマはスキーマ自動検出を使用して定義されます。 mybucket と mydataset は asia-northeast1 リージョンに作成されています。

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

• 次のコマンドは、gs://mybucket/ にある複数のファイルから mydataset 内の mytable というテーブルにデータを読み込みます。このコマンドには Cloud Storage URI のカンマ区切りのリストが含まれており、スキーマはスキーマ自動検出を使用して定義されます。 mybucket と mydataset は asia-northeast1 リージョンに作成されています。

  bq --location=asia-northeast1 load --autodetect --source_format=CSV mydataset.mytable "gs://mybucket/myfile.csv,gs://mybucket/myfile2.csv"
  

API

API を使用して CSV データを読み込むには、次のプロパティを設定します。

1. Google Cloud Storage のソースデータを指す読み込みジョブを作成します。

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

3. ソース URI は、完全修飾された gs://[BUCKET]/[OBJECT] 形式にする必要があります。各 URI に '*' ワイルドカード文字を 1 つ含めることができます。

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

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 回だけです（複数回のオペレーションが成功することはありません）。

Go

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

GitHub で表示 フィードバック

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)

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())
}

Node.js

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

GitHub で表示 フィードバック

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

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

/**
 * 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';

// Instantiates clients
const bigquery = new BigQuery({
  projectId: projectId,
});

const storage = new Storage({
  projectId: projectId,
});

// Configure the load job. For full list of options, see:
// https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.load
const metadata = {
  sourceFormat: 'CSV',
  skipLeadingRows: 1,
  autodetect: true,
};

// Loads data from a Google Cloud Storage file into the table
bigquery
  .dataset(datasetId)
  .table(tableId)
  .load(storage.bucket(bucketName).file(filename), metadata)
  .then(results => {
    const job = results[0];

    // 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;
    }
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

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

GitHub で表示 フィードバック

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';
$loadConfig = $table->loadFromStorage($gcsUri)->autodetect(true)->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 のリファレンス ドキュメントをご覧ください。

LoadJobConfig.autodetect プロパティを True に設定することで、BigQuery では入力データのサンプルからスキーマが推測されます。

GitHub で表示 フィードバック

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.autodetect = True
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.source_format = bigquery.SourceFormat.CSV
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv'
load_job = client.load_table_from_uri(
    uri,
    dataset_ref.table('us_states'),
    job_config=job_config)  # API request
print('Starting job {}'.format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print('Job finished.')

destination_table = client.get_table(dataset_ref.table('us_states'))
print('Loaded {} rows.'.format(destination_table.num_rows))

CSV データでテーブルを上書きする

テーブルに追加のデータを読み込むには、ソースファイルを使用するか、クエリ結果を追加します。データのスキーマが追加先テーブルまたはパーティションのスキーマと一致しない場合は、追加または上書きするときにスキーマを更新できます。

データを追加するときにスキーマを更新する場合、BigQuery では次のことが可能です。

• 新しいフィールドを追加する
• フィールドのモードを REQUIRED から NULLABLE に緩和する

テーブルを上書きする場合、スキーマは必ず上書きされます。テーブルを上書きするときに、スキーマの更新は制限されません。

BigQuery ウェブ UI では、[Write preference] オプションを使用して、ソースファイルまたはクエリ結果からデータを読み込むときに行う操作を指定します。CLI と API には次のオプションがあります。

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

デフォルトでは、書き込み処理が変更されない限り、読み込みジョブはデータをテーブルに追加します。読み込みジョブのデータでデータを置き換える場合は、BigQuery テーブルのデータの上書きを選択できます。

ウェブ UI

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

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

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

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

5. [Schema] セクションに、スキーマ定義を入力します。

   • CSV ファイルの場合、[Auto-detect] オプションをオンにすることでスキーマの自動検出を有効にできます。

     

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

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

       

       注意: 既存のテーブルのスキーマを JSON 形式で表示するには、bq show --format=prettyjson [DATASET].[TABLE] コマンドを入力します。

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

       

6. [Options] セクションの [Write preference] で、[Write if empty]、[Append to table]、または [Overwrite table] を選択します。

   

7. [Create Table] をクリックします。

コマンドライン

テーブルを上書きするには、--replace フラグを指定して bq load コマンドを入力します。--location フラグを指定し、その値をロケーションに設定します。テーブルにデータを追加するには、--noreplace フラグを使用します。フラグを指定しない場合、デフォルトではデータが追加されます。

テーブルに追加する、またはテーブルを上書きするときは、--schema_update_option フラグを使用して、宛先テーブルのスキーマを新しいデータのスキーマで更新できます。--schema_update_option フラグでは、次のオプションを使用できます。

• ALLOW_FIELD_ADDITION: スキーマに新しいフィールドを追加します。新しいフィールドは REQUIRED にすることはできません。
• ALLOW_FIELD_RELAXATION: 必須フィールドを Null 可能に緩和します。このオプションを繰り返して値のリストを指定します。

bq --location=[LOCATION] load --[no]replace [DATASET].[TABLE] [PATH_TO_SOURCE] [SCHEMA]

各項目の説明は次のとおりです。

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

その他に、BigQuery による CSV データの解析方法を制御するために CSV のオプション フラグを追加することもできます。たとえば、--skip_leading_rows フラグを使用して CSV ファイルのヘッダー行を無視したり、--encoding フラグを使用してデータの文字エンコードを指定したりできます。

例:

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

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

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

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

• 次のコマンドは、gs://mybucket/mydata.csv からデータを読み込んで mydataset 内の mytable というテーブルに追加します。myschema.json という名前のローカル JSON スキーマ ファイルが使用されます。スキーマ定義には、宛先テーブルに存在しない新しいフィールドが含まれています。mybucket と mydataset は asia-northeast1 リージョンに作成されています。

  bq --location=asia-northeast1 load --noreplace --schema_update_option=ALLOW_FIELD_ADDITION --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json
  

• 次のコマンドは、gs://mybucket/mydata.csv からデータを読み込んで mydataset 内の mytable というテーブルに追加します。myschema.json という名前のローカル JSON スキーマ ファイルが使用されます。スキーマ定義により、2 つの REQUIRED フィールドが NULLABLE に変更（緩和）されます。mybucket と mydataset は asia-northeast1 リージョンに作成されています。

  bq --location=asia-northeast1 load --noreplace --schema_update_option=ALLOW_FIELD_RELAXATION --source_format=CSV mydataset.mytable gs://mybucket/mydata.csv ./myschema.json
  

API

API を使用して CSV データを読み込むには、次のプロパティを設定します。

1. Google Cloud Storage のソースデータを指す読み込みジョブを作成します。

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

3. ソース URI は、完全修飾された gs://[BUCKET]/[OBJECT] 形式にする必要があります。複数の URI をカンマ区切りのリストとして含めることができます。Google Cloud Storage から CSV データを読み込むとき、ワイルドカードを使用することもできます。

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

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

6. 読み込みジョブでスキーマを更新するには、configuration.load.schemaUpdateOptions プロパティを ALLOW_FIELD_ADDITION または ALLOW_FIELD_RELAXATION に設定します。

Go

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

GitHub で表示 フィードバック

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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())
}

Node.js

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

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

GitHub で表示 フィードバック

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

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

/**
 * 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';

// Instantiates clients
const bigquery = new BigQuery({
  projectId: projectId,
});

const storage = new Storage({
  projectId: projectId,
});

// Configure the load job. For full list of options, see:
// https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.load
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',
};

// Loads data from a Google Cloud Storage file into the table
bigquery
  .dataset(datasetId)
  .table(tableId)
  .load(storage.bucket(bucketName).file(filename), metadata)
  .then(results => {
    const job = results[0];

    // 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;
    }
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

PHP

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

GitHub で表示 フィードバック

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

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

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

GitHub で表示 フィードバック

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

previous_rows = client.get_table(table_ref).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.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_ref,
    job_config=job_config)  # API request
print('Starting job {}'.format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print('Job finished.')

destination_table = client.get_table(table_ref)
print('Loaded {} rows.'.format(destination_table.num_rows))

CSV のオプション

BigQuery による CSV データの解析方法を変更するには、UI、CLI、または API で追加のオプションを指定します。CSV 形式の詳細については、RFC 4180 をご覧ください。

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