创建 Amazon S3 BigLake 表

本文档介绍如何创建 Amazon Simple Storage Service (Amazon S3) BigLake 表。BigLake 表可让您使用访问委派来查询 Amazon S3 中的数据。委托访问权限功能将对 BigLake 表的访问权限与对底层数据存储区的访问权限分离。

如需了解 BigQuery 和 Amazon S3 之间数据流动的方式，请参阅查询数据时的数据流。

准备工作

确保您拥有用于访问 Amazon S3 数据的连接。

所需的角色

如需获得创建外部表所需的权限，请让您的管理员为您授予数据集的 BigQuery Admin (roles/bigquery.admin) IAM 角色。 如需详细了解如何授予角色，请参阅管理访问权限。

此预定义角色包含创建外部表所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需创建外部表，您需要拥有以下权限：

• bigquery.tables.create
• bigquery.connections.delegate

您也可以使用自定义角色或其他预定义角色来获取这些权限。

创建数据集

创建外部表之前，您需要在支持的区域中创建数据集。从下列选项中选择一项：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，选择您要在其中创建数据集的项目。
3. 展开 查看操作选项，然后点击创建数据集。
4. 在创建数据集页面上，指定以下详细信息：
1. 对于数据集 ID，输入唯一的数据集名称。
2. 对于数据位置，请选择支持的区域。
3. 可选：如需自动删除表，请选中启用表过期时间复选框，并设置默认表存在时间上限（以天为单位）。表到期后，系统不会删除 Amazon S3 中的数据。
4. 如果要使用默认排序规则，请展开高级选项部分，然后选择启用默认排序规则选项。
5. 点击创建数据集。

SQL

使用 CREATE SCHEMA DDL 语句。以下示例在 aws-us-east-1 区域中创建数据集：

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

   转到 BigQuery

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

   CREATE SCHEMA mydataset
   OPTIONS (
     location = 'aws-us-east-1');
   

3. 点击 运行。

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

bq

在命令行环境中，使用 bq mk 命令创建数据集：

bq --location=LOCATION mk \
    --dataset \
PROJECT_ID:DATASET_NAME

--project_id 参数会替换默认项目。

替换以下内容：

• LOCATION：您的数据集所在的位置

  如需了解受支持的区域，请参阅位置。创建数据集后，您无法更改其位置。您可以使用 .bigqueryrc 文件设置位置的默认值。

• PROJECT_ID：您的项目 ID

• DATASET_NAME：您要创建的数据集的名称

  如需在非默认项目中创建数据集，请按照以下格式将项目 ID 添加到数据集名称：PROJECT_ID:DATASET_NAME。

Java

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

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetInfo;

// Sample to create a aws dataset
public class CreateDatasetAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    // Note: As of now location only supports aws-us-east-1
    String location = "aws-us-east-1";
    createDatasetAws(projectId, datasetName, location);
  }

  public static void createDatasetAws(String projectId, String datasetName, String location) {
    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();

      DatasetInfo datasetInfo =
          DatasetInfo.newBuilder(projectId, datasetName).setLocation(location).build();

      Dataset dataset = bigquery.create(datasetInfo);
      System.out.println(
          "Aws dataset created successfully :" + dataset.getDatasetId().getDataset());
    } catch (BigQueryException e) {
      System.out.println("Aws dataset was not created. \n" + e.toString());
    }
  }
}

对未分区数据创建 BigLake 表

从下列选项中选择一项：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目，然后选择数据集。

3. 在数据集信息部分中，点击 创建表。

4. 在创建表页面的来源部分，执行以下操作：

   1. 在基于以下数据创建表部分，选择 Amazon S3。
   2. 在选择 S3 路径部分，使用 s3://BUCKET_NAME/PATH 格式输入指向 Amazon S3 数据的 URI。将 BUCKET_NAME 替换为 Amazon S3 存储桶的名称；存储桶所在的区域应与数据集所在的区域相同。将 PATH 替换为您要将导出的文件写入其中的路径；它可以包含一个通配符 *。
   3. 在文件格式部分，选择 Amazon S3 中的数据格式。支持的格式包括 AVRO、PARQUET、ORC、CSV 和 JSONL（以换行符分隔的 JSON）。

5. 在目标部分，指定以下详细信息：

   1. 在数据集部分，选择相应的数据集。
   2. 在表字段中，输入表的名称。
   3. 验证表类型设置为外部表。
   4. 在连接 ID 部分，从下拉菜单中选择适当的连接 ID。如需了解连接，请参阅连接到 Amazon S3。

6. 在架构部分中，您可以启用架构自动检测功能，也可以手动指定架构（如果您拥有源文件）。如果您没有源文件，则必须手动指定架构。

   • 如需启用架构自动检测功能，请选择自动检测选项。

   • 如需手动指定架构，请让自动检测选项处于未选中状态。启用以文本形式修改，然后以 JSON 数组形式输入表架构。

7. 点击创建表。

SQL

如需创建 BigLake 表，请使用带有 WITH CONNECTION 子句的 CREATE EXTERNAL TABLE 语句：

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

   转到 BigQuery

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

   CREATE EXTERNAL TABLE DATASET_NAME.TABLE_NAME
     WITH CONNECTION `AWS_LOCATION.CONNECTION_NAME`
     OPTIONS (
       format = "DATA_FORMAT",
       uris = ["S3_URI"],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE');
   

   替换以下内容：

   • DATASET_NAME：您创建的数据集的名称
   • TABLE_NAME：您要为此表指定的名称
   • AWS_LOCATION：Google Cloud 中的 AWS 位置（例如“aws-us-east-1”）
   • CONNECTION_NAME：您创建的连接的名称
   • DATA_FORMAT：任何受支持的 BigQuery 联合格式（例如 AVRO、CSV 或 DELTA_LAKE [预览版]）
   • S3_URI：指向 Amazon S3 数据的 URI（例如 s3://bucket/path）
   • STALENESS_INTERVAL：指定对 BigLake 表执行的操作是否使用了缓存的元数据，以及操作使用的缓存的元数据的新鲜度。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。

     如需停用元数据缓存，请指定 0。这是默认设置。

     如需启用元数据缓存，请指定 30 分钟到 7 天之间的间隔时间字面量值。例如，指定 INTERVAL 4 HOUR 表示 4 小时过时间隔时间。使用此值时，如果缓存的元数据在过去 4 小时内刷新，则对表执行的操作会使用缓存的元数据。如果缓存的元数据早于该值，则操作会改为从 Amazon S3 中检索元数据。

   • CACHE_MODE：指定元数据缓存是自动刷新还是手动刷新。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。

     如果设置为 AUTOMATIC，元数据缓存会按系统定义的间隔时间刷新，通常在 30 到 60 分钟之间。

     如果要根据您确定的时间表刷新元数据缓存，请设置为 MANUAL。在这种情况下，您可以调用 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系统过程来刷新缓存。

     如果 STALENESS_INTERVAL 设置为大于 0 的值，您必须设置 CACHE_MODE。

3. 点击 运行。

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

示例：

CREATE EXTERNAL TABLE awsdataset.awstable
  WITH CONNECTION `aws-us-east-1.s3-read-connection`
  OPTIONS (
    format="CSV",
    uris=["s3://s3-bucket/path/file.csv"],
    max_staleness = INTERVAL 1 DAY,
    metadata_cache_mode = 'AUTOMATIC'
);

bq

创建表定义文件：

bq mkdef  \
--source_format=DATA_FORMAT \
--connection_id=AWS_LOCATION.CONNECTION_NAME \
--metadata_cache_mode=CACHE_MODE \
S3_URI > table_def

替换以下内容：

• DATA_FORMAT：任何受支持的 BigQuery 联合格式（例如 AVRO 或 CSV）。
• S3_URI：指向 Amazon S3 数据的 URI（例如 s3://bucket/path）。
• AWS_LOCATION：Google Cloud 中的 AWS 位置（例如 aws-us-east-1）。

• CONNECTION_NAME：您创建的连接的名称。

• CACHE_MODE：指定元数据缓存是自动刷新还是手动刷新。仅当您还计划在后续 bq mk 命令中使用 --max_staleness 标志来启用元数据缓存时，才需要添加此标志。 如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。

  如果设置为 AUTOMATIC，元数据缓存会按系统定义的间隔时间刷新，通常在 30 到 60 分钟之间。

  如果要根据您确定的时间表刷新元数据缓存，请设置为 MANUAL。在这种情况下，您可以调用 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系统过程来刷新缓存。 如果 STALENESS_INTERVAL 设置为大于 0 的值，您必须设置 CACHE_MODE。

注意：如需替换默认项目，请使用 --project_id=PROJECT_ID 参数。将 PROJECT_ID 替换为您的 Google Cloud 项目的 ID。

接下来，创建 BigLake 表：

bq mk --max_staleness=STALENESS_INTERVAL --external_table_definition=table_def DATASET_NAME.TABLE_NAME

替换以下内容：

• STALENESS_INTERVAL：指定对 BigLake 表执行的操作是否使用了缓存的元数据，以及操作使用的缓存元数据的新鲜度。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。

  如需停用元数据缓存，请指定 0。这是默认设置。

  如需启用元数据缓存，请指定 30 分钟到 7 天之间的间隔时间字面量值。例如，指定 INTERVAL 4 HOUR 表示 4 小时过时间隔时间。使用此值时，如果缓存的元数据在过去 4 小时内刷新，则对表执行的操作会使用缓存的元数据。如果缓存的元数据早于该值，则操作会改为从 Amazon S3 中检索元数据。

• DATASET_NAME：您创建的数据集的名称。

• TABLE_NAME：您要为此表指定的名称。

例如，以下命令会创建一个新的 BigLake 表 awsdataset.awstable，该表可以查询存储在路径 s3://s3-bucket/path/file.csv 中且在 aws-us-east-1 位置具有读取连接的 Amazon S3 数据：

bq mkdef  \
--autodetect \
--source_format=CSV \
--connection_id=aws-us-east-1.s3-read-connection \
--metadata_cache_mode=AUTOMATIC \
s3://s3-bucket/path/file.csv > table_def

bq mk --max_staleness=INTERVAL "1" HOUR \
--external_table_definition=table_def awsdataset.awstable

API

调用 tables.insert 方法 API 方法，并在传入的 Table 资源中创建 ExternalDataConfiguration。

指定 schema 属性或将 autodetect 属性设置为 true，为受支持的数据源启用架构自动检测功能。

指定 connectionId 属性以标识用于连接到 Amazon S3 的连接。

Java

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

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

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

// Sample to create an external aws table
public class CreateExternalTableAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String connectionId = "MY_CONNECTION_ID";
    String sourceUri = "s3://your-bucket-name/";
    CsvOptions options = CsvOptions.newBuilder().setSkipLeadingRows(1).build();
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    ExternalTableDefinition externalTableDefinition =
        ExternalTableDefinition.newBuilder(sourceUri, options)
            .setConnectionId(connectionId)
            .setSchema(schema)
            .build();
    createExternalTableAws(projectId, datasetName, tableName, externalTableDefinition);
  }

  public static void createExternalTableAws(
      String projectId,
      String datasetName,
      String tableName,
      ExternalTableDefinition externalTableDefinition) {
    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(projectId, datasetName, tableName);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, externalTableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Aws external table created successfully");

      // Clean up
      bigquery.delete(TableId.of(projectId, datasetName, tableName));
    } catch (BigQueryException e) {
      System.out.println("Aws external was not created." + e.toString());
    }
  }
}

对分区数据创建 BigLake 表

您可以在 Amazon S3 中为 Hive 分区数据创建 BigLake 表。创建外部分区表后，您便无法更改分区键。您需要重新创建表才能更改分区键。

如需根据 Hive 分区数据创建 BigLake 表，请选择以下选项之一：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在浏览器窗格中，展开您的项目，然后选择数据集。

3. 点击 查看操作，然后点击创建表。此时将打开创建表窗格。

4. 在来源部分，指定以下详细信息：

   1. 在基于以下数据创建表部分，选择 Amazon S3。

   2. 使用通配符提供文件夹的路径。例如 s3://mybucket/*。

      该文件夹必须与您要创建、附加或覆盖的表所属的数据集位于同一位置。

   3. 从文件格式列表中，选择文件类型。

   4. 选中源数据分区复选框，然后指定以下详细信息：

      1. 在选择来源 URI 前缀部分，输入 URI 前缀。例如 s3://mybucket/my_files。
      2. 可选：如需对此表的所有查询使用分区过滤条件，请选中需要分区过滤条件复选框。要求使用分区过滤条件可以减少费用并提高性能。如需了解详情，请参阅要求对查询中的分区键使用谓词过滤条件。

      3. 在分区推理模式部分中，选择以下选项之一：

         • 自动推断类型：将分区架构检测模式设置为 AUTO。
         • 所有列都是字符串：用于将分区架构检测模式设置为 STRINGS。
         • 自主提供：用于将分区架构检测模式设置为 CUSTOM，并手动输入分区键的架构信息。如需了解详情，请参阅提供自定义分区键架构。

5. 在目标部分，指定以下详细信息：

   1. 对于项目，选择要在其中创建表的项目。
   2. 在数据集部分，选择您要在其中创建表的数据集。
   3. 对于表，输入您要创建的表的名称。
   4. 在表类型部分，确认已选中外部表。
   5. 在连接 ID 部分，选择您之前创建的连接。

6. 在架构部分中，您可以启用架构自动检测功能，也可以手动指定架构（如果您拥有源文件）。如果您没有源文件，则必须手动指定架构。

   • 如需启用架构自动检测功能，请选择自动检测选项。

   • 如需手动指定架构，请让自动检测选项处于未选中状态。启用以文本形式修改，然后以 JSON 数组形式输入表架构。

7. 如需忽略额外列值与架构不匹配的行，请展开高级选项部分，然后选择未知值。

8. 点击创建表。

SQL

使用 CREATE EXTERNAL TABLE DDL 语句：

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

   转到 BigQuery

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

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
   WITH PARTITION COLUMNS
   (
     PARTITION_COLUMN PARTITION_COLUMN_TYPE,
   )
   WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS (
     hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
     uris=['FILE_PATH'],
     format ="TABLE_FORMAT"
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE'
   );
   

   替换以下内容：

   • PROJECT_ID：要在其中创建表的项目的名称，例如 myproject
   • DATASET：要在其中创建表的 BigQuery 数据集的名称，例如 mydataset
   • EXTERNAL_TABLE_NAME：要创建的表的名称，例如 mytable
   • PARTITION_COLUMN：分区列的名称
   • PARTITION_COLUMN_TYPE：分区列的类型
   • REGION：包含连接的区域，例如 us
   • CONNECTION_ID：Spark 连接的名称，例如 myconnection
   • HIVE_PARTITION_URI_PREFIX：Hive 分区 URI 前缀，例如：s3://mybucket/
   • FILE_PATH：要创建的外部表的数据源路径，例如：s3://mybucket/*.parquet
   • TABLE_FORMAT：要创建的表的格式，例如 PARQUET
   • STALENESS_INTERVAL：指定对 BigLake 表执行的操作是否使用了缓存的元数据，以及操作使用的缓存的元数据的新鲜度。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。

     如需停用元数据缓存，请指定 0。这是默认设置。

     如需启用元数据缓存，请指定 30 分钟到 7 天之间的间隔时间字面量值。例如，指定 INTERVAL 4 HOUR 表示 4 小时过时间隔时间。使用此值时，如果缓存的元数据在过去 4 小时内刷新，则对表执行的操作会使用缓存的元数据。如果缓存的元数据早于该值，则操作会改为从 Amazon S3 中检索元数据。

   • CACHE_MODE：指定元数据缓存是自动刷新还是手动刷新。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。

     如果设置为 AUTOMATIC，元数据缓存会按系统定义的间隔时间刷新，通常在 30 到 60 分钟之间。

     如果要根据您确定的时间表刷新元数据缓存，请设置为 MANUAL。在这种情况下，您可以调用 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系统过程来刷新缓存。

     如果 STALENESS_INTERVAL 设置为大于 0 的值，您必须设置 CACHE_MODE。

3. 点击 运行。

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

示例

以下示例基于 Amazon S3 中的分区数据创建了一个 BigLake 表。架构是自动检测的。

CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "s3://mybucket/products",
  uris = ['s3://mybucket/products/*']
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

bq

首先，使用 bq mkdef 命令创建表定义文件：

bq mkdef \
--source_format=SOURCE_FORMAT \
--connection_id=REGION.CONNECTION_ID \
--hive_partitioning_mode=PARTITIONING_MODE \
--hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 URIS > DEFINITION_FILE

替换以下内容：

• SOURCE_FORMAT：外部数据源的格式。例如 CSV。
• REGION：包含连接的区域，例如 us。
• CONNECTION_ID：Spark 连接的名称，例如 myconnection。
• PARTITIONING_MODE：Hive 分区模式。请使用下列其中一个值：
  • AUTO：自动检测键名称和类型。
  • STRINGS：自动将键名称转换为字符串。
  • CUSTOM：对来源 URI 前缀中的键架构进行编码。
• URI_SHARED_PREFIX：源 URI 前缀。

• BOOLEAN：指定查询时是否需要谓词过滤条件。此标志是可选标志。默认值为 false。

• CACHE_MODE：指定元数据缓存是自动刷新还是手动刷新。仅当您还计划在后续 bq mk 命令中使用 --max_staleness 标志来启用元数据缓存时，才需要添加此标志。 如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。

  如果设置为 AUTOMATIC，元数据缓存会按系统定义的间隔时间刷新，通常在 30 到 60 分钟之间。

  如果要根据您确定的时间表刷新元数据缓存，请设置为 MANUAL。在这种情况下，您可以调用 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系统过程来刷新缓存。 如果 STALENESS_INTERVAL 设置为大于 0 的值，您必须设置 CACHE_MODE。

• URIS：Amazon S3 文件夹的路径（使用通配符格式）。

• DEFINITION_FILE：本地机器上表定义文件的路径。

如果 PARTITIONING_MODE 为 CUSTOM，请使用以下格式将分区键架构包括在来源 URI 前缀中：

--hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...

创建表定义文件后，请使用 bq mk 命令来创建 BigLake 表：

bq mk --max_staleness=STALENESS_INTERVAL \
--external_table_definition=DEFINITION_FILE \
DATASET_NAME.TABLE_NAME \
SCHEMA

替换以下内容：

• STALENESS_INTERVAL：指定对 BigLake 表执行的操作是否使用了缓存的元数据，以及操作使用的缓存元数据的新鲜度。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。

  如需停用元数据缓存，请指定 0。这是默认设置。

  如需启用元数据缓存，请指定 30 分钟到 7 天之间的间隔时间字面量值。例如，指定 INTERVAL 4 HOUR 表示 4 小时过时间隔时间。使用此值时，如果缓存的元数据在过去 4 小时内刷新，则对表执行的操作会使用缓存的元数据。如果缓存的元数据早于该值，则操作会改为从 Amazon S3 中检索元数据。

• DEFINITION_FILE：表定义文件的路径。

• DATASET_NAME：包含该表的数据集的名称。

• TABLE_NAME：您要创建的表的名称。

• SCHEMA：指定 JSON 架构文件的路径，或者以 field:data_type,field:data_type,... 格式指定架构。如需使用架构自动检测功能，请省略此参数。

示例

以下示例对 Amazon S3 数据使用 AUTO Hive 分区模式：

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=AUTO \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/* > mytable_def

bq mk --max_staleness=INTERVAL "1" HOUR \
  --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

以下示例对 Amazon S3 数据使用 STRING Hive 分区模式：

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/myTable/* > mytable_def

bq mk --max_staleness=INTERVAL "1" HOUR \
  --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

如需使用 BigQuery API 设置 Hive 分区，请在创建表定义文件时在 ExternalDataConfiguration 对象中添加 hivePartitioningOptions 对象。如需创建 BigLake 表，您还必须指定 connectionId 字段的值。

如果将 hivePartitioningOptions.mode 字段设置为 CUSTOM，则必须在 hivePartitioningOptions.sourceUriPrefix 字段中对分区键架构进行如下所示的编码：s3://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

如需在查询时强制使用谓词过滤条件，请将 hivePartitioningOptions.requirePartitionFilter 字段设置为 true。

Delta Lake 表

预览

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

如需注册此预览版，请填写以下表单。

如需就此功能提供反馈或请求支持，请发送电子邮件至 [e-mail]。

Delta Lake 是一种支持 PB 级数据表的开源表格式。Delta Lake 表可以作为临时表和永久表进行查询，并且支持用作 BigLake 表。

架构同步

Delta Lake 维护规范化架构作为其元数据的一部分。您无法使用 JSON 元数据文件更新架构。如需更新架构，请执行以下操作：

1. 使用带有 --autodetect_schema 标志的 bq update 命令。

   bq update --autodetect_schema
   PROJECT_ID:DATASET.TABLE
   

   替换以下内容：

   • PROJECT_ID：要更新的表所属的项目的 ID

   • DATASET：包含要更新的表的数据集

   • TABLE：要更新的表

类型转换

BigQuery 会将 Delta Lake 数据类型转换为以下 BigQuery 数据类型：

Delta Lake 类型	BigQuery 类型
boolean	BOOL
byte	INT64
int	INT64
long	INT64
float	FLOAT64
double	FLOAT64
Decimal(P/S)	NUMERIC 或 BIG_NUMERIC，具体取决于精度
date	DATE
time	TIME
timestamp (not partition column)	TIMESTAMP
timestamp (partition column)	DATETIME
string	STRING
binary	BYTES
array<Type>	ARRAY<Type>
struct	STRUCT
map<KeyType, ValueType>	ARRAY<Struct<key KeyType, value ValueType>>

限制

以下限制适用于 Delta Lake 表：

• 外部表限制适用于 Delta Lake 表。

• Delta Lake 表仅在 BigQuery Omni 中受支持，并且具有相关限制。

• 您无法使用新的 JSON 元数据文件更新表，必须使用自动检测架构表更新操作。如需了解详情，请参阅架构同步。

• BigLake 安全功能仅在通过 BigQuery 服务访问时保护 Delta Lake 表。

创建 Delta Lake 表

以下示例使用具有 Delta Lake 格式的 CREATE EXTERNAL TABLE 语句创建外部表：

CREATE [OR REPLACE] EXTERNAL TABLE table_name
WITH CONNECTION connection_name
OPTIONS (
         format = 'DELTA_LAKE',
         uris = ["parent_directory"]
       );

替换以下内容：

• table_name：表格的名称。

• connection_name：连接的名称。连接必须标识 Amazon S3 或 Blob Storage 来源。

• parent_directory：父级目录的 URI。

使用 Delta Lake 进行跨云转移

以下示例使用 LOAD DATA 语句将数据加载到相应的表中：

LOAD DATA [INTO | OVERWRITE] table_name
FROM FILES (
        format = 'DELTA_LAKE',
        uris = ["parent_directory"]
)
WITH CONNECTION connection_name;

如需查看跨云数据传输的更多示例，请参阅通过跨云操作加载数据。

查询 BigLake 表

如需了解详情，请参阅查询 Amazon S3 数据。

查看资源元数据

预览

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

您可以使用 INFORMATION_SCHEMA 视图查看资源元数据。当您查询 JOBS_BY_*、JOBS_TIMELINE_BY_* 和 RESERVATION* 视图时，必须指定表区域所在的查询处理位置。如需了解 BigQuery Omni 位置，请参阅位置。对于所有其他系统表，不强制要求指定查询作业位置。

如需了解 BigQuery Omni 支持的系统表，请参阅限制。

如需查询 JOBS_* 和 RESERVATION* 系统表，请选择以下方法之一来指定处理位置：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 如果未显示编辑器标签页，则点击编写新查询。

3. 点击更多 > 查询设置。系统随即会打开查询设置对话框。

4. 在查询设置对话框中的其他设置 > 数据位置部分，选择 BigQuery Omni 区域所在的 BigQuery 区域。例如，如果 BigQuery Omni 区域为 aws-us-east-1，请指定 us-east4。

5. 选择其余字段，然后点击保存。

bq

使用 --location 标志可以将作业的处理位置设置为 BigQuery Omni 区域所在的 BigQuery 区域。 例如，如果 BigQuery Omni 区域为 aws-us-east-1，请指定 us-east4。

示例

bq query --use_legacy_sql=false --location=us-east4 \
"SELECT * FROM region-aws-us-east-1.INFORMATION_SCHEMA.JOBS limit 10;"

bq query --use_legacy_sql=false --location=asia-northeast3 \
"SELECT * FROM region-aws-ap-northeast-2.INFORMATION_SCHEMA.JOBS limit 10;"

API

如果您以编程方式运行作业，请将位置参数设置为 BigQuery Omni 区域所在的 BigQuery 区域。 例如，如果 BigQuery Omni 区域为 aws-us-east-1，请指定 us-east4。

以下示例列出了元数据刷新作业：

SELECT
 *
FROM
 `region-aws-us-east-1.INFORMATION_SCHEMA.JOBS_BY_PROJECT`
WHERE
 job_id LIKE '%metadata_cache_refresh%'
 AND creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 6 HOUR)
ORDER BY start_time desc
LIMIT 10;

VPC Service Controls

您可以使用 VPC Service Controls 边界来限制从 BigQuery Omni 对外部云服务的访问，作为一层额外的安全防御。例如，VPC Service Controls 边界可以限制从 BigQuery Omni 表到特定 Amazon S3 存储桶或 Blob Storage 容器的导出。

如需详细了解 VPC Service Controls，请参阅 VPC Service Controls 概览。

所需权限

确保您拥有配置服务边界所需的权限。如需查看配置 VPC Service Controls 所需的 IAM 角色列表，请参阅 VPC Service Controls 文档中的使用 IAM 进行访问权限控制。

使用 Google Cloud 控制台设置 VPC Service Controls

1. 在 Google Cloud 控制台导航菜单中，点击安全，然后点击 VPC Service Controls。

   转到 VPC Service Controls

2. 如需为 BigQuery Omni 设置 VPC Service Controls，请按照创建服务边界指南中的步骤操作，当您处于出站流量规则窗格中时，请按照以下步骤操作：

   1. 在出站流量规则面板中，点击添加规则。

   2. 在 API 客户端的属性部分中，从身份列表中选择一个选项。

   3. 选择转到外部资源的特性。

   4. 如需添加外部资源，请点击添加外部资源。

   5. 在添加外部资源对话框中，对于外部资源名称，输入有效的资源名称。例如：

      • 对于 Amazon Simple Storage Service (Amazon S3)：s3://BUCKET_NAME

        将 BUCKET_NAME 替换为您的 Amazon S3 存储桶的名称。

      • 对于 Azure Blob Storage：azure://myaccount.blob.core.windows.net/CONTAINER_NAME

        将 CONTAINER NAME 替换为 Blob Storage 容器的名称。

      如需查看出站规则特性的列表，请参阅出站规则参考。

   6. 选择您要在外部资源上允许的方法：

      1. 如果要允许所有方法，请选择方法列表中的所有方法。
      2. 如果要允许特定方法，请选择所选方法，点击选择方法，然后选择允许在外部资源中使用的方法。

   7. 点击创建边界。

使用 gcloud CLI 设置 VPC Service Controls

如需使用 gcloud CLI 设置 VPC Service Controls，请按照以下步骤操作：

1. 设置默认访问权限政策。
2. 创建出站流量政策输入文件
3. 添加出站流量政策。

设置默认访问权限政策

访问权限政策是规定访问权限级别和服务边界的组织范围容器。如需了解如何设置默认访问权限政策或获取访问权限政策名称，请参阅管理访问权限政策。

创建出站流量政策输入文件

出站规则块定义了允许从边界内对该边界外的资源进行的访问。对于外部资源，externalResources 属性定义了允许从 VPC Service Controls 边界内访问的外部资源路径。

您可以使用 JSON 文件或 YAML 文件配置出站规则。以下示例使用 .yaml 格式：

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
      *OR*
      - permission: "externalResource.read"
    externalResources:
      - EXTERNAL_RESOURCE_PATH
  egressFrom:
    identityType: IDENTITY_TYPE
    *OR*
    identities:
    - serviceAccount:SERVICE_ACCOUNT

• egressTo：列出允许对边界外的指定项目中的 Google Cloud 资源执行的服务操作。

• operations：列出允许满足 from 块条件的客户端访问的可访问服务和操作或方法。

• serviceName：为 BigQuery Omni 设置 bigquery.googleapis.com。

• methodSelectors：列出满足 from 条件的客户端可以访问的方法。如需查看服务的受限方法和权限，请参阅支持的服务方法限制。

• method：有效的服务方法，或 \"*\"，以允许所有 serviceName 方法。

• permission：有效的服务权限，例如 \"*\"、externalResource.read 或 externalResource.write。允许需要此权限的操作访问边界外的资源。

• externalResources：列出边界内的客户端可以访问的外部资源。将 EXTERNAL_RESOURCE_PATH 替换为有效的 Amazon S3 存储桶（例如 s3://bucket_name）或 Blob Storage 容器路径（例如 azure://myaccount.blob.core.windows.net/container_name）。

• egressFrom：列出允许对边界内的指定项目中的 Google Cloud 资源执行的服务操作。

• identityType 或 identities：定义可访问边界外的指定资源的身份类型。将 IDENTITY_TYPE 替换为下列其中一个有效值：

  • ANY_IDENTITY：允许所有身份。
  • ANY_USER_ACCOUNT：允许所有用户。
  • ANY_SERVICE_ACCOUNT：允许所有服务账号

• identities：列出可以访问边界外的指定资源的服务账号。

• serviceAccount（可选）：将 SERVICE_ACCOUNT 替换为可以访问边界外的指定服务账号的服务账号。

示例

以下示例是一项允许从边界内对 AWS 中的 s3://mybucket Amazon S3 位置执行出站操作的政策。

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - s3://mybucket
      - s3://mybucket2
  egressFrom:
    identityType: ANY_IDENTITY

以下示例允许对 Blob Storage 容器执行出站流量操作：

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - azure://myaccount.blob.core.windows.net/mycontainer
  egressFrom:
    identityType: ANY_IDENTITY

如需详细了解出站流量政策，请参阅出站规则参考。

添加出站流量政策

如需在创建新的服务边界时添加出站流量政策，请使用 gcloud access-context-manager perimeters create 命令。例如，以下命令会创建一个名为 omniPerimeter 的新边界，其中包含项目编号为 12345 的项目，限制 BigQuery API，并添加在 egress.yaml 文件中定义的出站流量政策：

gcloud access-context-manager perimeters create omniPerimeter \
    --title="Omni Perimeter" \
    --resources=projects/12345 \
    --restricted-services=bigquery.googleapis.com \
    --egress-policies=egress.yaml

如需将出站流量政策添加到现有服务边界，请使用 gcloud access-context-manager perimeters update 命令。例如，以下命令会将在 egress.yaml 文件中定义的出站流量政策添加到名为 omniPerimeter 的现有服务边界：

gcloud access-context-manager perimeters update omniPerimeter
    --set-egress-policies=egress.yaml

验证边界

如需验证边界，请使用 gcloud access-context-manager perimeters describe 命令：

gcloud access-context-manager perimeters describe PERIMETER_NAME

将 PERIMETER_NAME 替换为边界的名称。

例如，以下命令描述了边界 omniPerimeter：

gcloud access-context-manager perimeters describe omniPerimeter

如需了解详情，请参阅管理服务边界。

限制

如需查看适用于基于 Amazon S3 和 Blob Storage 的 BigLake 表的完整限制列表，请参阅限制。

后续步骤

• 了解 BigQuery Omni。
• 搭配使用 BigQuery Omni 和 AWS 实验。
• 了解 BigLake 表。
• 了解如何将查询结果导出到 Amazon S3。
• 了解如何通过 Amazon Simple Storage Service (Amazon S3) 元数据缓存表创建具体化视图。
• 了解如何通过创建具体化视图的副本使本地化视图中的 Amazon S3 数据可用于联接。