このページの情報の一部またはすべては、S3NS の Trusted Cloud には適用されない場合があります。

Spanner 外部データセットを作成する

このドキュメントでは、BigQuery で Spanner の既存のデータベースにリンクされる外部データセット（連携データセット）を作成する方法について説明します。

外部データセットは、BigQuery と外部データソース間のデータセットレベルでの接続です。これにより、Spanner から BigQuery ストレージにすべてのデータをコピーまたはインポートすることなく、GoogleSQL を使用して Spanner データベース内のトランザクションデータをクエリできます。これらのクエリ結果は BigQuery に保存されます。

外部データセット内のテーブルは、対応する外部データソース内のテーブルから自動的に入力されます。BigQuery では、これらのテーブルに対して直接クエリを実行できますが、変更、追加、削除はできません。ただし、外部データソースでの更新は、BigQuery に自動的に反映されます。

Spanner をクエリすると、クエリ結果はデフォルトで一時テーブルに保存されます。必要に応じて、新しい BigQuery テーブルとして保存したり、他のテーブルと結合したり、DML を使用して既存のテーブルと統合したりすることもできます。

必要な権限

外部データセットを作成するために必要な権限を取得するには、BigQuery ユーザー（roles/bigquery.user）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

この事前定義ロールには、外部データセットの作成に必要な bigquery.datasets.create 権限が含まれています。

カスタムロールや他の事前定義ロールを使用して、この権限を取得することもできます。

BigQuery における IAM ロールと権限の詳細については、IAM の概要をご覧ください。

`CLOUD_RESOURCE` 接続を使用する

必要に応じて、Spanner 外部データセットは CLOUD_RESOURCE 接続を使用して Spanner データベースとやり取りできます。これにより、ユーザーに Spanner データベースへの直接アクセス権を付与することなく、BigQuery を介して Spanner データへのアクセス権を付与できます。CLOUD_RESOURCE 接続のサービスアカウントが Spanner からデータを取得するため、ユーザーに Spanner 外部データセットへのアクセス権を付与するだけで済みます。

CLOUD_RESOURCE 接続を使用して Spanner 外部データセットを作成する前に、次の操作を行います。

接続を作成する

Spanner に接続するには、CLOUD_RESOURCE 接続を新たに作成するか、既存のものを使用します。Cloud リソース接続を作成するには、クラウドリソース接続を作成するの説明に沿って操作します。

接続を作成したらそれを開いて、[接続情報] ペインでサービスアカウント ID をコピーします。この ID は、接続の権限を構成するときに必要になります。接続リソースを作成すると、BigQuery は、一意のシステムサービスアカウントを作成し、それを接続に関連付けます。

アクセス権限を設定する

Spanner インスタンスまたはデータベースに対する読み取り権限を新しい接続に付与する必要があります。Cloud Spanner Database 読み取りと DataBoost（roles/spanner.databaseReaderWithDataBoost）の事前定義 IAM ロールを使用することをおすすめします。

接続からコピーしたサービスアカウントにデータベースレベルのロールのアクセス権を付与する手順は次のとおりです。

[Spanner インスタンス] ページに移動します。

インスタンスページに移動
データベースが含まれているインスタンスの名前をクリックして、[インスタンスの詳細] ページに移動します。
[概要] タブで、データベースのチェックボックスをオンにします。
情報パネルが表示されます。
[プリンシパルを追加] をクリックします。
[プリンシパルの追加] パネルの [新しいプリンシパル] に、前の手順でコピーしたサービスアカウント ID を入力します。
[ロールを選択] フィールドで、[Cloud Spanner Database Reader with DataBoost role] を選択します。
[保存] をクリックします。

外部データセットを作成する

外部データセットの作成手順は次のとおりです。

コンソール

Trusted Cloud コンソールで [BigQuery] ページを開きます。

[BigQuery] ページに移動
[エクスプローラ] パネルで、データセットを作成するプロジェクトを選択します。
アクション オプションを開いて、[データセットを作成] をクリックします。
[データセットを作成する] ページで、次の操作を行います。
- [データセット ID] に、データセットの一意の名前を入力します。
- [ロケーションタイプ] で、データセットのロケーション（us-central1 やマルチリージョンの us など）を選択します。データセットの作成後にロケーションを変更することはできません。
- [外部データセット] で、次の操作を行います。
  - [外部データセットへのリンク] の横にあるチェックボックスをオンにします。
  - [外部データセットのタイプ] で [Spanner] を選択します。
  - [外部ソース] に、Spanner データベースの完全な識別子を projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE の形式で入力します。例: projects/my_project/instances/my_instance/databases/my_database。
  - 省略可: [データベースロール] に、Spanner データベースロールの名前を入力します。詳細については、Spanner 接続の作成に使用されるデータベースロールをご覧ください。
  - 必要に応じて、[Cloud リソース接続を使用] の横にあるチェックボックスをオンにして、接続を使用して外部データセットを作成します。
- その他のデフォルトの設定はそのままにします。
[データセットを作成] をクリックします。

SQL

CREATE EXTERNAL SCHEMA データ定義言語（DDL）ステートメントを使用します。

Trusted 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 での新しいデータセットの名前。デフォルトプロジェクト以外のプロジェクト内にデータセットを作成するには、PROJECT_ID:DATASET_NAME の形式でそのプロジェクト ID をデータセット名に追加します。
（省略可）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 = ""
  }
}

Trusted Cloud プロジェクトで Terraform 構成を適用するには、次のセクションの手順を完了します。

Cloud Shell を準備する

Cloud Shell を起動します。
Terraform 構成を適用するデフォルトの Trusted Cloud プロジェクトを設定します。

このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。
```
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 を初期化します。これは、ディレクトリごとに 1 回だけ行います。
```
terraform init
```
最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。
```
terraform init -upgrade
```

変更を適用する

構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。
```
terraform plan
```
必要に応じて構成を修正します。
次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。
```
terraform apply
```
Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。
Trusted Cloud プロジェクトを開いて結果を表示します。 Trusted Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

API

datasets.insert メソッドを、定義済みのデータセットリソースと Spanner データベースの externalDatasetReference フィールドを指定して呼び出します。

外部データセット内のテーブル名は、大文字と小文字が区別されません。

CLOUD_RESOURCE 接続を使用して外部データセットを作成する場合は、外部データセットで使用される接続に対する bigquery.connections.delegate 権限（BigQuery Connection 管理者ロールに含まれる）が必要です。

テーブルへのアクセスの制御

Spanner 外部データセットは、エンドユーザー認証情報（EUC）をサポートしています。つまり、外部データセットからの Spanner テーブルへのアクセスは Spanner によって制御されます。ユーザーは、Spanner でアクセス権が付与されている場合にのみ、これらのテーブルに対してクエリを実行できます。

Spanner 外部データセットは、アクセス権の委任もサポートしています。アクセス権の委任により、Spanner テーブルへのアクセスが外部データセットと基盤となる Spanner テーブルへの直接アクセスから切り離されます。Spanner への接続には、サービスアカウントに関連付けられたクラウドリソース接続が使用されます。ユーザーは、Spanner でアクセス権が付与されていない場合でも、外部データセットからこれらの Spanner テーブルに対してクエリを実行できます。

外部データセット内のテーブルを一覧取得する

外部データセット内のクエリに使用できるテーブルを一覧取得するには、データセットの一覧取得をご覧ください。

テーブル情報の取得

スキーマの詳細など、外部データセット内のテーブルの情報を取得するには、テーブル情報の取得をご覧ください。

Spanner データにクエリを実行する

外部データセット内のテーブルのクエリは、他の BigQuery データセット内のテーブルに対するクエリと同じです。ただし、データ変更オペレーション（DML）はサポートされていません。

Spanner 外部データセット内のテーブルに対するクエリでは、デフォルトで Data Boost が使用されます。これは変更できません。そのため、このようなクエリを実行するには追加の権限が必要です。

外部データセットにビューを作成する

外部データセット内にはビューを作成できません。一方、外部データセットのテーブルに基づく標準データセットには、ビューを作成できます。詳細については、ビューの作成をご覧ください。

外部データセットを削除する

外部データセットの削除は、他の BigQuery データセットの削除と同じです。外部データセットを削除しても、Spanner データベース内のテーブルには影響しません。詳細については、データセットの削除をご覧ください。

制限事項

BigQuery 連携クエリの制限事項が適用されます。
BigQuery でアクセスできるのは、デフォルトの Spanner スキーマのテーブルのみです。名前スキーマのテーブルはサポートされていません。
Spanner データベースで定義された主キーと外部キーは BigQuery に表示されません。
Spanner データベースのテーブルに、BigQuery でサポートされていない型の列が含まれている場合、この列には BigQuery 側からアクセスできません。
Spanner 外部データセットのテーブル内のデータやメタデータは、追加、削除、更新できません。
Spanner 外部データセットには、新しいテーブル、ビュー、マテリアライズドビューを作成できません。
INFORMATION_SCHEMA ビューはサポートされていません。
メタデータのキャッシュ保存はサポートされていません。
テーブルの作成のデフォルトに関連するデータセットレベルの設定は、テーブルを手動で作成できないため、外部データセットには影響しません。
PostgreSQL 言語を使用する Spanner データベースはサポートされていません。
Write API と Read API はサポートされていません。
行レベルのセキュリティ、列レベルのセキュリティ、データマスキングはサポートされていません。
Spanner 外部データセットのテーブルに基づくマテリアライズドビューはサポートされていません。
Dataplex Universal Catalog とのインテグレーションはサポートされていません。たとえば、データプロファイルとデータ品質スキャンはサポートされていません。
テーブルレベルのタグはサポートされていません。
クエリの作成時に、Spanner 外部テーブルで SQL 自動補完は機能しません。
Sensitive Data Protection によるスキャンは、外部データセットではサポートされていません。
外部データセットでは、BigQuery Sharing（旧 Analytics Hub）との共有はサポートされていません。
Spanner 外部データセットがエンドユーザー認証情報（EUC）を使用している場合は、外部データセットを参照する承認済みビューを作成できます。ただし、このビューに対してクエリが実行されると、クエリを実行したユーザーの EUC が Spanner に送信されます。
Spanner 外部データセットがアクセス権の委任に Cloud リソース接続を使用している場合は、その外部データセットを参照する承認済みビューまたは承認済みルーティンを作成できます。

次のステップ

Spanner 連携クエリの詳細を確認する。