Algumas ou todas as informações nesta página podem não se aplicar à Trusted Cloud by S3NS. Consulte o artigo Diferenças em relação ao Google Cloud para mais detalhes.

Esta página foi traduzida pela API Cloud Translation.

Traduza consultas SQL com a API Translation

Este documento descreve como usar a API Translation no BigQuery para traduzir scripts escritos noutros dialetos SQL em consultas 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 uma tarefa de tradução, conclua os seguintes passos:

Certifique-se de que tem todas as autorizações necessárias.
Ative a API BigQuery Migration.
Recolha os ficheiros de origem que contêm os scripts e as consultas SQL a serem traduzidos.
Carregue os ficheiros de origem para o Cloud Storage.

Autorizações necessárias

Para obter as autorizações de que precisa para criar tarefas de tradução através da API Translation, peça ao seu administrador que lhe conceda a função IAM Editor do MigrationWorkflow (roles/bigquerymigration.editor) no recurso parent. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para criar tarefas de tradução através da API Translation. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para criar tarefas de tradução através da API Translation:

bigquerymigration.workflows.create
bigquerymigration.workflows.get

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Ative a API BigQuery Migration

Se o seu projeto da Google Cloud CLI foi criado antes de 15 de fevereiro de 2022, ative a API BigQuery Migration da seguinte forma:

Na Trusted Cloud consola, aceda à página API BigQuery Migration.

Aceda à API BigQuery Migration
Clique em Ativar.

Carregue ficheiros de entrada para o Cloud Storage

Se quiser usar a Trusted Cloud consola ou a API BigQuery Migration para executar uma tarefa de tradução, tem de carregar os ficheiros de origem que contêm as consultas e os scripts que quer traduzir para o Cloud Storage. Também pode carregar quaisquer ficheiros de metadados ou ficheiros YAML de configuração para o mesmo contentor do Cloud Storage que contém os ficheiros de origem. Para mais informações sobre como criar contentores e carregar ficheiros para o Cloud Storage, consulte os artigos Crie contentores e Carregue objetos a partir de um sistema de ficheiros.

Tipos de tarefas suportados

A API de tradução pode traduzir os seguintes dialetos SQL para GoogleSQL:

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

Processamento de funções SQL não suportadas com UDFs auxiliares

Quando traduz SQL de um dialeto de origem para o BigQuery, algumas funções podem não ter um equivalente direto. Para resolver este problema, o serviço de migração do BigQuery (e a comunidade do BigQuery em geral) disponibilizam funções definidas pelo utilizador (UDFs) auxiliares que replicam o comportamento destas funções de dialeto de origem não suportadas.

Estas FDU são frequentemente encontradas no conjunto de dados público bqutil, o que permite que as consultas traduzidas as referenciem inicialmente através do 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 estas FDU auxiliares para tradução e testes iniciais, a confiança direta no bqutil para cargas de trabalho de produção não é recomendada por vários motivos:

Controlo de versões: o projeto bqutil aloja a versão mais recente destas FDU, o que significa que as respetivas definições podem mudar ao longo do tempo. A utilização direta de bqutil pode levar a um comportamento inesperado ou a alterações significativas nas suas consultas de produção se a lógica de uma FDU for atualizada.
Isolamento de dependências: a implementação de FDU no seu próprio projeto isola o ambiente de produção de alterações externas.
Personalização: pode ter de modificar ou otimizar estas FDU para se adequarem melhor à sua lógica de negócio específica ou aos requisitos de desempenho. Isto só é possível se estiverem no seu próprio projeto.
Segurança e governação: as políticas de segurança da sua organização podem restringir o acesso direto a conjuntos de dados públicos, como o bqutil, para o tratamento de dados de produção. A cópia de FDU para o seu ambiente controlado está alinhada com essas políticas.

Implementar UDFs auxiliares no seu projeto:

Para uma utilização de produção fiável e estável, deve implementar estas UDFs auxiliares no seu próprio projeto e conjunto de dados. Isto dá-lhe controlo total sobre a versão, a personalização e o acesso. Para instruções detalhadas sobre como implementar estas FDU, consulte o guia de implementação de FDUs no GitHub. Este guia fornece os scripts e os passos necessários para copiar as FDUs para o seu ambiente.

Localizações

A API Translation está disponível nas seguintes localizações de processamento:

	Descrição da região	Nome da região	Detalhes
Ásia-Pacífico
	Deli	`asia-south2`
	Hong Kong	`asia-east2`
	Jacarta	`asia-southeast2`
	Melbourne	`australia-southeast2`
	Mumbai	`asia-south1`
	Osaca	`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`
	Multirregional da UE	`eu`
	Finlândia	`europe-north1`	Baixo CO₂
	Frankfurt	`europe-west3`
	Londres	`europe-west2`	Baixo CO₂
	Madrid	`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₂
Americas
	Columbus, Ohio	`us-east5`
	Dallas	`us-south1`	Baixo CO₂
	Iowa	`us-central1`	Baixo CO₂
	Las Vegas	`us-west4`
	Los Angeles	`us-west2`
	México	`northamerica-south1`
	Virgínia do Norte	`us-east4`
	Oregon	`us-west1`	Baixo CO₂
	Quebeque	`northamerica-northeast1`	Baixo CO₂
	São Paulo	`southamerica-east1`	Baixo CO₂
	Salt Lake City	`us-west3`
	Santiago	`southamerica-west1`	Baixo CO₂
	Carolina do Sul	`us-east1`
	Toronto	`northamerica-northeast2`	Baixo CO₂
	Multirregião dos EUA	`us`
África
	Joanesburgo	`africa-south1`
MiddleEast
	Damã	`me-central2`
	Doha	`me-central1`
	Israel	`me-west1`

Envie uma tarefa de tradução

Para enviar uma tarefa de tradução através da API Translation, use o método projects.locations.workflows.create e forneça uma instância do recurso MigrationWorkflow com um tipo de tarefa suportado.

Depois de enviar a tarefa, pode emitir uma consulta para obter resultados.

Crie uma tradução em lote

O seguinte comando curl cria uma tarefa de tradução em lote em que os ficheiros 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 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 o seguinte:

TYPE: o tipo de tarefa da tradução, que determina o dialeto de origem e de destino.
TARGET_BASE: o URI base para todos os resultados de tradução.
BASE: o URI base para todos os ficheiros lidos como origens para tradução.
TARGET_TYPES (opcional): os tipos de saída gerados. Se não for especificado, é gerado SQL.
- sql (predefinição): os ficheiros de consulta SQL traduzidos.
- suggestion: sugestões geradas pela IA.
O resultado é armazenado numa subpasta no diretório de saída. O nome da subpasta baseia-se no valor em TARGET_TYPES.
TOKEN: o token para autenticação. Para gerar um símbolo, use o comando gcloud auth print-access-token ou o OAuth 2.0 playground (use o âmbito https://www.googleapis.com/auth/cloud-platform).
PROJECT_ID: o projeto para processar a tradução.
LOCATION: a localização onde o trabalho é processado.

O comando anterior devolve uma resposta que inclui um ID do 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/, pode usar 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/"
             }
          },
       }
    }
  }
}

Esta chamada devolve uma mensagem que contém 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 obter o estado atualizado do fluxo de trabalho, execute uma consulta GET. À medida que avança, a tarefa envia resultados para o Cloud Storage. A tarefa state muda para COMPLETED depois de todos os target_types pedidos serem gerados. Se a tarefa for bem-sucedida, pode 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 seguinte traduz os scripts SQL do Teradata localizados no diretório do Cloud Storage e armazena os resultados no diretório do Cloud Storage com sugestões adicionais de IA:gs://my_data_bucket/teradata/input/gs://my_data_bucket/teradata/output/

{
  "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 de a tarefa ser executada com êxito, pode encontrar sugestões de IA no gs://my_data_bucket/teradata/output/suggestion diretório do Cloud Storage.

Crie uma tarefa de tradução interativa com entradas e saídas literais de strings

O comando curl seguinte cria uma tarefa de tradução com entradas e saídas de strings literais. O campo source_target_mapping contém uma lista que mapeia os diretórios de origem para um caminho relativo opcional para o resultado 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 o seguinte:

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 ficheiro ou um caminho.
STRING: string de dados de entrada literais (por exemplo, SQL) a serem traduzidos.
TARGETS: os alvos esperados que o utilizador quer que sejam devolvidos diretamente na resposta no formato literal. Estes devem estar no formato de URI de destino (por exemplo, GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). Tudo o que não estiver nesta lista não é devolvido na resposta. O diretório gerado, GENERATED_DIR para traduções gerais de SQL, é sql/.
TOKEN: o token para autenticação. Para gerar um símbolo, use o comando gcloud auth print-access-token ou o OAuth 2.0 playground (use o âmbito https://www.googleapis.com/auth/cloud-platform).
PROJECT_ID: o projeto para processar a tradução.
LOCATION: a localização onde o trabalho é processado.

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

Quando a tarefa estiver concluída, pode ver os resultados consultando a tarefa e examinando o campo translation_literals incorporado na resposta após a conclusão do fluxo de trabalho.

Exemplo de tradução interativa

Para traduzir a string Hive SQL select 1 de forma interativa, pode usar 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",
    }
  }
}

Pode usar qualquer relative_path que quiser para o literal, mas o literal traduzido só aparece nos resultados se incluir sql/$relative_path no seu target_return_literals. Também pode incluir vários literais numa única consulta, caso em que cada um dos respetivos caminhos relativos tem de ser incluído em target_return_literals.

Esta chamada devolve uma mensagem que contém 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 obter o estado atualizado do fluxo de trabalho, execute uma consulta GET. A tarefa está concluída quando "state" muda para COMPLETED. Se a tarefa for bem-sucedida, encontra 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"
}

Explore o resultado da tradução

Depois de executar a tarefa de tradução, obtenha os resultados especificando o ID do fluxo de trabalho da tarefa de tradução através do 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 o seguinte:

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 âmbito https://www.googleapis.com/auth/cloud-platform).
PROJECT_ID: o projeto para processar a tradução.
LOCATION: a localização onde o trabalho é processado.
WORKFLOW_ID: o ID gerado quando cria um fluxo de trabalho de tradução.

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

A resposta vai conter o estado do seu fluxo de trabalho de migração e todos os ficheiros concluídos em target_return_literals. Pode sondar este ponto final para verificar o estado do seu fluxo de trabalho.