Migre código com o tradutor de SQL em lote

Este documento descreve como usar o tradutor de SQL em lote no BigQuery para traduzir scripts escritos noutros dialetos de SQL em consultas GoogleSQL. Este documento destina-se a utilizadores que estão familiarizados com a Trusted Cloud consola.

Antes de começar

Antes de enviar uma tarefa de tradução, conclua os seguintes passos:

1. Certifique-se de que tem todas as autorizações necessárias.
2. Ative a API BigQuery Migration.
3. Recolha os ficheiros de origem que contêm os scripts e as consultas SQL a serem traduzidos.
4. Opcional. Crie um ficheiro de metadados para melhorar a precisão da tradução.
5. Opcional. Decida se precisa de mapear os nomes dos objetos SQL nos ficheiros de origem para novos nomes no BigQuery. Determine que regras de mapeamento de nomes usar, se for necessário.
6. Decida que método usar para enviar a tarefa de tradução.
7. Carregue os ficheiros de origem para o Cloud Storage.

Autorizações necessárias

Tem de ter as seguintes autorizações no projeto para ativar o BigQuery Migration Service:

• resourcemanager.projects.get
• serviceusage.services.enable
• serviceusage.services.get

Precisa das seguintes autorizações no projeto para aceder e usar o serviço de migração do BigQuery:

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

• bigquerymigration.subtasks.list

  Em alternativa, pode usar as seguintes funções para obter as mesmas autorizações:

  • bigquerymigration.viewer - Acesso só de leitura.
  • bigquerymigration.editor - Acesso de leitura/escrita.

Para aceder aos contentores do Cloud Storage para ficheiros de entrada e saída:

• storage.objects.get no contentor do Cloud Storage de origem.
• storage.objects.list no contentor do Cloud Storage de origem.
• storage.objects.create no contentor de destino do Cloud Storage.

Pode ter todas as autorizações necessárias do Cloud Storage a partir das seguintes funções:

• roles/storage.objectAdmin
• roles/storage.admin

Ative a API BigQuery Migration

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

1. Na Trusted Cloud consola, aceda à página API BigQuery Migration.

   Aceda à API BigQuery Migration

2. Clique em Ativar.

Recolha ficheiros de origem

Os ficheiros de origem têm de ser ficheiros de texto que contenham SQL válido para o dialeto de origem. Os ficheiros de origem também podem incluir comentários. Faça o seu melhor para garantir que o SQL é válido, usando os métodos disponíveis.

Crie ficheiros de metadados

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

Pode usar a ferramenta de extração de linha de comandos para gerar as informações de metadados ou fornecer os seus próprios ficheiros de metadados.dwh-migration-dumper Depois de preparar os ficheiros de metadados, pode incluí-los juntamente com os ficheiros de origem na pasta de origem da tradução. O tradutor deteta-os automaticamente e tira partido deles para traduzir ficheiros de origem. Não precisa de configurar definições adicionais para ativar esta opção.

Para gerar informações de metadados através da ferramenta dwh-migration-dumper, consulte o artigo Gere metadados para tradução.

Para fornecer os seus próprios metadados, recolha as declarações da linguagem de definição de dados (DDL) para os objetos SQL no seu sistema de origem em ficheiros de texto separados.

Decida como enviar a tarefa de tradução

Tem três opções para enviar uma tarefa de tradução em lote:

• Cliente de tradução em lote: configure uma tarefa alterando as definições num ficheiro de configuração e envie a tarefa através da linha de comandos. Esta abordagem não requer que carregue manualmente ficheiros de origem para o Cloud Storage. O cliente continua a usar o Cloud Storage para armazenar ficheiros durante o processamento de tarefas de tradução.

  O cliente de tradução em lote antigo é um cliente Python de código aberto que lhe permite traduzir ficheiros de origem localizados na sua máquina local e ter os ficheiros traduzidos enviados para um diretório local. Configura o cliente para utilização básica alterando algumas definições no respetivo ficheiro de configuração. Se quiser, também pode configurar o cliente para resolver tarefas mais complexas, como a substituição de macros e o pré-processamento e o pós-processamento de entradas e saídas de tradução. Para mais informações, consulte o readme do cliente de tradução em lote.

• Trusted Cloud consola: configure e envie uma tarefa através de uma interface de utilizador. Esta abordagem requer que carregue ficheiros de origem para o Cloud Storage.

Crie ficheiros YAML de configuração

Opcionalmente, pode criar e usar ficheiros YAML de configuração para personalizar as suas traduções em lote. Estes ficheiros podem ser usados para transformar o resultado da tradução de várias formas. Por exemplo, pode criar um ficheiro YAML de configuração para alterar a capitalização de um objeto SQL durante a tradução.

Se quiser usar a Trusted Cloud consola ou a API BigQuery Migration para uma tarefa de tradução em lote, pode carregar o ficheiro YAML de configuração para o contentor do Cloud Storage que contém os ficheiros de origem.

Se quiser usar o cliente de tradução em lote, pode colocar o ficheiro YAML de configuração na pasta de entrada de tradução local.

Carregue ficheiros de entrada para o Cloud Storage

Se quiser usar a Trusted Cloud consola ou a API BigQuery Migration para executar uma tarefa de tradução, tem de carregar os ficheiros de origem que contêm as consultas e os scripts que quer traduzir para o Cloud Storage. Também pode carregar quaisquer ficheiros de metadados ou ficheiros YAML de configuração para o mesmo contentor do Cloud Storage e diretório que contêm os ficheiros de origem. Para mais informações sobre como criar contentores e carregar ficheiros para o Cloud Storage, consulte os artigos Crie contentores e Carregue objetos a partir de um sistema de ficheiros.

Dialetos de SQL suportados

O tradutor de SQL em lote faz parte do serviço de migração do BigQuery. O tradutor de SQL em lote pode traduzir os seguintes dialetos de SQL para GoogleSQL:

• SQL do Amazon Redshift
• Apache HiveQL e CLI Beeline
• IBM Netezza SQL e NZPLSQL
• Teradata e Teradata Vantage
  • SQL
  • Basic Teradata Query (BTEQ)
  • Teradata Parallel Transport (TPT)

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

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

Processamento de funções SQL não suportadas com UDFs auxiliares

Quando traduz SQL de um dialeto de origem para o BigQuery, algumas funções podem não ter um equivalente direto. Para resolver este problema, o serviço de migração do BigQuery (e a comunidade do BigQuery em geral) disponibilizam funções definidas pelo utilizador (UDFs) auxiliares que replicam o comportamento destas funções de dialeto de origem não suportadas.

Estas FDU são frequentemente encontradas no conjunto de dados público bqutil, o que permite que as consultas traduzidas as referenciem inicialmente através do 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 estas FDU auxiliares para tradução e testes iniciais, a confiança direta no bqutil para cargas de trabalho de produção não é recomendada por vários motivos:

1. Controlo de versões: o projeto bqutil aloja a versão mais recente destas FDU, o que significa que as respetivas definições podem mudar ao longo do tempo. A utilização direta de bqutil pode levar a um comportamento inesperado ou a alterações significativas nas suas consultas de produção se a lógica de uma FDU for atualizada.
2. Isolamento de dependências: a implementação de FDU no seu próprio projeto isola o ambiente de produção de alterações externas.
3. Personalização: pode ter de modificar ou otimizar estas FDU para se adequarem melhor à sua lógica de negócio específica ou aos requisitos de desempenho. Isto só é possível se estiverem no seu próprio projeto.
4. Segurança e governação: as políticas de segurança da sua organização podem restringir o acesso direto a conjuntos de dados públicos, como o bqutil, para o tratamento de dados de produção. A cópia de FDU para o seu ambiente controlado está alinhada com essas políticas.

Implementar UDFs auxiliares no seu projeto:

Para uma utilização de produção fiável e estável, deve implementar estas UDFs auxiliares no seu próprio projeto e conjunto de dados. Isto dá-lhe controlo total sobre a versão, a personalização e o acesso. Para instruções detalhadas sobre como implementar estas FDU, consulte o guia de implementação de FDUs no GitHub. Este guia fornece os scripts e os passos necessários para copiar as FDUs para o seu ambiente.

Localizações

O tradutor de SQL em lote está disponível nas seguintes localizações de processamento:

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

Envie uma tarefa de tradução

Siga estes passos para iniciar uma tarefa de tradução, ver o respetivo progresso e consultar os resultados.

Explore o resultado da tradução

Após executar a tarefa de tradução, pode ver informações sobre a tarefa na Trusted Cloud consola. Se usou a Trusted Cloud consola para executar a tarefa, pode ver os resultados da tarefa no contentor do Cloud Storage de destino que especificou. Se usou o cliente de tradução em lote para executar a tarefa, pode ver os resultados da tarefa no diretório de saída que especificou. O tradutor de SQL em lote gera os seguintes ficheiros no destino especificado:

• Os ficheiros traduzidos.
• O relatório de resumo de tradução no formato CSV.
• O mapeamento do nome de saída consumido no formato JSON.
• Os ficheiros de sugestões de IA.

Trusted Cloud saída da consola

Para ver os detalhes da tarefa de tradução, siga estes passos:

1. Na Trusted Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No menu de navegação, clique em Tradução de SQL.

3. Na lista de tarefas de tradução, localize a tarefa cujos detalhes de tradução quer ver. Em seguida, clique no nome da tarefa de tradução. Pode ver uma visualização de Sankey que ilustra a qualidade geral da tarefa, 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. Deve priorizar as correções da esquerda para a direita. Os problemas numa fase inicial podem causar problemas adicionais nas fases subsequentes.

4. Mantenha o ponteiro sobre as barras de erro ou aviso e reveja as sugestões para determinar os passos seguintes para depurar a tarefa de tradução.

5. Selecione o separador Resumo do registo para ver um resumo dos problemas de tradução, incluindo categorias de problemas, ações sugeridas e a frequência com que cada problema ocorreu. Pode clicar nas barras de visualização de Sankey para filtrar problemas. Também pode selecionar uma categoria do problema para ver as mensagens de registo associadas a essa categoria do problema.

6. Selecione o separador Mensagens de registo para ver mais detalhes sobre cada problema de tradução, incluindo a categoria do problema, a mensagem de problema específica e um link para o ficheiro no qual o problema ocorreu. Pode clicar nas barras de visualização de Sankey para filtrar problemas. Pode selecionar um problema no separador Log Message para abrir o separador Code que apresenta o ficheiro de entrada e saída, se aplicável.

7. Clique no separador Detalhes da tarefa para ver os detalhes de configuração da tarefa de tradução.

Relatório de resumo

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

Para ver o ficheiro de resumo na Trusted Cloud consola, siga estes passos:

1. Na Trusted Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No menu de navegação, clique em Tradução de SQL.

3. Na lista de tarefas de tradução, localize a tarefa na qual tem interesse e, de seguida, clique no nome da tarefa ou em Mais opções > Mostrar detalhes.

4. No separador Detalhes da tarefa, na secção Relatório de tradução, clique em translation_report.csv.

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

A tabela seguinte descreve as colunas do ficheiro de resumo:

Separador Código

O separador Código permite-lhe rever mais informações sobre os ficheiros de entrada e saída de uma tarefa de tradução específica. No separador Código, pode examinar os ficheiros usados numa tarefa de tradução, rever uma comparação lado a lado de um ficheiro de entrada e a respetiva tradução para detetar imprecisões, e ver resumos e mensagens de registo para um ficheiro específico numa tarefa.

Para aceder ao separador Código, siga estes passos:

1. Na Trusted Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No menu de navegação, clique em Tradução de SQL.

3. Na lista de tarefas de tradução, localize a tarefa na qual tem interesse e, de seguida, clique no nome da tarefa ou em Mais opções > Mostrar detalhes.

4. Selecione o separador Código. O separador Código é composto pelos seguintes painéis:

   

   • File Explorer: contém todos os ficheiros SQL usados para tradução. Clique num ficheiro para ver a respetiva entrada e saída de tradução, bem como quaisquer problemas de tradução da respetiva tradução.
   • Entrada melhorada pelo Gemini: o SQL de entrada que foi traduzido pelo motor de tradução. Se tiver especificado regras de personalização do Gemini para o SQL de origem na configuração do Gemini, o tradutor transforma primeiro a entrada original e, em seguida, traduz a entrada melhorada pelo Gemini. Para ver a entrada original, clique em Ver entrada original.
   • Resultado da tradução: o resultado da tradução. Se tiver especificado regras de personalização do Gemini para o SQL de destino na configuração do Gemini, a transformação é aplicada ao resultado traduzido como um resultado melhorado pelo Gemini. Se estiver disponível um resultado melhorado pelo Gemini, pode clicar no botão Sugestão do Gemini para rever o resultado melhorado pelo Gemini.

5. Opcional: para ver um ficheiro de entrada e o respetivo ficheiro de saída no tradutor de SQL interativo do BigQuery, clique em Editar. Pode editar os ficheiros e guardar o ficheiro de saída novamente no Cloud Storage.

Separador Configuração

Pode adicionar, mudar o nome, ver ou editar os seus ficheiros YAML de configuração no separador Configuração.O Explorador de esquemas mostra a documentação dos tipos de configuração suportados para ajudar a escrever os seus ficheiros YAML de configuração. Depois de editar os ficheiros YAML de configuração, pode executar novamente a tarefa para usar a nova configuração.

Para aceder ao separador de configuração, siga estes passos:

1. Na Trusted Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No menu de navegação, clique em Tradução de SQL.

3. Na lista de tarefas de tradução, localize a tarefa na qual tem interesse e, de seguida, clique no nome da tarefa ou em Mais opções > Mostrar detalhes.

4. Na janela Detalhes da tradução, clique no separador Configuração.

Para adicionar um novo ficheiro de configuração:

1. Clique em more_vert Mais opções > Criar ficheiro YAML de configuração.
2. É apresentado um painel onde pode escolher o tipo, a localização e o nome do novo ficheiro YAML de configuração.
3. Clique em Criar.

Para editar um ficheiro de configuração existente:

1. Clique no ficheiro YAML de configuração.
2. Edite o ficheiro e, de seguida, clique em Guardar.
3. Clique em Executar novamente para executar uma nova tarefa de tradução que use os ficheiros YAML de configuração editados.

Pode mudar o nome de um ficheiro de configuração existente clicando em more_vert Mais opções > Mudar o nome.

Ficheiro de mapeamento de nomes de saída consumido

Este ficheiro JSON contém as regras de mapeamento de nomes de saída que foram usadas pela tarefa de tradução. As regras neste ficheiro podem diferir das regras de mapeamento de nomes de saída que especificou para a tarefa de tradução, devido a conflitos nas regras de mapeamento de nomes ou à falta de regras de mapeamento de nomes para objetos SQL que foram identificados durante a tradução. Reveja este ficheiro para determinar se as regras de mapeamento de nomes precisam de correção. Se o fizer, crie novas regras de mapeamento de nomes de saída que resolvam quaisquer problemas que identificar e execute uma nova tarefa de tradução.

Ficheiros traduzidos

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

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

Pode usar o tradutor de SQL interativo do BigQuery para rever ou depurar uma consulta SQL usando as mesmas informações de metadados ou mapeamento de objetos que a base de dados de origem. Depois de concluir uma tarefa de tradução em lote, o BigQuery gera um ID de configuração de tradução que contém informações sobre os metadados da tarefa, o mapeamento de objetos ou o caminho de pesquisa do esquema, conforme aplicável à consulta. Usa o ID da configuração de tradução em lote com o tradutor de SQL interativo para executar consultas SQL com a configuração especificada.

Para iniciar uma tradução de SQL interativa através de um ID de configuração de tradução em lote, siga estes passos:

1. Na Trusted Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No menu de navegação, clique em Tradução de SQL.

3. Na lista de tarefas de tradução, localize a tarefa na qual tem interesse e, de seguida, clique em more_vert Mais opções > Abrir tradução interativa.

   O tradutor de SQL interativo do BigQuery é agora aberto com o ID da configuração de tradução em lote correspondente. Para ver o ID da configuração de tradução para a tradução interativa, clique em Mais > Definições de tradução no tradutor de SQL interativo.

Para depurar um ficheiro de tradução em lote no tradutor de SQL interativo, siga estes passos:

1. Na Trusted Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No menu de navegação, clique em Tradução de SQL.

3. Na lista de tarefas de tradução, localize a tarefa na qual tem interesse e, de seguida, clique no nome da tarefa ou em Mais opções > Mostrar detalhes.

4. Na janela Detalhes da tradução, clique no separador Código.

5. No explorador de ficheiros, clique no nome do ficheiro para o abrir.

6. Junto ao nome do ficheiro de saída, clique em Editar para abrir os ficheiros no tradutor de SQL interativo (pré-visualização).

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

7. Para guardar o ficheiro de saída editado novamente no Cloud Storage, no tradutor de SQL interativo, clique em Guardar > Guardar no GCS.

Limitações

O tradutor não consegue traduzir funções definidas pelo utilizador (UDFs) de idiomas que não sejam SQL, porque não consegue analisá-las para determinar os respetivos tipos de dados de entrada e saída. Isto faz com que a tradução de declarações SQL que referenciam estas FDU seja imprecisa. Para se certificar de que as FDU não SQL são devidamente referenciadas durante a tradução, use SQL válido para criar FDU de marcadores de posição com as mesmas assinaturas.

Por exemplo, suponhamos que tem uma FDU escrita em C que calcula a soma de dois números inteiros. Para garantir que as declarações SQL que fazem referência a esta FDU são traduzidas corretamente, crie uma FDU SQL de marcador de posição que partilhe a mesma assinatura que a FDU C, conforme mostrado no exemplo seguinte:

CREATE FUNCTION Test.MySum (a INT, b INT)
  RETURNS INT
  LANGUAGE SQL
  RETURN a + b;

Guarde esta FDU de marcador de posição num ficheiro de texto e inclua esse ficheiro como um dos ficheiros de origem para a tarefa de tradução. Isto permite que o tradutor aprenda a definição da UDF e identifique os tipos de dados de entrada e saída esperados.

Quota e limites

• Aplicam-se as quotas da API BigQuery Migration.
• Cada projeto pode ter, no máximo, 10 tarefas de tradução ativas.
• Embora não exista um limite rígido para o número total de ficheiros de origem e de metadados, recomendamos que mantenha o número de ficheiros abaixo de 1000 para um melhor desempenho.

Resolva problemas de erros de tradução

Problemas de tradução de RelationNotFound ou AttributeNotFound

A tradução funciona melhor com DDLs de metadados. Quando não é possível encontrar as definições de objetos SQL, o motor de tradução gera problemas RelationNotFound ou AttributeNotFound. Recomendamos que use o extrator de metadados para gerar pacotes de metadados para garantir que todas as definições de objetos estão presentes. A adição de metadados é o primeiro passo recomendado para resolver a maioria dos erros de tradução, uma vez que, muitas vezes, pode corrigir muitos outros erros causados indiretamente pela falta de metadados.

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

Preços

Não é cobrado qualquer valor pela utilização do tradutor de SQL em lote. No entanto, o armazenamento usado para guardar ficheiros de entrada e saída incorre nas taxas normais. Para mais informações, consulte os preços de armazenamento.

O que se segue?

Saiba mais sobre os seguintes passos na migração do armazém de dados:

• Vista geral da migração
• Avaliação da migração
• Vista geral do esquema e da transferência de dados
• Data pipelines
• Tradução interativa de SQL
• Segurança e governação de dados
• Ferramenta de validação de dados