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 console doGoogle Cloud ou a Google Cloud CLI.

Observação: para criar uma integração de software personalizada, um pipeline de CI/CD automatizado ou outro fluxo de trabalho programático, consulte o guia da API BigQuery Migration.

Use o recurso de regra de tradução para personalizar a forma como o tradutor de SQL interativo traduz o SQL.

Para uma lista de dialetos SQL compatíveis com esse tradutor, consulte Dialetos SQL compatíveis.

Para conferir uma lista de locais de processamento compatíveis, consulte Locais.

Antes de começar

Antes de enviar um job de tradução, siga estas etapas.

Ativar traduções de SQL

Ative a API necessária e receba as permissões necessárias para usar um tradutor SQL do BigQuery. Para mais informações, consulte Ativar traduções de SQL.

Permissões necessárias

Para receber as permissões necessárias para criar jobs de tradução com o tradutor interativo, a API de tradução ou o tradutor de SQL em lote, peça ao administrador para conceder a você os seguintes papéis do IAM no recurso parent:

• Visualização e monitoramento de jobs de migração: Leitor do MigrationWorkflow (roles/bigquerymigration.viewer)
• Envio de jobs de migração: Editor de MigrationWorkflow (roles/bigquerymigration.editor)
• Acessar os buckets do Cloud Storage para entrada e arquivos: Administrador de objetos do Storage (roles/storage.objectAdmin) no bucket de origem e de destino do Cloud Storage.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para criar jobs de tradução com o tradutor interativo, a API de tradução ou o tradutor de SQL em lote. Para acessar 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 criar jobs de tradução com o tradutor interativo, a API de tradução ou o tradutor de SQL em lote:

• bigquerymigration.workflows.create
• bigquerymigration.workflows.get
• bigquerymigration.workflows.list
• bigquerymigration.workflows.delete
• bigquerymigration.subtasks.get
• bigquerymigration.subtasks.list
• storage.objects.get
• storage.objects.list
• storage.objects.create

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

Como lidar com funções SQL incompatíveis usando 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 isso, o serviço de migração do BigQuery (e a comunidade mais ampla do BigQuery) fornece funções auxiliares definidas pelo usuário (UDFs) que replicam o comportamento dessas funções de dialeto de origem não compatíveis.

Essas UDFs geralmente são encontradas no conjunto de dados público bqutil, permitindo que as consultas traduzidas as referenciem 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 testes iniciais, não é recomendável depender diretamente do bqutil para cargas de trabalho de produção por vários motivos:

1. Controle de versões: o projeto bqutil hospeda a versão mais recente dessas UDFs, o que significa que as definições delas podem mudar ao longo do tempo. Depender diretamente de bqutil pode levar a um comportamento inesperado ou a alterações interruptivas nas consultas de produção se a lógica de uma UDF for atualizada.
2. Isolamento de dependência: implantar UDFs no seu próprio projeto isola o ambiente de produção de mudanças externas.
3. Personalização: talvez seja necessário modificar ou otimizar essas UDFs para que elas se adaptem melhor à sua lógica de negócios ou aos requisitos de desempenho específicos. Isso só é possível se eles estiverem no seu próprio projeto.
4. 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 o processamento de dados de produção. Copiar UDFs para seu ambiente controlado está de acordo com essas políticas.

Como implantar UDFs auxiliares no projeto:

Para um uso de produção confiável e estável, implante essas UDFs auxiliares no seu próprio projeto e conjunto de dados. Isso dá a você 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árias para copiar as UDFs para seu ambiente.

Locais

O tradutor de SQL interativo está disponível apenas em alguns locais de processamento. Veja mais informações em Locais.

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

Traduzir uma consulta em GoogleSQL

É possível traduzir uma consulta com o console do Google Cloud ou a Google Cloud CLI.

Console

Siga estas etapas para traduzir uma consulta em GoogleSQL:

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

   Acessar o BigQuery

2. No painel Editor, clique em Ferramentas > Configurações de tradução.

3. Em Dialeto de origem, selecione o dialeto SQL que você quer traduzir.

4. 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.

5. Clique em Salvar.

6. No painel Editor, clique em Ferramentas > Ativar tradução do SQL.

   O painel Editor é dividido em dois.

7. No painel esquerdo, digite a consulta que você quer traduzir.

8. 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:

   

9. Opcional: para executar a consulta traduzida do GoogleSQL, clique em Executar.

10. Opcional: para retornar ao editor SQL, clique em Mais > Desativar tradução do SQL.

    O painel Editor retorna para um único painel.

gcloud

Visualizar

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para traduzir uma consulta da Google Cloud CLI, use o comando gcloud alpha bq translation translate:

gcloud alpha bq translation translate \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --input-file=INPUT_FILE

Substitua:

• SOURCE_DIALECT: o dialeto SQL que você quer traduzir, como teradata. Para ver os valores compatíveis, consulte Dialetos SQL compatíveis.
• TARGET_DIALECT: o dialeto para o qual a consulta será traduzida. Por exemplo, bigquery.
• LOCATION: o local em que você quer que o job de tradução seja executado. Por exemplo, se você estiver na Europa e não quiser que seus dados cruzem os limites de local, especifique a região eu.
• INPUT_FILE: o arquivo local que contém a consulta que você quer traduzir.

O comando mostra a consulta traduzida na CLI gcloud. Para gravar a consulta traduzida em um arquivo, adicione a flag --output-file.

Para traduzir uma consulta sem criar um arquivo, use o pipe na entrada padrão e omita a flag --input-file:

echo 'SELECT 1;' | gcloud alpha bq translation translate \
  --source-dialect=teradata \
  --target-dialect=bigquery \
  --location=us

Para aplicar as personalizações que você definiria em Configurações de tradução, use as seguintes flags:

• --translation-config-files: uma lista separada por vírgulas de arquivos YAML de configuração. Os nomes de arquivo precisam terminar com .config.yaml.
• --metadata-gcs-uri: o URI do Cloud Storage de um arquivo ZIP de metadados.
• --explanation-output-file: um arquivo local que recebe uma explicação da tradução gerada pelo Gemini.

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 tradução aprimoradas pelo Gemini

Observação :para receber suporte e enviar feedback sobre recursos em fase de pré-lançamento, entre em contato com [e-mail].

É 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.

Para criar uma regra de conversão de SQL aprimorada do Gemini, é possível criá-la 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)

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

Quando o menu Personalizar aparecer, siga as etapas abaixo.

1. 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ê queira substituir no campo Substituir e um padrão SQL para substituí-lo 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 na linguagem natural.

     Quando você cria uma regra usando esse comando, a tradução de SQL aprimorada pelo Gemini identifica a solicitação e faz a mudança especificada na consulta SQL.

2. Clique em Visualização.

3. Na caixa de diálogo Sugestões geradas pelo Gemini, revise as mudanças feitas pela tradução de SQL aprimorada pelo Gemini na consulta SQL com base na sua regra.

   

4. Opcional: para adicionar essa regra para uso em traduções futuras, marque a caixa de seleção Salvar este comando....

   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 de origem da configuração de tradução ainda não estiver definido, um navegador de pastas vai aparecer para você selecionar um. Um arquivo YAML de configuração está sujeito a limitações de tamanho do arquivo de configuração.

5. 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 upload dele para o Cloud Storage. Para mais informações, consulte Criar um arquivo YAML de configuração baseado no Gemini.

Depois de criar uma regra de conversão de SQL aprimorada do Gemini e fazer o upload dela para o Cloud Storage, aplique a regra fazendo o seguinte:

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

   Acessar o BigQuery

2. No Editor de consultas, clique em Ferramentas > Configurações de tradução.

3. No campo Translation Configuration Source Location, especifique o caminho para o arquivo YAML baseado no Gemini armazenado em uma pasta do Cloud Storage.

4. 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 houver um 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 as possíveis mudanças na entrada da tradução. (Prévia)

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:

1. Clique em Assist > Ver sugestões em qualquer lado do editor de código para revisar as mudanças sugeridas na consulta correspondente.

   

2. 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 tradução.

3. 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:

1. Na caixa de diálogo Sugestões geradas no Gemini, clique em Ver arquivo de configuração da regra do Gemini.

2. Quando o editor de configuração aparecer, selecione o arquivo YAML de configuração que você quer editar.

3. Faça a alteração e clique em Salvar.

4. Clique em Concluído para fechar o editor YAML.

5. Execute uma tradução interativa para aplicar a regra atualizada.

Explicar uma tradução

Visualizar

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação: com as traduções de SQL aprimoradas pelo Gemini, é possível gerar uma explicação em texto para seus scripts usando o modelo do Gemini. As traduções de SQL aprimoradas do Gemini têm permissão de uma quantidade limitada de uso do Gemini sem custos financeiros. Esse uso é suficiente para a maioria dos projetos de migração. Para solicitar um aumento desse limite ou para receber suporte e enviar feedback sobre esse recurso em fase de pré-lançamento, entre em contato com [e-mail].

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 e inconsistências de tradução entre a consulta SQL de origem e a consulta GoogleSQL traduzida.

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

1. Para criar uma explicação de tradução de SQL gerada pelo Gemini, clique em Assistir e em Explicar esta traduçã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.

1. No Editor de consultas, clique em Ferramentas > Configurações de tradução.

2. 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.

3. 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:

1. No Editor de consultas, clique em Ferramentas > Configurações de tradução.

2. 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 aceita 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.

3. 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

As seções a seguir descrevem os erros mais comuns ao usar o tradutor SQL interativo.

Problemas de tradução do RelationNotFound ou AttributeNotFound

Depois de traduzir uma consulta usando o tradutor de SQL interativo, talvez você encontre uma falha na tradução com o erro RelationNotFound ou AttributeNotFound.

Para encontrar traduções com falha, acesse a página Detalhes da tradução no BigQuery no console do Google Cloud e abra a guia Mensagens de registro.

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;, insira 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;

Corrigir problemas de tradução com o Gemini

Visualizar

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação :para solicitar feedback ou suporte sobre esse recurso, entre em contato com [e-mail].

Para corrigir jobs de tradução com falha com os erros RelationNotFound ou AttributeNotFound, use o Gemini para resolver esses problemas:

1. No BigQuery no console do Google Cloud , acesse a página Detalhes da tradução e abra a guia Mensagens de registro.
2. Clique na consulta que tem a mensagem RelationNotFound ou AttributeNotFound na coluna Categoria.
3. Clique em Correção sugerida.
4. Clique em Aplicar.
5. Para traduzir a consulta novamente, clique em Traduzir.

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 data warehouse:

• Visão geral da migração
• Avaliação da migração
• Visão geral de esquema e transferência de dados
• Tradução de SQL em lote
• Pipelines de dados
• Segurança e governança de dados
• Ferramenta de validação de dados