Esta página se ha traducido con Cloud Translation API.

Traducir consultas de SQL con la API Translation

En este documento se describe cómo usar la API Translation en BigQuery para traducir secuencias de comandos escritas en otros dialectos de SQL a consultas de GoogleSQL. La API Translation puede simplificar el proceso de migración de cargas de trabajo a BigQuery.

Antes de empezar

Antes de enviar un trabajo de traducción, completa los siguientes pasos:

Comprueba que tienes todos los permisos necesarios.
Habilite la API de migración de BigQuery.
Recopila los archivos de origen que contengan las secuencias de comandos y las consultas de SQL que quieras traducir.
Sube los archivos de origen a Cloud Storage.

Permisos obligatorios

Para obtener los permisos que necesitas para crear tareas de traducción con la API Translation, pide a tu administrador que te conceda el rol de gestión de identidades y accesos MigrationWorkflow Editor (roles/bigquerymigration.editor) en el recurso parent. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear trabajos de traducción mediante la API Translation. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Para crear tareas de traducción con la API Translation, se necesitan los siguientes permisos:

bigquerymigration.workflows.create
bigquerymigration.workflows.get

También puedes obtener estos permisos con roles personalizados u otros roles predefinidos.

Habilitar la API de migración de BigQuery

Si tu proyecto de la CLI de Google Cloud se creó antes del 15 de febrero del 2022, habilita la API BigQuery Migration de la siguiente manera:

En la Google Cloud consola, ve a la página API BigQuery Migration.

Ir a la API BigQuery Migration
Haz clic en Enable (Habilitar).

Subir archivos de entrada a Cloud Storage

Si quieres usar la consola de Google Cloud o la API de migración de BigQuery para realizar un trabajo de traducción, debes subir a Cloud Storage los archivos de origen que contengan las consultas y las secuencias de comandos que quieras traducir. También puede subir cualquier archivo de metadatos o archivo YAML de configuración al mismo segmento de Cloud Storage que contiene los archivos de origen. Para obtener más información sobre cómo crear contenedores y subir archivos a Cloud Storage, consulta Crear contenedores y Subir objetos desde un sistema de archivos.

Tipos de tareas admitidos

La API de traducción puede traducir los siguientes dialectos de SQL a GoogleSQL:

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

Gestionar funciones de SQL no admitidas con UDFs auxiliares

Al traducir SQL de un dialecto de origen a BigQuery, es posible que algunas funciones no tengan un equivalente directo. Para solucionar este problema, BigQuery Migration Service (y la comunidad de BigQuery en general) proporcionan funciones definidas por el usuario (UDFs) auxiliares que replican el comportamiento de estas funciones de dialecto de origen no admitidas.

Estas funciones definidas por el usuario se suelen encontrar en el conjunto de datos público bqutil, lo que permite que las consultas traducidas hagan referencia a ellas inicialmente con el formato bqutil.<dataset>.<function>(). Por ejemplo, bqutil.fn.cw_count().

Cuestiones importantes sobre los entornos de producción:

Aunque bqutil ofrece un acceso cómodo a estas funciones definidas por el usuario auxiliares para la traducción y las pruebas iniciales, no se recomienda depender directamente de bqutil para las cargas de trabajo de producción por varios motivos:

Control de versiones: el proyecto bqutil aloja la versión más reciente de estas funciones definidas por el usuario, lo que significa que sus definiciones pueden cambiar con el tiempo. Si dependes directamente de bqutil, se pueden producir comportamientos inesperados o cambios en tus consultas de producción si se actualiza la lógica de una UDF.
Aislamiento de dependencias: al implementar UDFs en tu propio proyecto, tu entorno de producción se aísla de los cambios externos.
Personalización: es posible que tenga que modificar u optimizar estas funciones definidas por el usuario para que se adapten mejor a la lógica de su empresa o a sus requisitos de rendimiento. Esto solo es posible si están en tu proyecto.
Seguridad y gobernanza: las políticas de seguridad de tu organización pueden restringir el acceso directo a conjuntos de datos públicos, como bqutil, para el tratamiento de datos de producción. Copiar las funciones definidas por el usuario en tu entorno controlado se ajusta a estas políticas.

Para desplegar UDFs auxiliares en tu proyecto, sigue estos pasos:

Para un uso fiable y estable en producción, debe implementar estas UDFs auxiliares en su propio proyecto y conjunto de datos. De esta forma, tendrás pleno control sobre su versión, personalización y acceso. Para obtener instrucciones detalladas sobre cómo implementar estas funciones definidas por el usuario, consulta la guía de implementación de funciones definidas por el usuario en GitHub. En esta guía se proporcionan las secuencias de comandos y los pasos necesarios para copiar las funciones definidas por el usuario en tu entorno.

Ubicaciones

La API Translation está disponible en las siguientes ubicaciones de procesamiento:

	Descripción de la región	Nombre de la región	Detalles
Asia‑Pacífico
	Deli	`asia-south2`
	Hong Kong	`asia-east2`
	Yakarta	`asia-southeast2`
	Melbourne	`australia-southeast2`
	Bombay	`asia-south1`
	Osaka	`asia-northeast2`
	Seúl	`asia-northeast3`
	Singapur	`asia-southeast1`
	Sídney	`australia-southeast1`
	Taiwán	`asia-east1`
	Tokio	`asia-northeast1`
Europa
	Bélgica	`europe-west1`	CO₂ bajo
	Berlín	`europe-west10`	CO₂ bajo
	Multirregional de la UE	`eu`
	Finlandia	`europe-north1`	CO₂ bajo
	Fráncfort	`europe-west3`
	Londres	`europe-west2`	CO₂ bajo
	Madrid	`europe-southwest1`	CO₂ bajo
	Milán	`europe-west8`
	Países Bajos	`europe-west4`	CO₂ bajo
	París	`europe-west9`	CO₂ bajo
	Estocolmo	`europe-north2`	CO₂ bajo
	Turín	`europe-west12`
	Varsovia	`europe-central2`
	Zúrich	`europe-west6`	CO₂ bajo
América
	Columbus (Ohio)	`us-east5`
	Dallas	`us-south1`	CO₂ bajo
	Iowa	`us-central1`	CO₂ bajo
	Las Vegas	`us-west4`
	Los Ángeles	`us-west2`
	México	`northamerica-south1`
	Norte de Virginia	`us-east4`
	Oregón	`us-west1`	CO₂ bajo
	Quebec	`northamerica-northeast1`	CO₂ bajo
	São Paulo	`southamerica-east1`	CO₂ bajo
	Salt Lake City	`us-west3`
	Santiago	`southamerica-west1`	CO₂ bajo
	Carolina del Sur	`us-east1`
	Toronto	`northamerica-northeast2`	CO₂ bajo
	Multirregional de EE. UU.	`us`
África
	Johannesburgo	`africa-south1`
MiddleEast
	Dammam	`me-central2`
	Doha	`me-central1`
	Israel	`me-west1`

Enviar una tarea de traducción

Para enviar un trabajo de traducción mediante la API Translation, usa el método projects.locations.workflows.create y proporciona una instancia del recurso MigrationWorkflow con un tipo de tarea admitido.

Una vez que se haya enviado el trabajo, puedes enviar una consulta para obtener los resultados.

Crear una traducción por lotes

El siguiente comando curl crea una tarea de traducción por lotes en la que los archivos de entrada y salida se almacenan en Cloud Storage. El campo source_target_mapping contiene una lista que asigna las entradas de origen literal a una ruta relativa opcional para la salida 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

Haz los cambios siguientes:

TYPE: el tipo de tarea de la traducción, que determina la variante de origen y de destino.
TARGET_BASE: el URI base de todos los resultados de traducción.
BASE: el URI base de todos los archivos leídos como fuentes de traducción.
TARGET_TYPES (opcional): los tipos de salida generados. Si no se especifica, se genera el SQL.
- sql (valor predeterminado): los archivos de consulta de SQL traducidos.
- suggestion: sugerencias generadas por IA.
El resultado se almacena en una subcarpeta del directorio de salida. El nombre de la subcarpeta se basa en el valor de TARGET_TYPES.
TOKEN: el token de autenticación. Para generar un token, usa el comando gcloud auth print-access-token o OAuth 2.0 Playground (usa el ámbito https://www.googleapis.com/auth/cloud-platform).
PROJECT_ID: el proyecto para procesar la traducción.
LOCATION: la ubicación en la que se procesa el trabajo.

El comando anterior devuelve una respuesta que incluye un ID de flujo de trabajo escrito en el formato projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Ejemplo de traducción por lotes

Para traducir las secuencias de comandos SQL de Teradata del directorio de Cloud Storage gs://my_data_bucket/teradata/input/ y almacenar los resultados en el directorio de Cloud Storage gs://my_data_bucket/teradata/output/, puedes usar la siguiente 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 llamada devolverá un mensaje que contiene el ID del flujo de trabajo creado en el campo "name":

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Para obtener el estado actualizado del flujo de trabajo, ejecuta una consulta GET. La tarea envía las salidas a Cloud Storage a medida que avanza. El estado de la tarea state cambia a COMPLETED cuando se han generado todos los target_types solicitados. Si la tarea se completa correctamente, puedes encontrar la consulta de SQL traducida en gs://my_data_bucket/teradata/output.

Ejemplo de traducción por lotes con sugerencias de IA

En el siguiente ejemplo se traducen las secuencias de comandos SQL de Teradata ubicadas en el directorio gs://my_data_bucket/teradata/input/ de Cloud Storage y se almacenan los resultados en el directorio gs://my_data_bucket/teradata/output/ de Cloud Storage con una sugerencia 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",
       }
    }
  }
}

Una vez que la tarea se haya ejecutado correctamente, las sugerencias de IA se encontrarán en el directorio gs://my_data_bucket/teradata/output/suggestion Cloud Storage.

Crear una tarea de traducción interactiva con entradas y salidas de literales de cadena

El siguiente comando curl crea un trabajo de traducción con entradas y salidas de cadena literal. El campo source_target_mapping contiene una lista que asigna los directorios de origen a una ruta relativa opcional para la salida 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

Haz los cambios siguientes:

TYPE: el tipo de tarea de la traducción, que determina la variante de origen y de destino.
PATH: identificador de la entrada literal, similar a un nombre de archivo o una ruta.
STRING: cadena de datos de entrada literales (por ejemplo, SQL) que se va a traducir.
TARGETS: los objetivos esperados que el usuario quiere que se devuelvan directamente en la respuesta en formato literal. Deben tener el formato de URI de destino (por ejemplo, GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). Cualquier otro valor no se devolverá en la respuesta. El directorio generado, GENERATED_DIR para traducciones generales de SQL, es sql/.
TOKEN: el token de autenticación. Para generar un token, usa el comando gcloud auth print-access-token o OAuth 2.0 Playground (usa el ámbito https://www.googleapis.com/auth/cloud-platform).
PROJECT_ID: el proyecto para procesar la traducción.
LOCATION: la ubicación en la que se procesa el trabajo.

El comando anterior devuelve una respuesta que incluye un ID de flujo de trabajo escrito en el formato projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Cuando se complete el trabajo, puedes ver los resultados consultando el trabajo y examinando el campo translation_literals insertado en la respuesta después de que se complete el flujo de trabajo.

Ejemplo de traducción interactiva

Para traducir la cadena de SQL de Hive select 1 de forma interactiva, puedes usar la siguiente 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",
    }
  }
}

Puedes usar cualquier relative_path que quieras para tu literal, pero el literal traducido solo aparecerá en los resultados si incluyes sql/$relative_path en tu target_return_literals. También puedes incluir varios literales en una sola consulta. En ese caso, cada una de sus rutas relativas debe incluirse en target_return_literals.

Esta llamada devolverá un mensaje que contiene el ID del flujo de trabajo creado en el campo "name":

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Para obtener el estado actualizado del flujo de trabajo, ejecuta una consulta GET. La tarea se habrá completado cuando "state" cambie a COMPLETED. Si la tarea se completa correctamente, verás el SQL traducido en el mensaje de respuesta:

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

Consultar el resultado de la traducción

Después de ejecutar el trabajo de traducción, obtenga los resultados especificando el ID del flujo de trabajo del trabajo de traducción con el siguiente 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

Haz los cambios siguientes:

TOKEN: el token de autenticación. Para generar un token, usa el comando gcloud auth print-access-token o OAuth 2.0 Playground (usa el ámbito https://www.googleapis.com/auth/cloud-platform).
PROJECT_ID: el proyecto para procesar la traducción.
LOCATION: la ubicación en la que se procesa el trabajo.
WORKFLOW_ID: el ID generado al crear un flujo de trabajo de traducción.

La respuesta contiene el estado de tu flujo de trabajo de migración y los archivos completados en target_return_literals.

La respuesta contendrá el estado de tu flujo de trabajo de migración y los archivos completados en target_return_literals. Puedes sondear este endpoint para comprobar el estado de tu flujo de trabajo.