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

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

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

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

必要な権限

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

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

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

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

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

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

コンソール

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

    [BigQuery] ページに移動

  2. [エクスプローラ] パネルで、データセットを作成するプロジェクトを選択します。

  3. [アクション] オプションを開いて、[データセットを作成] をクリックします。

  4. [データセットを作成する] ページで、次の操作を行います。

    • [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 接続の作成に使用されるデータベース ロールをご覧ください。

    • その他のデフォルトの設定はそのままにします。

  5. [データセットを作成] をクリックします。

SQL

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

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. クエリエディタで次のステートメントを入力します。

    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）。データセットを作成した後に、そのロケーションを変更することはできません。

  3. [実行] をクリックします。

クエリの実行方法については、インタラクティブ クエリを実行するをご覧ください。

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

Terraform

google_bigquery_dataset リソースを使用します。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。

次の例では、Spanner 外部データセットを作成します。

resource "google_bigquery_dataset" "dataset" {
  provider                    = google-beta
  dataset_id                  = "example_dataset"
  friendly_name               = "test"
  description                 = "This is a test description."
  location                    = "us-central1"

external_dataset_reference {
  external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
  }
}

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

Cloud Shell を準備する

  1. Cloud Shell を起動します。

  2. Terraform 構成を適用するデフォルトの Google Cloud プロジェクトを設定します。

    このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Terraform 構成ファイルに明示的な値を設定すると、環境変数がオーバーライドされます。

ディレクトリを準備する

Terraform 構成ファイルには独自のディレクトリ（ルート モジュールとも呼ばれます）が必要です。

  1. Cloud Shell で、ディレクトリを作成し、そのディレクトリ内に新しいファイルを作成します。ファイルの拡張子は .tf にする必要があります（例: main.tf）。このチュートリアルでは、このファイルを main.tf とします。 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. チュートリアルを使用している場合は、各セクションまたはステップのサンプルコードをコピーできます。

    新しく作成した main.tf にサンプルコードをコピーします。

    必要に応じて、GitHub からコードをコピーします。Terraform スニペットがエンドツーエンドのソリューションの一部である場合は、この方法をおすすめします。

  3. 環境に適用するサンプル パラメータを確認し、変更します。
  4. 変更を保存します。
  5. Terraform を初期化します。これは、ディレクトリごとに 1 回だけ行います。
    terraform init

    最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。

    terraform init -upgrade

変更を適用する

  1. 構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。
    terraform plan

    必要に応じて構成を修正します。

  2. 次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。
    terraform apply

    Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。

  3. Google Cloud プロジェクトを開いて結果を表示します。Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

API

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

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

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

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

テーブル情報を取得する

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

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

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

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

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

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

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

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

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

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

制限事項

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

次のステップ