Conectar ao Spanner
Como administrador do BigQuery, é possível criar uma conexão para acessar dados do Spanner. Com essa conexão, os analistas de dados podem consultar dados no Spanner.
Antes de começar
- Ative a API BigQuery Connection.
-
Para receber as permissões necessárias para se conectar ao Spanner, peça ao administrador para conceder a você o papel do IAM de Administrador de conexão do BigQuery (
roles/bigquery.connectionAdmin
) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.
Criar conexões do Spanner
Selecione uma das seguintes opções:
Console
Acessar a página do BigQuery.
No painel Explorer, clique em
Adicionar e, em seguida, selecione Conexões com fonte de dados externa.No painel Fonte de dados externa, insira as seguintes informações:
- Em Tipo de conexão, selecione Cloud Spanner.
- Em ID da conexão, insira um identificador para o recurso de conexão. Letras, números e sublinhados são permitidos.
- Em Tipo de local, selecione um local (ou região) do BigQuery que seja compatível com a região da fonte de dados externa.
- (Opcional) Em Nome amigável, insira um nome fácil de usar para
a conexão, como
My connection resource
. O nome amigável pode ser qualquer valor que ajude você a identificar o recurso de conexão se precisar modificá-lo mais tarde. - (Opcional) Em Descrição, insira uma descrição para este recurso de conexão.
- Em Nome do banco de dados, digite o nome do banco de dados do Spanner no seguinte formato:
"projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE"
- Opcional: para executar leituras paralelas, selecione Ler dados em paralelo. O Spanner pode dividir algumas consultas em partes menores, ou partições, e buscar as partições em paralelo. Para mais informações, consulte Ler dados em paralelo na documentação do Spanner. Essa opção é restrita a consultas em que o primeiro operador no plano de execução é um operador de união distribuída. Outras consultas retornam um erro. Para acessar o plano de execução de uma consulta do Spanner, consulte Noções básicas sobre como o Spanner executa consultas.
- Opcional: em Papel do banco de dados, insira o nome de um
papel do banco de dados do Spanner. Se não estiver vazio, essa conexão consulta o Spanner usando esse papel de banco de dados por padrão. Os usuários do controle de acesso detalhado do Spanner que enviam consultas por essa conexão precisam ter acesso concedido a esse papel pelo administrador, e o papel de banco de dados precisa ter o privilégio
SELECT
em todos os objetos de esquema especificados em consultas externas. Consulte informações em Sobre controle de acesso detalhado. - Opcional: para ativar o Data Boost, selecione Usar o Data Boost do Spanner. O Data Boost permite executar consultas de análise e exportações de dados com impacto quase zero nas cargas de trabalho da instância provisionada do BigQuery. Para ativar o Data Boost, selecione Data Boost e Ler dados em paralelo.
Clique em Criar conexão.
bq
Para criar a conexão, use o comando bq mk
com a sinalização --connection
.
bq mk --connection \ --connection_type=CLOUD_SPANNER \ --properties='PROPERTIES' \ --location=LOCATION \ --display_name='FRIENDLY_NAME' \ --description 'DESCRIPTION' \ CONNECTION_ID
Substitua:
PROPERTIES
: um objeto JSON com os campos a seguir:"database"
: o banco de dados do Spanner para a conexãoEspecifique como uma string com o seguinte formato:
"projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE"
."use_parallelism"
: (Opcional) setrue
, essa conexão executa leituras paralelasO valor padrão é
false
. O Spanner pode dividir algumas consultas em partes menores, ou partições, e buscar as partições em paralelo. Para mais informações, consulte Ler dados em paralelo na documentação do Spanner. Essa opção é restrita a consultas em que o primeiro operador no plano de execução é um operador de união distribuída. Outras consultas retornam um erro. Para acessar o plano de execução de uma consulta do Spanner, consulte Noções básicas sobre como o Spanner executa consultas."database_role"
(opcional): se não estiver vazio, essa conexão consulta o Spanner usando esse papel de banco de dados por padrão. Os usuários do controle de acesso detalhado do Spanner que enviam consultas por essa conexão precisam ter acesso concedido a esse papel pelo administrador, e o papel de banco de dados precisa ter o privilégioSELECT
em todos os objetos de esquema especificados em consultas externas.Se não for especificado, a conexão será autenticada com papéis predefinidos do IAM para o Spanner, e as principais consultas em execução com essa conexão precisarão ter o papel
roles/spanner.databaseReader
do IAM.Consulte informações em Sobre controle de acesso detalhado.
"useDataBoost"
(opcional): setrue
, essa conexão permite que os usuários usem o Data Boost. O Data Boost permite que os usuários executem consultas federadas em capacidade de computação separada e independente das instâncias provisionadas para evitar impacto nas cargas de trabalho. Para ativar o Data Boost, defina"useDataBoost"
comotrue
e"use_parallelism"
comotrue
.Para usar o Data Boost, a principal consulta em execução com essa conexão precisa ter recebido a permissão
spanner.databases.useDataBoost
. Por padrão, essa permissão está incluída nos papéisroles/spanner.admin
eroles/spanner.databaseAdmin
.
LOCATION
: um local do BigQuery que é compatível com a região de origem de dados externa.CONNECTION_ID
: um identificador para o recurso de conexãoO código da conexão pode conter letras, números e sublinhados. Se você não fornecer um ID de conexão, o BigQuery gerará automaticamente um ID exclusivo.
O exemplo a seguir cria um novo recurso de conexão chamado
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
Chame o método CreateConnection
no
serviço ConnectionService
.
Compartilhar conexões com os usuários
Você pode conceder os seguintes papéis para permitir que os usuários consultem dados e gerenciem conexões:
roles/bigquery.connectionUser
: permite aos usuários usar conexões para se conectar a fontes de dados externas e executar consultas nelas.roles/bigquery.connectionAdmin
: permite que os usuários gerenciem conexões.
Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.
Selecione uma das seguintes opções:
Console
Acessar a página do BigQuery.
As conexões são listadas no projeto, em um grupo chamado Conexões externas.
No painel Explorer, clique no nome do seu projeto > Explorer > conexão.
No painel Detalhes, clique em Compartilhar para compartilhar uma conexão. Em seguida, siga estas etapas:
Na caixa de diálogo Permissões de conexão, compartilhe a conexão com outros principais adicionando ou editando principais.
Clique em Salvar.
bq
Não é possível compartilhar uma conexão com a ferramenta de linha de comando bq. Para compartilhar um recurso de conexão, use o console do Google Cloud ou o método da API BigQuery Connections para compartilhar uma conexão.
API
Consulte o
método projects.locations.connections.setIAM
na seção de referência da API REST BigQuery Connections e
forneça uma instância do recurso policy
.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
A seguir
- Saiba sobre diferentes tipos de conexão.
- Saiba mais sobre como gerenciar conexões.
- Saiba mais sobre consultas federadas.
- Saiba como consultar dados do Spanner.