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

Se o local tiver suporte, use o recurso de regra de tradução (pré-lançamento) para personalizar a forma como o tradutor de SQL interativo traduz o SQL.

Limitações

É preciso fazer login com uma Conta do Google para usar o conversor de SQL interativo. O conversor de SQL interativo não é compatível com o uso de identidades federadas.

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:

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

    Acesse a API BigQuery Migration

  2. 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 a fim de usar o tradutor interativo, peça que o administrador conceda 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

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
Tóquio asia-northeast1
Mumbai asia-south1
Singapura asia-southeast1
Sydney australia-southeast1
Europa
UE multirregião eu
Varsóvia europe-central2
Finlândia europe-north1 Ícone de folha Baixo CO2
Madri europe-southwest1 Ícone de folha Baixo CO2
Bélgica europe-west1 Ícone de folha Baixo CO2
Londres europe-west2 ícone de folha CO2 baixo
Frankfurt europe-west3 ícone de folha Baixo CO2
Países Baixos europe-west4 Ícone de folha Baixo CO2
Zurique europe-west6 Ícone de folha Baixo CO2
Paris europe-west9 Ícone de folha Baixo CO2
Turim europe-west12
América
São Paulo southamerica-east1 Ícone de folha Baixo CO2
EUA multirregião us
Iowa us-central1 Ícone de folha CO2 baixo
Carolina do Sul us-east1
Norte da Virgínia us-east4
Columbus, Ohio us-east5
Dallas us-south1 Ícone de folha Baixo CO2
Oregon us-west1 Ícone de folha Baixo CO2
Los Angeles us-west2
Salt Lake City us-west3

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)

Traduzir uma consulta em GoogleSQL

Siga estas etapas para traduzir uma consulta em GoogleSQL:

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

    Ir para o BigQuery

  2. No painel Editor, clique em Mais e selecione 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 Mais e selecione 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:

    Exibe uma consulta SQL do Teradata traduzida para o GoogleSQL

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

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

    O painel Editor retorna para um único painel.

Configurar 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 uma regra de tradução

É 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, faça o seguinte:

Console

Para criar uma regra de conversão de SQL aprimorada do Gemini, faça o seguinte:

  1. Depois de executar uma tradução interativa, clique em Personalizar.

    Botão "Personalizar tradução".

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

    • No prompt Substituir um padrão SQL por outro, especifique um padrão SQL que você queira substituir no campo Substituir e um padrão SQL para substituir. no campo With.

      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 saída da tradução 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 de tradução, descreva 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 alteração especificada na saída da tradução.

  3. Clique em Visualizar.

  4. Na caixa de diálogo Visualizar alterações sugeridas, revise as mudanças feitas pela tradução aprimorada do SQL do Gemini para o resultado da tradução com base na sua regra.

  5. Opcional: para adicionar essa regra para uso em traduções futuras, marque a caixa de seleção Adicionar regra....

    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. Um arquivo YAML de configuração pode aceitar até 10 regras de tradução e está sujeito a limitações de tamanho do arquivo de configuração.

  6. Para aplicar as mudanças sugeridas à saída da tradução, clique em Aplicar.

YAML

É possível criar uma regra de conversão de SQL aprimorada do Gemini criando um arquivo YAML de configuração e fazendo o upload dele para o Cloud Storage.

Requisitos

O arquivo YAML da regra de tradução precisa ter o sufixo .ai_config.yaml. Por exemplo, rules_1.ai_config.yaml

Limitações

Campos aceitos

O exemplo a seguir mostra como criar um arquivo YAML de regra de tradução aprimorada pelo Gemini usando um comando de linguagem natural.

rewrite_target: TARGET
instruction: NL_PROMPT

Substitua:

  • TARGET: especifique se você quer aplicar a regra de tradução ao SQL de entrada, SOURCE_SQL, ou ao SQL de saída, TARGET_SQL (padrão).
  • NL_PROMPT: em linguagem natural, descreva uma mudança no SQL de destino. A tradução de SQL aprimorada do Gemini identifica a solicitação e faz a mudança especificada

Também é possível criar um arquivo YAML de regras de tradução com várias regras de tradução (até 10). Cada regra pode consistir em um comando de linguagem natural (instruction) que descreve uma regra e um ou mais exemplos para substituir um padrão de SQL (input) por outro (output). Uma regra de tradução pode usar o campo instruction, um ou mais campos examples ou os dois tipos de campos para descrever a regra.

rewrite_target: TARGET
instruction: NL_PROMPT
translation_rules:
- instruction: NL_RULE_1
  examples:
  - input: RULE_1_INPUT_1
    output: RULE_1_OUTPUT_1
  - input: RULE_1_INPUT_2
    output: RULE_1_OUTPUT_2
- instruction: NL_RULE_2
  examples:
  - input: RULE_2_INPUT_1
    output: RULE_2_OUTPUT_1
…
…

Substitua:

  • NL_RULE_1 (opcional): em linguagem natural, descreva uma regra de tradução.
  • RULE_1_INPUT_1 (opcional): um padrão SQL que você quer substituir.

  • RULE_1_OUTPUT_1 (opcional): o padrão SQL esperado depois que input foi substituído.

    É possível adicionar mais translation_rules (até 10) e mais examples, conforme necessário.

Para conferir exemplos de arquivos YAML de regras de conversão de SQL aprimoradas do Gemini, consulte os Exemplos de arquivos YAML de regras de conversão.

Aplicar um arquivo YAML de regra de tradução à próxima tradução

Para aplicar um arquivo YAML de regra de tradução:

  1. No Editor de consultas, clique em Mais > Configurações de tradução.
  2. No campo Translation Configuration Source Location, especifique o caminho para o arquivo YAML da regra de tradução armazenado em uma pasta do Cloud Storage.
  3. Clique em Salvar.

Exemplos de arquivos YAML de regras de tradução

Os exemplos a seguir são arquivos YAML de regras de conversão de SQL aprimoradas do Gemini.

Exemplo 1: especifique uma função para ser substituída por outra.

translation_rules:
- instruction:  "Remove upper() function"
  examples:
  - input: "upper(X)"
    output: "X"

Exemplo 2: especifique várias regras de tradução em um único arquivo YAML.

translation_rules:
- instruction:  "Remove upper() function"
  examples:
  - input: "upper(X)"
    output: "X"
- instruction: "Insert a comment at the head that explains each statement in detail."

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 Mais > 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 Mais > 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 de configuração 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

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: