查询 Cloud Storage 数据

BigQuery 支持查询以下格式的 Cloud Storage 数据：

英文逗号分隔值 (CSV)
JSON（以换行符分隔）
Avro
ORC
Parquet
Datastore 导出文件
Firestore 导出文件

BigQuery 支持查询以下存储类别的 Cloud Storage 数据：

标准
Nearline
Coldline
归档

如需查询 Cloud Storage 外部数据源，请提供数据的 Cloud Storage URI 路径，并创建一个引用该数据源的表。用于引用 Cloud Storage 数据源的表可以是永久表或临时表。

查询存储在 Cloud Storage 中的数据时，请务必考虑您的数据集和 Cloud Storage 存储桶的位置。

准备工作

授予为用户提供执行本文档中的每个任务所需权限的 Identity and Access Management (IAM) 角色。执行任务所需的权限（如果有）列出在任务的“所需权限”部分中。

检索 Cloud Storage URI

要使用 Cloud Storage 数据源创建外部表，则必须提供 Cloud Storage URI。

Cloud Storage URI 包含存储桶名称和对象（文件名）。例如，如果 Cloud Storage 存储分区的名称为 mybucket，且数据文件的名称为 myfile.csv，则存储分区 URI 为 gs://mybucket/myfile.csv。如果数据被分成多个文件，您可以在 URI 中使用通配符。如需了解详情，请参阅 Cloud Storage 请求 URI。

BigQuery 不支持数据源 URI 在初始双斜杠之后添加多个连续斜杠。Cloud Storage 对象名称可包含多个连续斜杠（“/”）字符。但是，BigQuery 会将多个连续斜杠转换为单个斜杠。例如，以下数据源 URI 在 Cloud Storage 中有效，但在 BigQuery 中则无效：gs://bucket/my//object//name。

如需检索 Cloud Storage URI，请执行以下操作：

打开 Cloud Storage 控制台

Cloud Storage 控制台
浏览到包含源数据的对象（文件）所在的位置。
在 Cloud Storage 控制台顶部，找到并记下该对象的路径。如需编写 URI，请将 gs://bucket/file 替换为适当的路径，例如 gs://mybucket/myfile.json。bucket 是 Cloud Storage 存储桶名称，file 是包含数据的对象（文件）的名称。

永久外部表与临时外部表

您可以使用永久表或临时表在 BigQuery 中查询外部数据源。永久表是在数据集中创建的表，该表链接到外部数据源。由于该表是永久性的，因此您可以使用访问权限控制与其他同样有权访问底层外部数据源的人员共享该表，还可以随时查询该表。

使用临时表查询外部数据源时，您需要提交一个命令，该命令必须包含查询并创建一个链接到外部数据源的非永久表。使用临时表时，不会在任何 BigQuery 数据集内创建表。由于该表并非永久存储在数据集内，因此无法与他人共享。使用临时表查询外部数据源适用于对外部数据进行一次性临时查询，或执行提取、转换和加载 (ETL) 过程。

使用永久外部表查询 Cloud Storage 数据

所需权限

如需使用永久表查询 Cloud Storage 中的外部数据，您需要拥有执行以下操作的权限：

在项目级层或更高级层运行查询作业。
创建一个指向外部数据的表。
访问该表。

如果外部数据存储在 Cloud Storage 中，您还需要有权访问包含您的数据的存储桶。

在 BigQuery 中创建和查询外部表的权限

如需在 BigQuery 中创建和查询外部表，您需要以下 IAM 权限：

bigquery.tables.create
bigquery.tables.getData
bigquery.jobs.create

以下每个预定义的 IAM 角色都包含在 BigQuery 中创建和查询外部表所需的权限：

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin（包括 bigquery.jobs.create 权限）
roles/bigquery.user（包括 bigquery.jobs.create 权限）
roles/bigquery.jobUser（包括 bigquery.jobs.create 权限）

此外，如果您拥有 bigquery.datasets.create 权限，则可以在您创建的数据集中创建和访问外部表。但您仍需要 bigquery.jobs.create 权限才能查询数据。

如需详细了解 BigQuery 中的 IAM 角色和权限，请参阅预定义的角色和权限。

查询 Cloud Storage 存储桶中的外部数据的权限

如需查询 Cloud Storage 存储桶中的外部数据，您需要以下 IAM 权限：

storage.objects.get
storage.objects.list（如果您使用的是 URI 通配符，则为必需）

预定义的 IAM 角色 roles/storage.objectViewer 包含查询 Cloud Storage 存储桶中的外部数据所需的所有权限。

Compute Engine 实例的访问权限范围

如果对于 Compute Engine 实例，您需要查询链接到 Cloud Storage 源的外部表，则该实例必须至少具有 Cloud Storage 只读访问权限范围 (https://www.googleapis.com/auth/devstorage.read_only)。

这些范围用于控制 Compute Engine 实例对 Google Cloud 产品（包括 Cloud Storage）的访问权限。在实例上运行的应用使用关联到实例的服务帐号来调用 Google Cloud API。

如果您设置某个 Compute Engine 实例作为默认 Compute Engine 服务帐号运行，则该实例默认会获得一些默认范围，包括 https://www.googleapis.com/auth/devstorage.read_only 范围。

如果您使用自定义服务帐号设置实例，请务必向该实例明确授予 https://www.googleapis.com/auth/devstorage.read_only 范围。

如需了解如何将范围应用于 Compute Engine 实例，请参阅更改实例的服务帐号和访问权限范围。如需详细了解 Compute Engine 服务帐号，请参阅服务帐号。

创建和查询永久外部表

您可以通过以下方式创建链接到外部数据源的永久表：

使用 Cloud Console
使用 bq mk 命令
使用 tables.insert API 方法时创建 ExternalDataConfiguration
运行 CREATE EXTERNAL TABLE 数据定义语言 (DDL) 语句。
使用客户端库

如需使用永久表查询外部数据源，需要在 BigQuery 数据集中创建一个链接到外部数据源的表。数据不会存储在 BigQuery 表中。由于该表是永久表，因此您可以使用访问权限控制与其他同样有权访问底层外部数据源的人员共享该表。

创建永久外部表时，您可以通过以下方式指定架构：

提供显式表架构。
使用架构自动检测功能。

如需创建外部表，请执行以下操作：

控制台

在 Cloud Console 中，打开 BigQuery 页面。

转到 BigQuery

在浏览器面板中，展开您的项目并选择数据集。
展开操作选项，然后点击创建表。
在创建表页面的来源部分，执行以下操作：
- 在基于以下数据创建表部分，选择 Google Cloud Storage。
- 在从 GCS 存储桶中选择文件字段中，浏览并找到相应的文件/Cloud Storage 存储桶，或输入 Cloud Storage URI。请注意，Cloud Console 不支持添加多个 URI，但支持使用通配符。Cloud Storage 存储桶必须与您要创建的表所属的数据集位于同一位置。
- 对于文件格式，请选择数据格式。
在创建表页面的目标部分，执行以下操作：
- 在数据集部分，选择相应的数据集。
- 验证表类型设置为外部表。
- 在表字段中，输入您要在 BigQuery 中创建的表的名称。
在架构部分中，您可以启用架构自动检测功能，也可以手动指定架构。
- 如需启用架构自动检测功能，请选择自动检测选项。
- 如需手动指定架构，请不要选中自动检测选项，然后执行以下任一操作：
  - 点击以文字形式修改，并以 JSON 数组格式输入表架构。
点击创建表。

创建永久表后，您可以对该表运行查询，就像对原生 BigQuery 表运行查询一样。查询完成后，可以将结果导出为 CSV 或 JSON 文件，将结果保存为表，或将结果保存到 Google 表格。

SQL

您可以通过运行 CREATE EXTERNAL TABLE DDL 语句创建永久外部表。您可以明确指定架构。如果未指定架构，BigQuery 将使用架构自动检测功能，通过外部数据来推断架构。

以下示例使用架构自动检测功能创建名为 sales 的外部表，该表链接到存储在 Cloud Storage 中的 CSV 文件：

转到 Cloud 控制台中的 BigQuery 页面。

前往 BigQuery

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

CREATE OR REPLACE EXTERNAL TABLE mydataset.sales
  OPTIONS (
  format = 'CSV',
  uris = ['gs://mybucket/sales.csv']);

点击运行。

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

下一个示例明确指定架构，并跳过 CSV 文件中的第一行：

CREATE OR REPLACE EXTERNAL TABLE mydataset.sales (
  Region STRING,
  Quarter STRING,
  Total_Sales INT64
) OPTIONS (
    format = 'CSV',
    uris = ['gs://mybucket/sales.csv'],
    skip_leading_rows = 1);

bq

如需创建外部表，请使用带有 --external_table_definition 标志的 bq mk 命令。此标志包含表定义文件的路径或内嵌表定义。

选项 1：表定义文件

使用 bq mkdef 命令创建表定义文件，然后将文件路径传递给 bq mk 命令，如下所示：

bq mkdef --source_format=SOURCE_FORMAT \
  BUCKET_URL > DEFINITION_FILE

bq mk --table \
  --external_table_definition=DEFINITION_FILE \
  DATASET_NAME.TABLE_NAME \
  SCHEMA

其中：

SOURCE_FORMAT 是外部数据源的格式。例如 CSV。
BUCKET_URI 是 Cloud Storage URI。
DEFINITION_FILE 是本地机器上表定义文件的路径。
DATASET_NAME 是包含该表的数据集的名称。
TABLE_NAME 是您要创建的表的名称。
SCHEMA 指定 JSON 架构文件的路径，或者以 field:data_type,field:data_type,... 格式指定架构。

例如：

bq mkdef --source_format=CSV gs://mybucket/sales.csv > mytable_def

bq mk --table --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

如需使用架构自动检测功能，请在 mkdef 命令中设置 --autodetect=true 标志并省略架构：

bq mkdef --source_format=CSV --autodetect=true \
  gs://mybucket/sales.csv > mytable_def

bq mk --table --external_table_definition=mytable_def \
  mydataset.mytable

选项 2：内嵌表定义

您可以将表定义直接传递给 bq mk 命令，而不用创建表定义文件：

bq mk --table \
  --external_table_definition=@SOURCE_FORMAT=BUCKET_URI \
  DATASET_NAME.TABLE_NAME \
  SCHEMA

其中：

SOURCE_FORMAT 是外部数据源的格式，例如 CSV。
BUCKET_URI 是 Cloud Storage URI。
DATASET_NAME 是包含该表的数据集的名称。
TABLE_NAME 是您要创建的表的名称。
SCHEMA 指定 JSON 架构文件的路径，或者以 field:data_type,field:data_type,... 格式指定架构。如需使用架构自动检测功能，请省略此参数。

例如：

bq mkdef --source_format=CSV gs://mybucket/sales.csv > mytable_def
bq mk --table --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

使用 tables.insert API 方法时创建 ExternalDataConfiguration。指定 schema 属性或将 autodetect 属性设置为 true，为受支持的数据源启用架构自动检测功能。

Java

试用此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Java 设置说明进行操作。如需了解详情，请参阅 BigQuery Java API 参考文档。

在 GitHub 上查看反馈

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.ExternalTableDefinition;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;
import com.google.cloud.bigquery.TableResult;

// Sample to queries an external data source using a permanent table
public class QueryExternalGCSPerm {

  public static void runQueryExternalGCSPerm() {
    // 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.csv";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    String query =
        String.format("SELECT * FROM %s.%s WHERE name LIKE 'W%%'", datasetName, tableName);
    queryExternalGCSPerm(datasetName, tableName, sourceUri, schema, query);
  }

  public static void queryExternalGCSPerm(
      String datasetName, String tableName, String sourceUri, Schema schema, String query) {
    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();

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      TableId tableId = TableId.of(datasetName, tableName);
      // Create a permanent table linked to the GCS file
      ExternalTableDefinition externalTable =
          ExternalTableDefinition.newBuilder(sourceUri, csvOptions).setSchema(schema).build();
      bigquery.create(TableInfo.of(tableId, externalTable));

      // Example query to find states starting with 'W'
      TableResult results = bigquery.query(QueryJobConfiguration.of(query));

      results
          .iterateAll()
          .forEach(row -> row.forEach(val -> System.out.printf("%s,", val.toString())));

      System.out.println("Query on external permanent table performed successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

Node.js

尝试此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情，请参阅 BigQuery Node.js API 参考文档。

在 GitHub 上查看反馈

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

async function queryExternalGCSPerm() {
  // Queries an external data source using a permanent table

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

  // Configure the external data source
  const dataConfig = {
    sourceFormat: 'CSV',
    sourceUris: ['gs://cloud-samples-data/bigquery/us-states/us-states.csv'],
    // Optionally skip header row
    csvOptions: {skipLeadingRows: 1},
  };

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    externalDataConfiguration: dataConfig,
  };

  // Create an external table linked to the GCS file
  const [table] = await bigquery
    .dataset(datasetId)
    .createTable(tableId, options);

  console.log(`Table ${table.id} created.`);

  // Example query to find states starting with 'W'
  const query = `SELECT post_abbr
  FROM \`${datasetId}.${tableId}\`
  WHERE name LIKE 'W%'`;

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(query);
  console.log(`Job ${job.id} started.`);

  // Wait for the query to finish
  const [rows] = await job.getQueryResults();

  // Print the results
  console.log('Rows:');
  console.log(rows);
}

Python

尝试此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Python 设置说明进行操作。如需了解详情，请参阅 BigQuery Python API 参考文档。

在 GitHub 上查看反馈

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

# Configure the external data source
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_id = "us_states"
schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
]
table = bigquery.Table(dataset_ref.table(table_id), schema=schema)
external_config = bigquery.ExternalConfig("CSV")
external_config.source_uris = [
    "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
]
external_config.options.skip_leading_rows = 1  # optionally skip header row
table.external_data_configuration = external_config

# Create a permanent table linked to the GCS file
table = client.create_table(table)  # API request

# Example query to find states starting with 'W'
sql = 'SELECT * FROM `{}.{}` WHERE name LIKE "W%"'.format(dataset_id, table_id)

query_job = client.query(sql)  # API request

w_states = list(query_job)  # Waits for query to finish
print("There are {} states with names starting with W.".format(len(w_states)))

使用临时表查询 Cloud Storage 数据

要在不创建永久表的情况下查询外部数据源，请运行命令以便进行以下组合：

将表定义文件与查询组合
将内嵌架构定义与查询组合
将 JSON 架构定义文件与查询组合

系统会使用表定义文件或提供的架构来创建临时外部表，然后对临时外部表运行查询。bq 命令行工具和 API 支持使用临时表查询外部数据源。

使用临时外部表时，并不会在您的某个 BigQuery 数据集中创建表。由于该表不会永久存储在数据集内，因此无法与他人共享。使用临时表查询外部数据源适用于对外部数据进行一次性临时查询，或执行提取、转换和加载 (ETL) 过程。

所需权限

当您使用临时表在 Cloud Storage 中查询外部数据时，您需要拥有相关权限才能在项目级层或更高级层运行查询作业，并且需要对指向该外部数据的表所属数据集的访问权限。如需查询 Cloud Storage 中的数据，您还需要拥有对您的数据所在的存储桶的访问权限。

在 BigQuery 中查询外部表的权限

如需使用临时表在 BigQuery 中查询外部表，您需要以下 IAM 权限：

bigquery.tables.getData
bigquery.jobs.create

以下预定义的 IAM 角色均包含使用临时表查询 BigQuery 中的外部表所需的权限：

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin（包括 bigquery.jobs.create 权限）
roles/bigquery.user（包括 bigquery.jobs.create 权限）
roles/bigquery.jobUser（包括 bigquery.jobs.create 权限）

此外，如果您拥有 bigquery.datasets.create 权限，则可以在您创建的数据集中创建和访问外部表。但您仍需要 bigquery.jobs.create 权限才能查询数据。

如需详细了解 BigQuery 中的 IAM 角色和权限，请参阅预定义的角色和权限。

查询 Cloud Storage 存储桶中的外部数据的权限

如需查询 Cloud Storage 存储桶中的外部数据，您需要以下 IAM 权限：

storage.objects.get
storage.objects.list（如果您使用的是 URI 通配符，则为必需）

预定义的 IAM 角色 roles/storage.objectViewer 包含查询 Cloud Storage 存储桶中的外部数据所需的所有权限。

创建和查询临时表

您可以使用 bq 命令行工具、API 或客户端库来创建和查询链接到外部数据源的临时表。

bq

您可以使用带有 --external_table_definition 标志的 bq query 命令查询链接到外部数据源的临时表。使用 bq 命令行工具查询链接到外部数据源的临时表时，您可以使用以下项来标识表的架构：

表定义文件（存储在本地机器上）
内嵌架构定义
JSON 架构文件（存储在本地机器上）

（可选）提供 --location 标志并将其值设置为您的位置。

如需使用表定义文件查询链接到外部数据源的临时表，请输入以下命令。

bq --location=location query \
--external_table_definition=table::definition_file \
'query'

其中：

location 是位置的名称。--location 是可选标志。例如，如果您在东京区域使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置该位置的默认值。
table 是您要创建的临时表的名称。
definition_file 是本地机器上表定义文件的路径。
query 是您要提交到临时表的查询。

例如，以下命令使用名为 sales_def 的表定义文件创建并查询名为 sales 的临时表。

bq query \
--external_table_definition=sales::sales_def \
'SELECT
  Region,
  Total_sales
FROM
  sales'

如需使用内嵌架构定义查询链接到外部数据源的临时表，请输入以下命令。

bq --location=location query \
--external_table_definition=table::schema@source_format=Cloud Storage URI \
'query'

其中：

location 是位置的名称。--location 是可选标志。例如，如果您在东京区域使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置该位置的默认值。
table 是您要创建的临时表的名称。
schema 是内嵌架构定义，格式为 field:data_type,field:data_type。
source_format 是外部数据源的格式，例如 CSV。
Cloud Storage URI 是 Cloud Storage URI。
query 是您要提交到临时表的查询。

例如，以下命令使用以下架构定义创建并查询名为 sales 的临时表，该表链接到存储在 Cloud Storage 中的 CSV 文件：Region:STRING,Quarter:STRING,Total_sales:INTEGER。

bq query \
--external_table_definition=sales::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv \
'SELECT
  Region,
  Total_sales
FROM
  sales'

如需使用 JSON 架构文件查询链接到外部数据源的临时表，请输入以下命令。

bq --location=location query \
--external_table_definition=schema_file@source_format=Cloud Storage URI \
'query'

其中：

location 是位置的名称。--location 是可选标志。例如，如果您在东京区域使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置该位置的默认值。
schema_file 是本地机器上 JSON 架构文件的路径。
source_format 是外部数据源的格式，例如 CSV。
Cloud Storage URI 是 Cloud Storage URI。
query 是您要提交到临时表的查询。

例如，以下命令使用 /tmp/sales_schema.json 架构文件创建并查询名为 sales 的临时表，该表链接到存储在 Cloud Storage 中的 CSV 文件。

  bq query \
  --external_table_definition=sales::/tmp/sales_schema.json@CSV=gs://mybucket/sales.csv \
  'SELECT
      Region,
      Total_sales
    FROM
      sales'

API

创建查询作业配置。如需了解如何调用 jobs.query 和 jobs.insert，请参阅查询数据。
创建 ExternalDataConfiguration 来指定外部数据源。

Java

试用此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Java 设置说明进行操作。如需了解详情，请参阅 BigQuery Java API 参考文档。

在 GitHub 上查看反馈

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.ExternalTableDefinition;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableResult;

// Sample to queries an external data source using a temporary table
public class QueryExternalGCSTemp {

  public static void runQueryExternalGCSTemp() {
    // TODO(developer): Replace these variables before running the sample.
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    String query = String.format("SELECT * FROM %s WHERE name LIKE 'W%%'", tableName);
    queryExternalGCSTemp(tableName, sourceUri, schema, query);
  }

  public static void queryExternalGCSTemp(
      String tableName, String sourceUri, Schema schema, String query) {
    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();

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      // Configure the external data source and query job.
      ExternalTableDefinition externalTable =
          ExternalTableDefinition.newBuilder(sourceUri, csvOptions).setSchema(schema).build();
      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              .addTableDefinition(tableName, externalTable)
              .build();

      // Example query to find states starting with 'W'
      TableResult results = bigquery.query(queryConfig);

      results
          .iterateAll()
          .forEach(row -> row.forEach(val -> System.out.printf("%s,", val.toString())));

      System.out.println("Query on external temporary table performed successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

Node.js

尝试此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情，请参阅 BigQuery Node.js API 参考文档。

在 GitHub 上查看反馈

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

async function queryExternalGCSTemp() {
  // Queries an external data source using a temporary table.

  const tableId = 'us_states';

  // Configure the external data source
  const externalDataConfig = {
    sourceFormat: 'CSV',
    sourceUris: ['gs://cloud-samples-data/bigquery/us-states/us-states.csv'],
    // Optionally skip header row.
    csvOptions: {skipLeadingRows: 1},
    schema: {fields: schema},
  };

  // Example query to find states starting with 'W'
  const query = `SELECT post_abbr
  FROM \`${tableId}\`
  WHERE name LIKE 'W%'`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    query,
    tableDefinitions: {[tableId]: externalDataConfig},
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);
  console.log(`Job ${job.id} started.`);

  // Wait for the query to finish
  const [rows] = await job.getQueryResults();

  // Print the results
  console.log('Rows:');
  console.log(rows);
}

Python

尝试此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Python 设置说明进行操作。如需了解详情，请参阅 BigQuery Python API 参考文档。

在 GitHub 上查看反馈

from google.cloud import bigquery

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

# Configure the external data source and query job.
external_config = bigquery.ExternalConfig("CSV")
external_config.source_uris = [
    "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
]
external_config.schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
]
external_config.options.skip_leading_rows = 1
table_id = "us_states"
job_config = bigquery.QueryJobConfig(table_definitions={table_id: external_config})

# Example query to find states starting with 'W'.
sql = 'SELECT * FROM `{}` WHERE name LIKE "W%"'.format(table_id)

query_job = client.query(sql, job_config=job_config)  # Make an API request.

w_states = list(query_job)  # Wait for the job to complete.
print("There are {} states with names starting with W.".format(len(w_states)))

查询外部分区数据

请参阅查询 Cloud Storage 外部分区数据的说明。

Cloud Storage URI 的通配符支持

如果您的 Cloud Storage 数据分散在多个共用一个通用基本名称的文件中，则可以在表定义文件的 URI 中使用通配符。在不使用表定义文件的情况下创建外部表时，也可以使用通配符。

要在 Cloud Storage URI 中添加通配符，可在基本名称后附加星号 (*)。

示例：

以下通配符 URI 会选择所有文件夹中以前缀 gs://mybucket/fed-samples/fed-sample 开头的所有文件：
```
gs://mybucket/fed-samples/fed-sample*
```
以下通配符 URI 仅选择名为 fed-samples 的文件夹中和 fed-samples 的任何子文件夹中扩展名为 .csv 的文件：
```
gs://mybucket/fed-samples/fed-sample/*.csv
```
以下通配符 URI 选择名为 fed-samples 的文件夹中命名模式为 fed-sample*.csv 的文件。此示例不会选择 fed-samples 子文件夹中的文件。
```
gs://mybucket/fed-samples/fed-sample*.csv
```

使用 bq 命令行工具时，您可能需要在某些平台上对星号进行转义。

存储桶中的对象（文件名）仅可使用一个通配符。通配符可以出现在对象名称内或对象名称末尾。不支持在存储桶名称后附加通配符。来源 URI 不支持多个通配符。例如，路径 gs://mybucket/fed-*/temp/*.csv 无效。

Google Datastore 导出文件只能指定一个 URI，且必须以 .backup_info 或 .export_metadata 结尾。

在执行以下操作时不可使用星号通配符：

创建与 Datastore 或 Firestore 导出文件关联的外部表
从 Cloud Storage 加载 Datastore 或 Firestore 导出数据

_FILE_NAME 伪列

基于外部数据源的表可提供名为 _FILE_NAME 的伪列。此列包含相应行所属文件的完全限定路径，且仅可用于引用存储在 Cloud Storage 和 Google 云端硬盘中的外部数据的表。

_FILE_NAME 列名为预留名称，也就是说，您不能在任何表中使用该名称创建列。如需选择 _FILE_NAME 的值，您必须使用别名。以下查询示例演示了如何通过将别名 fn 分配给伪列来选择 _FILE_NAME。

bq query \
--project_id=project_id \
--use_legacy_sql=false \
'SELECT
   name,
   _FILE_NAME AS fn
 FROM
   `dataset.table_name`
 WHERE
   name contains "Alex"'

其中：

project_id 是有效的项目 ID（如果使用 Cloud Shell 或在 Google Cloud CLI 中设置默认项目，则不需要此标志）
dataset 是存储永久外部表的数据集名称
table_name 是永久外部表的名称

如果查询在 _FILE_NAME 伪列上具有过滤条件谓词，则 BigQuery 会尝试跳过不满足过滤条件的读取文件。使用 _FILE_NAME 伪列构建查询谓词时，会应用使用伪列查询提取时间分区表的类似建议。