データをローカルデータソースから読み込む

このページでは、ローカルデータソースからデータを読み込むオペレーションについて説明します。

ローカルデータソースからのデータの読み込みに関するチュートリアルについては、以下をご覧ください。

GCP Console: ウェブ UI を使用したクイックスタート
コマンドライン: bq コマンドラインツールを使用したクイックスタート

概要

次の方法で、読み取り可能なデータソース（ローカルマシンなど）からデータを読み込むことができます。

GCP Console または従来の BigQuery ウェブ UI を使用する
CLI の bq load コマンドを使用する
API を使用する
クライアントライブラリを使用する

GCP Console、従来の BigQuery ウェブ UI、または CLI を使用してデータを読み込む際には、読み込みジョブが自動的に作成されます。

制限事項

ローカルデータソースからのデータの読み込みには、次の制限があります。

ワイルドカードやカンマ区切りのリストは、ローカルデータソースからファイルを読み込む場合にはサポートされません。ファイルは個別に読み込む必要があります。
従来の BigQuery ウェブ UI を使用するときは、ローカルデータソースから読み込まれるファイルのサイズが 10 MB 以下で、ファイル内の行数が 16,000 未満である必要があります。

必要な権限

データを BigQuery に読み込むには最低限、次の権限が付与されている必要があります。

bigquery.tables.create。新しいテーブルを作成する場合に必要です。
bigquery.tables.updateData。テーブルを上書きまたは追加する場合に必要です。
bigquery.jobs.create。読み込みジョブを実行する場合に必要です。

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

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

bigquery.jobs.create 権限は、事前定義された以下の Cloud IAM の役割に含まれています。

bigquery.user
bigquery.jobUser
bigquery.admin

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

BigQuery での Cloud IAM 役割と権限については、アクセス制御をご覧ください。

データをローカルデータソースから読み込むには:

Console

GCP Console で BigQuery ウェブ UI を開きます。
GCP Console に移動する
ナビゲーションパネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。
ウィンドウの右側の詳細パネルで、[テーブルを作成] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
- [テーブルの作成元] で [アップロード] を選択します。
- [ファイルを選択] の下の [参照] をクリックします。
- 一覧からファイルを選択して [開く] をクリックします。ワイルドカードやカンマ区切りのリストは、ローカルファイルに対してはサポートされないことに注意してください。
- ファイル形式として、CSV、JSON（改行区切り）、Avro、Parquet または ORC を選択します。
[テーブルを作成] ページの [送信先] セクションで、次の操作を行います。
- [データセット名] で、該当するデータセットを選択します。
- [テーブル名] に、BigQuery で作成するテーブルの名前を入力します。
- [テーブルタイプ] が [ネイティブテーブル] に設定されていることを確認します。
[スキーマ] セクションにスキーマ定義を入力します。
- CSV や JSON ファイルの場合は、自動検出オプションをオンにしてスキーマの自動検出を有効にできます。スキーマ情報は、サポートされているその他のファイル形式のソースデータで自己記述されます。
- 次の方法でスキーマ情報を手動で入力することもできます。
  - [テキストとして編集] をクリックし、テーブルスキーマを JSON 配列として入力します。
    
    注: 既存のテーブルのスキーマを JSON 形式で表示するには、CLI コマンド bq show --format=prettyjson dataset.table を入力します。
  - [フィールドを追加] を使用して、スキーマを手動で入力します。
[詳細オプション] セクションで該当の項目を選択し、[テーブルを作成] をクリックします。使用可能なオプションについては、CSV のオプションと JSON のオプションをご覧ください。

従来の UI

BigQuery ウェブ UI に移動します。
BigQuery ウェブ UI に移動
ナビゲーションパネルで、データセットにカーソルを合わせて下矢印アイコンをクリックし、[Create new table] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。
[Create Table] ページの [Source Data] セクションで、次の操作を行います。
- [Location] で、[File upload] を選択して [Choose file] をクリックし、一覧からファイルを選択して [Open] をクリックします。ワイルドカードやカンマ区切りのリストは、ローカルファイルに対してはサポートされないことに注意してください。
- ファイル形式として、CSV、JSON（改行区切り）、Avro、Parquet または ORC を選択します。
[Create Table] ページの [Destination Table] セクションで、次の操作を行います。
- [Table name] で適切なデータセットを選択し、BigQuery で作成するテーブルの名前をテーブル名のフィールドに入力します。
- [Table type] が [Native table] に設定されていることを確認します。
[Schema] セクションでスキーマ定義を入力します。
- CSV や JSON ファイルの場合は、[Auto-detect] オプションをオンにしてスキーマの自動検出を有効にできます。スキーマ情報は、サポートされているその他のファイル形式のソースデータで自己記述されます。
- 次の方法でスキーマ情報を手動で入力することもできます。
  - [Edit as text] をクリックし、テーブルスキーマを JSON 配列として入力します。
    
    注: 既存のテーブルのスキーマを JSON 形式で表示するには、CLI コマンド bq show --format=prettyjson dataset.table を入力します。
  - [Add Field] を使用して、スキーマを手動で入力します。
[Options] セクションで該当する項目を選択し、[Create Table] をクリックします。使用可能なオプションについては、CSV のオプションと JSON のオプションをご覧ください。

CLI

bq load コマンドを使用して source_format を指定し、ローカルファイルへのパスも指定します。

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

デフォルトプロジェクト以外のプロジェクトのデータを読み込む場合は、project_id:dataset の形式でプロジェクト ID をデータセットに追加します。

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

ここで

location は、ロケーションです。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
format は、CSV、AVRO、PARQUET、ORC、NEWLINE_DELIMITED_JSON のいずれかです。
project_id はプロジェクト ID です。
dataset は、既存のデータセットです。
table は、データの読み込み先のテーブル名です。
path_to_source は、ローカルファイルへのパスです。
schema は、有効なスキーマです。スキーマはローカルの JSON ファイルにすることも、コマンドの一部としてインラインで入力することもできます。また、スキーマ定義を指定する代わりに、--autodetect フラグを使用することもできます。

その他にも、BigQuery によるデータの解析方法を制御するオプションに対応するフラグを追加できます。たとえば、--skip_leading_rows フラグを使用すると、CSV ファイル内のヘッダー行が無視されます。詳細については、CSV のオプションと JSON のオプションをご覧ください。

例:

次のコマンドは、改行区切りの JSON ファイル（mydata.json）を、ローカルマシンからデフォルトプロジェクトの mydataset 内にある mytable という名前のテーブルに読み込みます。スキーマは、myschema.json という名前のローカルスキーマファイルで定義されています。

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

次のコマンドは、CSV ファイル（mydata.csv）をローカルマシンから myotherproject の mydataset 内にある mytable という名前のテーブルに読み込みます。スキーマは、field:data_type, field:data_type の形式でインラインで定義されます。

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

次のコマンドは、CSV ファイル（mydata.csv）をローカルマシンからデフォルトプロジェクトの mydataset 内にある mytable という名前のテーブルに読み込みます。スキーマはスキーマ自動検出を使用して定義されます。

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

C#

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

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカルファイルを読み込むには、UploadCsvOptions の代わりに、JobCreationOptions 基本クラスから適切な形式のアップデートオプションクラスを選択します。

GitHub で表示フィードバック


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

public class BigQueryLoadFromFile
{
    public void LoadFromFile(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id",
        string filePath = "path/to/file.csv"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Create job configuration
        var uploadCsvOptions = new UploadCsvOptions()
        {
            SkipLeadingRows = 1,  // Skips the file headers
            Autodetect = true
        };
        using (FileStream stream = File.Open(filePath, FileMode.Open))
        {
            // Create and run job
            // Note that there are methods available for formats other than CSV
            BigQueryJob job = client.UploadCsv(
                datasetId, tableId, null, stream, uploadCsvOptions);
            job.PollUntilCompleted();  // Waits for the job to complete.
            // Display the number of rows uploaded
            BigQueryTable table = client.GetTable(datasetId, tableId);
            Console.WriteLine(
                $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
        }
    }
}

Go

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

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカルファイルを読み込むには、NewReaderSource の DataFormat プロパティを適切な形式に設定します。

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")
f, err := os.Open(filename)
if err != nil {
	return err
}
source := bigquery.NewReaderSource(f)
source.AutoDetect = true   // Allow BigQuery to determine schema.
source.SkipLeadingRows = 1 // CSV has a single header line.

loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)

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

Java

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

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカルファイルを読み込むには、FormatOptions を該当の形式に設定します。

GitHub で表示フィードバック

TableId tableId = TableId.of(datasetName, tableName);
WriteChannelConfiguration writeChannelConfiguration =
    WriteChannelConfiguration.newBuilder(tableId).setFormatOptions(FormatOptions.csv()).build();
// The location must be specified; other fields can be auto-detected.
JobId jobId = JobId.newBuilder().setLocation(location).build();
TableDataWriteChannel writer = bigquery.writer(jobId, writeChannelConfiguration);
// Write data to writer
try (OutputStream stream = Channels.newOutputStream(writer)) {
  Files.copy(csvPath, stream);
}
// Get load job
Job job = writer.getJob();
job = job.waitFor();
LoadStatistics stats = job.getStatistics();
return stats.getOutputRows();

Node.js

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

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカルファイルを読み込むには、load 関数の metadata パラメータを適切な形式に設定します。

GitHub で表示フィードバック

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

async function loadLocalFile() {
  // Imports a local file into a table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const filename = '/path/to/file.csv';
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(filename);

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

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカルファイルを読み込むには、sourceFormat を該当の形式に設定します。

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';
// $source     = 'The path to the CSV source file to import';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
// create the import job
$loadConfig = $table->load(fopen($source, 'r'))->sourceFormat('CSV');

$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    printf('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 のリファレンスドキュメントをご覧ください。

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカルファイルを読み込むには、LoadJobConfig.source_format プロパティを該当の形式に設定します。

GitHub で表示フィードバック

# from google.cloud import bigquery
# client = bigquery.Client()
# filename = '/path/to/file.csv'
# dataset_id = 'my_dataset'
# table_id = 'my_table'

dataset_ref = client.dataset(dataset_id)
table_ref = dataset_ref.table(table_id)
job_config = bigquery.LoadJobConfig()
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1
job_config.autodetect = True

with open(filename, "rb") as source_file:
    job = client.load_table_from_file(source_file, table_ref, job_config=job_config)

job.result()  # Waits for table load to complete.

print("Loaded {} rows into {}:{}.".format(job.output_rows, dataset_id, table_id))

Ruby

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

次のコードは、ローカル CSV ファイルを新しい BigQuery テーブルに読み込む方法を示しています。別の形式のローカルファイルを読み込むには、Table#load_job メソッドの format パラメータを適切な形式に設定します。

GitHub で表示フィードバック

require "google/cloud/bigquery"

def load_from_file(dataset_id = "your_dataset_id",
                   file_path  = "path/to/file.csv")

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "new_table_id"

  # Infer the config.location based on the location of the referenced dataset.
  load_job = dataset.load_job table_id, file_path do |config|
    config.skip_leading = 1
    config.autodetect   = true
  end
  load_job.wait_until_done! # Waits for table load to complete.

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows into #{table.id}"
end

ローカルファイルを使用してテーブルに追加または上書きする

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

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

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

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

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

Console のオプション	従来の UI のオプション	CLI のフラグ	BigQuery API のプロパティ	説明
空の場合は書き込む	空の場合は書き込む	なし	WRITE_EMPTY	テーブルが空の場合にのみデータを書き込みます。
テーブルに追加する	テーブルに追加する	`--noreplace` または `--replace=false`（`--replace` を指定しない場合、デフォルトは追加）	WRITE_APPEND	（デフォルト）テーブルの末尾にデータを追加します。
テーブルを上書きする	テーブルを上書きする	`--replace` または `--replace=true`	WRITE_TRUNCATE	新しいデータを書き込む前に、テーブル内の既存のデータをすべて消去します。

CSV、JSON、Avro、Parquet、ORC のデータをローカルファイルから読み込んで BigQuery のテーブルに追加またはテーブルを上書きするには、次の操作を行います。

Console

GCP Console で BigQuery ウェブ UI を開きます。
GCP Console に移動する
ナビゲーションパネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。
ウィンドウの右側の詳細パネルで、[テーブルを作成] をクリックします。データを読み込むプロセスは、空のテーブルを作成するプロセスと同じです。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
- [テーブルの作成元] で [アップロード] を選択します。
- [ファイルを選択] の下の [参照] をクリックします。
- 一覧からファイルを選択して [開く] をクリックします。ワイルドカードやカンマ区切りのリストは、ローカルファイルに対してはサポートされないことに注意してください。
- ファイル形式として、CSV、JSON（改行区切り）、Avro、Parquet または ORC を選択します。
[テーブルを作成] ページの [送信先] セクションで、次の操作を行います。
- [データセット名] で、該当するデータセットを選択します。
- [テーブル名] に、BigQuery で作成するテーブルの名前を入力します。
- [テーブルタイプ] が [ネイティブテーブル] に設定されていることを確認します。
[スキーマ] セクションにスキーマ定義を入力します。
- CSV や JSON ファイルの場合は、自動検出オプションをオンにしてスキーマの自動検出を有効にできます。スキーマ情報は、サポートされているその他のファイル形式のソースデータで自己記述されます。
- 次の方法でスキーマ情報を手動で入力することもできます。
  - [テキストとして編集] をクリックし、テーブルスキーマを JSON 配列として入力します。
    
    注: 既存のテーブルのスキーマを JSON 形式で表示するには、CLI コマンド bq show --format=prettyjson dataset.table を入力します。
  - [フィールドを追加] を使用して、スキーマを手動で入力します。
[詳細オプション] セクションの [書き込み設定] で、[空の場合に書き込む]、[テーブルに追加する]、または [テーブルを上書きする] を選択します。
[テーブルを作成] をクリックします。

従来の UI

[Create Table] ページの [Source Data] セクションで、次の操作を行います。
- [Location] で、[File upload] を選択して [Choose file] をクリックし、一覧からファイルを選択して [Open] をクリックします。ワイルドカードやカンマ区切りのリストは、ローカルファイルに対してはサポートされないことに注意してください。
- ファイル形式として、CSV、JSON（改行区切り）、Avro、Parquet または ORC を選択します。
[Create Table] ページの [Destination Table] セクションで、次の操作を行います。
- [Table name] で適切なデータセットを選択し、追加または上書きするテーブルの名前をテーブル名のフィールドに入力します。
- [Table type] が [Native table] に設定されていることを確認します。
[Schema] セクションにスキーマ定義を入力します。スキーマを更新する場合は、新しいフィールドを追加できます。また、フィールドのモードを REQUIRED から NULLABLE に変更（緩和）することもできます。
- JSON ファイルの場合、[Auto-detect] オプションをオンにしてスキーマの自動検出を有効にできます。
- 次の方法でスキーマ情報を手動で入力することもできます。
  - [Edit as text] をクリックし、テーブルスキーマを JSON 配列として入力します。
    
    注: 既存のテーブルのスキーマを JSON 形式で表示するには、CLI コマンド bq show --format=prettyjson dataset.table を入力します。
  - [Add Field] を使用して、スキーマを手動で入力します。
[Options] セクションの [Write preference] で、[Write if empty]、[Append to table]、または [Overwrite table] を選択します。
[Create Table] をクリックします。

CLI

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

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

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

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

bq --location=location load \
--[no]replace \
dataset.table \
path_to_source \
schema

ここで

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

さらに、データがどのように解析されるかを制御する JSON のオプションまたは CSV のオプションに対応するフラグも追加できます。

例:

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

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

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

    bq load \
    --autodetect \
    --noreplace \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    ./mydata.json \
    ./myschema.json

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

    bq load \
    --noreplace \
    --schema_update_option=ALLOW_FIELD_ADDITION \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    ./mydata.json \
    ./myschema.json

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

    bq load \
    --noreplace \
    --schema_update_option=ALLOW_FIELD_RELAXATION \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    ./mydata.csv \
    ./myschema.json

API アップロード

メディアアップロード機能により、BigQuery API でクラウドにデータを保存し、サーバーで利用できるようになります。写真、動画、PDF ファイル、zip ファイルなど、さまざまな形式のデータをアップロードできます。

アップロードオプション

BigQuery API を使用して、特定の種類のバイナリデータまたはメディアをアップロードできます。アップロードできるデータの性質については、メディアアップロードをサポートするメソッドのリファレンスページをご覧ください。

最大アップロードファイルサイズ: このメソッドで保存できるデータの最大量。
受け入れ可能なメディア MIME タイプ: このメソッドで保存できるバイナリデータの種類。

アップロードは、次のいずれかの方法でリクエストできます。使用するメソッドは、uploadType リクエストパラメータで指定します。

マルチパートアップロード: uploadType=multipart。比較的小さいファイルとメタデータを高速転送します。ファイルおよびそれを記述するメタデータが、1 つのリクエストですべて転送されます。
再開可能なアップロード: uploadType=resumable。信頼性の高い転送で、特に、比較的大きいファイルで使用されます。このメソッドでは、セッション開始リクエストを使用します。オプションでメタデータを含めることができます。この方法は、小さいファイルでも機能し、コストについてはアップロードごとに HTTP リクエストが 1 つ追加されるだけなので、ほとんどのアプリケーションでの使用に適しています。

メディアをアップロードするときは、特別な URI を使用します。具体的には、メディアアップロードをサポートするメソッドには次の 2 種類の URI エンドポイントがあります。

/upload URI。メディアに使用されます。アップロードエンドポイントの形式は、標準リソース URI に「/upload」接頭辞を付けたものです。この URI は、メディアデータそのものを転送するときに使用します。例: POST /upload/bigquery/v2/projects/projectId/jobs
メタデータの場合、標準リソース URI。リソースにデータフィールドが含まれている場合、これらのフィールドは、アップロードするファイルを記述するメタデータの保管に使用されます。この URI は、メタデータ値の作成または更新の際に使用できます。例: POST /bigquery/v2/projects/projectId/jobs

マルチパートアップロード

アップロードするデータとともにメタデータを送信する場合は、1 つの multipart/related リクエストを作成できます。これは、送信するデータが小さく、接続が失敗しても全体を再アップロードできる場合に適しています。

マルチパートアップロードを使用するには、メソッドの /upload URI に対する POST リクエストを行い、クエリパラメータ uploadType=multipart を追加します。次に例を示します。

POST https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=multipart

マルチパートアップロードリクエストを作成するときに使用する最上位 HTTP ヘッダーには、以下を含めます。

Content-Type。multipart/related に設定し、リクエストの各部分の識別に使用する境界文字列を含めます。
Content-Length。リクエスト本文の合計バイト数を設定します。リクエストのメディア部分は、このメソッドに対して指定された最大ファイルサイズより小さくなければなりません。

リクエスト本文の形式は multipart/related コンテンツタイプ [RFC2387] となり、必ず 2 つの部分が含まれます。各部分は境界文字列で区別され、最後の境界文字列には後に 2 つのハイフンが続きます。

マルチパートリクエストの各部分には、次の Content-Type ヘッダーを追加する必要があります。

メタデータ部分: 最初に配置する必要があります。Content-Type は、受け入れ可能なメタデータ形式のいずれかと一致する必要があります。
メディア部分: 2 番目に配置する必要があります。Content-Type は、メソッドの受け入れ可能なメディア MIME タイプのいずれかと一致する必要があります。

各メソッドで使用できるメディア MIME タイプと、アップロードできるファイルのサイズの上限については、API リファレンスをご覧ください。

注: 関連付けられたデータをアップロードせずに、メタデータ部分のみを生成または更新するには、単に POST または PUT リクエストを標準リソースエンドポイント（https://www.googleapis.com/bigquery/v2/projects/projectId/jobs）に送信します。

例: マルチパートアップロード

次の例は、BigQuery API に対するマルチパートアップロードリクエストを示します。

POST /upload/bigquery/v2/projects/projectId/jobs?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "configuration": {
    "load": {
      "sourceFormat": "NEWLINE_DELIMITED_JSON",
      "schema": {
        "fields": [
          {"name": "f1", "type": "STRING"},
          {"name": "f2", "type": "INTEGER"}
        ]
      },
      "destinationTable": {
        "projectId": "projectId",
        "datasetId": "datasetId",
        "tableId": "tableId"
      }
    }
  }
}

--foo_bar_baz
Content-Type: */*

CSV, JSON, AVRO, PARQUET, or ORC data
--foo_bar_baz--

リクエストが成功すると、HTTP 200 OK ステータスコードとメタデータがサーバーから返されます。

HTTP/1.1 200
Content-Type: application/json

{
  "configuration": {
    "load": {
      "sourceFormat": "NEWLINE_DELIMITED_JSON",
      "schema": {
        "fields": [
          {"name": "f1", "type": "STRING"},
          {"name": "f2", "type": "INTEGER"}
        ]
      },
      "destinationTable": {
        "projectId": "projectId",
        "datasetId": "datasetId",
        "tableId": "tableId"
      }
    }
  }
}

再開可能なアップロード

より信頼性の高い方法でデータファイルをアップロードするには、再開可能なアップロードプロトコルを使用します。このプロトコルを使用すると、通信障害によってデータのフローが中断しても、その後アップロードオペレーションを再開できます。この方法は特に、大容量のファイルを転送するときや、モバイルクライアントアプリからのアップロードなどでネットワークの中断やその他の送信エラーが起こる可能性が高いときに役立ちます。また、ネットワーク障害が発生した場合に大容量のファイルのアップロードを最初からやり直す必要がなくなり、使用する帯域幅を削減できます。

再開可能なアップロードを使用する手順は、以下のとおりです。

再開可能なセッションを開始します。アップロード URI（メタデータがある場合は、メタデータを含むアップロード URI）に対する最初のリクエストを作成します。
再開可能なセッション URI を保存します。最初のリクエストのレスポンスで返されるセッション URI を保存します。この URI をこのセッションの他のリクエストで使用します。
ファイルをアップロードします。再開可能なセッション URI にメディアファイルを送信します。

また、再開可能なアップロードを使用するアプリには、中断したアップロードを再開するためのコードが必要です。アップロードが中断した場合、正常に受信されたデータの量を判別し、そのポイントからアップロードを再開します。

注: アップロード URI の有効期間は 1 週間です。

手順 1: 再開可能なセッションを開始する

再開可能なアップロードを開始するには、メソッドの /upload URI に対する POST リクエストを行い、クエリパラメータ uploadType=resumable を追加します。次に例を示します。

POST https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable

この開始リクエストでは本文が空であるか、メタデータのみが含まれています。アップロードするファイルの実際の内容は、後続のリクエストで転送します。

最初のリクエストでは、次の HTTP ヘッダーを使用します。

X-Upload-Content-Type。後続のリクエストで転送するアップロードデータのメディア MIME タイプを設定します。
X-Upload-Content-Length。後続のリクエストで転送するアップロードデータのバイト数を設定します。このリクエストの時点で長さが不明な場合は、このヘッダーを省略できます。
メタデータを提供する場合: Content-Type。メタデータのデータ型に応じて設定します。
Content-Length。最初のリクエストの本文で提供するバイト数を設定します。チャンク形式転送エンコーディングを使用する場合は不要です。

各メソッドで使用できるメディア MIME タイプと、アップロードできるファイルのサイズの上限については、API リファレンスをご覧ください。

例: 再開可能なセッション開始リクエスト

次の例は、BigQuery API の再開可能なセッションを開始する方法を示しています。

POST /upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: */*
X-Upload-Content-Length: 2000000

{
  "configuration": {
    "load": {
      "sourceFormat": "NEWLINE_DELIMITED_JSON",
      "schema": {
        "fields": [
          {"name": "f1", "type": "STRING"},
          {"name": "f2", "type": "INTEGER"}
        ]
      },
      "destinationTable": {
        "projectId": "projectId",
        "datasetId": "datasetId",
        "tableId": "tableId"
      }
    }
  }
}

注: 最初の再開可能な更新リクエストをメタデータなしで発行する場合は、リクエスト本文を空のままにして、Content-Length ヘッダーを 0 に設定します。

次に、レスポンスを処理する方法を説明します。

手順 2：再開可能なセッション URI を保存する

セッション開始リクエストが成功すると、API サーバーは HTTP ステータスコード 200 OK のレスポンスを返します。また、再開可能なセッション URI を指定した Location ヘッダーも返します。下の例に示されている Location ヘッダーには、このセッションで使用する一意のアップロード ID を指定した upload_id クエリパラメータ部分が含まれています。

例: 再開可能なセッション開始のレスポンス

手順 1 のリクエストに対するレスポンスは次のとおりです。

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

上のレスポンス例に示されている Location ヘッダーの値は、実際にファイルをアップロードするとき、またはアップロードステータスを照会するときに HTTP エンドポイントとして使用するセッション URI です。

後続のリクエストで使用できるように、このセッション URI をコピーして保存します。

手順 3: ファイルをアップロードする

ファイルをアップロードするには、前の手順で取得したアップロード URI に PUT リクエストを送信します。アップロードリクエストの形式は次のとおりです。

PUT session_uri

再開可能なファイルアップロードのリクエストを作成するときに使用する HTTP ヘッダーには、Content-Length を含めます。このフィールドに、このリクエストでアップロードするバイト数（通常はアップロードファイルのサイズ）を設定します。

例: 再開可能なファイルアップロードリクエスト

現在の例で、全体で 2,000,000 バイトの CSV、JSON、AVRO、PARQUET または ORC のファイルをアップロードする再開可能なリクエストを以下に示します。

PUT https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: */*

bytes 0-1999999

リクエストが成功すると、サーバーは HTTP 201 Created のレスポンスを、このリソースに関連付けられているメタデータとともに返します。再開可能なセッションの最初のリクエストが PUT だった場合、既存のリソースを更新したときの成功のレスポンスは 200 OK となり、このリソースに関連付けられているメタデータが返されます。

アップロードリクエストが中断された場合や、サーバーから HTTP 503 Service Unavailable などの 5xx レスポンスが返された場合は、中断されたアップロードを再開するに記載された手順に従ってください。

チャンク形式でファイルをアップロードする

再開可能なアップロードでは、ファイルをチャンクに分割して、各チャンクを順にアップロードする一連のリクエストを送信できます。追加のリクエストに付随してパフォーマンスコストが発生するため、この方法は推奨されず、通常は不要です。ただし、1 つのリクエストで転送するデータの量を減らすために、チャンクの使用が必要になることもあります。Google App Engine リクエストの一部のクラスのように、リクエストごとに固定の時間制限がある場合は、この方法が役立ちます。また、たとえばデフォルトでアップロードの進捗表示をサポートしていない古いブラウザに、アップロードの進捗インジケーターを表示することもできます。

展開して詳細を表示

データをチャンク形式でアップロードする場合は、ファイル全体のアップロードに必要な Content-Length ヘッダーに加えて、Content-Range ヘッダーも必要です。

Content-Length。チャンクサイズを設定します。最後のリクエストでは、チャンクサイズより小さい値になることがあります。
Content-Range: ファイルの何バイト目から何バイト目までをアップロードするかを設定します。たとえば、Content-Range: bytes 0-524287/2000000 は、2,000,000 バイトのファイルで先頭の 524,288 バイト（256 x 1,024 x 2）をアップロードすることを意味します。

チャンクサイズの制限: 最後にアップロードするチャンクを除き、チャンクのサイズはすべて、256 KB（256 x 1,024 バイト）の倍数にする必要があります。チャンクを使用する場合は、効率的にアップロードするために、チャンクサイズをできるだけ大きくすることが重要です。

例: 再開可能なチャンク形式のファイルアップロードリクエスト

先頭の 524,288 バイトを送信するリクエストは次のようになります。

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: */*
Content-Range: bytes 0-524287/2000000

bytes 0-524288

リクエストが成功すると、サーバーは 308 Resume Incomplete のレスポンスとともに、その時点までに格納された合計バイト数を示す Range ヘッダーを返します。

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

Range ヘッダーで返された上限値を使用して、次のチャンクの開始位置を決定します。ファイル全体のアップロードが完了するまで、ファイルの各チャンクの PUT を続行します。

チャンクの PUT リクエストが中断された場合や、サーバーから HTTP 503 Service Unavailable などの 5xx レスポンスが返された場合は、中断されたアップロードを再開するに記載された手順に従ってください。ただし、ファイルの残りをアップロードするのではなく、中断した位置からチャンクのアップロードを続行します。

注意事項

次のチャンクの開始位置は、必ずレスポンスの Range ヘッダーを使用して決定してください。前のリクエストで送信したすべてのバイトをサーバーが受信しているとは限りません。
アップロード URI にはそれぞれ有効期限があり、いつかは期限切れになります（使用しない場合は約 1 日です）。そのため、アップロード URI を取得したらすぐに再開可能なアップロードを開始し、中断が発生したらすぐにそのアップロードを再開することをおすすめします。
有効期限が切れたアップロードセッション ID を使用してリクエストを送信すると、サーバーからステータスコード 404 Not Found が返されます。この場合は、再開可能なアップロードを新たに開始して新しいアップロード URI を取得し、新しいエンドポイントを使用してアップロードを最初からやり直す必要があります。

ファイル全体のアップロードが完了すると、サーバーは HTTP 201 Created のレスポンスとともに、このリソースに関連付けられているメタデータを返します。このリクエストが新しいエンティティの作成ではなく既存のエンティティの更新リクエストであった場合、完了したアップロードの HTTP レスポンスコードは 200 OK になります。

中断されたアップロードを再開する

レスポンスを受信する前にアップロードリクエストが終了した場合や、サーバーから HTTP 503 Service Unavailable レスポンスが返された場合は、中断されたアップロードを再開する必要があります。方法は次のとおりです。

ステータスをリクエストする。空の PUT リクエストをアップロード URI に発行して、アップロードの現在のステータスを照会します。このリクエストの HTTP ヘッダーには、ファイルの現在の位置が不明であることを示す Content-Range ヘッダーを含める必要があります。たとえば、ファイルの合計サイズが 2,000,000 の場合、Content-Range を */2000000 に設定します。ファイル全体のサイズがわからない場合は、Content-Range を */* に設定します。
注: アップロードが中断された場合でなくても、チャンク間のステータスをリクエストできます。これは、たとえば古いブラウザにアップロードの進捗インジケーターを表示する場合に役立ちます。
アップロードされたバイト数を取得する。ステータスクエリからのレスポンスを処理します。サーバーはレスポンスの Range ヘッダーを使用して、その時点までに何バイト受信したかを示します。たとえば、Range ヘッダーが 0-299999 の場合、ファイルの先頭から 300,000 バイトを受信したという意味になります。
残りのデータをアップロードする。最後に、リクエストを再開する位置を確認して、残りのデータまたは現在のチャンクを送信します。どちらの場合も、残りのデータは独立したチャンクとして扱う必要があります。つまり、アップロードを再開するときに Content-Range ヘッダーを送信する必要があります。

例: 中断されたアップロードを再開する

1）アップロードステータスをリクエストします。

次のリクエストでは、Content-Range ヘッダーを使用して、2,000,000 バイトのファイルで現在の位置が不明であることを示しています。

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2）レスポンスから、これまでにアップロードされたバイト数を抽出します。

サーバーのレスポンスの Range ヘッダーは、これまでにファイルの先頭の 43 バイトを受信したことを示しています。Range ヘッダーの上限値を使用して、再開可能なアップロードを開始する位置を決定します。

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

注: アップロードが完了している場合、ステータスのレスポンスが201 Created または 200 OK になることがあります。このような状況は、すべてのバイトがアップロードされた後、クライアントがサーバーからレスポンスを受信する前に接続が切断された場合に発生します。

3）中断された位置からアップロードを再開します。

次のリクエストは、ファイルの 43 番目以降の残りのバイトを送信して、アップロードを再開します。

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

データをローカルデータソースから読み込む

概要

制限事項

必要な権限