此页面由 Cloud Translation API 翻译。

从 Cloud Storage 加载 ORC 数据

本页简要介绍了如何将 Cloud Storage 中的 ORC 数据加载到 BigQuery 中。

ORC 是一种开源列式数据格式，广泛应用于 Apache Hadoop 生态系统。

从 Cloud Storage 加载 ORC 数据时，可以将数据加载到新的表或分区中，也可以覆盖或附加到现有的表或分区。数据加载到 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，您需要拥有 IAM 权限才能运行加载作业以及将数据加载到 BigQuery 表和分区中。如果要从 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 存储桶加载数据所需的权限，请让您的管理员为您授予存储桶的 Storage Admin (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 数据类型转换为 BigQuery 数据类型，使其与 GoogleSQL 语法兼容。检测到的架构中的所有字段均为 NULLABLE。如需了解详情，请参阅 ORC 转换。

加载具有不同架构的多个 ORC 文件时，多个架构中指定的相同字段（具有相同名称和嵌套级别）必须在每个架构定义中映射到同一种转换后的 BigQuery 数据类型。

如需提供用于创建外部表的表架构，请将 BigQuery API 中的 referenceFileSchemaUri 属性或 bq 命令行工具中的
--reference_file_schema_uri 参数设置为参考文件的网址。

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

ORC 压缩

BigQuery 支持对 ORC 文件内容使用以下压缩编解码器：

Zlib
Snappy
LZO
LZ4
ZSTD

ORC 文件中的数据在上传到 BigQuery 后不会保持压缩状态。数据存储以逻辑字节或物理字节的形式报告，具体取决于数据集存储结算模式。如需获取有关存储空间用量的信息，请查询 INFORMATION_SCHEMA.TABLE_STORAGE 视图。

将 ORC 数据加载到新表

您可以通过以下方式向新表加载 ORC 数据：

使用 Google Cloud 控制台
使用 bq 命令行工具的 bq load 命令
调用 jobs.insert API 方法并配置 load 作业
使用客户端库

如需将 ORC 数据从 Cloud Storage 加载到新的 BigQuery 表格中，请执行以下操作：

控制台

在 Google Cloud 控制台中，转到 BigQuery 页面。

转到 BigQuery
在浏览器窗格中，展开您的项目，然后选择数据集。
在数据集信息部分中，点击 创建表。
在创建表面板中，指定以下详细信息：

在来源部分中，从基于以下数据源创建表列表中选择 Google Cloud Storage。之后，执行以下操作：
1. 从 Cloud Storage 存储桶中选择一个文件，或输入 Cloud Storage URI。您无法在 Google Cloud 控制台中添加多个 URI，但支持使用通配符。Cloud Storage 存储桶必须与您要创建、附加或覆盖的表所属的数据集位于同一位置。
2. 在文件格式部分，选择 ORC。
在目标部分，指定以下详细信息：
1. 在数据集部分，选择您要在其中创建表的数据集。
2. 在表字段中，输入您要创建的表的名称。
3. 确认表类型字段是否设置为原生表。
在架构部分中，无需执行任何操作。架构在 ORC 文件中为自描述形式。
可选：指定分区和聚簇设置。如需了解详情，请参阅创建分区表和创建和使用聚簇表。
点击高级选项，然后执行以下操作：
- 在写入偏好设置部分，选中只写入空白表。此选项创建一个新表并向其中加载数据。
- 如果要忽略表架构中不存在的行中的值，请选择未知值。
- 在加密部分，点击客户管理的密钥，以使用 Cloud Key Management Service 密钥。如果保留 Google 管理的密钥设置，BigQuery 将对静态数据进行加密。
点击创建表。

SQL

使用 LOAD DATA DDL 语句. 以下示例将 ORC 文件加载到新表 mytable 中：

在 Google Cloud 控制台中，进入 BigQuery 页面。

转到 BigQuery

在查询编辑器中，输入以下语句：

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

点击运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

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

创建指向 Cloud Storage 中源数据的 load 作业。
（可选）在作业资源 jobReference 部分的 location 属性中指定您所在的位置。
source URIs 属性必须是完全限定的，格式为 gs://bucket/object。每个 URI 都可以包含一个“*”通配符。
将 sourceFormat 属性设置为 ORC，以指定 ORC 数据格式。
如需检查作业状态，请调用 jobs.get(job_id*)，其中 job_id 是初始请求返回的作业的 ID。
- 如果 status.state = DONE，则表示作业已成功完成。
- 如果出现 status.errorResult 属性，则表示请求失败，并且该对象将包含描述问题的相关信息。如果请求失败，则不创建任何表且不加载任何数据。
- 如果未出现 status.errorResult，则表示作业已成功完成，但可能存在一些非严重错误，如导入一些行时出错。非严重错误会列在返回的作业对象的 status.errors 属性中。

API 说明：

加载作业兼具原子性和一致性。也就是说，如果加载作业失败，则所有数据都不可用；如果加载作业成功，则所有数据全部可用。
通过调用 jobs.insert 来创建加载作业时，最佳做法是生成唯一 ID，并将其作为 jobReference.jobId 传递。此方法受网络故障影响较小，因为客户端可以对已知的作业 ID 进行轮询或重试。
对指定的作业 ID 调用 jobs.insert 具有幂等性。您可以对同一作业 ID 进行无限次重试，但最多只会有一个成功操作。

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`	仅当表为空时才写入数据。
Append to table	`--noreplace` 或 `--replace=false`；如果未指定 `--[no]replace`，则默认为附加	`WRITE_APPEND`	（默认）在表末尾附加数据。
覆盖表	`--replace` 或 `--replace=true`	`WRITE_TRUNCATE`	清空表中所有现有数据然后再写入新数据。此操作还会删除表架构和行级安全性，并移除所有 Cloud KMS 密钥。

如果将数据加载到现有表中，加载作业可以附加数据或覆盖表。

您可以通过以下方式附加或覆盖表：

使用 Google Cloud 控制台
使用 bq 命令行工具的 bq load 命令
调用 jobs.insert API 方法并配置 load 作业
使用客户端库

如需使用 ORC 数据附加或覆盖表，请执行以下操作：

控制台

在 Google Cloud 控制台中，转到 BigQuery 页面。

转到 BigQuery
在浏览器窗格中，展开您的项目，然后选择数据集。
在数据集信息部分中，点击 创建表。
在创建表面板中，指定以下详细信息：

在来源部分中，从基于以下数据源创建表列表中选择 Google Cloud Storage。之后，执行以下操作：
1. 从 Cloud Storage 存储桶中选择一个文件，或输入 Cloud Storage URI。您无法在 Google Cloud 控制台中添加多个 URI，但支持使用通配符。Cloud Storage 存储桶必须与您要创建、附加或覆盖的表所属的数据集位于同一位置。
2. 在文件格式部分，选择 ORC。

在目标部分，指定以下详细信息：
1. 在数据集部分，选择您要在其中创建表的数据集。
2. 在表字段中，输入您要创建的表的名称。
3. 确认表类型字段是否设置为原生表。
在架构部分中，无需执行任何操作。架构在 ORC 文件中为自描述形式。

可选：指定分区和聚簇设置。如需了解详情，请参阅创建分区表和创建和使用聚簇表。您无法通过附加或覆盖表将表转换为分区表或聚簇表。Google Cloud 控制台不支持在加载作业中对分区表或聚簇表执行附加或覆盖操作。
点击高级选项，然后执行以下操作：
- 在写入偏好设置部分，选择附加到表或覆盖表。
- 如果要忽略表架构中不存在的行中的值，请选择未知值。
- 在加密部分，点击客户管理的密钥，以使用 Cloud Key Management Service 密钥。如果保留 Google 管理的密钥设置，BigQuery 将对静态数据进行加密。
点击创建表。

SQL

使用 LOAD DATA DDL 语句. 以下示例将 ORC 文件附加到表 mytable：

在 Google Cloud 控制台中，进入 BigQuery 页面。

转到 BigQuery

在查询编辑器中，输入以下语句：

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

点击运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

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

创建指向 Cloud Storage 中源数据的 load 作业。
（可选）在作业资源 jobReference 部分的 location 属性中指定您所在的位置。
source URIs 属性必须是完全限定的，格式为 gs://bucket/object。您可以采用逗号分隔列表的形式添加多个 URI。请注意，系统也支持通配符。
将 configuration.load.sourceFormat 属性设置为 ORC，以指定数据格式。
将 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 数据，并将 Hive 分区列作为目标 BigQuery 代管表中的列进行填充。如需了解详情，请参阅从 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	日期	尝试转换 ORC 数据中小于 -719162 天或大于 2932896 天的任何值会返回 `invalid date value` 错误。如果此问题影响您，请与支持团队联系，视情况将不受支持的值转换为 BigQuery 最小值 `0001-01-01` 或最大值 `9999-12-31`。
时间戳	TIMESTAMP	ORC 支持纳秒级精度，但 BigQuery 会在读取数据时将亚微秒值转换为微秒值。尝试转换 ORC 数据中小于 -719162 天或大于 2932896 天的任何值会返回 `invalid date value` 错误。如果此问题影响您，请与支持团队联系，视情况将不受支持的值转换为 BigQuery 最小值 `0001-01-01` 或最大值 `9999-12-31`。
decimal	NUMERIC、BIGNUMER 或 STRING	请参阅十进制类型。

十进制类型

Decimal 逻辑类型可以转换为 NUMERIC、BIGNUMERIC 或 STRING 类型。转换后的类型取决于 decimal 逻辑类型的精度和比例参数以及指定的 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> 字段会转换为包含以下两个字段的重复 RECORD：与 K 具有相同数据类型的键以及与 V 具有相同数据类型的值。这两个字段均为 NULLABLE。
list	重复字段	系统不支持嵌套列表和映射列表。
union	RECORD	如果 union 只有一个变量，它会转换为可以为 Null 的字段。否则，它会转换为带有可以为 Null 的字段列表的 RECORD。可以为 Null 的字段具有 field_0 和 field_1 等后缀。在读取数据时，系统仅向其中一个字段分配值。

列名称

列名称可以包含字母（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 表达式会将 test 列解释为包含所有其他表列的 STRUCT。如需避免这种冲突，请使用以下方法之一：

避免为表及其列使用相同的名称。
为表分配其他别名。例如，以下查询会为表 project1.dataset.test 分配表别名 t：
```
SELECT test FROM project1.dataset.test AS t;
```

引用列时添加表名称。例如：

SELECT test.test FROM project1.dataset.test;

灵活的列名称

您可以更灵活地命名列，包括扩展使用非英语字符以及其他符号。

灵活的列名称支持以下字符：

任何语言的任何字母，由 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 都支持扩展的列字符。如需将扩展的 Unicode 字符列表与 BigQuery Storage Read API 搭配使用，您必须设置标志。您可以使用 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

如需将扩展的 Unicode 字符列表与 BigQuery Storage Write API 搭配使用，您必须提供采用 column_name 表示法的架构，除非您使用的是 JsonStreamWriter 写入器对象。以下示例展示了如何提供架构：

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 注解始终优先于占位名称。

限制

外部表不支持灵活的列名称。

`NULL` 个值

请注意，对于加载作业，BigQuery 会忽略 list 复合类型的 NULL 元素，因为如果未忽略，其将转换为 NULL ARRAY 元素，而这些元素无法持久保留到表中。如需了解详情，请参阅数据类型。

如需详细了解 ORC 数据类型，请参阅 Apache ORC™ 规范第 1 版。

从 Cloud Storage 加载 ORC 数据

限制

准备工作

所需权限

将数据加载到 BigQuery 的权限

从 Cloud Storage 加载数据的权限

所需权限

创建数据集

ORC 架构

ORC 压缩

将 ORC 数据加载到新表

控制台

SQL

bq

API

C#

Go

Java

Node.js

PHP

Python

Ruby

使用 ORC 数据覆盖或附加到表

控制台

SQL

bq

API

C#

Go

Java

Node.js

PHP

Python

Ruby

加载 Hive 分区的 ORC 数据

ORC 转换

原始类型

十进制类型

复合类型

列名称

灵活的列名称

限制

NULL 个值

`NULL` 个值