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:

1. Certifique-se de que tem todas as autorizações necessárias.
2. Ative a API BigQuery Migration.
3. Recolha os ficheiros de origem que contêm os scripts e as consultas SQL a serem traduzidos.
4. 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:

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

   Aceda à API BigQuery Migration

2. Clique em Ativar.

Nota: os projetos criados após 15 de fevereiro de 2022 têm esta API ativada automaticamente.

Carregue ficheiros de entrada para o Cloud Storage

Se quiser usar a Google 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
• SQL PostgreSQL – 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:

1. 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.
2. Isolamento de dependências: a implementação de FDU no seu próprio projeto isola o ambiente de produção de alterações externas.
3. 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.
4. 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. Copiar FDU para o seu ambiente controlado está em conformidade 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 CO2
	Berlim	europe-west10
	Multirregional da UE	eu
	Finlândia	europe-north1	Baixo CO2
	Frankfurt	europe-west3
	Londres	europe-west2	Baixo CO2
	Madrid	europe-southwest1	Baixo CO2
	Milão	europe-west8
	Países Baixos	europe-west4	Baixo CO2
	Paris	europe-west9	Baixo CO2
	Estocolmo	europe-north2	Baixo CO2
	Turim	europe-west12
	Varsóvia	europe-central2
	Zurique	europe-west6	Baixo CO2
Americas
	Columbus, Ohio	us-east5
	Dallas	us-south1	Baixo CO2
	Iowa	us-central1	Baixo CO2
	Las Vegas	us-west4
	Los Angeles	us-west2
	México	northamerica-south1
	Virgínia do Norte	us-east4
	Oregon	us-west1	Baixo CO2
	Quebeque	northamerica-northeast1	Baixo CO2
	São Paulo	southamerica-east1	Baixo CO2
	Salt Lake City	us-west3
	Santiago	southamerica-west1	Baixo CO2
	Carolina do Sul	us-east1
	Toronto	northamerica-northeast2	Baixo CO2
	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 o resultado 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 resultados 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/"
             }
          },
       }
    }
  }
}

Nota: a string "task_name" neste exemplo é um identificador da tarefa de tradução e pode ser definida para qualquer valor que preferir.

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

Pré-visualização

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Nota: a API Translation pode chamar o Gemini através da integração do Vertex AI com o BigQuery para gerar sugestões para a sua consulta SQL traduzida com base no seu ficheiro YAML de configuração 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",
       }
    }
  }
}

Nota: para gerar sugestões de IA, o diretório de origem do Cloud Storage tem de conter, pelo menos, um ficheiro YAML de configuração com o sufixo .ai_config.yaml. Para saber como escrever o ficheiro YAML de configuração para sugestões de IA, consulte o artigo Crie um ficheiro YAML de configuração baseado no Gemini.

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",
    }
  }
}

Nota: a string "task_name" neste exemplo é um identificador da tarefa de tradução e pode ser definida para qualquer valor que preferir.

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.