Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 Data Boost 執行聯合查詢

本頁面說明如何從 BigQuery 對 Spanner 資料庫執行聯合查詢時，使用 Spanner Data Boost。有了 Data Boost，聯合查詢執行時，對已佈建 Spanner 執行個體上現有工作負載的影響極小。從 BigQuery 到 Spanner 資料庫的 Data Boost 查詢，可彙整 BigQuery 資料與 Spanner 資料。

您可以使用 Data Boost，透過下列任一方法，從 BigQuery 對 Spanner 執行聯合查詢：

執行聯合 Data Boost 查詢，這項查詢會使用 EXTERNAL_QUERY 聯合查詢函式。
搭配外部資料集使用 Data Boost。

Spanner 聯合查詢可讓 BigQuery 即時查詢 Spanner 中的資料，不必複製或移動資料。如要進一步瞭解 Spanner 聯合查詢，請參閱「 Spanner 聯合查詢」。如要瞭解 Data Boost，請參閱「Data Boost 總覽」。

事前準備

您必須先完成下列工作，才能使用 Data Boost 執行聯合查詢：

建立 Spanner 執行個體和資料庫。
啟用 BigQuery Connection API。
授予必要的 Identity and Access Management (IAM) 權限。

建立 Spanner 執行個體和資料庫

如果您沒有 Spanner 執行個體和資料庫，請按照「使用 Google Cloud 控制台建立及查詢資料庫」中的步驟建立。

啟用 BigQuery Connection API

BigQuery Connection API 可讓您管理 BigQuery 與外部資料來源 (例如 Spanner 資料庫) 的連線。

啟用 BigQuery Connection API (如果尚未啟用)。
啟用 API 所需的角色
您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
啟用 API

詳情請參閱 BigQuery 說明文件中的「BigQuery Connection API」。

將 Data Boost 的 IAM 權限授予主體

主體必須具備下列權限，才能透過 Data Boost 執行聯合查詢：

spanner.instances.get：可取得執行個體的設定。
spanner.databases.useDataBoost：可讓您使用 Data Boost 運算資源處理分區查詢。

如要進一步瞭解 Spanner 權限，請參閱「IAM 權限」。

如要授予這些必要權限，建議您使用 Cloud Spanner Database Reader With DataBoost (roles/spanner.databaseReaderWithDataBoost) IAM 角色。您可以將該角色新增至任何需要透過 Data Boost 執行聯合查詢的主體。如要進一步瞭解 Spanner 的預先定義角色，請參閱「預先定義的角色」。如要瞭解如何建立自訂 IAM 角色，請參閱「建立自訂角色」。

執行聯合 Data Boost 查詢

如要從 BigQuery 對外部來源執行 Data Boost 查詢，您必須建立 BigQuery 與外部來源的連線，並取得連線 ID。使用 Data Boost 執行 Spanner 聯合查詢時，外部來源是 Spanner 資料庫。建立連線 ID 後，BigQuery 會使用該 ID 執行 Spanner 資料庫的 Data Boost 查詢。

請使用下列任一選項建立 BigQuery 連線 ID，然後使用該 ID 從 BigQuery 執行 Data Boost 查詢：

從 Spanner 開始：在 Spanner 控制台中建立 BigQuery 外部連線 ID。在 Spanner 控制台建立連線 ID 後，系統會將您重新導向至 BigQuery 控制台，對 Spanner 資料庫執行 Data Boost 聯合查詢。
從 BigQuery 開始：在 BigQuery 控制台或使用 bq 指令列工具，建立 Data Boost 外部連線 ID。建立連線 ID 後，請留在 BigQuery 控制台，對 Spanner 資料庫執行 Data Boost 聯合查詢。

在 Spanner 中執行 Data Boost 查詢

如要從 Spanner Studio 執行 Data Boost 聯合查詢，請按照下列步驟操作：

前往Google Cloud 控制台的 Spanner「Instances」(執行個體) 頁面。

前往「Instances」(執行個體) 頁面

控制台會顯示 Spanner 執行個體清單。
選取 Spanner 執行個體，然後選取資料庫。
在「Database overview」(資料庫總覽) 頁面的導覽選單中，按一下「Spanner Studio」。
按一下「在 BigQuery 中查看」。
在「View in BigQuery」(在 BigQuery 中查看) 對話方塊中，輸入連線 ID。

連線 ID 是用來建立連至 Spanner 資料庫的新 BigQuery 外部連線。請使用下列模式參照外部連線：
```
PROJECT-ID.LOCATION.CONNECTION-ID
```
如果 ID 已存在，系統會顯示錯誤訊息。
填寫對話方塊中的其餘部分，並執行下列操作：
- 選取「Read data in parallel」(並行讀取資料)。
- 選取「使用 Spanner Data Boost」。

按一下「在 BigQuery 中查看」。

BigQuery Studio 隨即開啟，並顯示下列查詢：

SELECT * FROM EXTERNAL_QUERY("PROJECT-ID.LOCATION.CONNECTION-ID", "SELECT * FROM INFORMATION_SCHEMA.TABLES;");

您可以將其替換為聯合查詢。例如，您可以建立類似下列範例的查詢。這個範例會從 Spanner 資料庫中名為 orders 的資料表執行聯合查詢，並將結果與名為 mydataset.customers 的 BigQuery 資料表彙整。

SELECT c.customer_id, c.name, rq.first_order_date
FROM mydataset.customers AS c
LEFT OUTER JOIN EXTERNAL_QUERY(
  'my-project.us.example-db',
  '''SELECT customer_id, MIN(order_date) AS first_order_date
  FROM orders
  GROUP BY customer_id''') AS rq
  ON rq.customer_id = c.customer_id
GROUP BY c.customer_id, c.name, rq.first_order_date;

在 BigQuery 執行 Data Boost 查詢

如要建立從 BigQuery 到 Spanner 資料庫的外部資料連線，並使用該連線從 BigQuery 執行 Data Boost 聯合查詢，請選取下列其中一個選項：

控制台

請參閱 BigQuery 說明文件中的「建立 Spanner 連線」，並按照「控制台」分頁中的操作說明操作。
在「外部資料來源」窗格中，執行下列操作：
- 選取「Read data in parallel」(並行讀取資料)。
- 選取「使用 Spanner Data Boost」。

bq

請參閱 BigQuery 說明文件中的「建立 Spanner 連線」一節，並按照「bq」* 分頁中的操作說明操作。
將下列連線屬性設為 true：
- useParallelism
- useDataBoost

下列範例使用 bq mk 指令建立名為 my_connection 的新連線，並設定 Data Boost 的兩項必要屬性：

bq mk --connection --connection_type='CLOUD_SPANNER' --location='us' \
--properties='{"database":"projects/my-project/instances/my-instance/databases/my-database", "useParallelism":true, "useDataBoost": true}' my_connection

搭配外部資料集使用 Data Boost

如要從 BigQuery 執行 Data Boost 查詢，並將 Spanner 做為外部來源，您可以在 BigQuery 中建立外部資料集 (也稱為聯合資料集)，並連結至 Spanner 中現有的 GoogleSQL 或 PostgreSQL 資料庫。

使用 `CLOUD_RESOURCE` 連線

根據預設，Spanner 外部資料集會使用使用者憑證 (EUC)，因此使用者必須能直接存取 Spanner 資料庫。使用者只要在 Spanner 取得存取權，就能查詢這些資料集。

Spanner 外部資料集可視需要使用 CLOUD_RESOURCE 連線與 Spanner 資料庫互動，這樣您就能透過 BigQuery 為使用者提供 Spanner 資料存取權，而不必直接授予 Spanner 資料庫存取權。CLOUD_RESOURCE 連線的服務帳戶會負責從 Spanner 擷取資料，因此您只需授予使用者 Spanner 外部資料集的存取權。這項存取權委派功能可將 Spanner 資料表的存取權，與外部資料集和基礎 Spanner 資料表的直接存取權分開。與服務帳戶相關聯的 Cloud 資源連結，用於連線至 Spanner。即使使用者未獲授予 Spanner 存取權，仍可從外部資料集查詢這些 Spanner 資料表。

使用 CLOUD_RESOURCE 連線建立 Spanner 外部資料集前，請先完成下列操作：

建立連線

您可以建立或使用現有的 CLOUD_RESOURCE 連線，連線至 Spanner。請務必在您打算建立 Spanner 外部資料集的位置建立連線。

選取下列選項之一：

控制台

前往「BigQuery」頁面。

前往「BigQuery」
點選左側窗格中的「Explorer」。

如果沒有看到左側窗格，請按一下「Expand left pane」(展開左側窗格)，開啟窗格。
在「Explorer」窗格中展開專案名稱，然後點選「Connections」(連線)。
在「Connections」(連線) 頁面，按一下「Create connection」(建立連線)。
在「連線類型」部分，選擇「Vertex AI 遠端模型、遠端函式、BigLake 和 Spanner (Cloud 資源)」。
在「連線 ID」欄位輸入連線名稱。
在「位置類型」部分，選取連線位置。連線應與資料集等其他資源位於相同位置。
點選「建立連線」。
點選「前往連線」。
在「連線資訊」窗格中，複製服務帳戶 ID，以便在後續步驟中使用。

SQL

使用 CREATE CONNECTION 陳述式：

前往 Google Cloud 控制台的「BigQuery」頁面。

前往「BigQuery」
在查詢編輯器中輸入下列陳述式：
```
CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
OPTIONS (
  connection_type = "CLOUD_RESOURCE",
  friendly_name = "FRIENDLY_NAME",
  description = "DESCRIPTION"
  );
```
替換下列內容：
- CONNECTION_NAME：連線名稱，格式為 PROJECT_ID.LOCATION.CONNECTION_ID、LOCATION.CONNECTION_ID 或 CONNECTION_ID。如果省略專案或位置，系統會根據執行陳述式的專案和位置推論。
- FRIENDLY_NAME (選用)：連線的描述性名稱。
- DESCRIPTION (選用)：連線說明。
按一下「執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

bq

在指令列環境中建立連線：
```
bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID
```
--project_id 參數會覆寫預設專案。

更改下列內容：
- REGION：連線區域
- PROJECT_ID：您的 Google Cloud 專案 ID
- CONNECTION_ID：連線 ID
建立連線資源時，BigQuery 會建立專屬的系統服務帳戶，並與連線建立關聯。

疑難排解：如果收到下列連線錯誤，請更新 Google Cloud SDK：
```
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
```

擷取並複製服務帳戶 ID，以便在後續步驟中使用：

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

輸出結果會與下列內容相似：

name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Python

如要瞭解如何安裝及使用 Spanner 的用戶端程式庫，請參閱「Spanner 用戶端程式庫」。

如要向 Spanner 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

如要瞭解如何安裝及使用 Spanner 的用戶端程式庫，請參閱「Spanner 用戶端程式庫」。

如要向 Spanner 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

Java

如要瞭解如何安裝及使用 Spanner 的用戶端程式庫，請參閱「Spanner 用戶端程式庫」。

如要向 Spanner 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.connection.v1.CloudResourceProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

public class CreateConnection {

  /**
   * Creates a BigQuery connection to a Cloud Resource. A Cloud Resource connection provisions a
   * service account that can be granted access to other Google Cloud resources for federated
   * queries.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the connection (for example, "us-central1").
   * @param connectionId The ID of the connection to create (for example, "example-connection-id").
   */
  public static void createConnection(String projectId, String location, String connectionId) {
    LocationName parent = LocationName.of(projectId, location);

    // CloudResourceProperties provisions a managed Google Cloud service account on creation.
    CloudResourceProperties cloudResourceProperties = CloudResourceProperties.newBuilder().build();
    Connection connection =
        Connection.newBuilder()
            .setFriendlyName("Example Connection")
            .setDescription("Cloud Resource connection for federated queries.")
            .setCloudResource(cloudResourceProperties)
            .build();

    CreateConnectionRequest request =
        CreateConnectionRequest.newBuilder()
            .setParent(parent.toString())
            .setConnectionId(connectionId)
            .setConnection(connection)
            .build();

    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      Connection response = client.createConnection(request);

      System.out.printf("Successfully created connection: %s%n", response.getName());
      System.out.printf("Friendly name: %s%n", response.getFriendlyName());
      System.out.printf(
          "Service Account: %s%n", response.getCloudResource().getServiceAccountId());
    } catch (AlreadyExistsException err) {
      System.err.printf(
          "error: connection '%s' already exists in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to create connection '%s' in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    }
  }

Terraform

使用 google_bigquery_connection 資源。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

下列範例會在 US 區域建立名為 my_cloud_resource_connection 的 Cloud 資源連結：


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

如要在 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 顯示「Apply complete!」訊息。
開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

建立連線後，請開啟連線，然後在「Connection info」(連線資訊) 窗格中複製服務帳戶 ID。設定連線權限時，會需要這個 ID。建立連線資源時，BigQuery 會建立專屬的系統服務帳戶，並與連線建立關聯。

設定存取權

您必須為與新連線相關聯的服務帳戶，授予 Spanner 執行個體或資料庫的讀取權限。建議使用 Cloud Spanner 資料庫讀取者 (使用 Data Boost) (roles/spanner.databaseReaderWithDataBoost) 預先定義的 IAM 角色。

請按照下列步驟，將資料庫層級角色的存取權，授予先前從連線複製的服務帳戶：

前往 Spanner 的「Instances」(執行個體) 頁面。

前往執行個體頁面
點選包含您的資料庫的執行個體名稱，前往「執行個體詳細資料」頁面。
在「Overview」(總覽) 分頁中，勾選資料庫的核取方塊。
「Info panel」(資訊面板) 隨即顯示。
按一下「Add principal」(新增主體)。
在「新增主體」面板的「新增主體」部分，輸入先前複製的服務帳戶 ID。
在「請選擇角色」欄位，選取「Cloud Spanner 資料庫讀取者 (使用 Data Boost)」角色。
按一下 [儲存]。

建立外部資料集

如要建立外部資料集，請按照下列步驟操作：

控制台

在 Google Cloud 控制台開啟「BigQuery」頁面。

前往「BigQuery」頁面
點選左側窗格中的「Explorer」。

如果沒有看到左側窗格，請按一下「Expand left pane」(展開左側窗格)，開啟窗格。
在「Explorer」窗格中，選取要建立資料集的專案。
按一下「View actions」(查看動作)，然後點選「Create dataset」(建立資料集)。
在「Create dataset」(建立資料集) 頁面執行下列操作：
- 針對「Dataset ID」(資料集 ID)，輸入唯一的資料集名稱。
- 在「Location type」(位置類型) 部分，選擇資料集的位置，例如 us-central1 或多區域 us。資料集建立後即無法變更位置。
- 針對「External Dataset」(外部資料集)，執行下列操作：
  - 勾選「連結至外部資料集」旁的方塊。
  - 在「External dataset type」(外部資料集類型) 部分，選取「Spanner」。
  - 在「外部來源」部分，按照下列格式輸入 Spanner 資料庫的完整 ID：projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE。例如：projects/my_project/instances/my_instance/databases/my_database。
  - 您也可以在「Database role」(資料庫角色) 輸入 Spanner 資料庫角色名稱。如要進一步瞭解用於建立 Spanner 連線的資料庫角色，請參閱相關說明
  - (選用) 勾選「使用 Cloud 資源連結」旁的方塊，即可使用連結建立外部資料集。
- 其他設定均保留預設值。
點選「建立資料集」。

SQL

使用 CREATE EXTERNAL SCHEMA 資料定義語言 (DDL) 陳述式。

前往 Google Cloud 控制台的「BigQuery」頁面。

前往「BigQuery」
在查詢編輯器中輸入下列陳述式：
```
CREATE EXTERNAL SCHEMA DATASET_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');
/*
  Alternatively, create with a connection:
*/
CREATE EXTERNAL SCHEMA DATASET_NAME
  WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_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。資料集建立後即無法變更位置。
- (選用)CONNECTION_NAME：Cloud 資源連結的名稱。
按一下「執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

bq

在指令列環境中，使用 bq mk 指令建立外部資料集：

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

或者，您也可以使用連線建立：

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    --connection_id PROJECT_ID.LOCATION.CONNECTION_NAME \
    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。
(選用)CONNECTION_NAME：Cloud 資源連結的名稱。

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 顯示「Apply complete!」訊息。
開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

API

使用定義的資料集資源和 Spanner 資料庫的 externalDatasetReference 欄位，呼叫 datasets.insert 方法。

請注意，外部資料集中的資料表名稱不區分大小寫。

使用 CLOUD_RESOURCE 連線建立外部資料集時，您必須具備外部資料集所用連線的 bigquery.connections.delegate 權限 (可透過 BigQuery 連線管理員角色取得)。

根據外部資料集的資料表，建立非漸進式 materialized view

繼續操作前，請務必使用 CLOUD_RESOURCE 連線建立基礎 Spanner 外部資料集。

您可以使用 allow_non_incremental_definition 選項，建立參照 Spanner 外部資料集資料表的非增量 materialized view。以下範例使用基礎 Spanner 外部資料集資料表：

/*
  You must create the spanner_external_dataset with a CLOUD_RESOURCE connection.
*/
CREATE MATERIALIZED VIEW sample_dataset.sample_spanner_mv
  OPTIONS (
      enable_refresh = true, refresh_interval_minutes = 60,
      max_staleness = INTERVAL "24" HOUR,
        allow_non_incremental_definition = true)
AS
  SELECT COUNT(*) cnt FROM spanner_external_dataset.spanner_table;

只有 BigQuery 非增量 materialized view，才能以 Spanner 外部資料集資料表做為基礎資料表。如果非增量 materialized view 的上次重新整理時間超出 max_staleness 間隔，查詢就會讀取基礎 Spanner 外部資料集資料表。進一步瞭解 BigQuery 非漸進式 materialized view。

後續步驟

如要瞭解 Data Boost，請參閱「Data Boost 總覽」
在應用程式中使用 Data Boost
監控 Data Boost 用量
監控及管理 Data Boost 配額用量
進一步瞭解 Spanner 外部資料集。
進一步瞭解如何依據 Spanner 外部資料集建立 materialized view。

使用 Data Boost 執行聯合查詢 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

建立 Spanner 執行個體和資料庫

啟用 BigQuery Connection API

將 Data Boost 的 IAM 權限授予主體

執行聯合 Data Boost 查詢

在 Spanner 中執行 Data Boost 查詢

在 BigQuery 執行 Data Boost 查詢

控制台

bq

搭配外部資料集使用 Data Boost

使用 CLOUD_RESOURCE 連線

建立連線

控制台

SQL

bq

Python

Node.js

Java

Terraform

準備 Cloud Shell

準備目錄

套用變更

設定存取權

建立外部資料集

控制台

SQL

bq

Terraform

準備 Cloud Shell

準備目錄

套用變更

API

根據外部資料集的資料表，建立非漸進式 materialized view

後續步驟

使用 Data Boost 執行聯合查詢

使用 `CLOUD_RESOURCE` 連線