O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Converter consultas SQL com a API de tradução

Neste documento, descrevemos como usar a API de tradução no BigQuery para traduzir scripts escritos em outros dialetos SQL em consultas do GoogleSQL. A API Translation pode simplificar o processo de migração de cargas de trabalho para o BigQuery.

Para uma lista de dialetos SQL com suporte nesse tradutor de SQL e uma lista de locais de processamento com suporte, consulte Dialetos SQL com suporte e locais.

Antes de começar

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

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 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 do MigrationWorkflow (roles/bigquerymigration.editor)
Acesso aos buckets do Cloud Storage para entrada e arquivos: Administrador de objetos do Storage (roles/storage.objectAdmin) no bucket do Cloud Storage de origem e de destino.

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 papéis personalizados ou outros papéis predefinidos.

Fazer upload de arquivos de entrada no Cloud Storage

Se você quiser usar o Google Cloud console 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.

Processar funções SQL sem suporte com 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 BigQuery Migration Service (e a comunidade do BigQuery em geral) fornecem funções definidas pelo usuário (UDFs) auxiliares que replicam o comportamento dessas funções de dialeto de origem sem suporte.

Essas UDFs geralmente são encontradas no conjunto de dados público bqutil, permitindo que as consultas traduzidas inicialmente façam referência a elas usando o 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 essas UDFs auxiliares para tradução e testes iniciais, a dependência direta do bqutil para cargas de trabalho de produção não é recomendada por vários motivos:

Controle de versão: o projeto bqutil hospeda a versão mais recente dessas UDFs, o que significa que as definições delas podem mudar com o tempo. Depender diretamente do bqutil pode levar a comportamentos inesperados ou mudanças interruptivas nas consultas de produção se a lógica de uma UDF for atualizada.
Isolamento de dependências: a implantação de UDFs no seu próprio projeto isola o ambiente de produção de mudanças externas.
Personalização: talvez seja necessário modificar ou otimizar essas UDFs para se adequar melhor à sua lógica de negócios específica ou aos requisitos de desempenho. Isso só é possível se elas estiverem no seu próprio projeto.
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 processamento de dados de produção. Copiar UDFs para seu ambiente controlado está alinhado a essas políticas.

Como implantar UDFs auxiliares no seu projeto

Para uso de produção confiável e estável, implante essas UDFs auxiliares no seu próprio projeto e conjunto de dados. Isso oferece controle total sobre a versão, a personalização e o acesso delas. Para instruções detalhadas sobre como implantar essas UDFs, consulte o guia de implantação de UDFs no GitHub. Esse guia fornece os scripts e as etapas necessários para copiar as UDFs para seu ambiente.

Enviar um job de tradução

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

Depois que o job for enviado, você poderá emitir uma consulta para receber os resultados.

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 as entradas literal 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/v2alpha/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. A subpasta é nomeada com base 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 contendo o ID do fluxo de trabalho criado no "name" campo:

{
  "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 state do job muda para COMPLETED depois que todos os target_types solicitados são gerados. Se a tarefa for bem-sucedida, você poderá 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 SQL do Teradata localizados no diretório do Cloud Storage gs://my_data_bucket/teradata/input/ e armazena os resultados no diretório do Cloud Storage gs://my_data_bucket/teradata/output/ com sugestão de IA adicional:

{
  "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 executada, as sugestões de IA poderão ser encontradas no diretório do Cloud Storage gs://my_data_bucket/teradata/output/suggestion.

Criar um job de tradução interativo com entradas e saídas de literal de string

O comando curl a seguir cria um job de tradução com entradas e saídas de literais de string. 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\": {
        \"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/v2alpha/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.

Quando o job for concluído, você poderá consultar os resultados consultando o job e examinando o campo translation_literals inline na resposta após a conclusão do fluxo de trabalho.

Exemplo de tradução interativa

Para traduzir a string SQL do 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 o literal, mas o literal traduzido só vai aparecer nos resultados se você incluir sql/$relative_path em 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 contendo o ID do fluxo de trabalho criado no "name" campo:

{
  "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 será concluído quando "state" mudar para COMPLETED. Se a tarefa for bem-sucedida, você 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"
}

Explorar o resultado da tradução

Depois de executar o job de tradução, recupere os resultados especificando o ID do fluxo de trabalho do job de tradução com o seguinte comando:

curl \
-H "Content-Type:application/json" \
-H "Authorization:Bearer TOKEN" -X GET https://bigquerymigration.googleapis.com/v2alpha/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 vai processar a tradução.
LOCATION: o local em que o job é processado.
WORKFLOW_ID: o ID gerado quando você cria um fluxo de trabalho de tradução.

A resposta contém o status do fluxo de trabalho de migração e todos os arquivos concluídos em target_return_literals.

A resposta vai conter o status do fluxo de trabalho de migração e todos os arquivos concluídos em target_return_literals. É possível consultar esse endpoint para verificar o status do fluxo de trabalho.