Esta página foi traduzida pela API Cloud Translation.

Traduzir consultas com o tradutor SQL interativo

Neste documento, descrevemos como traduzir uma consulta de um dialeto SQL diferente para uma consulta do GoogleSQL pelo tradutor de SQL interativo do BigQuery. O tradutor de SQL interativo pode ajudar a reduzir o tempo e o esforço da migração de cargas de trabalho para o BigQuery. Este documento é destinado a usuários familiarizados com o consoleGoogle Cloud .

Se o local tiver suporte, use o recurso de regra de tradução para personalizar a forma como o tradutor de SQL interativo traduz o SQL.

Antes de começar

Se o projeto da Google Cloud CLI foi criado antes de 15 de fevereiro de 2022, ative a API BigQuery Migration da seguinte maneira:

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

Acesse a API BigQuery Migration
Clique em Ativar.

Permissões e papéis

Nesta seção, descrevemos as permissões do Identity and Access Management (IAM) necessárias para usar o tradutor de SQL interativo e os papéis predefinidos do IAM que concedem essas permissões. Nesta seção, também descrevemos as permissões necessárias para a definição de configurações de tradução adicionais.

Permissões para usar o conversor de SQL interativo

Para receber as permissões necessárias para usar o tradutor interativo, peça ao administrador para conceder a você o papel do IAM de MigrationWorkflow Editor (roles/bigquerymigration.editor) no recurso parent. 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 as permissões necessárias para usar o tradutor interativo. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para usar o tradutor interativo:

bigquerymigration.workflows.create
bigquerymigration.workflows.get

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Permissões para definir outras configurações de tradução

É possível definir configurações de tradução adicionais pelos campos Translation Config ID e Translation Configuration Source Location das configurações de tradução. Para definir essas configurações de tradução, você precisa destas permissões:

bigquerymigration.workflows.get
bigquerymigration.workflows.list

O papel predefinido do IAM a seguir fornece as permissões necessárias para definir configurações de tradução adicionais:

roles/bigquerymigration.viewer

Consulte mais informações sobre o IAM do BigQuery em Controle de acesso com o IAM.

Dialetos SQL compatíveis

O tradutor de SQL interativo do BigQuery traduz os seguintes dialetos SQL para o GoogleSQL:

SQL do Amazon Redshift
Apache HiveQL e CLI Beeline
IBM Netezza SQL e NZPLSQL
Teradata e Teradata Vantage
- SQL
- Basic Teradata Query (BTEQ)
- Transporte paralelo do Teradata (TPT)

Além disso, a tradução dos seguintes dialetos SQL é suportada na versão de pré-lançamento:

SQL do Apache Spark
T-SQL do Azure Synapse
SQL do Greenplum
SQL do IBM DB2
SQL para MySQL
SQL da Oracle, PL/SQL, Exadata
SQL do PostgreSQL
Trino ou PrestoSQL
SQL do Snowflake
T-SQL do SQL Server
SQLite
SQL da Vertica

Como processar funções SQL sem suporte com UDFs auxiliares

Ao traduzir SQL de um dialeto de origem para o BigQuery, algumas funções podem não ter um equivalente direto. Para resolver esse problema, o serviço de migração do BigQuery (e a comunidade do BigQuery) fornecem funções definidas pelo usuário (UDFs) auxiliares que replicam o comportamento dessas funções de dialeto de origem sem suporte.

Essas UDFs geralmente são encontradas no conjunto de dados público bqutil, permitindo que as consultas traduzidas as refiram inicialmente usando o formato bqutil.<dataset>.<function>(). Por exemplo, bqutil.fn.cw_count().

Considerações importantes para ambientes de produção:

Embora o bqutil ofereça acesso conveniente a essas UDFs auxiliares para tradução e teste iniciais, a dependência direta do bqutil para cargas de trabalho de produção não é recomendada por vários motivos:

Controle de versão: o projeto bqutil hospeda a versão mais recente dessas UDFs, o que significa que as definições delas podem mudar com o tempo. A dependência direta de bqutil pode levar a um comportamento inesperado ou a mudanças nas consultas de produção se a lógica de uma UDF for atualizada.
Isolamento de dependência: implantar UDFs no seu projeto isola o ambiente de produção de mudanças externas.
Personalização: talvez seja necessário modificar ou otimizar esses UDFs para que se adaptem melhor à sua lógica de negócios ou aos requisitos de performance. Isso só é possível se eles estiverem no seu próprio projeto.
Segurança e governança: as políticas de segurança da sua organização podem restringir o acesso direto a conjuntos de dados públicos, como bqutil, para processamento de dados de produção. A cópia de UDFs para o ambiente controlado está alinhada a essas políticas.

Implantar UDFs auxiliares no projeto:

Para uso de produção confiável e estável, implante essas UDFs auxiliares no seu projeto e conjunto de dados. Assim, você tem controle total sobre a versão, a personalização e o acesso. Para instruções detalhadas sobre como implantar essas UDFs, consulte o guia de implantação de UDFs no GitHub. Este guia fornece os scripts e as etapas necessários para copiar as UDFs para seu ambiente.

Locais

O conversor de SQL interativo está disponível nos seguintes locais de processamento:

	Descrição da região	Nome da região	Detalhes
Ásia-Pacífico
	Délhi	`asia-south2`
	Hong Kong	`asia-east2`
	Jacarta	`asia-southeast2`
	Melbourne	`australia-southeast2`
	Mumbai	`asia-south1`
	Osaka	`asia-northeast2`
	Seul	`asia-northeast3`
	Singapura	`asia-southeast1`
	Sydney	`australia-southeast1`
	Taiwan	`asia-east1`
	Tóquio	`asia-northeast1`
Europa
	Bélgica	`europe-west1`	Baixo CO₂
	Berlim	`europe-west10`	Baixo CO₂
	UE multirregião	`eu`
	Finlândia	`europe-north1`	CO₂ baixo
	Frankfurt	`europe-west3`	Baixo CO₂
	Londres	`europe-west2`	Baixo CO₂
	Madri	`europe-southwest1`	Baixo CO₂
	Milão	`europe-west8`
	Países Baixos	`europe-west4`	Baixo CO₂
	Paris	`europe-west9`	Baixo CO₂
	Estocolmo	`europe-north2`	Baixo CO₂
	Turim	`europe-west12`
	Varsóvia	`europe-central2`
	Zurique	`europe-west6`	Baixo CO₂
América
	Columbus, Ohio	`us-east5`
	Dallas	`us-south1`	Baixo CO₂
	Iowa	`us-central1`	CO₂ baixo
	Las Vegas	`us-west4`
	Los Angeles	`us-west2`
	México	`northamerica-south1`
	Norte da Virgínia	`us-east4`
	Oregon	`us-west1`	Baixo CO₂
	Quebec	`northamerica-northeast1`	Baixo CO₂
	São Paulo	`southamerica-east1`	CO₂ baixo
	Salt Lake City	`us-west3`
	Santiago	`southamerica-west1`	CO₂ baixo
	Carolina do Sul	`us-east1`
	Toronto	`northamerica-northeast2`	Baixo CO₂
	EUA multirregião	`us`
África
	Johannesburgo	`africa-south1`
MiddleEast
	Damã	`me-central2`
	Doha	`me-central1`
	Israel	`me-west1`

Por padrão, o recurso de regra de tradução está disponível nos seguintes locais de processamento:

us (EUA multirregional)
eu (UE multirregião)
us-central1 (Iowa)
europe-west4 (Países Baixos)

As configurações de tradução baseadas em Gemini estão disponíveis apenas em locais de processamento específicos. Para mais informações, consulte Locais de endpoint de modelo do Google.

Traduzir uma consulta em GoogleSQL

Siga estas etapas para traduzir uma consulta em GoogleSQL:

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

Acessar o BigQuery
No painel Editor, clique em Mais e selecione Configurações de tradução.
Em Dialeto de origem, selecione o dialeto SQL que você quer traduzir.
Opcional. Em local de processamento, selecione o local em que você quer que o trabalho de tradução seja executado. Por exemplo, se você estiver na Europa e não quiser que seus dados cruzem os limites de local, selecione a região eu.
Clique em Salvar.
No painel Editor, clique em Mais e selecione Ativar tradução do SQL.

O painel Editor é dividido em dois.
No painel esquerdo, digite a consulta que você quer traduzir.
Clique em Traduzir.

O BigQuery traduz a consulta em GoogleSQL e a exibe no painel direito. Por exemplo, a captura de tela a seguir mostra o Teradata SQL traduzido:
Opcional: para executar a consulta traduzida do GoogleSQL, clique em Executar.
Opcional: para retornar ao editor SQL, clique em Mais e selecione Desativar tradução do SQL.

O painel Editor retorna para um único painel.

Usar o Gemini com o tradutor de SQL interativo

É possível configurar o tradutor de SQL interativo para ajustar a tradução do SQL de origem. Para fazer isso, forneça suas regras para uso com o Gemini em um arquivo de configuração YAML ou um arquivo de configuração YAML contendo metadados de objetos SQL ou informações de mapeamento de objetos.

Criar e aplicar regras de conversão aprimoradas do Gemini

É possível personalizar a forma como o tradutor de SQL interativo converte o SQL criando regras de tradução. O conversor de SQL interativo ajusta as traduções com base nas regras de conversão SQL aprimoradas do Gemini atribuídas a ele, permitindo personalizar os resultados de conversão com base nas necessidades de migração. Esse recurso é compatível apenas com determinados locais.

Para criar uma regra de conversão de SQL aprimorada do Gemini, é possível fazer isso no console ou criar um arquivo YAML de configuração e fazer o upload dele para o Cloud Storage.

Console

Para criar uma regra de conversão de SQL aprimorada do Gemini para o SQL de entrada, escreva uma consulta SQL de entrada no editor de consultas e clique em ASSIST > Personalizar. (Pré-lançamento)

Personalizar a entrada de tradução

Da mesma forma, para criar uma regra de conversão de SQL aprimorada do Gemini para o SQL de saída, execute uma tradução interativa e clique em ASSIST > Personalizar essa tradução.

Personalizar a saída da tradução

Quando o menu Personalizar aparecer, siga as etapas abaixo.

Use uma ou as duas solicitações a seguir para criar uma regra de tradução:
- No comando Encontrar e substituir um padrão, especifique um padrão SQL que você quer substituir no campo Substituir e um padrão SQL para substituir no campo Com.
  
  Um padrão SQL pode conter qualquer número de instruções, cláusulas ou funções em um script SQL. Quando você cria uma regra usando esse comando, a tradução de SQL aprimorada do Gemini identifica todas as instâncias desse padrão de SQL na consulta SQL e as substitui dinamicamente por outro padrão de SQL. Por exemplo, use essa solicitação para criar uma regra que substitua todas as ocorrências de months_between (X,Y) por date_diff(X,Y,MONTH).
- No campo Descrever uma alteração na saída, digite uma mudança na saída de tradução do SQL em linguagem natural.
  
  Quando você cria uma regra usando esse comando, a tradução do SQL aprimorada do Gemini identifica a solicitação e faz a mudança especificada na consulta SQL.
Clique em Visualização.
Na caixa de diálogo Sugestões geradas pelo Gemini, revise as mudanças feitas pela tradução aprimorada do SQL do Gemini na consulta SQL com base na sua regra.
Opcional: para adicionar essa regra para uso em traduções futuras, marque a caixa de seleção Salvar essa solicitação....

As regras são salvas no arquivo YAML de configuração padrão ou __default.ai_config.yaml. Esse arquivo YAML de configuração é salvo na pasta do Cloud Storage, conforme especificado no campo Translation Configuration Source Location nas configurações de tradução. Se o Local da origem da configuração de tradução ainda não estiver definido, um navegador de pastas vai aparecer e você poderá selecionar um. Um arquivo YAML de configuração está sujeito a limitações de tamanho do arquivo de configuração.
Para aplicar as mudanças sugeridas à consulta SQL, clique em Aplicar.

YAML

Para criar uma regra de conversão de SQL aprimorada do Gemini, crie um arquivo YAML de configuração baseado no Gemini e faça o upload dele para o Cloud Storage. Para mais informações, consulte Criar um arquivo YAML de configuração baseado em Gemini.

Depois de fazer upload de uma regra de conversão de SQL aprimorada do Gemini para o Cloud Storage, você pode aplicá-la da seguinte maneira:

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

Acessar o BigQuery
No Editor de consultas, clique em Mais > Configurações de tradução.
No campo Translation Configuration Source Location, especifique o caminho para o arquivo YAML baseado em Gemini armazenado em uma pasta do Cloud Storage.
Clique em Salvar.

Depois de salvar, execute uma tradução interativa. O tradutor interativo sugere mudanças nas traduções com base nas regras do arquivo YAML de configuração, se disponível.

Se uma sugestão do Gemini estiver disponível para a entrada com base na sua regra, a caixa de diálogo Visualizar alterações sugeridas vai aparecer e mostrar possíveis mudanças na entrada de tradução. (Visualização)

Se uma sugestão do Gemini estiver disponível para a saída com base na sua regra, um banner de notificação vai aparecer no editor de código. Para analisar e aplicar essas sugestões, faça o seguinte:

Clique em Assist > Conferir sugestões em qualquer lado do editor de código para revisar as mudanças sugeridas na consulta correspondente.
Na caixa de diálogo Sugestões geradas pelo Gemini, revise as mudanças feitas pelo Gemini na consulta SQL com base na sua regra de conversão.
Para aplicar as mudanças sugeridas à saída da tradução, clique em Aplicar.

Atualizar o arquivo YAML de configuração com base no Gemini

Para atualizar um arquivo YAML de configuração, faça o seguinte:

Na caixa de diálogo Sugestões geradas no Gemini, clique em Ver arquivo de configuração da regra do Gemini.
Quando o editor de configuração aparecer, selecione o arquivo YAML de configuração que você quer editar.
Faça a mudança e clique em Salvar.
Feche o editor YAML clicando em Concluído.
Execute uma tradução interativa para aplicar a regra atualizada.

Explicar uma tradução

Depois de executar uma tradução interativa, você pode solicitar uma explicação de texto gerada pelo Gemini. O texto gerado inclui um resumo da consulta SQL traduzida. O Gemini também identifica diferenças de tradução e inconsistências entre a consulta SQL de origem e a consulta GoogleSQL traduzida.

Para receber a explicação da conversão de SQL gerada pelo Gemini, faça o seguinte:

Para criar uma explicação de conversão de SQL gerada pelo Gemini, clique em Assistir e em Explicar essa conversão.

Traduzir com um ID de configuração de tradução em lote

É possível executar uma consulta interativa com as mesmas configurações de tradução de um job de tradução em lote fornecendo um ID de configuração de tradução em lote.

No Editor de consultas, clique em Mais > Configurações de tradução.
No campo ID de configuração de tradução, forneça um ID de configuração para tradução em lote para aplicar a mesma configuração de tradução de um job de migração em lote concluído do BigQuery.

Para encontrar o ID de configuração de tradução em lote de um job, selecione um job de tradução em lote na página Tradução de SQL e clique na guia Configuração de tradução. O ID de configuração de tradução em lote é listado como Nome do recurso.
Clique em Salvar.

Traduzir com outras configurações

Execute uma consulta interativa com configurações de tradução adicionais especificando arquivos YAML de configuração armazenados em uma pasta do Cloud Storage. As configurações de tradução podem incluir metadados de objetos SQL ou informações de mapeamento de objetos do banco de dados de origem que podem melhorar a qualidade da tradução. Por exemplo, inclua informações DDL ou esquemas do banco de dados de origem para melhorar a qualidade da tradução de SQL interativa.

Para especificar as configurações de tradução fornecendo um local para os arquivos de origem da configuração de tradução, faça o seguinte:

No Editor de consultas, clique em Mais > Configurações de tradução.
No campo Translation Configuration Source Location, especifique o caminho para os arquivos de configuração de tradução armazenados em uma pasta do Cloud Storage.

O tradutor de SQL interativo do BigQuery oferece suporte a arquivos ZIP de metadados que contêm metadados de tradução e mapeamento de nome de objeto. Consulte informações sobre como fazer upload de arquivos para o Cloud Storage em Fazer upload de objetos de um sistema de arquivos.
Clique em Salvar.

Para armazenar informações dos arquivos de metadados gerados pela ferramenta dwh-migration-dumper no back-end do BigQuery, faça o seguinte:

No Editor de consultas, clique em Mais > Configurações de tradução.
Marque a caixa de seleção Ativar o armazenamento em cache de metadados. Para jobs com arquivos de metadados grandes, esse processo reduz significativamente a latência de tradução para solicitações posteriores. Os metadados em cache ficam ativos por até sete dias. Esse recurso está na visualização. Para solicitar suporte ou enviar feedback sobre esse recurso, entre em contato com bq-edw-migration-support@google.com.
Clique em Salvar.

Limitações de tamanho do arquivo de configuração

Ao usar um arquivo de configuração de tradução com o conversor de SQL interativo do BigQuery, o arquivo de metadados compactado ou o arquivo de configuração YAML precisa ser menor que 50 MB. Se o tamanho do arquivo exceder 50 MB, o tradutor interativo pula esse arquivo de configuração durante a tradução e produz uma mensagem de erro semelhante a esta:

CONFIG ERROR: Skip reading file "gs://metadata-file.zip". File size (150,000,000 bytes) exceeds limit (50 MB).

Um método para reduzir o tamanho do arquivo de metadados é usar as sinalizações --database ou --schema para extrair apenas metadados de bancos de dados ou esquemas relevantes para as consultas de entrada de tradução. Para mais informações sobre como usar essas sinalizações ao gerar arquivos de metadados, consulte Sinalizações globais.

Resolver erros de tradução

Os erros a seguir costumam ser encontrados ao usar o conversor de SQL interativo.

Problemas de tradução do `RelationNotFound` ou `AttributeNotFound`

Para garantir a conversão mais precisa, insira as instruções da linguagem de definição de dados (DDL) para todas as tabelas usadas em uma consulta antes da consulta. Por exemplo, para traduzir a consulta do Amazon Redshift select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id;, é necessário inserir as seguintes instruções SQL no tradutor de SQL interativo:

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

Preços

Não há custo para usar o conversor de SQL interativo. No entanto, o armazenamento usado para armazenar arquivos de entrada e saída incorre em taxas normais. Para mais informações, consulte preços de armazenamento.

A seguir

Saiba mais sobre as seguintes etapas na migração do armazenamento de dados: