此页面由 Cloud Translation API 翻译。

创建 Spanner 外部数据集

本文档介绍如何在 BigQuery 中创建与 Spanner 中的现有数据库关联的外部数据集（也称为联合数据集）。

外部数据集是 BigQuery 与外部数据源之间在数据集级层的连接。借助它，您可以使用 GoogleSQL 查询 Spanner 数据库中的事务数据，而无需将数据从 Spanner 移至 BigQuery 存储空间。

系统会根据相应的外部数据源中的表自动填充外部数据集中的表。您可以直接在 BigQuery 中查询这些表，但无法执行修改、添加或删除操作。但是，您在外部数据源中进行的任何更新都会自动反映在 BigQuery 中。

所需权限

如需获得创建外部数据集所需的权限，请让您的管理员为您授予 BigQuery User (roles/bigquery.user) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含 bigquery.datasets.create 权限，这是创建外部数据集所必需的。

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

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

创建外部数据集

如需创建外部数据集，请执行以下操作：

控制台

在 Google Cloud 控制台中打开 BigQuery 页面。

转到 BigQuery 页面
在探索器面板中，选择您要在其中创建数据集的项目。
展开操作选项，然后点击创建数据集。
在 创建数据集 页面上，执行以下操作：
- 对于 Dataset ID，输入唯一的数据集名称。
- 对于位置类型，为数据集选择一个位置，例如 us-central1 或多区域 us。创建数据集后，此位置无法再更改。
- 对于外部数据集，请执行以下操作：
  - 勾选指向外部数据集的链接旁边的复选框。
  - 对于外部数据集类型，选择 Spanner。
  - 对于外部来源，请输入 Spanner 数据库的完整标识符，格式如下：projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE。例如：projects/my_project/instances/my_instance/databases/my_database。
  - （可选）对于数据库角色，输入 Spanner 数据库角色的名称。如需了解详情，请参阅用于创建 Spanner 连接的数据库角色
- 将其他默认设置保持不变。
点击创建数据集。

SQL

使用 CREATE EXTERNAL SCHEMA 数据定义语言 (DDL) 语句。

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

转到 BigQuery
在查询编辑器中，输入以下语句：
```
CREATE EXTERNAL SCHEMA DATASET_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');
```
替换以下内容：
- DATASET_NAME：BigQuery 中的新数据集的名称。
- SPANNER_EXTERNAL_SOURCE：完全限定的 Spanner 数据库名称，其中包含用于标识来源的前缀，格式如下：google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE。例如：google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database 或 google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database。
- LOCATION：BigQuery 中的新数据集的位置，例如 us-central1。创建数据集后，您无法更改其位置。
点击运行。

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

bq

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

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    DATASET_NAME

替换以下内容：

LOCATION：BigQuery 中的新数据集的位置，例如 us-central1。创建数据集后，您无法更改其位置。您可以使用 .bigqueryrc 文件设置默认位置值。
SPANNER_EXTERNAL_SOURCE：完全限定的 Spanner 数据库名称，其中包含用于标识来源的前缀，格式如下：google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE。例如：google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database 或 google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database。
DATASET_NAME：BigQuery 中的新数据集的名称。如需在非默认项目中创建数据集，请按照以下格式将项目 ID 添加到数据集名称：PROJECT_ID:DATASET_NAME。

Terraform

使用 google_bigquery_dataset 资源。

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

以下示例创建了一个 Spanner 外部数据集：

resource "google_bigquery_dataset" "default" {
  dataset_id    = "my_external_dataset"
  friendly_name = "My external dataset"
  description   = "This is a test description."
  location      = "US"
  external_dataset_reference {
    # The full identifier of your Spanner database.
    external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
    # Must be empty for a Spanner external dataset.
    connection = ""
  }
}

如需在 Google Cloud 项目中应用 Terraform 配置，请完成以下部分中的步骤。

准备 Cloud Shell

启动 Cloud Shell。
设置要在其中应用 Terraform 配置的默认 Google Cloud 项目。

您只需为每个项目运行一次以下命令，即可在任何目录中运行它。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录（也称为“根模块”）。

在 Cloud Shell 中，创建一个目录，并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名，例如 main.tf。在本教程中，该文件称为 main.tf。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
如果您按照教程进行操作，可以在每个部分或步骤中复制示例代码。

将示例代码复制到新创建的 main.tf 中。

（可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。
查看和修改要应用到您的环境的示例参数。
保存更改。
初始化 Terraform。您只需为每个目录执行一次此操作。
```
terraform init
```
（可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：
```
terraform init -upgrade
```

应用更改

查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：
```
terraform plan
```
根据需要更正配置。
通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：
```
terraform apply
```
等待 Terraform 显示“应用完成！”消息。
打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

API

调用 datasets.insert 方法，并指定 Spanner 数据库的数据集资源和 externalDatasetReference 字段。

请注意，外部数据集中的表名称不区分大小写。

列出外部数据集中的表

如需列出外部数据集中可用于查询的表，请参阅列出数据集。

获取表信息

如需获取外部数据集中的表的相关信息（例如架构详细信息），请参阅获取表信息。

控制对表的访问权限

Spanner 外部数据集支持最终用户凭据 (EUC)。这意味着，对外部数据集的 Spanner 表的访问权限由 Spanner 控制。只有在 Spanner 中获得访问权限后，用户才能查询这些表。

查询 Spanner 数据

查询外部数据集中的表的方法与查询任何其他 BigQuery 数据集中的表相同。不过，不支持数据修改操作 (DML)。

对 Spanner 外部数据集中表的查询默认使用 Data Boost，且无法更改。因此，您需要额外权限才能运行此类查询。

在外部数据集中创建视图

您无法在外部数据集中创建视图。不过，您可以在标准数据集中创建基于外部数据集中的表的视图。如需了解详情，请参阅创建视图。

删除外部数据集

删除外部数据集的方法与删除任何其他 BigQuery 数据集相同。删除外部数据集不会影响 Spanner 数据库中的表。如需了解详情，请参阅删除数据集。

限制

需遵循 BigQuery 联合查询限制。
在 BigQuery 中，只能访问默认 Spanner 架构中的表。不支持名称架构中的表。
如果 Spanner 数据库中的表包含 BigQuery 不支持的类型的列，则 BigQuery 端将无法访问此列。
您无法在 Spanner 外部数据集中的表中添加、删除或更新数据或元数据。
您无法在 Spanner 外部数据集中创建新表、视图或具体化视图。
不支持 INFORMATION_SCHEMA 视图。
不支持元数据缓存。
与表创建默认设置相关的数据集级设置不会影响外部数据集，因为您无法手动创建表。
不支持使用 PostgreSQL 方言的 Spanner 数据库。
不支持 Write API 和 Read API。
不支持行级安全性、列级安全性和数据遮盖。
不支持基于 Spanner 外部数据集中的表的具体化视图。
不支持与 Dataplex 集成。例如，不支持数据配置文件和数据质量扫描。
不支持表级标记。
在编写查询时，SQL 自动补全功能不适用于 Spanner 外部表。
外部数据集不支持使用敏感数据保护功能进行扫描。
您可以创建引用 Spanner 外部数据集的授权视图。不过，当查询此视图时，系统会将执行查询的用户的 EUC 发送到 Spanner。

后续步骤

详细了解 Spanner 联合查询。