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 Google Cloud console.

É possível usar o recurso de regra de tradução para personalizar a forma como o tradutor de SQL interativo converte o SQL.

Para uma lista de dialetos SQL com suporte, consulte Dialetos SQL com suporte.

Para uma lista de locais de processamento com suporte, 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 de 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 consolidada 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)
• Acesso aos buckets do Cloud Storage para entrada e arquivos: Administrador de objetos do Storage (roles/storage.objectAdmin) no bucket do Cloud Storage de origem e destino.

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 consolidada de tradução ou o tradutor de SQL em lote. Para acessar as permissões exatas que são 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 consolidada 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 papéis personalizados ou outros papéis predefinidos.

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 isso, o BigQuery Migration Service (e a comunidade mais ampla 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 inicialmente façam referência a elas 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, a dependência direta do bqutil para cargas de trabalho de produção não é recomendada por vários motivos:

1. 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. Depender diretamente do bqutil pode levar a um comportamento inesperado ou a mudanças interruptivas nas consultas de produção se a lógica de uma UDF for atualizada.
2. Isolamento de dependências: a implantação de 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 melhor atender à lógica de negócios ou aos requisitos de desempenho específicos. Isso só é possível se elas 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 processamento de dados de produção. Copiar UDFs para o ambiente controlado está alinhado a essas políticas.

Como implantar UDFs auxiliares no seu projeto:

Para uso de produção confiável e estável, implante essas UDFs auxiliares no seu próprio projeto e conjunto de dados. Isso oferece 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. Esse guia fornece os scripts e as etapas necessários para copiar as UDFs para o ambiente.

Locais

O tradutor de SQL interativo está disponível apenas em locais de processamento selecionados. 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 modelos do Google

Traduzir uma consulta em GoogleSQL

Siga estas etapas para traduzir uma consulta em GoogleSQL:

1. No Google Cloud console, 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.

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 com o Gemini

**Observação** : para receber suporte e enviar feedback sobre recursos 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 tradutor 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 com o Gemini, crie-a no console ou crie um arquivo YAML de configuração e faça o upload dele para o Cloud Storage.

Console

Para criar uma regra de conversão de SQL aprimorada com o Gemini para o SQL de entrada , escreva uma consulta SQL de entrada no editor de consultas e clique em ASSISTIR > Personalizar. (Prévia)

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

Quando o menu Personalizar aparecer, continue com as etapas a seguir.

1. Use uma ou as duas solicitações a seguir para criar uma regra de tradução:

   • No prompt Encontrar e substituir um padrão , especifique um padrão SQL que você queira 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 prompt, 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 mudança 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 prompt, a tradução do SQL aprimorada do 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 do 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 prompt....

   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 Translation Configuration Source Location ainda não estiver definido, um navegador de pastas vai aparecer e permitir que você selecione 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 com o 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 no Gemini.

Depois de fazer o upload de uma regra de conversão de SQL aprimorada com o Gemini para o Cloud Storage, é possível aplicar a regra fazendo o seguinte:

1. No Google Cloud console, 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 mudanças sugeridas vai aparecer e mostrar possíveis mudanças na entrada de 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 revisar e aplicar essas sugestões, faça o seguinte:

1. Clique em Assistir > Ver sugestões em qualquer um dos lados 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 por 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 baseado no Gemini

Para atualizar um arquivo YAML de configuração atual, 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 mudança e clique em Salvar.

4. Feche o editor YAML clicando em Concluído.

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

Explicar uma tradução

Visualizar

Esse produto ou recurso está sujeito aos "Termos de ofertas 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 com o Gemini, é possível gerar explicações de texto para seus scripts pelo modelo do Gemini. As traduções de SQL aprimoradas com o 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 de 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 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.

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

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

Problemas de tradução do RelationNotFound ou AttributeNotFound

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

Para encontrar traduções com falha, acesse a página Detalhes da tradução 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;, é 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;

Corrigir problemas de tradução com o Gemini

Visualizar

Esse produto ou recurso está sujeito aos "Termos de ofertas 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 para esse recurso, entre em contato com [e-mail].

Para corrigir jobs de tradução com falha com os erros RelationNotFound ou AttributeNotFound, também é possível usar o Gemini para tentar resolver esses problemas com as etapas a seguir.

1. 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. Clique em Traduzir para traduzir a consulta novamente.

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