Migrar código com o tradutor de SQL em lote

Observação: para traduções baseadas em API, incluindo novas traduções em lote, recomendamos que você use a API BigQuery Migration para traduzir seus scripts SQL. A API Translation funciona como o tradutor do SQL em lote, mas sem a necessidade de instalar ou usar o código do cliente.

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. Este documento é destinado a usuários familiarizados com o Console do Google Cloud.

Antes de começar

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

1. Verifique se você tem todas ss permissões necessárias.
2. Ative a API BigQuery Migration.
3. Colete os arquivos de origem que contêm os scripts SQL e as consultas a serem traduzidos.
4. Opcional. Crie um arquivo de metadados para melhorar a precisão da tradução.
5. Opcional. Decida se você precisa mapear nomes de objetos SQL nos arquivos de origem para novos nomes no BigQuery. Determine quais regras de mapeamento de nome usar se isso for necessário.
6. Decida qual método usar para enviar o job de tradução.
7. Faça upload dos arquivos de origem para o Cloud Storage.

Permissões necessárias

É necessário ter as seguintes permissões no projeto para ativar o serviço de migração do BigQuery:

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

Você precisa das seguintes permissões no projeto para acessar 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

  Como alternativa, é possível usar os seguintes papéis para receber as mesmas permissões:

  • bigquerymigration.viewer: acesso somente de leitura.
  • bigquerymigration.editor: acesso de leitura e gravação.

Para acessar os buckets do Cloud Storage para arquivos de entrada e saída:

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

É possível conseguir todas as permissões necessárias do Cloud Storage com estes papéis:

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

Ativar a API BigQuery Migration

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.

Observação: os projetos criados após 15 de fevereiro de 2022 têm essa API ativada automaticamente.

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 ou forneça seus próprios arquivos 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.

Para fornecer seus próprios metadados, colete as instruções de linguagem de definição de dados (DDL) dos objetos SQL do sistema de origem em arquivos de texto separados.

Mapear nomes de objetos SQL

Observação: o mapeamento de nome de objeto usando JSON só é aceito pela API legada em lote. Se você estiver usando a API BigQuery Migration ou iniciar jobs em lote no console do Google Cloud, use o mapeamento de nome de objeto baseado em YAML.

Também é possível executar o mapeamento de nome de saída durante a tradução em lote. Ao usar o mapeamento de nome de saída, você especifica regras de mapeamento de nome que mudam os nomes de objetos SQL no sistema de origem para novos nomes no BigQuery. Por exemplo, você tem o objeto schema1.table1 no sistema de origem e você quer que ele seja nomeado como project1.dataset1.table1 no BigQuery. Se você usar o mapeamento do nome de saída, defina as regras de mapeamento de nome antes de iniciar um job de tradução em lote. Insira essas regras manualmente ao configurar o job ou crie um arquivo JSON que contenha as regras de mapeamento de nome e faça upload delas.

Decidir como enviar o trabalho de tradução

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

• Cliente da tradução em lote: para definir um job, altere as configurações em um arquivo de configuração e envie o job usando a linha de comando. Essa abordagem não exige o upload manual dos arquivos de origem para o Cloud Storage. O cliente ainda usa o Cloud Storage para armazenar arquivos durante o processamento do job de tradução.

  O cliente de tradução em lote é um cliente Python de código aberto que permite traduzir arquivos de origem localizados na máquina local e fazer com que os arquivos traduzidos sejam enviados para um diretório local. Defina o cliente para uso básico alterando algumas configurações no arquivo de configuração. Se quiser, também é possível configurar o cliente para realizar tarefas mais complexas, como substituição de macros e pré e 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.

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

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.

Se você quiser usar o console do Google Cloud ou a API BigQuery Migration para um job de tradução em lote, faça upload do arquivo YAML de configuração para o bucket do Cloud Storage que contém os arquivos de origem.

Se você quiser usar o cliente de tradução em lote, coloque o arquivo YAML de configuração na pasta de entrada da tradução local.

Fazer upload de arquivos de entrada no Cloud Storage

Se você quiser usar o console do Google Cloud ou a API BigQuery Migration para executar um job de tradução, 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 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.

Dialetos SQL compatíveis

O tradutor do SQL em lote faz parte do Serviço de migração do BigQuery. O tradutor de SQL em lote traduz os seguintes dialetos SQL em 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

Importante: a tradução é feita da melhor maneira possível. O sucesso da conversão pode variar dependendo da exclusividade e da complexidade das instruções SQL nos scripts de origem. Talvez seja necessário traduzir manualmente alguns scripts. Use a guia Ações na saída do Console do Google Cloud para diagnosticar e corrigir problemas de tradução.

Locais

O conversor de SQL em lote 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	Baixo CO2
	Madri	europe-southwest1	Baixo CO2
	Bélgica	europe-west1	Baixo CO2
	Londres	europe-west2	CO2 baixo
	Frankfurt	europe-west3	Baixo CO2
	Países Baixos	europe-west4	Baixo CO2
	Zurique	europe-west6	Baixo CO2
	Paris	europe-west9	Baixo CO2
	Turim	europe-west12
América
	São Paulo	southamerica-east1	Baixo CO2
	EUA multirregião	us
	Iowa	us-central1	CO2 baixo
	Carolina do Sul	us-east1
	Norte da Virgínia	us-east4
	Columbus, Ohio	us-east5
	Dallas	us-south1	Baixo CO2
	Oregon	us-west1	Baixo CO2
	Los Angeles	us-west2
	Salt Lake City	us-west3

Enviar um job de tradução

Siga estas etapas para iniciar um job de tradução, ver o progresso dele e ver os resultados.

Console

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

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

   Ir para o BigQuery

2. Na seção Migração do painel de navegação, clique em Tradução do SQL.

3. Clique em Iniciar tradução.

4. Preencha a caixa de diálogo de configuração de tradução.

   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 desejado, selecione BigQuery.

5. Clique em Próxima.

6. Em Local da origem, especifique o caminho da pasta do Cloud Storage que contém os arquivos a serem traduzidos. É possível digitar o caminho no formato bucket_name/folder_name/ ou usar a opção Procurar.

7. Clique em Próxima.

8. Em Região de destino, especifique o caminho da pasta de destino do Cloud Storage para os arquivos traduzidos. É possível digitar o caminho no formato bucket_name/folder_name/ ou usar a opção Procurar.

9. Se você estiver fazendo traduções que não precisem ter nomes de objetos padrão ou mapeamento de nomes de origem para destino especificado, pule para a etapa 11. Caso contrário, clique em Próxima.

10. Preencha as configurações opcionais necessárias.

    1. Opcional. Em Banco de dados padrão, digite um nome de banco de dados padrão para usar com os arquivos de origem. O tradutor usa esse nome de banco de dados padrão para resolver os nomes totalmente qualificados dos objetos SQL em que o nome do banco de dados está ausente.

    2. Opcional. No Caminho de pesquisa de esquema, especifique o esquema a ser pesquisado quando o tradutor precisar resolver nomes totalmente qualificados de objetos SQL nos arquivos de origem em que o nome do esquema esteja ausente. Se os arquivos de origem usarem vários nomes de esquema diferentes, clique em Adicionar nome de esquema e adicione um valor para cada nome de esquema que possa ser referenciado.

       O tradutor faz pesquisas nos arquivos de metadados fornecidos para validar tabelas com os nomes dos esquemas. Se não for possível determinar uma opção definida usando os metadados, o primeiro nome de esquema inserido será usado como padrão. Para mais informações sobre como o nome do esquema padrão é usado, consulte esquema padrão.

    3. Opcional. Se quiser especificar regras de mapeamento de nome para renomear objetos SQL entre o sistema de origem e o BigQuery durante a conversão, forneça um arquivo JSON pelo par de mapeamento de nomes ou use o console do Google Cloud para especificar os valores a serem mapeados.

       Para usar um arquivo JSON:

       1. Clique em Fazer upload do arquivo JSON para mapeamento de nome.

       2. Acesse o local de um arquivo de mapeamento de nome no formato adequado, selecione-o e clique em Abrir.

          O tamanho do arquivo precisa ser inferior a 5 MB.

       Para usar o console do Google Cloud:

       1. Clique em Adicionar par de mapeamento de nomes.
       2. Adicione as partes apropriadas do nome do objeto de origem aos campos Database, Schema, Relationship e Attribute na coluna Source.
       3. Adicione as partes do nome do objeto de destino no BigQuery nos campos da coluna Target.
       4. Em Tipo, selecione o tipo de objeto que descreve o objeto que você está mapeando.
       5. Repita as etapas de 1 a 4 até especificar todos os pares de mapeamento de nome necessários. Só é possível especificar até 25 pares de mapeamento de nome ao usar o console do Google Cloud.

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

Depois que o job de tradução for criado, será possível ver o status na lista de jobs de tradução.

Cliente de tradução em lote

Observação: recomendamos que as novas traduções usem a API BigQuery Migration em vez do cliente de tradução em lote.

1. Instale o cliente de tradução em lote e a Google Cloud CLI.

2. Gere um arquivo de credenciais da CLI gcloud.

3. No diretório de instalação do cliente de tradução em lote, use o editor de texto de sua preferência para abrir o arquivo config.yaml e modificar as seguintes configurações:

   • project_number: digite o número do projeto que você quer usar para o job de tradução em lote. É possível encontrá-lo no painel Informações do projeto na página de boas-vindas do console do Google Cloud do projeto.
   • gcs_bucket: digite o nome do bucket do Cloud Storage que o cliente de tradução em lote precisa usar para armazenar arquivos durante o processamento do job de tradução.
   • input_directory: digite o caminho absoluto ou relativo para o diretório que contém os arquivos de origem e os de metadados.
   • output_directory: digite o caminho absoluto ou relativo para o diretório de destino dos arquivos traduzidos.

4. Salve as alterações e feche o arquivo config.yaml.

5. Coloque os arquivos de origem e de metadados no diretório de entrada.

6. Execute o cliente de tradução em lote usando o seguinte comando:

   bin/dwh-migration-client
   

   Depois que o job de tradução for criado, será possível ver o status dele na lista de jobs de tradução no console do Google Cloud.

7. Opcional. Depois que o job de tradução for concluído, exclua os arquivos criados no bucket do Cloud Storage especificado para evitar custos de armazenamento.

Explorar o resultado da tradução

Depois de executar o job de tradução, é possível ver informações sobre ele no console do Google Cloud. Se você usou o console do Google Cloud para executar o job, poderá ver os resultados dele no bucket de destino do Cloud Storage especificado. Se você usou o cliente de tradução em lote para executar o job, será possível ver os resultados do job no diretório de saída especificado. 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.
• O mapeamento do nome de saída consumido no formato JSON.

Saída do console do Google Cloud

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

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

   Ir para o BigQuery

2. Na seção Migração do painel de navegação, clique em Tradução do SQL.

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

4. Na seção Resultados, é possível ver a taxa geral de êxito da tradução, o número de instruções processadas e a duração do job.

5. 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. Você também pode selecionar uma categoria de problema para ver as mensagens de registro associadas a ela (Visualização).

6. Selecione a guia Log Messages 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. 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 (prévia).

7. Selecione a guia Configuração da tradução para ver os detalhes da configuração do job.

Relatório do resumo

O relatório de resumo é um arquivo CSV que contém uma tabela de todas as mensagens de aviso e 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 BigQuery.

   Ir para o BigQuery

2. Na seção Migração do painel de navegação, clique em Tradução do SQL.

3. Na lista de jobs de tradução, localize o job que você quer e clique em Mostrar detalhes na coluna Status.

4. Na seção Relatório de tradução, clique em batch_translation_report.csv.

5. 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"

Visualização

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do 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.

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

   Acessar o BigQuery

2. Na seção Migração do painel de navegação, clique em Tradução do SQL.

3. Na lista de jobs de tradução, localize o job que você quer e clique em Mostrar detalhes na coluna Status.

4. Selecione a guia "Código".

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

.

Arquivo de mapeamento de nome de saída consumido

Esse arquivo JSON contém as regras de mapeamento do nome de saída que foram usadas pelo job de tradução. As regras nesse arquivo podem ser diferentes das regras de mapeamento de nome de saída especificadas para o job de tradução devido a conflitos nas regras de mapeamento de nome ou falta de regras de mapeamento de nome para objetos SQL que foram identificados durante a tradução. Revise esse arquivo para determinar se as regras de mapeamento de nome precisam de correção. Se isso acontecer, crie novas regras de mapeamento de nome de saída para resolver os problemas identificados e execute um novo job de tradução.

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.

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.

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

   Ir para o BigQuery

2. Na seção Migração do menu de navegação, clique em Tradução de SQL.

3. 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 Mais > Configurações de tradução no tradutor interativo.

Limitações

O tradutor não pode traduzir funções definidas pelo usuário (UDFs) de linguagens que não sejam SQL, porque não é possível analisá-las para determinar os tipos de dados de entrada e saída. Isso faz com que a conversão de instruções SQL que façam referência a essas UDFs seja imprecisa. Para garantir que as UDFs não SQL sejam referenciadas corretamente durante a conversão, use SQL válido para criar UDFs de marcador com as mesmas assinaturas.

Por exemplo, digamos que você tenha uma UDF escrita em C que calcula a soma de dois inteiros. Para garantir que as instruções SQL que se referem a essa UDF sejam traduzidas corretamente, crie uma UDF em SQL com marcador que compartilhe a mesma assinatura da UDF em C, conforme mostrado no exemplo a seguir:

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

Salve essa UDF de marcador em um arquivo de texto e inclua-o como um dos arquivos de origem do job de tradução. Isso permite que o tradutor aprenda a definição de UDF e identifique os tipos de dados de entrada e saída esperados.

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.

Resolver erros de tradução

Problemas de tradução do RelationNotFound ou AttributeNotFound

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.

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.

A seguir

Saiba mais sobre as seguintes etapas na migração do armazenamento de dados:

• 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