Esta página foi traduzida pela API Cloud Translation.

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.

Antes de começar

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

Verifique se você tem todas ss permissões necessárias.
Ative a API BigQuery Migration.
Colete os arquivos de origem que contêm os scripts SQL e as consultas a serem traduzidos.
Faça upload dos arquivos de origem para o Cloud Storage.

Permissões necessárias

Para receber as permissões necessárias para criar jobs de tradução usando a API consolidada de tradução, peça ao administrador para conceder a você o papel MigrationWorkflow Editor (roles/bigquerymigration.editor) do IAM no recurso parent. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar jobs de tradução usando a API consolidada de tradução. Para conferir 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 usando a API consolidada de tradução:

bigquerymigration.workflows.create
bigquerymigration.workflows.get

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

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:

No console do Google Cloud, acesse a página da API BigQuery Migration.

Acesse a API BigQuery Migration
Clique em Ativar.

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.

Tipos de tarefas com suporte

A API Translation pode traduzir os seguintes dialetos SQL para o GoogleSQL:

SQL do Amazon Redshift: Redshift2BigQuery_Translation
Apache HiveQL e CLI Beeline: HiveQL2BigQuery_Translation
SQL do Apache Spark: SparkSQL2BigQuery_Translation
T-SQL do Azure Synapse: AzureSynapse2BigQuery_Translation
SQL do Greenplum: Greenplum2BigQuery_Translation
SQL do IBM Database2: Db22BigQuery_Translation
IBM Netezza SQL e NZPLSQL: Netezza2BigQuery_Translation
SQL para MySQL: MySQL2BigQuery_Translation
SQL da Oracle, PL/SQL, Exadata: Oracle2BigQuery_Translation
SQL do PostgreSQL: Postgresql2BigQuery_Translation
Presto ou Trino SQL: Presto2BigQuery_Translation
SQL do Snowflake: Snowflake2BigQuery_Translation
SQLite - SQLite2BigQuery_Translation
T-SQL do SQL Server: SQLServer2BigQuery_Translation
Teradata e Teradata Vantage: Teradata2BigQuery_Translation
SQL da Vertica: Vertica2BigQuery_Translation

Locais

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

Enviar um job de tradução

Para enviar um job de tradução usando a API Translation, 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 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 pela 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 gs://my_data_bucket/teradata/input/ do Cloud Storage e armazenar os resultados no diretório gs://my_data_bucket/teradata/output/ do Cloud Storage, 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 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, 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 todas as target_types solicitadas são geradas. Se a tarefa for concluída, a consulta SQL traduzida vai estar 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 mais sugestões 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 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á conferir 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 maneira 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 no 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 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, execute uma consulta GET. O job é concluído quando "state" muda para COMPLETED. Se a tarefa for bem-sucedida, 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"
}

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 seu fluxo de trabalho.