Criar conjuntos de dados externos do Spanner

Neste documento, descrevemos como criar um conjunto de dados externo (também conhecido como conjunto de dados federado) no BigQuery que está vinculado a um banco de dados existente no Spanner.

Um conjunto de dados externo é uma conexão entre o BigQuery e uma fonte de dados externa no nível do conjunto de dados. Ele permite consultar dados transacionais em bancos de dados do Spanner com o GoogleSQL sem precisar copiar ou importar todos os dados do Spanner para o armazenamento do BigQuery. Os resultados da consulta são armazenados no BigQuery.

As tabelas em um conjunto de dados externo são preenchidas automaticamente com base nas tabelas na fonte de dados externa correspondente. Você pode consultar essas tabelas diretamente no BigQuery, mas não é possível fazer modificações, adições ou exclusões. No entanto, as atualizações feitas na fonte de dados externa são refletidas automaticamente no BigQuery.

Quando você consulta o Spanner, os resultados são salvos por padrão em tabelas temporárias. Eles também podem ser salvos como uma nova tabela do BigQuery, mesclados com outras tabelas ou combinados com tabelas atuais usando DML.

Permissões necessárias

Para receber a permissão necessária para criar um conjunto de dados externo, peça ao administrador para conceder a você o papel do IAM de Usuário do BigQuery (roles/bigquery.user). Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão bigquery.datasets.create, que é necessária para criar um conjunto de dados externo.

Também é possível conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Introdução ao IAM.

Usar uma conexão CLOUD_RESOURCE

De maneira opcional, os conjuntos de dados externos do Spanner podem usar uma conexão CLOUD_RESOURCE para interagir com seu banco de dados do Spanner. Assim, você pode dar acesso aos dados do Spanner por meio do BigQuery, sem conceder acesso direto ao banco de dados do Spanner. Como a conta de serviço da conexão CLOUD_RESOURCE processa a recuperação de dados do Spanner, você só precisa conceder aos usuários acesso ao conjunto de dados externo do Spanner.

Antes de criar conjuntos de dados externos do Spanner com uma conexão CLOUD_RESOURCE, faça o seguinte:

Crie uma conexão

Você pode criar ou usar uma conexão CLOUD_RESOURCE para se conectar ao Spanner. Para criar a conexão de recursos do Cloud, siga as etapas na página Criar uma conexão de recursos do Cloud.

Depois de criar a conexão, abra-a e, no painel Informações da conexão, copie o ID da conta de serviço. Você precisa desse ID ao configurar permissões para a conexão. Quando você cria um recurso de conexão, o BigQuery cria uma conta de serviço do sistema exclusiva e a associa à conexão.

Configurar o acesso

Conceda à nova conexão acesso de leitura à sua instância ou banco de dados do Spanner. Recomendamos usar o papel predefinido do IAM Leitor de banco de dados do Cloud Spanner com Data Boost (roles/spanner.databaseReaderWithDataBoost).

Siga estas etapas para conceder acesso a papéis no nível do banco de dados à conta de serviço que você copiou anteriormente da conexão:

  1. Acesse a página Instâncias do Spanner.

    Acesse a página "Instâncias".

  2. Clique no nome da instância que contém seu banco de dados para acessar a página Detalhes da instância.

  3. Na guia Visão geral, marque a caixa de seleção do seu banco de dados.
    O painel de informações é exibido.

  4. Clique em Adicionar principal.

  5. No painel Adicionar principais, em Novos principais, insira o ID da conta de serviço que você copiou anteriormente.

  6. No campo Selecionar um papel, escolha Leitor de banco de dados do Cloud Spanner com o papel DataBoost.

  7. Clique em Salvar.

Criar um conjunto de dados externo

Para criar um conjunto de dados externo, faça o seguinte:

Console

  1. Abra a página do BigQuery no console do Google Cloud .

    Acessar a página do BigQuery

  2. No painel Explorador, selecione o projeto em que você quer criar o conjunto de dados.

  3. Expanda a opção Ações e clique em Criar conjunto de dados.

  4. Na página Criar conjunto de dados, faça o seguinte:

    • Em Código do conjunto de dados, digite um nome exclusivo.
    • Em Tipo de local, escolha um local para o conjunto de dados, como us-central1 ou multirregião us. Depois que você cria um conjunto de dados, o local não pode ser alterado.

    • Em Conjunto de dados externo, faça o seguinte:

      • Marque a caixa ao lado de Vincular a um conjunto de dados externo.
      • Em Tipo de conjunto de dados externo, selecione Spanner.
      • Em Origem externa, insira o identificador completo do seu banco de dados do Spanner no seguinte formato: projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Por exemplo: projects/my_project/instances/my_instance/databases/my_database.
      • Opcional: em Papel do banco de dados, insira o nome de um papel do banco de dados do Spanner. Para mais informações, leia sobre as funções de banco de dados usadas para criar conexões do Spanner.
      • Se quiser, marque a caixa ao lado de Usar uma conexão de recurso do Cloud para criar o conjunto de dados externo com uma conexão.

    • Não altere as outras configurações.

  5. Clique em Criar conjunto de dados.

SQL

Use a instrução de linguagem de definição de dados (DDL) CREATE EXTERNAL SCHEMA:

  1. No console Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. No editor de consultas, digite a seguinte instrução:

    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');

    Substitua:

    • DATASET_NAME: o nome do novo conjunto de dados no BigQuery.
    • SPANNER_EXTERNAL_SOURCE: o nome completo e qualificado do banco de dados do Spanner, com um prefixo que identifica a origem, no seguinte formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Por exemplo: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database ou google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
    • LOCATION: o local do novo conjunto de dados no BigQuery. Por exemplo, us-central1. Depois de criar um conjunto de dados, não será possível alterar o local dele.
    • (Opcional) CONNECTION_NAME: o nome da sua conexão de recurso do Cloud.

  3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Em um ambiente de linha de comando, crie um conjunto de dados externo usando o comando bq mk:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    DATASET_NAME

Ou crie com uma conexão:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    --connection_id PROJECT_ID.LOCATION.CONNECTION_NAME \
    DATASET_NAME

Substitua:

  • LOCATION: o local do novo conjunto de dados no BigQuery. Por exemplo, us-central1. Depois de criar um conjunto de dados, não será possível alterar o local dele. É possível definir um valor de local padrão usando o arquivo .bigqueryrc.
  • SPANNER_EXTERNAL_SOURCE: o nome completo e qualificado do banco de dados do Spanner, com um prefixo que identifica a origem, no seguinte formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Por exemplo: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database ou google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
  • DATASET_NAME: o nome do novo conjunto de dados no BigQuery. Para criar um conjunto de dados em um projeto diferente do projeto padrão, adicione a ID do projeto ao nome do conjunto de dados no seguinte formato: PROJECT_ID:DATASET_NAME.
  • (Opcional) CONNECTION_NAME: o nome da sua conexão de recurso do Cloud.

Terraform

Use o recurso google_bigquery_dataset.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

O exemplo a seguir cria um conjunto de dados externo do 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 = ""
  }
}

Para aplicar a configuração do Terraform em um projeto Google Cloud , siga as etapas nas seções a seguir.

Preparar o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o projeto Google Cloud padrão em que você quer aplicar as configurações do Terraform.

    Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

  1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

    Copie o exemplo de código no main.tf recém-criado.

    Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório. 
    terraform init

    Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade: 

    terraform init -upgrade

Aplique as alterações

  1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas: 
    terraform plan

    Faça as correções necessárias na configuração.

  2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

    Aguarde até que o Terraform exiba a mensagem "Apply complete!".

  3. Abra seu Google Cloud projeto para ver os resultados. No console Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

API

Chame o método datasets.insert com um recurso de conjunto de dados definido e o campo externalDatasetReference para seu banco de dados do Spanner.

Os nomes das tabelas nos conjuntos de dados externos não diferenciam maiúsculas de minúsculas.

Ao criar os conjuntos de dados externos com uma conexão CLOUD_RESOURCE, você precisa ter a permissão bigquery.connections.delegate (disponível no papel Administrador de conexões do BigQuery) na conexão usada pelos conjuntos de dados externos.

Controlar o acesso a tabelas

Os conjuntos de dados externos do Spanner são compatíveis com credenciais de usuário final (EUC, na sigla em inglês). Isso significa que o acesso às tabelas do Spanner de conjuntos de dados externos é controlado pelo Spanner. Os usuários só podem consultar essas tabelas se tiverem acesso concedido no Spanner.

Os conjuntos de dados externos do Spanner também são compatíveis com a delegação de acesso. A delegação de acesso desacopla o acesso às tabelas do Spanner de conjuntos de dados externos e o acesso direto às tabelas subjacentes do Spanner. Uma conexão de recursos do Cloud associada a uma conta de serviço é usada para se conectar ao Spanner. Os usuários podem consultar essas tabelas do Spanner em conjuntos de dados externos, mesmo que não tenham acesso concedido no Spanner.

Listar tabelas em um conjunto de dados externo

Se quiser listar as tabelas disponíveis para consulta no conjunto de dados externo, confira Como listar conjuntos de dados.

Receber informações de tabelas

Para informações sobre as tabelas no conjunto de dados externo, como detalhes de esquema, consulte Receber informações da tabela.

Consultar dados do Spanner

Consultar tabelas em conjuntos de dados externos é igual a consultar tabelas em qualquer outro conjunto de dados do BigQuery. No entanto, as operações de modificação de dados (DML) não são compatíveis.

As consultas em tabelas de conjuntos de dados externos do Spanner usam o Data Boost por padrão, e isso não pode ser mudado. Por isso, você precisa de permissões adicionais para executar essas consultas.

Criar uma visualização em um conjunto de dados externo

Não é possível criar uma visualização em um conjunto de dados externo. No entanto, é possível criar uma visualização em um conjunto de dados padrão com base em uma tabela em um conjunto de dados externo. Para mais informações, consulte Criar visualizações.

Excluir um conjunto de dados externo

Excluir um conjunto de dados externo é igual a excluir qualquer outro conjunto de dados do BigQuery. A exclusão de conjuntos de dados externos não afeta as tabelas no banco de dados do Spanner. Para mais informações, consulte Excluir conjuntos de dados.

Limitações

  • As limitações das consultas federadas do BigQuery são aplicáveis.
  • Somente tabelas de um esquema padrão do Spanner podem ser acessadas no BigQuery. Tabelas de esquemas de nomes não são compatíveis.
  • As chaves primárias e estrangeiras definidas no banco de dados do Spanner não ficam visíveis no BigQuery.
  • Se uma tabela no banco de dados do Spanner tiver uma coluna de um tipo não compatível com o BigQuery, essa coluna não poderá ser acessada no BigQuery.
  • Não é possível adicionar, excluir ou atualizar dados ou metadados em tabelas em um conjunto de dados externo do Spanner.
  • Não é possível criar tabelas, visualizações ou visualizações materializadas em um conjunto de dados externo do Spanner.
  • As visualizações INFORMATION_SCHEMA não têm suporte.
  • Não há suporte para armazenamento em cache de metadados.
  • As configurações no nível do conjunto de dados relacionadas aos padrões de criação de tabelas não afetam os conjuntos de dados externos porque não é possível criar tabelas de modo manual.
  • Não há suporte para bancos de dados do Spanner que usam o dialeto PostgreSQL.
  • As APIs Write e Read não são compatíveis.
  • A segurança no nível da linha e da coluna e o mascaramento de dados não são compatíveis.
  • Não há suporte para visualizações materializadas baseadas em tabelas de conjuntos de dados externos do Spanner.
  • A integração com o Dataplex Universal Catalog não é compatível. Por exemplo, não há suporte para perfis e verificações de qualidade de dados.
  • Não é possível usar tags no nível da tabela.
  • A conclusão automática de SQL não funciona com tabelas externas do Spanner ao escrever consultas.
  • A verificação com a proteção de dados sensíveis não é compatível com conjuntos de dados externos.
  • O compartilhamento com o BigQuery (antigo Analytics Hub) não é compatível com conjuntos de dados externos.
  • Se o conjunto de dados externo do Spanner usar credenciais do usuário final (EUC, na sigla em inglês), crie uma visualização autorizada que faça referência ao conjunto de dados externo. No entanto, quando essa visualização é consultada, o EUC de uma pessoa que executa uma consulta é enviado ao Spanner.
  • Se o conjunto de dados externo do Spanner usar uma conexão de recurso do Cloud para delegação de acesso, você poderá criar uma visualização ou rotina autorizada que faça referência ao conjunto de dados externo.

A seguir