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

このページでは、Cloud Storage から BigQuery への ORC データの読み込みの概要を説明します。

ORC は、Apache Hadoop エコシステムで広く使用されているオープンソースの列指向のデータ形式です。

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

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

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

ORC スキーマ

ORC ファイルを BigQuery に読み込むと、自己記述型ソースデータから自動的にテーブルスキーマが取得されます。BigQuery がソースデータからスキーマを取得する際は、アルファベット順で最後のファイルが使用されます。

たとえば、Cloud Storage に次の ORC ファイルがあるとします。

gs://mybucket/00/
  a.orc
  z.orc
gs://mybucket/01/
  b.orc

bq コマンドラインツールでこのコマンドを実行すると、すべてのファイルがカンマ区切りのリストとして読み込まれ、mybucket/01/b.orc からスキーマが取得されます。

bq load \
--source_format=ORC \
dataset.table \
"gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"

BigQuery がスキーマを検出すると、一部の ORC データ型は、BigQuery SQL 構文に対応するように BigQuery データ型に変換されます。検出されたスキーマに含まれるフィールドはすべて NULLABLE です。詳細については、ORC 変換をご覧ください。

スキーマが異なる複数の ORC ファイルを読み込む場合、複数のスキーマで指定された同一のフィールド（名前とネストレベルが同じ）は、各スキーマ定義の同じ変換済み BigQuery データ型にマッピングする必要があります。

ORC 圧縮

BigQuery は、ORC ファイルの内容に対して次のタイプの圧縮をサポートします。

Zlib
Snappy
LZO
LZ4

必要な権限

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

BigQuery の権限

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

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

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

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

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

bigquery.user
bigquery.jobUser
bigquery.admin

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

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

Cloud Storage の権限

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

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

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

新しいテーブルに ORC データを読み込むには、次の方法を使用します。

Cloud Console を使用する
bq コマンドラインツールの bq load コマンドを使用する
jobs.insert API メソッドを呼び出して load ジョブを構成する
クライアントライブラリを使用する

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

Console

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

[BigQuery] ページに移動
[エクスプローラ] パネルでプロジェクトを展開し、データセットを選択します。

注: デフォルトでは、プレビューリリースの Cloud Console が表示されます。[PREVIEW 機能を非表示] をクリックして一般提供の Cloud Console に移動した場合は、ナビゲーションパネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。
詳細パネルで「テーブルを作成」をクリックします。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
- [テーブルの作成元] で [Cloud Storage] を選択します。
- ソースフィールドで Cloud Storage URI を参照するかまたは入力します。Cloud Console で複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在する必要があります。
- [ファイル形式] で、[ORC] を選択します。
[テーブルを作成] ページの [送信先] セクションで、次の操作を行います。
- [データセット名] で、該当するデータセットを選択します。
- [テーブルタイプ] が [ネイティブテーブル] に設定されていることを確認します。
- [テーブル名] フィールドに、BigQuery で作成するテーブルの名前を入力します。
[スキーマ] セクションでは、何もする必要はありません。スキーマは ORC ファイルで自己記述されます。
（省略可）テーブルをパーティション分割するには、[パーティションとクラスタの設定] で次のオプションを選択します。
- パーティション分割テーブルを作成するには、[パーティショニングなし] をクリックして [フィールドにより分割] を選択し、DATE または TIMESTAMP の列を選択します。スキーマに DATE または TIMESTAMP の列が含まれていない場合、このオプションは使用できません。
- 取り込み時間パーティション分割テーブルを作成するには、[パーティショニングなし] をクリックして [取り込み時間により分割] を選択します。
（省略可）クエリを実行するパーティションを指定する WHERE 句の使用を必須にするには、[パーティショニングフィルタ] で [パーティションフィルタを要求] ボックスをクリックします。パーティションフィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。[パーティショニングなし] を選択している場合、このオプションは使用できません。
（省略可）テーブルをクラスタ化するには、[クラスタリング順序] ボックスに 1～4 個のフィールド名を入力します。
（省略可）[詳細オプション] をクリックします。
- [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
- [許可されているエラー数] で、デフォルト値の 0 を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブは invalid メッセージとなり、失敗します。
- [不明な値] で [不明な値を無視する] をオフのままにします。このオプションは、CSV ファイルと JSON ファイルにのみ適用されます。
- Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] をクリックします。[Google が管理する鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
[テーブルを作成] をクリックします。

bq

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

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

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

--max_bad_records: ジョブ全体が失敗する前に許容される不良レコードの最大数を指定する整数。デフォルト値は 0 です。--max_bad_records の値にかかわらず、最大で 5 つの任意のタイプのエラーが返されます。
--time_partitioning_type: テーブルでの時間ベースのパーティショニングを有効にし、パーティションタイプを設定します。有効な値は HOUR、DAY、MONTH、YEAR です。DATE、DATETIME、TIMESTAMP 列でパーティション分割されたテーブルを作成する場合、このフラグは省略可能です。時間ベースのパーティショニングのデフォルトパーティションタイプは DAY です。
--time_partitioning_expiration: 時間ベースのパーティションを削除する必要があるタイミングを指定する整数（秒単位）。パーティションの日付（UTC）に、この整数値を足した値が有効期限になります。
--time_partitioning_field: パーティション分割テーブルの作成に使用される DATE または TIMESTAMP の列。この値を指定せずに時間ベースのパーティショニングを有効にすると、取り込み時間パーティション分割テーブルが作成されます。
--require_partition_filter: 有効にすると、クエリの実行時に WHERE 句でパーティションを指定するようユーザーに求めます。パーティションフィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。
--clustering_fields: クラスタ化テーブルの作成に使用する列名のカンマ区切りのリスト。最大 4 個の列名を指定できます。
--destination_kms_key: テーブルデータの暗号化に使用される Cloud KMS 鍵。

パーティション分割テーブルの詳細については、以下をご覧ください。
- パーティション分割テーブルの作成と使用
- 取り込み時間パーティション分割テーブルの作成と使用
クラスタ化テーブルの詳細については、以下をご覧ください。
- クラスタ化テーブルの作成と使用
テーブルの暗号化の詳細については、以下をご覧ください。
- Cloud KMS 鍵によるデータの保護

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

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

ここで

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

例:

次のコマンドは、gs://mybucket/mydata.orc から、mydataset 内の mytable というテーブルにデータを読み込みます。

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

次のコマンドは、gs://mybucket/mydata.orc から mydataset 内の mytable という取り込み時間パーティション分割テーブルにデータを読み込みます。

    bq load \
    --source_format=ORC \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.orc

次のコマンドは、gs://mybucket/mydata.orc からデータを読み込んで mydataset 内の mytable というパーティション分割テーブルに追加します。テーブルは mytimestamp 列でパーティション分割されます。

    bq load \
    --source_format=ORC \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata*.orc

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

    bq load --autodetect \
    --source_format=ORC \
    mydataset.mytable \
    "gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"

API

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

GitHub で表示フィードバック


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

public class BigQueryLoadTableGcsOrc
{
    public void LoadTableGcsOrc(
        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.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null,
            options: jobOptions
        );
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Go

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

GitHub で表示フィードバック

import (
	"context"
	"fmt"

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

// importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table.
func importORC(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.orc")
	gcsRef.SourceFormat = bigquery.ORC
	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())
	}
	return nil
}

Java

GitHub で表示

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

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

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

  public static void loadOrcFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

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

      // Load data from a GCS ORC 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() && job.getStatus().getError() == null) {
        System.out.println("ORC 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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

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

async function loadTableGCSORC() {
  // Imports a GCS file into a table with ORC source format.

  /**
   * TODO(developer): Uncomment the following line 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: 'ORC',
    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 のリファレンスドキュメントをご覧ください。

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

GitHub で表示フィードバック

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(source_format=bigquery.SourceFormat.ORC)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

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

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

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

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

GitHub で表示フィードバック

require "google/cloud/bigquery"

def load_table_gcs_orc 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.orc"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, format: "orc"
  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

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

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

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

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

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

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

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

Cloud Console を使用する
bq コマンドラインツールの bq load コマンドを使用する
jobs.insert API メソッドを呼び出して load ジョブを構成する
クライアントライブラリを使用する

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

Console

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

[BigQuery] ページに移動
[エクスプローラ] パネルでプロジェクトを展開し、データセットを選択します。

注: デフォルトでは、プレビューリリースの Cloud Console が表示されます。[PREVIEW 機能を非表示] をクリックして一般提供の Cloud Console に移動した場合は、ナビゲーションパネルの [リソース] セクションでプロジェクトを展開し、データセットを選択します。
詳細パネルで「テーブルを作成」をクリックします。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
- [テーブルの作成元] で [Cloud Storage] を選択します。
- ソースフィールドで Cloud Storage URI を参照するかまたは入力します。Cloud Console で複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、データを追加または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
- [ファイル形式] で、[ORC] を選択します。
[テーブルを作成] ページの [送信先] セクションで、次の操作を行います。
- [データセット名] で、該当するデータセットを選択します。
- [テーブル名] フィールドに、BigQuery で追加または上書きするテーブルの名前を入力します。
- [テーブルタイプ] が [ネイティブテーブル] に設定されていることを確認します。
[Schema] セクションでは、何もする必要はありません。スキーマは ORC ファイルで自己記述されます。

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

bq

テーブルを上書きするには、--replace フラグを指定して bq load コマンドを入力します。テーブルにデータを追加するには、--noreplace フラグを使用します。フラグを指定しない場合、デフォルトではデータが追加されます。--source_format フラグを指定し、ORC に設定します。ORC スキーマは自己記述型ソースデータから自動的に取得されるため、スキーマ定義を指定する必要はありません。

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

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

--max_bad_records: ジョブ全体が失敗する前に許容される不良レコードの最大数を指定する整数。デフォルト値は 0 です。--max_bad_records の値にかかわらず、最大で 5 つの任意のタイプのエラーが返されます。
--destination_kms_key: テーブルデータの暗号化に使用される Cloud KMS 鍵。

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

ここで

location はロケーションです。--location フラグは省略可能です。ロケーションのデフォルト値は、.bigqueryrc ファイルを使用して設定できます。
format は ORC です。
dataset は既存のデータセットです。
table は、データの読み込み先のテーブル名です。
path_to_source は、完全修飾の Cloud Storage URI または URI のカンマ区切りのリストです。ワイルドカードもサポートされます。

例:

次のコマンドは、gs://mybucket/mydata.orc からデータを読み込んで mydataset 内の mytable というテーブルを上書きします。

    bq load \
    --replace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

次のコマンドは、gs://mybucket/mydata.orc からデータを読み込んで mydataset 内の mytable というテーブルに追加します。

    bq load \
    --noreplace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

bq コマンドラインツールでパーティション分割テーブルへの追加や上書きを行う方法については、パーティション分割テーブルデータの追加と上書きをご覧ください。

API

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

C#

GitHub で表示フィードバック


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

public class BigQueryLoadTableGcsOrcTruncate
{
    public void LoadTableGcsOrcTruncate(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc,
            WriteDisposition = WriteDisposition.WriteTruncate
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null, options: jobOptions);
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Go

GitHub で表示フィードバック

import (
	"context"
	"fmt"

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

// importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importORCTruncate(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.orc")
	gcsRef.SourceFormat = bigquery.ORC
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	// Default for import jobs is to append data to a table.  WriteTruncate
	// specifies that existing data should instead be replaced/overwritten.
	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

GitHub で表示

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.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

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

  public static void runLoadOrcFromGcsTruncate() {
    // 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.orc";
    loadOrcFromGcsTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadOrcFromGcsTruncate(
      String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.orc())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS ORC 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() && job.getStatus().getError() == null) {
        System.out.println("Table is successfully overwritten by ORC file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

GitHub で表示フィードバック

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

// Instantiate the 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.orc';

async function loadORCFromGCSTruncate() {
  /**
   * 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: 'ORC',
    // 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;
  }
}

PHP

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.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC')->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

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

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

Python

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

GitHub で表示フィードバック

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.ORC,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

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

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

GitHub で表示フィードバック

require "google/cloud/bigquery"

def load_table_gcs_orc_truncate dataset_id = "your_dataset_id",
                                table_id   = "your_table_id"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

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

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

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

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

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

ORC 変換

BigQuery は ORC のデータ型を次の BigQuery データ型に変換します。

プリミティブ型

ORC のデータ型	BigQuery のデータ型	注
boolean	BOOLEAN
byte	INTEGER
short	INTEGER
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
string	STRING	UTF-8 のみ
varchar	STRING	UTF-8 のみ
char	STRING	UTF-8 のみ
binary	BYTES
date	DATE
timestamp	TIMESTAMP	ORC はナノ秒単位の精度をサポートしますが、BigQuery はデータを読み取るときにマイクロ秒未満の値をマイクロ秒に変換します。
decimal	NUMERIC、BIGNUMERIC、または STRING	固定小数点型をご覧ください。

固定小数点型

Decimal 論理型は、NUMERIC、BIGNUMERIC（プレビュー）、または STRING 型に変換できます。変換される型は、decimal 論理型の精度とスケールのパラメータ、また指定されたターゲットの固定小数点型によって異なります。ターゲットの固定小数点型は次のように指定します。

jobs.insert API を使用する読み込みジョブの場合: JobConfigurationLoad.decimalTargetTypes フィールドを使用します。
bq コマンドラインツールで bq load コマンドを使用する読み込みジョブの場合: --decimal_target_types フラグを使用します。
外部ソースを含むテーブルに対するクエリの場合: ExternalDataConfiguration.decimalTargetTypes フィールドを使用します。
DDL で作成した永続外部テーブルの場合: decimal_target_types オプションを使用します。

複合型

ORC のデータ型	BigQuery のデータ型	注
struct	RECORD	すべてのフィールドは NULLABLE です。フィールドの順序は無視されます。フィールドの名前は有効な列名にする必要があります。
map<K,V>	RECORD	ORC の map<K,V> フィールドは、2 つのフィールド（K と同じデータ型のキー、V と同じデータ型の値）を含む、繰り返し RECORD に変換されます。両方のフィールドが NULLABLE です。
list	繰り返しフィールド	ネストされたリストとマップのリストはサポートされていません。
union	RECORD	union に 1 つのバリアントしかない場合は、NULLABLE フィールドに変換されます。それ以外の場合は、union は NULLABLE フィールドのリストを持つ RECORD に変換されます。NULLABLE フィールドには、field_0、field_1 などの接尾辞が付きます。データを読み取るときに、このようなフィールドの 1 つのみに値が割り当てられます。

列名

列名には、英字（a-z、A-Z）、数字（0-9）、アンダースコア（_）のみを使用できます。先頭文字は英字またはアンダースコアにする必要があります。列名の最大長は 128 文字です。列名には、次のいずれの接頭辞も使用できません。

_TABLE_
_FILE_
_PARTITION

大文字と小文字が異なっている場合でも、重複する列名は使用できません。たとえば、Column1 という列は column1 という列と同じとみなされます。

`NULL` 値

BigQuery は読み込みジョブで list 複合型の NULL 要素を無視します。理由は、無視されずに NULL ARRAY 要素に変換されるとテーブルに存続できなくなるからです（詳細はデータ型をご覧ください）。

ORC のデータ型の詳細については、Apache ORC™ Specification v1 をご覧ください。

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

ORC スキーマ

ORC 圧縮

必要な権限

BigQuery の権限

Cloud Storage の権限

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

Console

bq

API

C#

Go

Java

Node.js

PHP

Python

Ruby

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

Console

bq

API

C#

Go

Java

Node.js

PHP

Python

Ruby

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

ORC 変換

プリミティブ型

固定小数点型

複合型

列名

NULL 値

`NULL` 値