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 a fim de criar jobs de tradução usando a API Translation, peça ao administrador para conceder a você o papel do IAM de Editor do MigrationWorkflow (roles/bigquerymigration.editor) 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 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

Como 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 mais ampla do BigQuery) oferecem 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úblicos bqutil, permitindo que as consultas traduzidas se refiram a elas inicialmente 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, não é recomendável depender diretamente do bqutil para cargas de trabalho de produção 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 podem mudar com o tempo. Depender diretamente de bqutil pode levar a um comportamento inesperado ou a mudanças incompatíveis 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 ou requisitos de performance específicos. Isso só é possível se eles estiverem no seu 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 o processamento de dados de produção. Copiar UDFs para seu ambiente controlado está de acordo com essas políticas.

Como implantar UDFs auxiliares no projeto:

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

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
	Délhi	`asia-south2`
	Hong Kong	`asia-east2`
	Jacarta	`asia-southeast2`
	Melbourne	`australia-southeast2`
	Mumbai	`asia-south1`
	Osaka	`asia-northeast2`
	Seul	`asia-northeast3`
	Singapura	`asia-southeast1`
	Sydney	`australia-southeast1`
	Taiwan	`asia-east1`
	Tóquio	`asia-northeast1`
Europa
	Bélgica	`europe-west1`	Baixo CO₂
	Berlim	`europe-west10`
	UE multirregião	`eu`
	Finlândia	`europe-north1`	CO₂ baixo
	Frankfurt	`europe-west3`
	Londres	`europe-west2`	Baixo CO₂
	Madri	`europe-southwest1`	Baixo CO₂
	Milão	`europe-west8`
	Países Baixos	`europe-west4`	Baixo CO₂
	Paris	`europe-west9`	Baixo CO₂
	Estocolmo	`europe-north2`	Baixo CO₂
	Turim	`europe-west12`
	Varsóvia	`europe-central2`
	Zurique	`europe-west6`	Baixo CO₂
América
	Columbus, Ohio	`us-east5`
	Dallas	`us-south1`	Baixo CO₂
	Iowa	`us-central1`	CO₂ baixo
	Las Vegas	`us-west4`
	Los Angeles	`us-west2`
	México	`northamerica-south1`
	Norte da Virgínia	`us-east4`
	Oregon	`us-west1`	Baixo CO₂
	Quebec	`northamerica-northeast1`	Baixo CO₂
	São Paulo	`southamerica-east1`	CO₂ baixo
	Salt Lake City	`us-west3`
	Santiago	`southamerica-west1`	CO₂ baixo
	Carolina do Sul	`us-east1`
	Toronto	`northamerica-northeast2`	Baixo CO₂
	EUA multirregião	`us`
África
	Johannesburgo	`africa-south1`
MiddleEast
	Damã	`me-central2`
	Doha	`me-central1`
	Israel	`me-west1`

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 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 com 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 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 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 executada, 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, será possível 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 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 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 receber o status atualizado do fluxo de trabalho, execute uma consulta GET. 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"
}

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 pesquisar esse endpoint para verificar o status do seu fluxo de trabalho.