Configurar o acesso do AlloyDB a dados em tempo real no BigQuery

Para consultar dados analíticos em tempo real no BigQuery diretamente do AlloyDB para PostgreSQL sem executar migrações de extração, transformação e carregamento (ETL), configure a federação de lakehouse. A federação de lakehouse unifica seu banco de dados operacional e o data warehouse de análise para que você possa oferecer suporte a análises em tempo real e aplicativos interativos sem manter pipelines de dados separados. Para mais informações, consulte Visão geral do acesso a dados em tempo real.

Com essa integração, é possível executar consultas no AlloyDB que acessam dados do BigQuery em tempo real e mesclar tabelas operacionais no AlloyDB com tabelas externas que referenciam seus conjuntos de dados do BigQuery.

Antes de configurar a federação do lakehouse, você precisa de um cluster e uma instância principal do AlloyDB, além de um conjunto de dados e tabelas do BigQuery. Para mais informações, consulte Criar conjuntos de dados e Criar e usar tabelas.

Antes de começar

  1. Ative a flag bigquery_fdw.enabled na instância do AlloyDB para PostgreSQL.
  2. Conheça os tipos de dados compatíveis.
  3. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  6. Ative as APIs do Cloud necessárias para criar e se conectar ao AlloyDB.

    Ativar as APIs

  7. Na etapa Confirmar projeto, clique em Avançar para confirmar o nome do projeto em que você vai fazer alterações.

  8. Na etapa Ativar APIs, clique em Ativar para ativar o seguinte:

    • API AlloyDB
    • API Compute Engine
    • API Cloud Resource Manager
    • API Service Networking
    • API BigQuery Storage
    • API BigQuery

    A API Service Networking é necessária se você planeja configurar a conectividade de rede com o AlloyDB usando uma rede VPC que reside no mesmo projeto do Google Cloud AlloyDB.

    As APIs Compute Engine e Cloud Resource Manager são necessárias se você planeja configurar a conectividade de rede com o AlloyDB usando uma rede VPC que reside em um projeto do Google Cloud diferente.

Funções exigidas

Para conceder acesso de leitura ao conjunto de dados do BigQuery à conta de serviço do cluster do AlloyDB, você precisa das seguintes permissões. Para mais informações, consulte Conceder ao AlloyDB acesso ao conjunto de dados do BigQuery.

  • Visualizador de dados do BigQuery (roles/bigquery.dataViewer) ou qualquer papel personalizado com as permissões bigquery.tables.get e bigquery.tables.getData. Quando concedido em uma tabela ou visualização, esse papel fornece permissões para ler dados e metadados da tabela ou visualização.
  • Usuário de sessão de leitura do BigQuery (roles/bigquery.readSessionUser) ou qualquer papel personalizado com as permissões bigquery.readsessions.create e bigquery.readsessions.getData. Permite criar e usar sessões de leitura.
  • Usuário de jobs do BigQuery (roles/bigquery.jobUser) ou qualquer papel personalizado com permissões bigquery.jobs.create. Concede permissões para executar jobs, incluindo consultas, no projeto usando a API BigQuery. Esse papel só pode ser concedido em recursos do Resource Manager (projetos, pastas e organizações). Quando você fornece um projeto de ambiente de execução separado, o job é executado nele, em vez de no projeto de dados. Isso significa que você precisa conceder o papel de usuário do job no projeto de ambiente de execução.

Para acessar as tabelas do BigLake Metastore:

  • Leitor do BigLake (roles/biglake.viewer) ou qualquer papel personalizado com as permissões biglake.catalogs.get, biglake.namespaces.get, biglake.tables.get e biglake.tables.getData. Concede permissões para ler catálogos, namespaces e tabelas do BigLake Metastore.
  • Leitor de objetos do Storage (roles/storage.objectViewer) ou qualquer papel personalizado com permissões storage.objects.get. Fornece permissões para acessar tabelas externas do BigQuery e ler objetos do Cloud Storage que dão suporte às tabelas do BigLake e do BigLake Metastore. Precisa ser concedida no nível do projeto ou do bucket.

Conceder ao AlloyDB acesso ao conjunto de dados do BigQuery

Depois de ativar os papéis e as permissões necessários para a federação do lakehouse, conceda à conta de serviço do cluster do AlloyDB acesso ao conjunto de dados do BigQuery.

O console do Google Cloud concede automaticamente as permissões necessárias à conta de serviço do cluster quando você conecta uma tabela do BigQuery usando o AlloyDB Studio.

Para conceder acesso usando a CLI gcloud, siga estas etapas:

gcloud

Para usar a CLI gcloud, você pode instalar e inicializar a Google Cloud CLI ou usar o Cloud Shell.

  1. Abra a CLI gcloud. Se você não tiver a CLI gcloud instalada, instale e inicialize a CLI gcloud ou use o Cloud Shell.

  2. Execute o comando gcloud beta alloydb clusters describe:

    gcloud beta alloydb clusters describe CLUSTER --region=REGION

    Substitua:

    • CLUSTER: o ID do cluster do AlloyDB.
    • REGION: o local do cluster do AlloyDB, por exemplo, asia-east1, us-east1. Confira a lista completa de regiões em Locais do AlloyDB.

    A saída contém um campo serviceAccountEmail, que é a conta de serviço desse cluster. Também é possível encontrar a conta de serviço na página Visão geral do cluster.

  3. Conceder as permissões necessárias. Para mais informações, consulte Controlar o acesso a recursos com o IAM.

    Se a conta de serviço do cluster não tiver as permissões necessárias, os seguintes erros vão aparecer quando uma consulta for executada na tabela do BigQuery:

    • The user does not have bigquery.readsessions.create permissions
    • Permission bigquery.tables.get denied on table
    • Permission bigquery.tables.getData denied on table

Configurar a extensão

Para configurar a extensão, siga estas etapas:

Console

  1. Acesse a página Clusters.

    Acessar Clusters

  2. Clique no ID do cluster que você quer usar.

  3. No menu de navegação, clique em AlloyDB Studio.

  4. Faça login no banco de dados.

  5. No painel Explorador, expanda o esquema relevante.

  6. Clique no menu Ações ao lado de Tabelas do BigQuery e clique em Conectar tabela do BigQuery.

  7. No painel Conectar tabela do BigQuery, escolha um projeto de origem, um conjunto de dados de origem e uma tabela.

  8. A tabela Analisar e selecionar colunas mostra as colunas da tabela selecionada. Selecione as colunas que você quer mapear.

  9. No campo Nome da tabela, insira um nome para a tabela externa.

  10. Opcional: clique em Ver comando SQL para conferir o comando gerado.

  11. Clique em Conectar tabela. Uma caixa de diálogo mostra o progresso. Depois que o processo for concluído, será possível consultar a tabela como qualquer outra no AlloyDB.

psql

  1. Crie a extensão.

    1. Conecte-se à instância do AlloyDB usando o cliente psql seguindo as instruções em Conectar um cliente psql a uma instância. Se preferir, use o AlloyDB Studio. Para mais informações, consulte Gerenciar seus dados usando o console do Google Cloud .
    2. Execute este comando:

      CREATE EXTENSION bigquery_fdw;
      
  2. Crie um servidor externo para definir os parâmetros de conexão do conjunto de dados remoto do BigQuery.

    CREATE SERVER BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw
      OPTIONS (runtime_project 'RUNTIME_PROJECT_ID');
    

    Substitua:

    • BIGQUERY_SERVER_NAME: identificador exclusivo do servidor externo. Defina isso uma vez em um determinado banco de dados. É possível substituir BIGQUERY_SERVER_NAME pelo nome do servidor.
    • RUNTIME_PROJECT_ID: opcional. O ID do projeto do Google Cloud que processa a consulta e acumula custos de computação. Se você omitir esse ID, as consultas serão cobradas do projeto que armazena os dados.
  3. Crie o mapeamento de usuário executando o comando CREATE USER MAPPING, que mapeia um usuário local do PostgreSQL que você quer conectar ao servidor externo.

    CREATE USER MAPPING FOR USERNAME SERVER BIGQUERY_SERVER_NAME ;
    

    Substitua:

    • USERNAME: um nome de usuário do banco de dados ou um usuário do IAM que acessa a tabela externa.
    • BIGQUERY_SERVER_NAME: identificador exclusivo do servidor externo que você criou.
  4. Defina tabelas externas que correspondam às tabelas que você quer acessar no BigQuery usando o comando CREATE FOREIGN TABLE. Esse comando permite definir a estrutura de uma tabela remota. A tabela externa pode ter todas ou um subconjunto das colunas na tabela de origem no BigQuery.

    CREATE FOREIGN TABLE TABLENAME (
      COLUMN1_NAME DATA_TYPE,
      COLUMN2_NAME DATA_TYPE,
      ...
    ) SERVER BIGQUERY_SERVER_NAME OPTIONS (
      project 'BIGQUERY_PROJECT_ID',
      dataset 'BIGQUERY_DATASET_NAME',
      table 'BIGQUERY_TABLE_NAME',
      runtime_project 'RUNTIME_PROJECT_ID'
    );
    

    Substitua:

    • TABLENAME: o nome da tabela externa no banco de dados local do AlloyDB.
    • COLUMNX_NAME: o nome da coluna do AlloyDB. O nome da coluna precisa corresponder exatamente ao nome da coluna correspondente na tabela de origem do BigQuery. X indica que a tabela pode ser criada com várias colunas. O nome também precisa corresponder exatamente às letras maiúsculas e minúsculas da coluna do BigQuery. Se o nome da coluna do BigQuery contiver letras maiúsculas (por exemplo, employeeID), o identificador do AlloyDB precisará ser colocado entre aspas duplas (por exemplo, "employeeID") para preservar letras mistas ou maiúsculas.
    • DATA_TYPE: o tipo de dados da coluna. Ao definir o DATA_TYPE para cada coluna na tabela estrangeira, verifique se ele é um tipo compatível do PostgreSQL. Para mais informações sobre como os tipos do BigQuery são convertidos, consulte Mapeamentos de tipos de dados.
    • BIGQUERY_SERVER_NAME: identificador exclusivo do servidor externo que você criou.
    • BIGQUERY_PROJECT_ID: ID do projeto em que o conjunto de dados do BigQuery reside.
    • BIGQUERY_DATASET_NAME: nome do conjunto de dados do BigQuery para a tabela.
    • BIGQUERY_TABLE_NAME: nome da tabela do BigQuery.
    • RUNTIME_PROJECT_ID: opcional. O ID do projeto do Google Cloud a ser faturado pela execução da consulta. Definir isso no nível da tabela substitui o projeto de ambiente de execução definido no nível do servidor.

    Depois que a tabela externa for criada, será possível consultá-la da mesma forma que qualquer tabela no AlloyDB.

Mapeamentos de tipo de dados

Use a tabela a seguir para saber mais sobre os mapeamentos de tipos de dados entre o BigQuery e o AlloyDB. Para mais informações, consulte Considerações sobre tipos de dados para consultas federadas.

A tabela a seguir lista os mapeamentos de tipos de dados entre o BigQuery e o AlloyDB.

Tipos de dados da tabela do BigQuery Tipos de dados recomendados para tabelas externas do PostgreSQL

BOOLEAN

BOOLEAN

INTEGER (INT64)

BIGINT

FLOAT (FLOAT64)

DOUBLE PRECISION

STRING

VARCHAR

NUMERIC

NUMERIC(38, 9)

NUMERIC(P[, S])

NUMERIC(P, S)

BIGNUMERIC

NUMERIC(77, 38)

BIGNUMERIC(P[, S])

NUMERIC(P, S)

DATE

DATE

TIMESTAMP

TIMESTAMPTZ

TIME

TIME

JSON

JSONB

BYTES

BYTEA

GEOGRAPHY

GEOGRAPHY(POINT), ...

Para mais informações, consulte PostGIS_Geography.

DATETIME

TIMESTAMP

ARRAY

VECTOR(N)

N é a dimensão do vetor. Defina a flag bigquery_fdw.enable_vector_downcasting na sessão. Como o tipo VECTOR no AlloyDB usa o tipo float4, pode haver perda de precisão nessa conversão.

Para mais informações, consulte a extensão pgvector.

A seguir