Esta página foi traduzida pela API Cloud Translation.

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 mover dados do Spanner para o armazenamento do 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.

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.

Criar um conjunto de dados externo

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

Console

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

Acesse a página do BigQuery
No painel Explorador, selecione o projeto em que você quer criar o conjunto de dados.
Expanda a opção Ações e clique em Criar conjunto de dados.
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.
  - Opcionalmente, 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 do banco de dados usadas para criar conexões do Spanner.
- Não altere as outras configurações.
Clique em Criar conjunto de dados.

SQL

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

No Console do Google Cloud, acesse a página BigQuery.

Ir para o BigQuery
No editor de consultas, digite a seguinte instrução:
```
CREATE EXTERNAL SCHEMA DATASET_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.
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

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 do banco de dados do Spanner totalmente qualificado, com um prefixo que identifica a fonte, 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.

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 do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

Inicie o Cloud Shell.
Defina o projeto padrão do Google Cloud 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.

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
```
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.
Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
Salve as alterações.
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

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.
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!".
Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

API

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

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

Listar tabelas em um conjunto de dados externo

Para listar as tabelas disponíveis para consulta no conjunto de dados externo, consulte Como listar conjuntos de dados.

Receber informações de tabelas

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

Controlar o acesso a tabelas

Os conjuntos de dados externos do Spanner são compatíveis com as credenciais do usuário final (EUC). 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.

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 em conjuntos de dados externos do Spanner usam o Data Boost por padrão, e isso não pode ser alterado. 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 as tabelas de um esquema padrão do Spanner podem ser acessadas no BigQuery. Não é possível usar tabelas de esquemas de nomes.
Se uma tabela no banco de dados do Spanner contiver uma coluna de um tipo que não é aceito pelo BigQuery, essa coluna não será acessível 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 novas 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 manualmente.
Não há suporte para bancos de dados do Spanner que usam o dialeto PostgreSQL.
Não há suporte para as APIs Write e Read.
Não há suporte para segurança no nível da linha, segurança no nível da coluna e mascaramento de dados.
Não há suporte para visualizações materializadas com base em tabelas de conjuntos de dados externos do Spanner.
Não há suporte para integração com o Dataplex. Por exemplo, não é possível usar perfis de dados e verificações de qualidade de dados.
Não é possível usar tags no nível da tabela.
A conclusão automática do 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.
É possível criar uma visualização autorizada que faz referência ao conjunto de dados externo do Spanner. No entanto, quando essa visualização é consultada, o EUC de uma pessoa que executa uma consulta é enviado ao Spanner.

A seguir

Saiba mais sobre as consultas federadas do Spanner.