Console

1. Go to theBigQuery page.

   Go to BigQuery

2. In theExplorer pane, clickaddAdd data.

   TheAdd data dialog opens.

3. In theFilter By pane, in theData Source Type section, selectDatabases.

   Alternatively, in theSearch for data sources field, you can enterSpanner.

4. In theFeatured data sources section, clickGoogle Cloud Spanner.

5. Click theGoogle Cloud Spanner: BigQuery Federation solution card.

6. In theExternal data source pane, enter the following information:

   • ForConnection type, selectCloud Spanner.
   • ForConnection ID, enter an identifier for the connectionresource. Letter, numbers, and underscores are allowed.
   • ForLocation type, select a BigQuerylocation (or region) that iscompatible with your external data source region.
   • Optional: ForFriendly name, enter a user-friendly name for theconnection, such asMy connection resource. The friendly name canbe any value that helps you identify the connection resource if youneed to modify it later.
   • Optional: ForDescription, enter a description for thisconnection resource.
   • ForDatabase name, enter the name of the Spannerdatabase in the following format:"projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE"
   • Optional: To perform parallel reads, selectRead data inparallel. Spanner can divide certain queries intosmaller pieces, or partitions, and fetch the partitions in parallel.For more information, seeRead data in parallelin the Spanner documentation. This option isrestricted to queries whose first operator in the execution plan isadistributed unionoperator. Other queries return an error. To view the query executionplan for a Spanner query, seeUnderstand howSpanner executes queries.
   • Optional: ForDatabase role, enter the name of aSpanner database role. If not empty, thisconnection queries Spanner using this database roleby default. Spanner fine-grained access control users who submitqueries through this connectionmust have been granted access to this role by their administrator,and the database role must have theSELECT privilege on all schemaobjects specified in external queries. For information aboutfine-grained access control, seeAbout fine-grained access control.
   • Optional: To enable Data Boost, selectUse Spanner Data Boost.Data Boostlets you execute analytics queries and data exportswith near-zero impact to existing workloads on the provisionedBigQuery instance. To enable Data Boost, selectData Boost andRead data in parallel.

7. ClickCreate connection.

bq

To create the connection, use thebq mk commandwith the--connection flag.

bqmk--connection\--connection_type=CLOUD_SPANNER\--properties='PROPERTIES'\--location=LOCATION\--display_name='FRIENDLY_NAME'\--description'DESCRIPTION'\CONNECTION_ID

Replace the following:

• PROPERTIES: a JSON object with the followingfields:

  • "database": the Spanner database for the connection

    Specify as a string with the following format:"projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE".

  • "use_parallelism": (Optional) iftrue, this connection performsparallel reads

    The default value isfalse. Spanner can divide certainqueries into smaller pieces, or partitions, and fetch the partitions inparallel. For more information, seeRead data in parallelin the Spanner documentation. This option is restrictedto queries whose first operator in the execution plan is adistributedunionoperator. Other queries return an error. To view the query executionplan for a Spanner query, seeUnderstand howSpanner executes queries.

  • "database_role": (Optional) If not empty, this connection queriesSpanner using this database role by default.Spanner fine-grained access control users who submitqueries through this connectionmust have been granted access to this role by their administrator,and the database role must have theSELECT privilege on all schemaobjects specified in external queries.

    If not specified, the connection authenticates withIAM predefined roles for Spanner, andthe principal running queries with this connection must havebeen granted theroles/spanner.databaseReader IAMrole.

    For information aboutfine-grained access control, seeAbout fine-grained access control.

  • "useDataBoost": (Optional) Iftrue, this connection lets users useData Boost. Data Boost lets users run federated queries in separate, independent, compute capacity distinct from provisioned instances to avoid impacting existing workloads. To enable Data Boost, set"useDataBoost" totrue and"use_parallelism" totrue.

    In order to use Data Boost, the principal running queries with this connection must have been granted thespanner.databases.useDataBoost permission. This permission is included by default in theroles/spanner.admin androles/spanner.databaseAdmin roles.

• LOCATION: a BigQuery location thatiscompatible with your external data source region.

• CONNECTION_ID: an identifier for the connectionresource

  The connection ID can contain letters, numbers and underscores.If you don't provide a connection ID, BigQueryautomatically generates a unique ID.

  The following example creates a new connection resource namedmy_connection_id.

  bqmk--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

Call theCreateConnection method withintheConnectionService service.

Console

1. Go to theBigQuery page.

   Go to BigQuery

   Connections are listed in your project, in a group calledConnections.

2. In the left pane, clickexploreExplorer:

   

   If you don't see the left pane, clicklast_pageExpand left pane to open the pane.

3. Click your project, clickConnections, and then select a connection.

4. In theDetails pane, clickShare to share a connection.Then do the following:

   1. In theConnection permissions dialog, share theconnection with other principals by adding or editingprincipals.

   2. ClickSave.

bq

You cannot share a connection with the bq command-line tool.To share a connection, use the Google Cloud console orthe BigQuery Connections API method to share a connection.

API

Use theprojects.locations.connections.setIAM methodin the BigQuery Connections REST API reference section, andsupply an instance of thepolicy resource.

Java

importcom.google.api.resourcenames.ResourceName;importcom.google.cloud.bigquery.connection.v1.ConnectionName;importcom.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;importcom.google.iam.v1.Binding;importcom.google.iam.v1.Policy;importcom.google.iam.v1.SetIamPolicyRequest;importjava.io.IOException;// Sample to share connectionspublicclassShareConnection{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace these variables before running the sample.StringprojectId="MY_PROJECT_ID";Stringlocation="MY_LOCATION";StringconnectionId="MY_CONNECTION_ID";shareConnection(projectId,location,connectionId);}staticvoidshareConnection(StringprojectId,Stringlocation,StringconnectionId)throwsIOException{try(ConnectionServiceClientclient=ConnectionServiceClient.create()){ResourceNameresource=ConnectionName.of(projectId,location,connectionId);Bindingbinding=Binding.newBuilder().addMembers("group:example-analyst-group@google.com").setRole("roles/bigquery.connectionUser").build();Policypolicy=Policy.newBuilder().addBindings(binding).build();SetIamPolicyRequestrequest=SetIamPolicyRequest.newBuilder().setResource(resource.toString()).setPolicy(policy).build();client.setIamPolicy(request);System.out.println("Connection shared successfully");}}}