Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 gravados em outros dialetos SQL em consultas SQL padrão do Google. Este documento é destinado a usuários familiarizados com o Console do Google Cloud.

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

  • SQL do Amazon Redshift
  • SQL do Teradata, exceto SPL

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

  • Apache HiveQL
  • SQL do Apache Spark
  • T-SQL do Azure Synapse
  • Basic Teradata Query (BTEQ)
  • IBM Netezza SQL/NZPLSQL
  • SQL para MySQL
  • SQL da Oracle, PL/SQL, Exadata
  • SQL do Presto
  • SQL do PostgreSQL
  • SQL do Snowflake
  • T-SQL do SQL Server
  • Teradata SPL
  • SQL da Vertica

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

Antes de começar

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

  1. Ative a API BigQuery Migration.
  2. Colete os arquivos de origem que contêm os scripts SQL e as consultas a serem traduzidos.
  3. Opcional. Crie um arquivo de metadados para melhorar a precisão da tradução.
  4. 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.
  5. Decida qual método usar para enviar o job de tradução.
  6. Faça upload dos arquivos de origem para o Cloud Storage.

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

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.

É possível usar a ferramenta de linha de comando dwh-migration-dumper para gerar as informações de metadados ou fornecer 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

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.

  • API BigQuery Migration: configure e envie um job de maneira programática. Essa abordagem exige que você faça upload de arquivos de origem para o Cloud Storage.

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 é necessário fazer upload de todos os arquivos de metadados que você escolheu criar. Para informações sobre como criar buckets e fazer upload de arquivos no Cloud Storage, consulte Como criar buckets de armazenamento e Como fazer upload de objetos.

Enviar um job de tradução

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

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. Isso pode ser encontrado no painel Informações do projeto no painel 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.

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.

API

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

  1. Chame o método create com um fluxo de trabalho definido.
  2. Chame o método start para iniciar o fluxo de trabalho de tradução.

Use as bibliotecas de cliente da API BigQuery Migration para Go, Java e Python a fim de facilitar a configuração e o envio de jobs de tradução em lote de maneira programática.

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 ou a API BigQuery Migration para executar o job, poderá ver os resultados do job no bucket de destino do Cloud Storage que você especificou. Se você usou o cliente de tradução em lote para executar o job, poderá 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 o que você quer e clique no nome dele.

  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 Ações para ver problemas de tradução e com que frequência eles ocorreram. Cada ação listada tem linhas filhas que mostram a categoria do problema, a mensagem específica do problema e um link para o arquivo em que o problema ocorreu.

  6. 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 aquele em que você tem interesse 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
Timestamp 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.
Environment 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.
Severity A gravidade do problema, seja de aviso ou erro.
Category É a categoria do problema de tradução.
Message O aviso ou a mensagem de erro do problema de tradução.
ScriptContext O snippet SQL no arquivo de origem associado ao problema.
Action A ação recomendada para resolver o problema.

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.

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.

A seguir

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