Migrar código con el traductor de SQL por lotes

En este documento se describe cómo usar el traductor de SQL por lotes de BigQuery para traducir secuencias de comandos escritas en otros dialectos de SQL a consultas de GoogleSQL. Este documento está dirigido a usuarios que conocen la Google Cloud consola.

Antes de empezar

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

1. Comprueba que tienes todos los permisos necesarios.
2. Habilite la API de migración de BigQuery.
3. Recopila los archivos de origen que contengan las secuencias de comandos y las consultas de SQL que quieras traducir.
4. Opcional. Crea un archivo de metadatos para mejorar la precisión de la traducción.
5. Opcional. Decide si quieres asignar nombres de objetos SQL de los archivos de origen a nombres nuevos en BigQuery. Determina qué reglas de asignación de nombres usar si es necesario.
6. Decide qué método quieres usar para enviar el trabajo de traducción.
7. Sube los archivos de origen a Cloud Storage.

Permisos obligatorios

Debes tener los siguientes permisos en el proyecto para habilitar el servicio de migración de BigQuery:

• resourcemanager.projects.get
• serviceusage.services.enable
• serviceusage.services.get

Necesita los siguientes permisos en el proyecto para acceder al servicio de migración de BigQuery y usarlo:

• bigquerymigration.workflows.create
• bigquerymigration.workflows.get
• bigquerymigration.workflows.list
• bigquerymigration.workflows.delete
• bigquerymigration.subtasks.get

• bigquerymigration.subtasks.list

  También puedes usar los siguientes roles para obtener los mismos permisos:

  • bigquerymigration.viewer - Acceso de solo lectura.
  • bigquerymigration.editor - Acceso de lectura/escritura.

Para acceder a los segmentos de Cloud Storage de los archivos de entrada y salida, haz lo siguiente:

• storage.objects.get en el segmento de Cloud Storage de origen.
• storage.objects.list en el segmento de Cloud Storage de origen.
• storage.objects.create en el segmento de destino de Cloud Storage.

Puedes tener todos los permisos de Cloud Storage necesarios anteriores con los siguientes roles:

• roles/storage.objectAdmin
• roles/storage.admin

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:

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

   Ir a la API BigQuery Migration

2. Haz clic en Enable (Habilitar).

Recopilar archivos de origen

Los archivos de origen deben ser archivos de texto que contengan código SQL válido para el dialecto de origen. Los archivos de origen también pueden incluir comentarios. Haz todo lo posible para asegurarte de que el código SQL sea válido, usando los métodos que tengas a tu disposición.

Crear archivos de metadatos

Para ayudar al servicio a generar resultados de traducción más precisos, le recomendamos que proporcione archivos de metadatos. Sin embargo, no es obligatorio.

Puede usar la herramienta de extracción de la línea de comandos dwh-migration-dumper para generar la información de los metadatos o proporcionar sus propios archivos de metadatos. Una vez que los archivos de metadatos estén preparados, puede incluirlos junto con los archivos de origen en la carpeta de origen de la traducción. El traductor los detecta automáticamente y los aprovecha para traducir los archivos de origen, por lo que no tienes que configurar ningún ajuste adicional para habilitar esta función.

Para generar información de metadatos con la herramienta dwh-migration-dumper, consulta el artículo Generar metadatos para la traducción.

Para proporcionar sus propios metadatos, recopile las instrucciones del lenguaje de definición de datos (DDL) de los objetos SQL de su sistema de origen en archivos de texto independientes.

Decide cómo enviar el trabajo de traducción

Tiene tres opciones para enviar un trabajo de traducción por lotes:

• Cliente de traducción por lotes: configura un trabajo cambiando los ajustes en un archivo de configuración y envía el trabajo mediante la línea de comandos. Con este método, no es necesario subir manualmente los archivos de origen a Cloud Storage. El cliente sigue usando Cloud Storage para almacenar archivos durante el procesamiento de los trabajos de traducción.

  El cliente de traducción por lotes antiguo es un cliente de Python de código abierto que te permite traducir archivos de origen ubicados en tu máquina local y generar los archivos traducidos en un directorio local. Para configurar el cliente para un uso básico, debes cambiar algunos ajustes en su archivo de configuración. Si quieres, también puedes configurar el cliente para que realice tareas más complejas, como la sustitución de macros y el preprocesamiento y el posprocesamiento de las entradas y salidas de traducción. Para obtener más información, consulta el archivo readme del cliente de traducción por lotes.

• Google Cloud Consola: configura y envía un trabajo mediante una interfaz de usuario. Para usar este método, debes subir los archivos de origen a Cloud Storage.

Crear archivos YAML de configuración

También puedes crear y usar archivos YAML de configuración para personalizar tus traducciones en lote. Estos archivos se pueden usar para transformar el resultado de la traducción de varias formas. Por ejemplo, puedes crear un archivo YAML de configuración para cambiar las mayúsculas y minúsculas de un objeto SQL durante la traducción.

Si quieres usar la Google Cloud consola o la API de migración de BigQuery para un trabajo de traducción por lotes, puedes subir el archivo YAML de configuración al segmento de Cloud Storage que contiene los archivos de origen.

Si quieres usar el cliente de traducción por lotes, puedes colocar el archivo YAML de configuración en la carpeta de entrada de traducción local.

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 y directorio de Cloud Storage que contenga 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.

Dialectos de SQL admitidos

El traductor de SQL por lotes forma parte de BigQuery Migration Service. El traductor de SQL por lotes puede traducir los siguientes dialectos de SQL a GoogleSQL:

• SQL de Amazon Redshift
• Apache HiveQL y Beeline CLI
• IBM Netezza SQL y NZPLSQL
• Teradata y Teradata Vantage
  • SQL
  • Basic Teradata Query (BTEQ)
  • Teradata Parallel Transport (TPT)

Además, se admite la traducción de los siguientes dialectos de SQL en versión preliminar:

• Apache Spark SQL
• T-SQL de Azure Synapse
• Greenplum SQL
• IBM DB2 SQL
• MySQL SQL
• Oracle SQL, PL/SQL y Exadata
• SQL de PostgreSQL
• Trino o PrestoSQL
• SQL de Snowflake
• T-SQL de SQL Server
• SQLite
• Vertica SQL

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:

1. 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.
2. Aislamiento de dependencias: al implementar UDFs en tu propio proyecto, tu entorno de producción se aísla de los cambios externos.
3. 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.
4. 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

El traductor de SQL por lotes 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	CO2 bajo
	Berlín	europe-west10	CO2 bajo
	Multirregional de la UE	eu
	Finlandia	europe-north1	CO2 bajo
	Fráncfort	europe-west3
	Londres	europe-west2	CO2 bajo
	Madrid	europe-southwest1	CO2 bajo
	Milán	europe-west8
	Países Bajos	europe-west4	CO2 bajo
	París	europe-west9	CO2 bajo
	Estocolmo	europe-north2	CO2 bajo
	Turín	europe-west12
	Varsovia	europe-central2
	Zúrich	europe-west6	CO2 bajo
América
	Columbus (Ohio)	us-east5
	Dallas	us-south1	CO2 bajo
	Iowa	us-central1	CO2 bajo
	Las Vegas	us-west4
	Los Ángeles	us-west2
	México	northamerica-south1
	Norte de Virginia	us-east4
	Oregón	us-west1	CO2 bajo
	Quebec	northamerica-northeast1	CO2 bajo
	São Paulo	southamerica-east1	CO2 bajo
	Salt Lake City	us-west3
	Santiago	southamerica-west1	CO2 bajo
	Carolina del Sur	us-east1
	Toronto	northamerica-northeast2	CO2 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

Sigue estos pasos para iniciar un trabajo de traducción, ver su progreso y consultar los resultados.

Consultar el resultado de la traducción

Una vez que hayas ejecutado el trabajo de traducción, podrás ver información sobre él en la Google Cloud consola. Si has usado la Google Cloud consola para ejecutar el trabajo, puedes ver los resultados en el segmento de Cloud Storage de destino que hayas especificado. Si has usado el cliente de traducción por lotes para ejecutar el trabajo, puedes ver los resultados en el directorio de salida que hayas especificado. El traductor de SQL por lotes genera los siguientes archivos en el destino especificado:

• Los archivos traducidos.
• El informe de resumen de la traducción en formato CSV.
• La asignación de nombres de salida consumida en formato JSON.
• Los archivos de sugerencias de IA.

Google Cloud Salida de la consola

Para ver los detalles de un trabajo de traducción, sigue estos pasos:

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

   Ir a BigQuery

2. En el menú de navegación, haz clic en Traducción de SQL.

3. En la lista de tareas de traducción, busca la tarea de la que quieras ver los detalles de la traducción. A continuación, haz clic en el nombre del trabajo de traducción. Puedes ver una visualización de Sankey que ilustra la calidad general del trabajo, el número de líneas de código de entrada (sin incluir las líneas en blanco ni los comentarios) y una lista de los problemas que se han producido durante el proceso de traducción. Debes priorizar las correcciones de izquierda a derecha. Los problemas en una fase inicial pueden provocar problemas adicionales en fases posteriores.

4. Coloca el puntero sobre las barras de errores o advertencias y consulta las sugerencias para determinar los pasos que debes seguir para depurar el trabajo de traducción.

5. Seleccione la pestaña Resumen de registro para ver un resumen de los problemas de traducción, incluidas las categorías de problemas, las acciones sugeridas y la frecuencia con la que se ha producido cada problema. Puedes hacer clic en las barras de la visualización de Sankey para filtrar los problemas. También puedes seleccionar una categoría de problema para ver los mensajes de registro asociados a esa categoría.

6. Selecciona la pestaña Mensajes de registro para ver más detalles sobre cada problema de traducción, como la categoría del problema, el mensaje específico y un enlace al archivo en el que se ha producido. Puedes hacer clic en las barras de visualización de Sankey para filtrar los problemas. Puede seleccionar un problema en la pestaña Mensaje de registro para abrir la pestaña Código, que muestra el archivo de entrada y el de salida, si procede.

7. Haz clic en la pestaña Detalles del trabajo para ver los detalles de configuración del trabajo de traducción.

Informe resumido

El informe de resumen es un archivo CSV que contiene una tabla con todos los mensajes de advertencia y error que se han detectado durante el trabajo de traducción.

Para ver el archivo de resumen en la Google Cloud consola, sigue estos pasos:

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

   Ir a BigQuery

2. En el menú de navegación, haz clic en Traducción de SQL.

3. En la lista de tareas de traducción, busca la tarea que te interese y haz clic en su nombre o en Más opciones > Mostrar detalles.

4. En la pestaña Detalles del trabajo, en la sección Informe de traducción, haz clic en translation_report.csv.

5. En la página Detalles del objeto, haga clic en el valor de la fila URL autenticada para ver el archivo en su navegador.

En la siguiente tabla se describen las columnas del archivo de resumen:

Pestaña Código

La pestaña de código te permite consultar más información sobre los archivos de entrada y salida de un trabajo de traducción concreto. En la pestaña de código, puedes examinar los archivos utilizados en un trabajo de traducción, consultar una comparación en paralelo de un archivo de entrada y su traducción para detectar posibles imprecisiones, y ver resúmenes de registros y mensajes de un archivo específico de un trabajo.

Para acceder a la pestaña de código, sigue estos pasos:

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

   Ir a BigQuery

2. En el menú de navegación, haz clic en Traducción de SQL.

3. En la lista de tareas de traducción, busca la tarea que te interese y haz clic en su nombre o en Más opciones > Mostrar detalles.

4. Selecciona la pestaña Código. La pestaña de código consta de los siguientes paneles:

   

   • Explorador de archivos: contiene todos los archivos SQL que se usan para la traducción. Haga clic en un archivo para ver el texto de entrada y de salida de la traducción, así como los problemas de traducción que haya.
   • Entrada mejorada con Gemini: el SQL de entrada que ha traducido el motor de traducción. Si has especificado reglas de personalización de Gemini para el SQL de origen en la configuración de Gemini, el traductor transforma primero la entrada original y, a continuación, traduce la entrada mejorada con Gemini. Para ver la entrada original, haz clic en Ver entrada original.
   • Resultado de la traducción: el resultado de la traducción. Si has especificado reglas de personalización de Gemini para el SQL de destino en la configuración de Gemini, la transformación se aplicará al resultado traducido como una salida mejorada con Gemini. Si hay un resultado mejorado con Gemini, puedes hacer clic en el botón Sugerencia de Gemini para ver el resultado mejorado.

5. Opcional: Para ver un archivo de entrada y su archivo de salida en el traductor interactivo de SQL de BigQuery, haz clic en Editar. Puedes editar los archivos y guardar el archivo de salida en Cloud Storage.

Pestaña Configuración

Puedes añadir, cambiar el nombre, ver o editar tus archivos YAML de configuración en la pestaña Configuración.El Explorador de esquemas muestra la documentación de los tipos de configuración admitidos para ayudarte a escribir tus archivos YAML de configuración. Después de editar los archivos YAML de configuración, puedes volver a ejecutar el trabajo para usar la nueva configuración.

Para acceder a la pestaña de configuración, sigue estos pasos:

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

   Ir a BigQuery

2. En el menú de navegación, haz clic en Traducción de SQL.

3. En la lista de tareas de traducción, busca la tarea que te interese y haz clic en su nombre o en Más opciones > Mostrar detalles.

4. En la ventana Detalles de la traducción, haga clic en la pestaña Configuración.

Para añadir un archivo de configuración, sigue estos pasos:

1. Haz clic en more_vert Más opciones > Crear archivo YAML de configuración.
2. Aparecerá un panel en el que podrás elegir el tipo, la ubicación y el nombre del nuevo archivo YAML de configuración.
3. Haz clic en Crear.

Para editar un archivo de configuración:

1. Haz clic en el archivo YAML de configuración.
2. Edita el archivo y haz clic en Guardar.
3. Haz clic en Volver a ejecutar para ejecutar una nueva tarea de traducción que use los archivos YAML de configuración editados.

Para cambiar el nombre de un archivo de configuración, haz clic en more_vert Más opciones > Cambiar nombre.

Archivo de asignación de nombres de salida consumido

Este archivo JSON contiene las reglas de asignación de nombres de salida que ha usado el trabajo de traducción. Las reglas de este archivo pueden ser diferentes de las reglas de asignación de nombres de salida que hayas especificado para el trabajo de traducción, ya sea por conflictos en las reglas de asignación de nombres o por la falta de reglas de asignación de nombres para los objetos SQL que se hayan identificado durante la traducción. Revisa este archivo para determinar si las reglas de asignación de nombres deben corregirse. Si es así, cree nuevas reglas de asignación de nombres de salida que solucionen los problemas que haya identificado y ejecute un nuevo trabajo de traducción.

Archivos traducidos

Por cada archivo de origen, se genera un archivo de salida correspondiente en la ruta de destino. El archivo de salida contiene la consulta traducida.

Depurar consultas de SQL traducidas por lotes con el traductor de SQL interactivo

Puedes usar el traductor interactivo de SQL de BigQuery para revisar o depurar una consulta de SQL con la misma información de metadatos o de asignación de objetos que tu base de datos de origen. Una vez que hayas completado un trabajo de traducción por lotes, BigQuery generará un ID de configuración de traducción que contendrá información sobre los metadatos del trabajo, la asignación de objetos o la ruta de búsqueda del esquema, según corresponda a la consulta. Utiliza el ID de configuración de traducción por lotes con el traductor de SQL interactivo para ejecutar consultas de SQL con la configuración especificada.

Para iniciar una traducción interactiva de SQL mediante un ID de configuración de traducción por lotes, sigue estos pasos:

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

   Ir a BigQuery

2. En el menú de navegación, haz clic en Traducción de SQL.

3. En la lista de tareas de traducción, busca la que te interese y haz clic en more_vert Más opciones > Abrir traducción interactiva.

   El traductor interactivo de SQL de BigQuery ahora se abre con el ID de configuración de traducción por lotes correspondiente. Para ver el ID de configuración de la traducción interactiva, haz clic en Más > Configuración de traducción en el traductor de SQL interactivo.

Para depurar un archivo de traducción por lotes en el traductor de SQL interactivo, sigue estos pasos:

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

   Ir a BigQuery

2. En el menú de navegación, haz clic en Traducción de SQL.

3. En la lista de tareas de traducción, busca la tarea que te interese y haz clic en su nombre o en Más opciones > Mostrar detalles.

4. En la ventana Detalles de la traducción, haz clic en la pestaña Código.

5. En el explorador de archivos, haz clic en el nombre del archivo para abrirlo.

6. Junto al nombre del archivo de salida, haz clic en Editar para abrir los archivos en el traductor de SQL interactivo (Vista previa).

   Verá los archivos de entrada y salida rellenados en el traductor de SQL interactivo, que ahora usa el ID de configuración de traducción por lotes correspondiente.

7. Para guardar el archivo de salida editado en Cloud Storage, en el traductor de SQL interactivo, haz clic en Guardar > Guardar en GCS.

Limitaciones

El traductor no puede traducir funciones definidas por el usuario (UDFs) de idiomas distintos de SQL porque no puede analizarlas para determinar sus tipos de datos de entrada y salida. Esto provoca que la traducción de las instrucciones SQL que hacen referencia a estas funciones definidas por el usuario sea imprecisa. Para asegurarse de que se haga referencia correctamente a las funciones definidas por el usuario que no son de SQL durante la traducción, use SQL válido para crear funciones definidas por el usuario de marcador de posición con las mismas firmas.

Por ejemplo, supongamos que tienes una función definida por el usuario escrita en C que calcula la suma de dos números enteros. Para asegurarte de que las instrucciones SQL que hacen referencia a esta función definida por el usuario se traducen correctamente, crea una función definida por el usuario de SQL de marcador de posición que comparta la misma firma que la función definida por el usuario de C, tal como se muestra en el siguiente ejemplo:

CREATE FUNCTION Test.MySum (a INT, b INT)
  RETURNS INT
  LANGUAGE SQL
  RETURN a + b;

Guarda esta función definida por el usuario de marcador de posición en un archivo de texto e incluye ese archivo como uno de los archivos de origen de la tarea de traducción. De esta forma, el traductor puede aprender la definición de la función definida por el usuario e identificar los tipos de datos de entrada y salida esperados.

Cuotas y límites

• Se aplican las cuotas de la API de migración de BigQuery.
• Cada proyecto puede tener como máximo 10 tareas de traducción activas.
• Aunque no hay un límite estricto en cuanto al número total de archivos de origen y de metadatos, te recomendamos que no superes los 1000 archivos para que el rendimiento sea mejor.

Solucionar errores de traducción

Problemas de traducción de RelationNotFound o AttributeNotFound

La traducción funciona mejor con DDLs de metadatos. Cuando no se encuentran definiciones de objetos SQL, el motor de traducción genera problemas de tipo RelationNotFound o AttributeNotFound. Te recomendamos que uses el extractor de metadatos para generar paquetes de metadatos y asegurarte de que estén presentes todas las definiciones de objetos. Añadir metadatos es el primer paso recomendado para resolver la mayoría de los errores de traducción, ya que a menudo puede corregir muchos otros errores que se deben indirectamente a la falta de metadatos.

Para obtener más información, consulta Generar metadatos para la traducción y la evaluación.

Precios

No se te cobrará nada por usar el traductor de SQL por lotes. Sin embargo, el almacenamiento que se usa para almacenar archivos de entrada y salida está sujeto a las tarifas normales. Para obtener más información, consulta los precios de almacenamiento.

Siguientes pasos

Consulta más información sobre los siguientes pasos de la migración de almacenes de datos:

• Información general sobre la migración
• Evaluación de la migración
• Información general sobre la transferencia de esquemas y datos
• Flujos de datos
• Traducción interactiva de SQL
• Gobierno y seguridad de los datos
• Herramienta de validación de datos