Converter consultas SQL com a API de tradução

Neste documento, descrevemos como usar a API BigQuery Migration no BigQuery para traduzir scripts escritos em outros dialetos SQL em consultas do GoogleSQL.

Para uma lista de dialetos SQL compatíveis com esse tradutor e de locais de processamento aceitos, consulte Dialetos SQL compatíveis e Locais.

Antes de começar

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

Escolher um modo de tradução

A API BigQuery Migration oferece suporte a dois modos de tradução. Os dois modos usam o mesmo método de API e são executados como jobs assíncronos. Os modos diferem na forma como você fornece o SQL de origem e recebe o SQL traduzido:

  • Tradução em lote: a API lê arquivos de origem do Cloud Storage e grava os arquivos e relatórios traduzidos no Cloud Storage. Use a tradução em lote para traduzir vários arquivos de uma vez, por exemplo, ao migrar uma base de código inteira.
  • Tradução interativa: você transmite seu SQL como strings literais no corpo da solicitação e lê o SQL traduzido na resposta do fluxo de trabalho. Não é necessário armazenar seu SQL ou a saída da tradução no Cloud Storage. Use a tradução interativa para traduzir consultas individuais sob demanda, por exemplo, ao traduzir consultas de um aplicativo ou uma ferramenta de desenvolvedor.

Ativar traduções

Ative a API BigQuery Migration necessária. 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 Translation ou o tradutor de SQL em lote, peça ao administrador para conceder a você os seguintes papéis do IAM no recurso parent:

  • Visualizar e monitorar jobs de migração: Leitor do MigrationWorkflow (roles/bigquerymigration.viewer)
  • Envio de jobs de migração: Editor do 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 Translation 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 Translation 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.

Fazer upload de arquivos de entrada no Cloud Storage

Para jobs de tradução em lote, 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.

Funções SQL sem suporte

Se as consultas de origem fizerem referência a funções SQL que não têm equivalentes diretos no GoogleSQL, use funções auxiliares definidas pelo usuário (UDFs). Para mais informações, consulte Como processar funções SQL não compatíveis com UDFs auxiliares.

Enviar um job de tradução

Para enviar um job de tradução usando a API BigQuery Migration, use o método projects.locations.workflows.create e forneça uma instância do recurso MigrationWorkflow com um tipo de tarefa compatível.

Depois de enviar o job, é possível pesquisar o status dele.

Criar uma tradução em lote

O comando curl a seguir cria um job de tradução em lote em que os arquivos de entrada e saída são armazenados no Cloud Storage. O campo source_target_mapping contém uma lista que mapeia os diretórios de origem para um caminho relativo opcional para a saída de destino.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
            \"target_base_uri\": \"TARGET_BASE\",
            \"source_target_mapping\": {
              \"source_spec\": {
                  \"base_uri\": \"BASE\"
              }
            },
            \"target_types\": \"TARGET_TYPES\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows

Substitua:

  • TYPE: o tipo de tarefa da tradução, que determina o dialeto de origem e de destino.
  • TARGET_BASE: o URI base de todas as saídas de tradução.
  • BASE: o URI de base de todos os arquivos lidos como origens para tradução.

  • TARGET_TYPES (opcional): os tipos de saída gerados. Se não for especificado, o SQL será gerado.

    • sql (padrão): os arquivos de consulta SQL traduzidos.
    • suggestion: sugestões geradas por IA.

    A saída é armazenada em uma subpasta no diretório de saída. O nome da subpasta é baseado no valor em TARGET_TYPES.

  • TOKEN: o token para autenticação. Para gerar um token, use o comando gcloud auth print-access-token ou o OAuth 2.0 Playground (use o escopo https://www.googleapis.com/auth/cloud-platform).

  • PROJECT_ID: o projeto que vai processar a tradução.

  • LOCATION: o local em que o job é processao.

O comando anterior retorna uma resposta que inclui um ID de fluxo de trabalho escrito no formato projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Exemplo de tradução em lote

Para traduzir os scripts SQL do Teradata no diretório do Cloud Storage gs://my_data_bucket/teradata/input/ e armazenar os resultados no diretório do Cloud Storage gs://my_data_bucket/teradata/output/, use a seguinte consulta:

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
       }
    }
  }
}

Essa chamada vai retornar uma mensagem com o ID do fluxo de trabalho criado no campo "name":

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Para receber o status atualizado do fluxo de trabalho, execute uma consulta GET. O job envia saídas para o Cloud Storage à medida que avança. O job state muda para COMPLETED depois que todos os target_types solicitados são gerados. Se a tarefa for concluída, você vai encontrar a consulta SQL traduzida em gs://my_data_bucket/teradata/output.

Exemplo de tradução em lote com sugestões de IA

O exemplo a seguir traduz os scripts do Teradata SQL localizados no diretório gs://my_data_bucket/teradata/input/ do Cloud Storage e armazena os resultados no diretório gs://my_data_bucket/teradata/output/ do Cloud Storage com uma sugestão adicional de IA:

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
          "target_types": "suggestion",
       }
    }
  }
}

Depois que a tarefa for concluída, as sugestões de IA poderão ser encontradas no diretório gs://my_data_bucket/teradata/output/suggestion do Cloud Storage.

Criar uma tradução interativa

O comando curl a seguir cria um job de tradução interativo com entradas e saídas de literais de string. O campo source_target_mapping contém uma lista que mapeia as entradas literal de origem para um caminho relativo opcional para a saída de destino.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
        \"source_target_mapping\": {
            \"source_spec\": {
              \"literal\": {
              \"relative_path\": \"PATH\",
              \"literal_string\": \"STRING\"
              }
            }
        },
        \"target_return_literals\": \"TARGETS\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows

Substitua:

  • TYPE: o tipo de tarefa da tradução, que determina o dialeto de origem e de destino.
  • PATH: o identificador da entrada literal, semelhante a um nome de arquivo ou caminho.
  • STRING: string de dados de entrada literal (por exemplo, SQL) a serem traduzidos.
  • TARGETS: os segmentos esperados que o usuário quer que sejam retornados diretamente na resposta no formato literal. Eles precisam estar no formato de URI de destino (por exemplo, GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). O que estiver fora dessa lista não será retornado na resposta. O diretório gerado, GENERATED_DIR para traduções gerais de SQL, é sql/.
  • TOKEN: o token para autenticação. Para gerar um token, use o comando gcloud auth print-access-token ou o OAuth 2.0 Playground (use o escopo https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: o projeto que vai processar a tradução.
  • LOCATION: o local em que o job é processado.

O comando anterior retorna uma resposta que inclui um ID de fluxo de trabalho escrito no formato projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Depois que o fluxo de trabalho for criado, confira os resultados verificando o status do job.

Exemplo de tradução interativa

Para traduzir a string SQL do Apache Hive select 1 de forma interativa, use a seguinte consulta:

"tasks": {
  string: {
    "type": "HiveQL2BigQuery_Translation",
    "translation_details": {
      "source_target_mapping": {
        "source_spec": {
          "literal": {
            "relative_path": "input_file",
            "literal_string": "select 1"
          }
        }
      },
      "target_return_literals": "sql/input_file",
    }
  }
}

Você pode usar qualquer relative_path que quiser para seu literal, mas o literal traduzido só vai aparecer nos resultados se você incluir sql/$relative_path no seu target_return_literals. Também é possível incluir vários literais em uma única consulta. Nesse caso, cada um dos caminhos relativos precisa ser incluído em target_return_literals.

Essa chamada vai retornar uma mensagem com o ID do fluxo de trabalho criado no campo "name":

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Para conferir o status atualizado do fluxo de trabalho, verifique o status do job. O job é concluído quando "state" muda para COMPLETED. Se a tarefa for concluída com êxito, você vai encontrar o SQL traduzido na mensagem de resposta:

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "string": {
      "id": "0fedba98-7654-3210-1234-56789abcdef",
      "type": "HiveQL2BigQuery_Translation",
      /* ... */
      "taskResult": {
        "translationTaskResult": {
          "translatedLiterals": [
            {
              "relativePath": "sql/input_file",
              "literalString": "-- Translation time: 2023-10-05T21:50:49.885839Z\n-- Translation job ID: projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00\n-- Source: input_file\n-- Translated from: Hive\n-- Translated to: BigQuery\n\nSELECT\n    1\n;\n"
            }
          ],
          "reportLogMessages": [
            ...
          ]
        }
      },
      /* ... */
    }
  },
  "state": "COMPLETED",
  "createTime": "2023-10-05T21:50:49.543221Z",
  "lastUpdateTime": "2023-10-05T21:50:50.462758Z"
}

Verificar o status do job

Os jobs de tradução são executados de forma assíncrona. Depois de enviar um fluxo de trabalho, recupere o status dele enviando uma solicitação GET com o ID do fluxo de trabalho:

curl \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer TOKEN" \
  -X GET https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Substitua:

  • TOKEN: o token para autenticação. Para gerar um token, use o comando gcloud auth print-access-token ou o OAuth 2.0 Playground (use o escopo https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: o projeto que está executando o job de tradução.
  • LOCATION: o local em que o job é processado.
  • WORKFLOW_ID: o ID do fluxo de trabalho retornado quando você criou o fluxo de trabalho de tradução.

Estados do fluxo de trabalho

A resposta inclui um campo state que indica o status atual do fluxo de trabalho:

  • STATE_UNSPECIFIED: o estado do fluxo de trabalho não foi especificado.
  • RUNNING: o fluxo de trabalho está em execução. Faça uma pesquisa periódica no endpoint até que o estado mude.
  • PAUSED: o fluxo de trabalho está pausado.
  • COMPLETED: o fluxo de trabalho foi concluído com sucesso. Agora você pode recuperar os resultados.
  • FAILED: o fluxo de trabalho encontrou erros. Inspecione os campos taskResult e reportLogMessages na resposta para ver os detalhes do erro.

Quando o fluxo de trabalho state atingir COMPLETED ou FAILED, você poderá interromper a pesquisa.

Recuperar resultados

A forma de recuperar os resultados depende de você ter enviado uma tradução em lote ou interativa:

  • Traduções em lote: os arquivos traduzidos, os relatórios de resumo e as sugestões de IA são gravados no diretório de destino do Cloud Storage especificado em target_base_uri. É possível ler esses arquivos diretamente do Cloud Storage usando comandos de armazenamento da CLI gcloud, as bibliotecas de cliente do Cloud Storage ou a API REST:

    gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY

    Substitua:

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

    Para mais detalhes sobre os arquivos gerados no bucket de destino, consulte Analisar a saída da tradução.

  • Traduções interativas: para jobs configurados com entradas de literal de string e target_return_literals, a consulta traduzida é retornada diretamente na resposta do fluxo de trabalho no campo translatedLiterals:

    "taskResult": {
  "translationTaskResult": {
    "translatedLiterals": [
      {
        "relativePath": "sql/input_file",
        "literalString": "SELECT 1;\n"
      }
    ]
  }
}

    Extraia o campo literalString de cada entrada em translatedLiterals para receber a consulta traduzida.