Spanner に接続する
BigQuery 管理者は、接続を作成して Spanner データにアクセスできます。この接続により、データ アナリストは Spanner のデータにクエリを実行できるようになります。
始める前に
- BigQuery Connection API を有効にします。
-
Spanner への接続に必要な権限を取得するには、プロジェクトに BigQuery 接続管理者(
roles/bigquery.connectionAdmin
)の IAM ロールを付与するよう管理者に依頼してください。ロールの付与の詳細については、アクセス権の管理をご覧ください。
Spanner 接続を作成する
次のオプションのいずれかを選択します。
コンソール
[BigQuery] ページに移動します。
[エクスプローラー] ペインで
[追加] をクリックし、[外部データソースへの接続] を選択します。[外部データソース] ペインで、次の情報を入力します。
- [接続タイプ] で [Cloud Spanner] を選択します。
- [接続 ID] に、接続リソースの識別子を入力します。文字、数字、アンダースコアを使用できます。
- [ロケーション タイプ] として、外部データソースのリージョンと互換性のある BigQuery ロケーション(またはリージョン)を選択します。
- (省略可)[わかりやすい名前] に、わかりやすい接続名を入力します(例:
My connection resource
)。後で修正が必要になった場合、わかりやすい名前だと接続リソースを簡単に識別できます。 - (省略可)[説明] に、この接続リソースの説明を入力します。
- [データベース名] に、Spanner データベースの名前を
"projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE"
の形式で入力します。 - 省略可: 同時読み取りを実行するには、[データを同時に読み込む] を選択します。Spanner は、特定のクエリをより小さな部分またはパーティションに分割し、パーティションを同時に取得します。詳細については、Spanner ドキュメントのデータを同時に読み込むをご覧ください。このオプションは、実行プランの最初の演算子が分散ユニオン演算子であるクエリに限定されます。その他のクエリではエラーが返されます。Spanner クエリのクエリ実行プランを表示するには、Spanner がクエリを実行する方法を理解するをご覧ください。
- 省略可: [データベース ロール] に、Spanner データベース ロールの名前を入力します。空でない場合、この接続はデフォルトでこのデータベース ロールを使用して Spanner にクエリを実行します。この接続を介してクエリを送信するユーザーに Spanner のきめ細かいアクセス制御が設定されている場合、このロールへのアクセス権が管理者によってユーザーに付与されている必要があります。また、データベース ロールには、外部クエリで指定されているすべてのオブジェクト スキーマに対する
SELECT
権限が必要です。きめ細かなアクセス制御については、きめ細かなアクセス制御についてをご覧ください。 - 省略可: Data Boost を有効にするには、[Spanner Data Boost を使用する] を選択します。Data Boost を使用すると、プロビジョニングされた BigQuery インスタンスの既存のワークロードへの影響がほぼゼロの状態で、分析クエリとデータ エクスポートを実行できます。Data Boost を有効にするには、[Data Boost] と [データを同時に読み込む] を選択します。
[接続を作成] をクリックします。
bq
接続を作成するには、--connection
フラグを指定して bq mk
コマンドを使用します。
bq mk --connection \ --connection_type=CLOUD_SPANNER \ --properties='PROPERTIES' \ --location=LOCATION \ --display_name='FRIENDLY_NAME' \ --description 'DESCRIPTION' \ CONNECTION_ID
次のように置き換えます。
PROPERTIES
: 次のフィールドを持つ JSON オブジェクト"database"
: 接続用の Spanner データベース"projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE"
の形式の文字列として指定します。"use_parallelism"
: (省略可)true
の場合、この接続は同時読み取りを実行します。デフォルト値は
false
です。Spanner は、特定のクエリをより小さな部分またはパーティションに分割し、パーティションを同時に取得します。詳細については、Spanner ドキュメントのデータを同時に読み込むをご覧ください。このオプションは、実行プランの最初の演算子が分散ユニオン演算子であるクエリに限定されます。その他のクエリではエラーが返されます。Spanner クエリのクエリ実行プランを表示するには、Spanner がクエリを実行する方法を理解するをご覧ください。"database_role"
: (省略可)空でない場合、この接続は、デフォルトでこのデータベース ロールを使用して Spanner にクエリを実行します。この接続を介してクエリを送信するユーザーに Spanner のきめ細かいアクセス制御が設定されている場合、このロールへのアクセス権が管理者によってユーザーに付与されている必要があります。また、データベース ロールには、外部クエリで指定されているすべてのオブジェクト スキーマに対するSELECT
権限が必要です。指定されていない場合、接続は Spanner に対する IAM 事前定義ロールで認証されます。この接続でクエリを実行するプリンシパルには、
roles/spanner.databaseReader
IAM ロールが付与されている必要があります。きめ細かなアクセス制御については、きめ細かなアクセス制御についてをご覧ください。
"useDataBoost"
: (省略可)true
の場合、この接続によりユーザーは Data Boost を使用できます。Data Boost を使用すると、ユーザーは、プロビジョニングされたインスタンスとは異なる独立したコンピューティング容量で連携クエリを実行し、既存のワークロードへの影響を回避できます。Data Boost を有効にするには、"useDataBoost"
をtrue
に、"use_parallelism"
をtrue
に設定します。Data Boost を使用するには、この接続でクエリを実行するプリンシパルに
spanner.databases.useDataBoost
権限が付与されている必要があります。この権限は、デフォルトでroles/spanner.admin
ロールとroles/spanner.databaseAdmin
ロールに含まれています。
LOCATION
: 外部データソースのリージョンと互換性がある BigQuery のロケーション。CONNECTION_ID
: 接続リソースの識別子接続 ID には、文字、数字、アンダースコアを使用できます。接続 ID を指定しない場合、BigQuery は自動的に一意の ID を生成します。
次の例では、
my_connection_id
という名前の新しい接続リソースを作成します。bq mk --connection \ --connection_type='CLOUD_SPANNER' \ --properties='{"database":"projects/my_project/instances/my_instance/databases/database1"}' \ --project_id=federation-test \ --location=us \ my_connection_id
API
ConnectionService
サービス内で CreateConnection
メソッドを呼び出します。
ユーザーと接続を共有する
次のロールを付与することで、ユーザーがデータをクエリして接続を管理できます。
roles/bigquery.connectionUser
: ユーザーが接続を使用して外部データソースに接続し、クエリを実行できるようにします。roles/bigquery.connectionAdmin
: ユーザーが接続を管理できるようにします。
BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。
次のオプションのいずれかを選択します。
コンソール
[BigQuery] ページに移動します。
接続は、プロジェクトで外部接続というグループに一覧表示されます。
[エクスプローラ] ペインで、[プロジェクト名] > [外部接続] > [接続] の順にクリックします。
[詳細] ペインで、[共有] をクリックして接続を共有します。次に、以下の操作を行います。
[接続の権限] ダイアログで、プリンシパルを追加または編集して、他のプリンシパルと接続を共有します。
[保存] をクリックします。
bq
bq コマンドライン ツールを使用して接続を共有することはできません。接続を共有するには、Google Cloud コンソールまたは BigQuery Connections API メソッドを使用します。
API
BigQuery Connections REST API の projects.locations.connections.setIAM
メソッドを使用して、policy
リソースのインスタンスを指定します。
Java
このサンプルを試す前に、クライアント ライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
次のステップ
- さまざまな接続タイプについて確認する。
- 接続の管理について確認する。
- 連携クエリについて確認する。
- Spanner データのクエリを実行する方法を確認する。