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

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

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

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

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

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

制限事項

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

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

始める前に

このドキュメントの各タスクを行うのに必要な権限をユーザーに与える Identity and Access Management（IAM）ロールを付与し、データを保存するためのデータセットを作成します。

必要な権限

BigQuery にデータを読み込むには、読み込みジョブを実行してデータを BigQuery のテーブルとパーティションに読み込む IAM 権限が必要です。Cloud Storage からデータを読み込む場合は、データを含むバケットに対する IAM アクセス権限も必要です。

BigQuery にデータを読み込む権限

新しい BigQuery テーブルやパーティションにデータを読み込む場合、または既存のテーブルやパーティションにデータの追加や上書きを行う場合は、次の IAM 権限が必要です。

• bigquery.tables.create
• bigquery.tables.updateData
• bigquery.tables.update
• bigquery.jobs.create

以下の各事前定義 IAM ロールには、BigQuery テーブルやパーティションにデータを読み込むために必要な権限が含まれています。

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin（bigquery.jobs.create 権限を含む）
• bigquery.user（bigquery.jobs.create 権限を含む）
• bigquery.jobUser（bigquery.jobs.create 権限を含む）

また、bigquery.datasets.create 権限がある場合は、作成するデータセットで読み込みジョブを使用してテーブルの作成と更新を行えます。

BigQuery での IAM のロールと権限については、事前定義ロールと権限をご覧ください。

Cloud Storage からデータを読み込む権限

Cloud Storage バケットからデータを読み込むために必要な権限を取得するには、バケットに対するストレージ管理者（roles/storage.admin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与の詳細については、アクセス権の管理に関する記事をご覧ください。

この事前定義ロールには、Cloud Storage バケットからデータを読み込むために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

Cloud Storage バケットからデータを読み込むには、次の権限が必要です。

• storage.buckets.get
• storage.objects.get
• storage.objects.list (required if you are using a URI wildcard)

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

データセットを作成する

データを保存する BigQuery データセットを作成します。

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 データ型は、GoogleSQL 構文に対応するように BigQuery データ型に変換されます。検出されたスキーマに含まれるフィールドはすべて NULLABLE です。詳細については、ORC 変換をご覧ください。

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

外部テーブルを作成するためのテーブル スキーマを提供するには、参照ファイルの URL に BigQuery API の referenceFileSchemaUri プロパティを設定するか、
bq コマンドライン ツールの --reference_file_schema_uri パラメータを設定します。

例: --reference_file_schema_uri="gs://mybucket/schema.orc"

ORC 圧縮

BigQuery は、ORC ファイルの内容に対して次の圧縮コーデックをサポートしています。

• Zlib
• Snappy
• LZO
• LZ4

BigQuery にアップロード後、ORC ファイルのデータは圧縮されたままにはなりません。データ ストレージは、データセット ストレージの課金モデルに応じて、論理バイトまたは物理バイトで報告されます。ストレージ使用量に関する情報を取得するには、INFORMATION_SCHEMA.TABLE_STORAGE ビューにクエリを実行します。

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

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

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

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

コンソール

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

   [BigQuery] に移動

2. [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
3. [データセット情報] セクションで、[ テーブルを作成] をクリックします。
4. [テーブルを作成] パネルで、次の詳細を指定します。
1. [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
   1. Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
   2. [ファイル形式] で、[ORC] を選択します。
2. [宛先] セクションで、次の詳細を指定します。
   1. [データセット] で、テーブルを作成するデータセットを選択します。
   2. [テーブル] フィールドに、作成するテーブルの名前を入力します。
   3. [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
3. [スキーマ] セクションでは、何もする必要はありません。スキーマは ORC ファイルで自己記述されます。
4. 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。
5. [詳細オプション] をクリックして、次の操作を行います。
   • [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
   • テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
   • Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
6. [テーブルを作成] をクリックします。

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

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

SQL

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

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

   [BigQuery] に移動

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

   LOAD DATA OVERWRITE mydataset.mytable
   FROM FILES (
     format = 'ORC',
     uris = ['gs://bucket/path/file.orc']);
   

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

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

bq

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

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

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

• --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

1. Cloud Storage のソースデータを参照する load ジョブを作成します。

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

3. source URIs プロパティは、完全修飾の gs://bucket/object の形式にする必要があります。各 URI にワイルドカード文字（*）を 1 つ含めることができます。

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

5. ジョブのステータスを確認するには、jobs.get(job_id*) を呼び出します。ここで、job_id は、最初のリクエストによって返されたジョブの ID です。

   • status.state = DONE である場合、ジョブは正常に完了しています。
   • status.errorResult プロパティが存在する場合は、リクエストが失敗したことを意味し、該当するオブジェクトにエラーを説明する情報が格納されます。リクエストが失敗した場合、テーブルは作成されず、データは読み込まれません。
   • status.errorResult が存在しない場合、ジョブは正常に完了していますが、一部の行のインポートで問題があったなど、非致命的なエラーが発生した可能性があります。致命的でないエラーは、返されたジョブ オブジェクトの status.errors プロパティに格納されています。

API に関する注:

• 読み込みジョブはアトミックで整合性があります。読み込みジョブが失敗した場合、データは一切利用できず、読み込みジョブが成功した場合はすべてのデータが利用可能になります。

• おすすめの方法として、jobs.insert を呼び出して読み込みジョブを作成する際に、一意の ID を生成して、その ID を jobReference.jobId として渡すようにします。この手法を使用すると、ネットワーク障害時にクライアントは既知のジョブ ID を使ってポーリングまたは再試行できるので、頑健性が向上します。

• 同じジョブ ID に対して jobs.insert を呼び出しても結果は同じになります。同じジョブ ID で何回でも再試行できますが、成功するオペレーションはそのうちの 1 回だけです。

C#

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

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

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 = loadJob.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Go

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

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

import (
	"context"
	"fmt"

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

// 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

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

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

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

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

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

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.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 のリファレンス ドキュメントをご覧ください。

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

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

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

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 データをテーブルに追加または上書きする

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

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

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

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

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

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

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

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

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

コンソール

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

   [BigQuery] に移動

2. [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。
3. [データセット情報] セクションで、[ テーブルを作成] をクリックします。
4. [テーブルを作成] パネルで、次の詳細を指定します。
1. [ソース] セクションの [テーブルの作成元] リストで [Google Cloud Storage] を選択します。次に、以下の操作を行います。
   1. Cloud Storage バケットからファイルを選択するか、Cloud Storage URI を入力します。Google Cloud コンソールで複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成、追加、または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
   2. [ファイル形式] で、[ORC] を選択します。
注: テーブルを追加または上書きするときに、テーブルのスキーマを変更できます。読み込みオペレーション中にサポートされるスキーマの変更については、テーブル スキーマの変更をご覧ください。
2. [宛先] セクションで、次の詳細を指定します。
   1. [データセット] で、テーブルを作成するデータセットを選択します。
   2. [テーブル] フィールドに、作成するテーブルの名前を入力します。
   3. [テーブルタイプ] フィールドが [ネイティブ テーブル] に設定されていることを確認します。
3. [スキーマ] セクションでは、何もする必要はありません。スキーマは ORC ファイルで自己記述されます。
注: テーブルを追加または上書きするときに、テーブルのスキーマを変更できます。読み込みオペレーション中にサポートされるスキーマの変更については、テーブル スキーマの変更をご覧ください。
4. 省略可: [パーティションとクラスタの設定] を指定します。詳細については、パーティション分割テーブルの作成とクラスタ化テーブルの作成と使用をご覧ください。追加や上書きではテーブルをパーティション分割テーブルまたはクラスタ化テーブルに変換できません。Google Cloud コンソールでは、読み込みジョブでパーティション分割テーブルやクラスタ化テーブルの追加または上書きを行うことはできません。
5. [詳細オプション] をクリックして、次の操作を行います。
   • [書き込み設定] で、[テーブルに追加する] または [テーブルを上書きする] を選択します。
   • テーブルのスキーマに存在しない行の値を無視する場合は、[不明な値] を選択します。
   • Cloud Key Management Service 鍵を使用するには、[暗号化] で [顧客管理の暗号鍵] クリックします。[Google が管理する暗号鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
6. [テーブルを作成] をクリックします。

SQL

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

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

   [BigQuery] に移動

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

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

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

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

bq

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

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

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

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

• --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

1. Cloud Storage のソースデータを参照する load ジョブを作成します。

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

3. source URIs プロパティは、完全修飾の gs://bucket/object の形式にする必要があります。複数の URI をカンマ区切りのリストとして含めることができます。ワイルドカードも使用できます。

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

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

C#

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

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

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 = loadJob.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Go

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

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

import (
	"context"
	"fmt"

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

// 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

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

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

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

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

// Instantiate 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

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

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableID = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.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

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

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

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

import io

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = io.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.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 のリファレンス ドキュメントをご覧ください。

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

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	ORC データで -719,162 日未満または 2,932,896 日を超える値を変換しようとすると、invalid date value エラーが返されます。これによって影響を受ける場合は、サポートに連絡して、必要に応じて、サポートされていない値を BigQuery の最小値 0001-01-01、または最大値 9999-12-31 に変換してください。
timestamp	TIMESTAMP	ORC はナノ秒単位の精度をサポートしますが、BigQuery はデータを読み取るときにマイクロ秒未満の値をマイクロ秒に変換します。 ORC データで -719,162 日未満または 2,932,896 日を超える値を変換しようとすると、invalid date value エラーが返されます。これによって影響を受ける場合は、サポートに連絡して、必要に応じて、サポートされていない値を BigQuery の最小値 0001-01-01、または最大値 9999-12-31 に変換してください。
decimal	NUMERIC、BIGNUMERIC、または STRING	固定小数点型をご覧ください。

Decimal 型

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 つのみに値が割り当てられます。

Column names

列名には、英字（a～z、A～Z）、数字（0～9）、アンダースコア（_）を使用できます。列名の先頭は英字またはアンダースコアにする必要があります。柔軟な列名を使用する場合、BigQuery では列名の先頭に数字を使用できます。BigQuery Storage Read API または BigQuery Storage Write API で柔軟な列名を使用するには、特別な処理が必要となるため、数字で列を開始する場合は注意してください。柔軟な列名のサポートについて詳しくは、柔軟な列名をご覧ください。

列名の最大文字数は 300 文字です。列名には、次のいずれの接頭辞も使用できません。

• _TABLE_
• _FILE_
• _PARTITION
• _ROW_TIMESTAMP
• __ROOT__
• _COLIDENTIFIER

大文字と小文字が異なっている場合でも、重複する列名は使用できません。たとえば、Column1 という列は column1 という列と同じとみなされます。列の命名規則の詳細については、GoogleSQL リファレンスの列名をご覧ください。

テーブル名（test など）が列名（test など）のいずれかと同一である場合、SELECT 式は、他のすべてのテーブル列を含む STRUCT として test 列を解釈します。この競合を回避するには、次のいずれかの方法を使用します。

• テーブルとその列に同じ名前を使用しない。

• テーブルに別のエイリアスを割り当てる。たとえば、次のクエリでは、テーブル エイリアス t をテーブル project1.dataset.test に割り当てます。

  SELECT test FROM project1.dataset.test AS t;
  

• 列を参照する際にテーブル名を含める。次に例を示します。

  SELECT test.test FROM project1.dataset.test;
  

柔軟な列名

プレビュー

このプロダクトまたは機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 一般提供前のプロダクトと機能は「現状のまま」ご利用いただけますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

英語以外の言語の文字へのアクセスの拡張、記号の追加など、列名の柔軟性が向上しました。

柔軟な列名では、次の文字がサポートされています。

• Unicode 正規表現 \p{L} で表される任意の言語の任意の文字。
• Unicode 正規表現 \p{N} で表される任意の言語の任意の数字。
• Unicode 正規表現 \p{Pc} で表される任意の連結用句読記号文字（アンダースコアを含む）。
• Unicode 正規表現 \p{Pd} で表されるハイフンまたはダッシュ。
• Unicode 正規表現 \p{M} で表される、別の文字に付随して使用するための任意のマーク（アクセント記号、傘、囲み記号など）。
• 次の特殊文字:
  • Unicode 正規表現 \u0026 で表されるアンパサンド（&）。
  • Unicode 正規表現 \u0025 で表されるパーセント記号（%）。
  • Unicode 正規表現 \u003D で表される等号（=）。
  • Unicode 正規表現 \u002B で表されるプラス記号（+）。
  • Unicode 正規表現 \u003A で表されるコロン（:）。
  • Unicode 正規表現 \u0027 で表されるアポストロフィ（'）。
  • Unicode 正規表現 \u003C で表される小なり記号（<）。
  • Unicode 正規表現 \u003E で表される大なり記号（>）。
  • Unicode 正規表現 \u0023 で表されるナンバー記号（#）。
  • Unicode 正規表現 \u007c で表される縦線（|）。
  • 空白文字。

柔軟な列名は、次の特殊文字をサポートしていません。

• Unicode 正規表現 \u0021 で表される感嘆符（!）。
• Unicode 正規表現 \u0022 で表される引用符（"）。
• Unicode 正規表現 \u0024 で表されるドル記号（$）。
• Unicode 正規表現 \u0028 で表される左かっこ（(）。
• Unicode 正規表現 \u0029 で表される右かっこ（)）。
• Unicode 正規表現 \u002A で表されるアスタリスク（*）。
• Unicode 正規表現 \u002C で表されるカンマ（,）。
• Unicode 正規表現 \u002E で表されるピリオド（.）。
• Unicode 正規表現 \u002F で表されるスラッシュ（/）。
• Unicode 正規表現 \u003B で表されるセミコロン（;）。
• Unicode 正規表現 \u003F で表される疑問符（?）。
• Unicode 正規表現 \u0040 で表されるアットマーク（@）。
• Unicode 正規表現 \u005B で表される左角かっこ（[）。
• Unicode 正規表現 \u005C で表されるバックスラッシュ（\）。
• Unicode 正規表現 \u005D で表される、右角かっこ（]）。
• Unicode 正規表現 \u005E で表される曲折アクセント（^）。
• Unicode 正規表現 \u0060 で表される抑音アクセント（`）。
• Unicode 正規表現 \u007B で表される左波かっこ（{）。
• Unicode 正規表現 \u007D で表される右波かっこ（}）。
• Unicode 正規表現 \u007E で表されるチルダ（~）。

追加のガイドラインについては、列名をご覧ください。

拡張された列の文字は、BigQuery Storage Read API と BigQuery Storage Write API の両方でサポートされています。BigQuery Storage Read API で Unicode 文字の拡張リストを使用するには、フラグを設定する必要があります。displayName 属性を使用すると列名を取得できます。次の例では、Python クライアントでフラグを設定する方法を示します。

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

BigQuery Storage Write API で Unicode 文字の拡張リストを使用するには、JsonStreamWriter ライター オブジェクトを使用している場合を除き、column_name 表記でスキーマを指定する必要があります。次の例では、スキーマの指定方法を示します。

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

この例では、item_name_column と item_description_column はプレースホルダ名で、プロトコル バッファの命名規則に準拠する必要があります。column_name アノテーションは、常にプレースホルダ名よりも優先されます。

• Parquet データの読み込みでは、デフォルトでは柔軟な列名はサポートされません。このプレビューに参加するには、登録フォームにご記入ください。プレビューに登録後、無効な列名（列名の照合など）ではエラーが返されます。プロジェクトが登録されていない場合、読み込みリクエストでは、エラーを返すのではなく、無効な文字がアンダースコアに置き換えられます。
• スキーマの自動検出を使用して CSV データを読み込む場合、デフォルトでは柔軟な列名はサポートされません。このプレビューに参加するには、登録フォームにご記入ください。プレビューに登録後、無効な列名（列名の照合など）ではエラーが返されます。プロジェクトが登録されていない場合、読み込みリクエストでは、エラーを返すのではなく、無効な文字がアンダースコアに置き換えられます。

制限事項

柔軟な列名は、外部テーブルではサポートされていません。

NULL 値

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

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