Migrar código com o tradutor de SQL em lote

Neste documento, descrevemos como usar o tradutor de SQL em lote no BigQuery para traduzir scripts escritos em outros dialetos de SQL em consultas do GoogleSQL. É possível enviar e analisar os resultados de um job de tradução no console do Google Cloud ou na linha de comando.

Observação: para criar uma integração de software personalizada, um pipeline de CI/CD automatizado ou outro fluxo de trabalho programático, recomendamos que você chame a API BigQuery Migration diretamente.

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.

Coletar arquivos de origem

Os arquivos de origem precisam ser arquivos de texto com SQL válido para o dialeto de origem. Os arquivos de origem também podem incluir comentários. Faça o possível para garantir que o SQL seja válido usando os métodos disponíveis.

Criar arquivos de metadados

Para ajudar o serviço a gerar resultados de tradução mais precisos, recomendamos que você forneça arquivos de metadados. No entanto, isso não é obrigatório.

Use a ferramenta de extração de linha de comando dwh-migration-dumper para gerar as informações de metadados. Depois que os arquivos de metadados forem preparados, será possível incluí-los com os arquivos de origem na pasta de origem da tradução. O tradutor os detecta automaticamente e os aproveita para traduzir arquivos de origem. Não é necessário definir configurações extras para isso.

Para gerar informações de metadados usando a ferramenta dwh-migration-dumper, consulte Gerar metadados para tradução.

Criar arquivos YAML de configuração

Também é possível criar e usar arquivos YAML de configuração para personalizar as traduções em lote. Esses arquivos podem ser usados para transformar a saída da tradução de várias maneiras. Por exemplo, é possível criar um arquivo YAML de configuração para alterar o caso de um objeto SQL durante a conversão.

Use uma das opções a seguir para incluir um arquivo YAML de configuração no job de tradução.

Console

Faça upload do arquivo YAML de configuração para o diretório do Cloud Storage que contém os arquivos de origem. Quando você seleciona esse diretório como um local de entrada, o job de tradução inclui o arquivo YAML de configuração automaticamente.

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.

As flags usadas com o comando gcloud alpha bq translation translate-batch dependem de onde o arquivo YAML de configuração está armazenado:

• Se o arquivo YAML de configuração estiver no mesmo diretório que os arquivos de origem, não será necessário usar outras flags. Quando você define esse diretório na flag --source-gcs-uris ou --source-local-dirs, o job inclui o arquivo YAML de configuração automaticamente.
• Se o arquivo YAML de configuração estiver armazenado separadamente na máquina local, use a flag --source-local-files para fazer upload dele e adicioná-lo ao job.
• Se o arquivo YAML de configuração estiver armazenado separadamente no Cloud Storage, use a flag --source-gcs-files para adicioná-lo ao job.

Por exemplo, o comando a seguir faz upload dos arquivos de origem e de um arquivo YAML de configuração armazenado separadamente da máquina local e, em seguida, executa o job de tradução:

gcloud alpha bq translation translate-batch \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-local-dirs=LOCAL_DIR=SOURCE_URI \
  --source-local-files=LOCAL_CONFIG_YAML=CONFIG_YAML_URI \
  --target-gcs-path=TARGET_URI

Substitua:

• LOCAL_CONFIG_YAML: o caminho local para o arquivo YAML de configuração, como ./configs/change-case.config.yaml.
• CONFIG_YAML_URI: o URI do Cloud Storage para o qual o comando faz upload do arquivo YAML de configuração, como gs://my_data_bucket/teradata/configs/change-case.config.yaml. Esse URI precisa estar fora do diretório SOURCE_URI.

Para descrições dos outros marcadores, consulte Enviar um job de tradução.

Fazer upload de arquivos de entrada no Cloud Storage

Faça upload dos arquivos de origem que contêm as consultas e os scripts que você quer traduzir para o Cloud Storage. Também é possível fazer upload de qualquer arquivo de metadados ou arquivos YAML de configuração para o mesmo bucket do Cloud Storage e diretório que contém os arquivos de origem. Para mais informações sobre como criar buckets e fazer upload de arquivos para o Cloud Storage, consulte Criar buckets e Fazer upload de objetos de um sistema de arquivos.

Escolher como enviar o job de tradução

Você tem duas opções para enviar um job de tradução em lote:

• Console doGoogle Cloud : configure e envie um job usando uma interface do usuário. Essa abordagem exige que você faça upload de arquivos de origem para o Cloud Storage.

• Google Cloud CLI: envie um job pela linha de comando usando a CLI gcloud. O comando translate-batch aceita os locais de origem e de destino como sinalizações e pode fazer upload de diretórios e arquivos locais para o Cloud Storage. Para mais informações, consulte Enviar um job de tradução.

As duas opções exigem que os arquivos de origem estejam acessíveis no Cloud Storage e criam o mesmo tipo de job de tradução. Um job enviado pela linha de comando ainda aparece na lista de jobs de tradução no console doGoogle Cloud .

Enviar um job de tradução

Use uma das seguintes opções para iniciar um job de tradução e conferir o progresso dele. Para analisar os resultados depois, consulte Analisar a saída da tradução.

Console

Para seguir estas etapas, é necessário ter feito upload dos arquivos de origem em um bucket do Cloud Storage.

Para usar o console do Google Cloud e enviar um job de tradução em lote, siga estas etapas:

1. No console do Google Cloud , acesse a página Tradução SQL.

   Acessar a tradução de SQL

2. No painel Tradução de SQL, clique em Iniciar tradução.

3. Em Configuração de tradução, digite o seguinte:

   1. Em Nome de exibição, digite um nome para o job de tradução. O nome pode conter letras, números ou sublinhados.
   2. 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. O job de tradução tem um desempenho melhor quando você escolhe o mesmo local que seu bucket de arquivo de origem.
   3. Em Dialeto de origem, selecione o dialeto SQL que você quer traduzir.
   4. Em Dialeto de destino, selecione GoogleSQL.

4. Clique em Próxima.

5. Em Detalhes do local do arquivo, especifique os caminhos do Cloud Storage a serem usados para entrada e saída de tradução. É possível digitar os caminhos no formato bucket_name/folder_name/ ou usar a opção Procurar para navegar até uma pasta.

   1. Em Local do diretório de saída, especifique um caminho para a pasta de destino do Cloud Storage para os arquivos traduzidos. Ele serve como um diretório raiz para todas as saídas de tradução.
   2. Escolha um ou mais locais de diretório de entrada que contenham o caminho para os arquivos SQL a serem traduzidos.
   3. Cada diretório de entrada pode receber um nome de subdiretório de saída abaixo do diretório de saída raiz, se necessário.

6. Clique em Próxima.

7. Selecione as configurações opcionais necessárias para personalizar os metadados e as saídas de tradução adicionais.

8. Opcional: para personalizar ainda mais o comportamento da tradução, crie arquivos YAML de configuração e coloque-os no bucket de entrada do Cloud Storage. Esses arquivos podem ser usados para renomear objetos, ativar otimizações, melhorar traduções com o Gemini e muito mais. Para mais informações sobre arquivos YAML de configuração, consulte Criar um arquivo YAML de configuração.

9. Clique em Criar para iniciar o job de tradução.

   Depois de criar o job de tradução, você pode ver o status dele na lista de jobs de tradução.

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 enviar um job de tradução em lote, use o comando gcloud alpha bq translation translate-batch. As flags usadas para identificar os arquivos de origem dependem de os arquivos estarem no Cloud Storage ou na máquina local.

Traduzir arquivos SQL no Cloud Storage

Para traduzir arquivos SQL que você já enviou para o Cloud Storage, identifique os diretórios de origem com a flag --source-gcs-uris. Se você quiser incluir arquivos que não estão em --source-gcs-uris, use a flag --source-gcs-files:

gcloud alpha bq translation translate-batch \
    --source-dialect=SOURCE_DIALECT \
    --target-dialect=TARGET_DIALECT \
    --location=LOCATION \
    --source-gcs-uris=SOURCE_URI \
    --target-gcs-path=TARGET_URI

Substitua:

• SOURCE_DIALECT: o dialeto dos arquivos SQL de origem, como teradata. Para ver os valores compatíveis, consulte Dialetos SQL compatíveis.
• TARGET_DIALECT: o dialeto para o qual os arquivos de origem serão traduzidos. Por exemplo, bigquery.
• LOCATION: o local que processa o job, como us.
• SOURCE_URI: o diretório do Cloud Storage que contém os arquivos de origem, como gs://my_data_bucket/teradata/input/.
• TARGET_URI: o diretório do Cloud Storage que recebe os arquivos traduzidos, como gs://my_data_bucket/teradata/output/.

Traduzir arquivos SQL na máquina local

Para traduzir arquivos que estão na sua máquina local, mapeie cada diretório local para um URI do Cloud Storage com a flag --source-local-dirs. O comando faz upload do diretório para esse URI e o inclui no job de tradução. Assim, você não precisa fazer upload dos arquivos por conta própria:

gcloud alpha bq translation translate-batch \
    --source-dialect=SOURCE_DIALECT \
    --target-dialect=TARGET_DIALECT \
    --location=LOCATION \
    --source-local-dirs=LOCAL_DIR=SOURCE_URI \
    --target-gcs-path=TARGET_URI

Substitua LOCAL_DIR pelo diretório local que contém os arquivos de origem, como ./teradata_queries. Para descrições dos outros marcadores de posição, consulte Traduzir arquivos SQL no Cloud Storage.

Para mapear arquivos individuais em vez de diretórios, use a flag --source-local-files.

Adicionar flags opcionais

Para gerar sugestões do Gemini junto com o SQL traduzido, adicione a flag --enable-ai-suggestion.

Por padrão, o comando aguarda a conclusão do job de tradução. Para enviar o job e retornar imediatamente, adicione a flag --async. Em seguida, o comando mostra um ID de tradução que pode ser transmitido ao comando gcloud alpha bq translation describe para verificar o status do job:

gcloud alpha bq translation describe TRANSLATION_ID \
    --location=LOCATION

Recuperar os arquivos de saída

O job de tradução grava os resultados no diretório do Cloud Storage definido na flag --target-gcs-path. Esse diretório de destino contém os arquivos traduzidos, o relatório de resumo da tradução e todos os arquivos de sugestão de IA.

Para copiar a saída para sua máquina local, use o seguinte comando:

gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY

Substitua:

• TARGET_URI: o URI de base de destino, como gs://my_data_bucket/teradata/output/.
• LOCAL_DIRECTORY: o diretório local que recebe os arquivos.

Seu job também aparece na lista de jobs de tradução no console doGoogle Cloud , mesmo que você o tenha enviado pela linha de comando. Para analisar a qualidade de uma saída de tradução, consulte Analisar a saída da tradução.

Tradução de metadados

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.

Além de traduzir scripts SQL, é possível traduzir os metadados que descrevem o data warehouse de origem. Um job de tradução de metadados lê os arquivos de metadados que você extraiu do sistema de origem e grava instruções de linguagem de definição de dados (DDL) do GoogleSQL que recriam esses objetos no BigQuery.

A entrada é um ou mais arquivos ZIP de metadados. Para saber como produzir esses arquivos com a ferramenta dwh-migration-dumper, consulte Gerar metadados para tradução.

É possível traduzir metadados usando o console do Google Cloud ou a CLI gcloud. Selecione uma das seguintes opções:

Console

A tradução de metadados é uma opção de saída em um job de tradução comum:

1. Siga as etapas em Enviar um job de tradução para configurar um job, usando o diretório do Cloud Storage que contém os arquivos ZIP de metadados como um local de entrada.
2. Em Configurações opcionais, selecione DDL.
3. Clique em Criar para criar o job.

O job grava as instruções DDL traduzidas no diretório de saída, junto com qualquer SQL traduzido.

gcloud

É possível traduzir metadados como um job próprio ou como uma saída extra de um job de tradução de SQL em lote.

Traduzir metadados por conta própria

Use o comando gcloud alpha bq translation translate-metadata quando as entradas forem arquivos ZIP de metadados e você não tiver SQL para traduzir:

gcloud alpha bq translation translate-metadata \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI

Substitua:

• SOURCE_DIALECT: o dialeto dos metadados de origem, como teradata. Para ver os valores compatíveis, consulte Dialetos SQL compatíveis.
• TARGET_DIALECT: o dialeto das tabelas de destino. Por exemplo, bigquery.
• LOCATION: o local que processa o job, como us.
• SOURCE_URI: o diretório do Cloud Storage que contém os arquivos ZIP de metadados, como gs://my_data_bucket/teradata/metadata/.
• TARGET_URI: o diretório do Cloud Storage que recebe as instruções DDL traduzidas, como gs://my_data_bucket/teradata/ddl_output/.

Para apontar para arquivos ZIP de metadados individuais em vez de um diretório, use a flag --source-gcs-files. Para fazer upload de arquivos de metadados da máquina local como parte do job, use a flag --source-local-dirs ou --source-local-files.

Assim como em um job de tradução em lote, o comando aguarda a conclusão do job. Adicione a flag --async para enviar o job e retornar um ID de tradução imediatamente.

Traduzir metadados como parte de uma tradução de SQL em lote

Se as entradas de tradução em lote já incluírem os arquivos ZIP de metadados, não será necessário um segundo job. Adicione metadata às saídas de tradução do job em lote com a flag --target-types, e o job vai gravar o SQL traduzido e as instruções DDL em uma única execução:

gcloud alpha bq translation translate-batch \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI \
  --target-types=sql,metadata

Para as outras flags que o comando translate-batch aceita, consulte Enviar um job de tradução.

Gerar DDL de origem

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.

Quando o SQL de origem faz referência a tabelas sem definições, o tradutor nem sempre consegue resolver os objetos, o que leva a problemas RelationNotFound ou AttributeNotFound.

A melhor maneira de resolver esses problemas é fornecer as definições reais dos objetos de origem. Execute a ferramenta dwh-migration-dumper no sistema de origem e inclua o arquivo ZIP de metadados resultante nas entradas de tradução. Para instruções, consulte Gerar metadados para tradução. Os metadados extraídos descrevem os objetos com exatidão, para que o tradutor os resolva sem suposições.

Se não for possível extrair metadados, por exemplo, quando você não tiver mais acesso ao sistema de origem, peça ao Gemini para inferir as instruções DDL ausentes do SQL de origem. O Gemini infere essas instruções DDL com base em como os objetos são usados nas suas consultas. Por isso, sempre revise e verifique essas instruções antes de usá-las.

É possível gerar a DDL de origem para suas traduções usando o Google Cloud console ou a CLI gcloud. Selecione uma destas opções:

Console

O Gemini gera sugestões de DDL de origem como parte de um job de tradução regular:

1. Siga as etapas em Enviar um job de tradução para configurar um job.
2. Em Configurações opcionais, selecione Sugestões da IA do Gemini.
3. Clique em Criar para criar o job.

Se a tradução produzir problemas RelationNotFound ou AttributeNotFound, o job vai gerar sugestões de instruções DDL de origem para os objetos não resolvidos. O job também traduz o SQL, então você não precisa de um job separado.

gcloud

O comando gcloud alpha bq translation generate-source-ddl lê o SQL de origem e retorna as instruções DDL de origem sugeridas:

gcloud alpha bq translation generate-source-ddl \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI

Substitua SOURCE_URI pelo diretório do Cloud Storage que contém os arquivos SQL de origem e TARGET_URI pelo diretório do Cloud Storage que recebe as instruções DDL geradas. Os outros marcadores de posição são os mesmos descritos em Traduzir metadados.

Para gerar sugestões como parte de um job de tradução, adicione a flag --enable-ai-suggestion ao comando translate-batch.

Em seguida, é possível fornecer as instruções DDL geradas como entrada para um job de tradução posterior para melhorar a qualidade da tradução. Para mais informações, consulte Problemas de tradução do RelationNotFound ou do AttributeNotFound.

Explorar o resultado da tradução

É possível analisar os resultados de um job de tradução no console do Google Cloud , independentemente de o job ter sido enviado pela linha de comando ou pelo console do Google Cloud . O tradutor SQL em lote gera os seguintes arquivos para o destino especificado:

• Os arquivos traduzidos.
• O relatório de resumo da tradução no formato CSV.
• Os arquivos de sugestão de IA.

Saída do console doGoogle Cloud

Para ver detalhes do job de tradução, siga estas etapas:

1. No console do Google Cloud , acesse a página Tradução SQL.

   Acessar a tradução de SQL

2. Na lista de jobs de tradução, localize aquele para o qual você quer ver os detalhes de tradução. Em seguida, clique no nome do job de tradução. Você verá uma visualização de Sankey que ilustra a qualidade geral do job, o número de linhas de código de entrada (excluindo linhas em branco e comentários) e uma lista de problemas que ocorreram durante o processo de tradução. Priorize as correções da esquerda para a direita. Problemas em um estágio inicial podem causar outros problemas nos estágios seguintes.

3. Mantenha o ponteiro sobre as barras de erro ou aviso e analise as sugestões para determinar as próximas etapas de depuração do job de tradução.

4. Selecione a guia Resumo do registro para ver um resumo dos problemas de tradução, incluindo as categorias de problemas, as ações sugeridas e a frequência com que cada problema ocorreu. Clique nas barras de visualização de Sankey para filtrar os problemas. Você também pode selecionar uma categoria de problema para ver as mensagens de registro associadas a ela.

5. Selecione a guia Mensagens de registro para ver mais detalhes sobre cada problema de tradução, incluindo a categoria dele, a mensagem específica e um link para o arquivo em que o problema ocorreu. Clique nas barras de visualização de Sankey para filtrar os problemas. Selecione um problema na guia Mensagem de registro para abrir a guia "Código", que exibe o arquivo de entrada e saída, se aplicável.

6. Clique na guia Detalhes do job para ver os detalhes da configuração do job de tradução.

Relatório do resumo

O relatório de resumo é um arquivo CSV que contém uma tabela de todas as mensagens de aviso e mensagem de erro encontradas durante o job de tradução.

Para ver o arquivo de resumo no console do Google Cloud , siga estas etapas:

1. No console do Google Cloud , acesse a página Tradução SQL.

   Acessar a tradução de SQL

2. Na lista de jobs de tradução, localize o job que você quer e clique no nome dele ou em Mais opções > Mostrar detalhes.

3. Na guia Detalhes do job, na seção Relatório de tradução, clique em translation_report.csv.

4. Na página Detalhes do objeto, clique no valor na linha URL autenticado para ver o arquivo no navegador.

A tabela a seguir descreve as colunas do arquivo de resumo:

Coluna	Descrição
Carimbo de data/hora	O carimbo de data/hora em que o problema ocorreu.
FilePath	O caminho para o arquivo de origem ao qual o problema está associado.
FileName	O nome do arquivo de origem ao qual o problema está associado.
ScriptLine	O número da linha em que o problema ocorreu.
ScriptColumn	O número da coluna em que o problema ocorreu
TranspilerComponent	O componente interno do mecanismo de tradução em que ocorreu o aviso ou o erro. Essa coluna pode estar vazia.
Ambiente	Ambiente de dialeto de tradução associado ao aviso ou erro. Essa coluna pode estar vazia.
ObjectName	O objeto SQL no arquivo de origem associado ao aviso ou erro. Essa coluna pode estar vazia.
Gravidade	A gravidade do problema, seja de aviso ou erro.
Categoria	É a categoria do problema de tradução.
SourceType	A origem do problema. O valor nesta coluna pode ser SQL, indicando um problema nos arquivos SQL de entrada, ou METADATA, indicando um problema no pacote de metadados.
Mensagem	O aviso ou a mensagem de erro do problema de tradução.
ScriptContext	O snippet SQL no arquivo de origem associado ao problema.
Ação	A ação recomendada para resolver o problema.

Guia "Código"

A guia de código permite revisar mais informações sobre os arquivos de entrada e saída de um job de tradução específico. Na guia de código, é possível examinar os arquivos usados em um job de tradução, analisar uma comparação lado a lado de um arquivo de entrada e a tradução dele em busca de imprecisões e ver mensagens e resumos de registro. para um arquivo específico em um job.

Para acessar a guia "Código", siga estas etapas:

1. No console do Google Cloud , acesse a página Tradução SQL.

   Acessar a tradução de SQL

2. Na lista de jobs de tradução, localize o job que você quer e clique no nome dele ou em Mais opções > Mostrar detalhes.

3. Selecione a guia "Código". A guia de código consiste nos seguintes painéis:

   

   • Explorador de arquivos: contém todos os arquivos SQL usados para tradução. Clique em um arquivo para ver a entrada e a saída da tradução e os problemas de tradução da tradução.
   • Entrada aprimorada pelo Gemini: o SQL de entrada que foi traduzido pelo mecanismo de tradução. Se você tiver especificado regras de personalização do Gemini para o SQL de origem na configuração do Gemini, o tradutor vai transformar a entrada original primeiro e, em seguida, traduzir a entrada aprimorada do Gemini. Para conferir a entrada original, clique em Abrir entrada original.
   • Resultado da tradução: o resultado da tradução. Se você tiver especificado regras de personalização do Gemini para o SQL de destino na configuração do Gemini, a transformação será aplicada ao resultado traduzido como uma saída aprimorada do Gemini. Se uma saída aprimorada pelo Gemini estiver disponível, clique no botão Sugestão do Gemini para analisá-la.

4. Opcional: para visualizar um arquivo de entrada e o arquivo de saída no tradutor de SQL interativo do BigQuery, clique em Editar. É possível editar os arquivos e salvar o arquivo de saída de volta no Cloud Storage.

Observação: é possível ver resumos de registro e mensagens do job de tradução geral na página de resultados.

.

Guia "Configuração"

É possível adicionar, renomear, visualizar ou editar os arquivos YAML de configuração na guia Configuração. O Explorador de esquemas mostra a documentação dos tipos de configuração compatíveis para ajudar você a escrever seus arquivos YAML de configuração. Depois de editar os arquivos YAML de configuração, execute o job novamente para usar a nova configuração.

Para acessar a guia de configuração, siga estas etapas:

1. No console do Google Cloud , acesse a página Tradução SQL.

   Acessar a tradução de SQL

2. Na lista de jobs de tradução, localize o job que você quer e clique no nome dele ou em Mais opções > Mostrar detalhes.

3. Na janela Detalhes da tradução, clique na guia Configuração.

Para adicionar um novo arquivo de configuração:

1. Clique em more_vert Mais opções > Criar arquivo YAML de configuração.
2. Um painel vai aparecer para você escolher o tipo, o local e o nome do novo arquivo YAML de configuração.
3. Clique em Criar.

Para editar um arquivo de configuração:

1. Clique no arquivo YAML de configuração.
2. Edite o arquivo e clique em Salvar.
3. Clique em Executar novamente para executar um novo job de tradução que use os arquivos YAML de configuração editados.

Para renomear um arquivo de configuração, clique em more_vert Mais opções > Renomear.

Arquivos traduzidos

Para cada arquivo de origem, um arquivo de saída correspondente é gerado no caminho de destino. O arquivo de saída contém a consulta traduzida.

Importante: a tradução é feita da melhor maneira possível. Sempre que possível, valide as consultas traduzidas.

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 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 pelos seguintes 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 que você tenha controle total sobre a versão, a personalização e o acesso da UDF, recomendamos implantar UDFs auxiliares no seu próprio projeto e conjunto de dados para um uso de produção confiável e estável. Para mais informações sobre os scripts e as etapas necessários para implantar UDFs auxiliares no seu ambiente, consulte Como implantar as UDFs.

Solução de problemas

Nesta seção, descrevemos como depurar consultas individuais e como resolver os erros de tradução mais comuns.

Depurar consultas SQL traduzidas em lote com o tradutor de SQL interativo

Use o tradutor de SQL interativo do BigQuery para analisar ou depurar uma consulta SQL usando os mesmos metadados ou informações de mapeamento de objetos do banco de dados de origem. Depois de concluir um job de tradução em lote, o BigQuery gera um ID de configuração de tradução com informações sobre os metadados do job, o mapeamento de objetos ou o caminho de pesquisa do esquema, conforme aplicável para a consulta. Use o ID de configuração da tradução em lote com o tradutor de SQL interativo para executar consultas SQL com a configuração especificada.

É possível depurar consultas SQL traduzidas em lote usando o console doGoogle Cloud ou a CLI gcloud. Selecione uma das seguintes opções:

Console

Para iniciar uma tradução de SQL interativa usando um ID de configuração de tradução em lote, siga estas etapas:

1. No console do Google Cloud , acesse a página Tradução SQL.

   Acessar a tradução de SQL

2. Na lista de jobs de tradução, localize o job que você quer e clique em Mais opções > Abrir tradução interativa.

   O tradutor de SQL interativo do BigQuery agora é aberto com o ID de configuração da tradução em lote correspondente. Para consultar o ID de configuração da tradução interativa, clique em Ferramentas > Tradução de consulta > Configurações de tradução no tradutor de SQL interativo.

Para depurar um arquivo de tradução em lote no tradutor de SQL interativo, siga estas etapas:

1. No console do Google Cloud , acesse a página Tradução SQL.

   Acessar a tradução de SQL

2. Na lista de jobs de tradução, localize o job que você quer e clique no nome dele ou em Mais opções > Mostrar detalhes.

3. Na janela Detalhes da tradução, clique na guia Código.

4. No explorador de arquivos, clique no nome do arquivo para abri-lo.

5. Ao lado do nome do arquivo de saída, clique em Editar para abrir os arquivos no tradutor de SQL interativo (pré-lançamento).

   Os arquivos de entrada e saída são preenchidos no tradutor de SQL interativo, que agora usa o ID de configuração da tradução em lote correspondente.

6. Para salvar o arquivo de saída editado de volta no Cloud Storage, no tradutor de SQL interativo, clique em Salvar > Salvar no GCS.

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 retraduzir e inspecionar uma única consulta sem abrir o console doGoogle Cloud , use o comando gcloud alpha bq translation translate. Isso é útil quando você reduz um problema de tradução em lote a uma consulta e quer iterar nela localmente.

gcloud alpha bq translation translate \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --input-file=INPUT_FILE \
  --output-file=OUTPUT_FILE \
  --translation-log-file=LOG_FILE \
  --explanation-output-file=EXPLANATION_FILE

Substitua:

• INPUT_FILE: o arquivo local que contém a consulta a ser traduzida. Se você omitir essa flag, o comando vai ler a consulta da entrada padrão.
• OUTPUT_FILE: o arquivo local que recebe a consulta traduzida. Se você omitir essa flag, o comando vai gravar a consulta na saída padrão.
• LOG_FILE: o arquivo YAML local que recebe os registros de tradução, que contêm as mesmas mensagens de problema que o console doGoogle Cloud mostra na guia Mensagens de registro.
• EXPLANATION_FILE: o arquivo local que recebe uma explicação da tradução gerada pelo Gemini.

Para reutilizar os metadados do job em lote para que a consulta resolva os mesmos objetos, adicione a flag --metadata-gcs-uri. Para mais informações, consulte Traduzir uma consulta em GoogleSQL.

Resolver erros de tradução

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

Problemas de tradução do RelationNotFound ou AttributeNotFound

Depois de traduzir uma consulta usando o tradutor de SQL em lote, pode ser que 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.

A tradução funciona melhor com DDLs de metadados. Quando as definições de objetos SQL não são encontradas, o mecanismo de tradução gera problemas RelationNotFound ou AttributeNotFound. Recomendamos o uso do extrator de metadados para gerar pacotes de metadados e garantir que todas as definições de objetos estejam presentes. Adicionar metadados é a primeira etapa recomendada para resolver a maioria dos erros de tradução, já que geralmente pode corrigir muitos outros erros causados indiretamente pela falta de metadados.

Para mais informações, consulte Gerar metadados para tradução e avaliação.

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. 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. Para acessar o arquivo e a linha que contém o erro na guia de código, clique no

   mensagem de erro.

4. Na coluna Ação, clique em Correção sugerida.

5. Selecione uma das seguintes opções: Aplicar ou Aplicar e executar novamente:

   • Para copiar o arquivo de esquema gerado do diretório de saída para o diretório de entrada, clique em Aplicar.
   • Para copiar o arquivo de esquema gerado do diretório de saída para o diretório de entrada e abrir uma janela de nova execução, clique em Apply and rerun.

Cotas e limites

• Aplicam-se as cotas da API BigQuery Migration.
• Cada projeto pode ter no máximo 10 tarefas de tradução ativas.
• Não há um limite rígido para o número total de arquivos de origem e de metadados, mas recomendamos manter o número de arquivos abaixo de 1.000 para melhor desempenho.

Preços

Não há cobrança para usar o conversor de SQL em lote. 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.

Ferramentas de linha de comando alternativas para fluxos de trabalho de migração

Também é possível enviar um job de tradução em lote usando um arquivo de configuração de tradução com a Google Cloud CLI (gcloud bq migration-workflows) ou com a ferramenta de linha de comando bq.

Para seguir estas etapas, é necessário ter feito upload dos arquivos de origem em um bucket do Cloud Storage.

Criar um arquivo de configuração de tradução

Um arquivo de configuração de tradução define o caminho para os arquivos de origem, o destino de saída e os dialetos de origem e de destino da tradução. É possível escrever esse arquivo em YAML ou JSON.

Observação: um arquivo de configuração de tradução não é o mesmo que um arquivo YAML de configuração. Um arquivo de configuração de tradução define o job em si. Um arquivo YAML de configuração personaliza como o tradutor transforma seu SQL.

O exemplo a seguir mostra um arquivo YAML de configuração de tradução do Teradata para o BigQuery:

tasks:
  translation_task:
    type: Teradata2BigQuery_Translation
    translationDetails:
      sourceTargetMapping:
      - sourceSpec:
          baseUri: gs://bq-translations/input
        targetSpec:
          relativePath: output
      targetBaseUri: gs://bq-translations
      targetTypes:
      - sql
      sourceEnvironment:
        defaultDatabase: default_db
        schemaSearchPath:
        - foo

O exemplo a seguir mostra um arquivo JSON de configuração de tradução do Teradata para o BigQuery:

{
  "tasks": {
    "translation_task": {
      "type": "Teradata2BigQuery_Translation",
      "translationDetails": {
        "sourceTargetMapping": [
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 1",
                "relativePath": "my_input_1"
              },
              "encoding": "UTF-8"
            }
          },
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 2",
                "relativePath": "my_input_2"
              },
              "encoding": "UTF-8"
            }
          }
        ],
        "targetReturnLiterals": [
          "sql/my_input_1",
          "sql/my_input_2"
        ]
      }
    }
  }
}

Enviar e gerenciar jobs de tradução

Use uma das seguintes ferramentas de linha de comando para enviar e gerenciar seus jobs de tradução.

gcloud

Para criar um job de tradução e executar o fluxo de trabalho, use o seguinte comando:

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE

Para criar e executar o fluxo de trabalho e retornar imediatamente com um link para ele, adicione a flag --async:

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE --async

Para listar seus jobs de tradução, use o seguinte comando:

gcloud bq migration-workflows list --location=LOCATION

Para ver os detalhes de um job de tradução específico, use o seguinte comando:

gcloud bq migration-workflows describe projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Substitua:

• LOCATION: o local do projeto do Google Cloud que está executando esse job de tradução.
• CONFIG_FILE: o caminho para o arquivo de configuração de tradução.
• PROJECT_ID: o ID do projeto do Google Cloud que está executando esse job de tradução.
• WORKFLOW_ID: o ID do job de tradução.

bq

Para executar o job de tradução, use o seguinte comando:

bq mk --migration_workflow --location=LOCATION --config_file=CONFIG_FILE

Para listar todos os jobs de tradução, use o seguinte comando:

bq ls --migration_workflow --location=LOCATION

Para ver detalhes sobre um job de tradução específico, use o seguinte comando:

bq show --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Para remover um job de tradução da lista, use o seguinte comando:

bq rm --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Substitua:

• LOCATION: o local do projeto do Google Cloud que está executando esse job de tradução.
• CONFIG_FILE: o caminho para o arquivo de configuração de tradução.
• PROJECT_ID: o ID do projeto do Google Cloud que está executando esse job de tradução.
• WORKFLOW_ID: o ID do job de tradução.

Recuperar arquivos de saída

Para baixar os arquivos de saída após a conclusão do job, use gcloud storage cp, conforme descrito em Recuperar os arquivos de saída. Para analisar o job no console do Google Cloud , consulte Analisar a saída da tradução.

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
• Pipelines de dados
• Tradução de SQL interativo
• Segurança e governança de dados
• Ferramenta de validação de dados