Traduce consultas con el traductor interactivo de SQL

En este documento, se describe cómo traducir una consulta de un dialecto de SQL diferente a una consulta en GoogleSQL mediante el traductor de SQL interactivo de BigQuery. El traductor interactivo de SQL puede ayudar a reducir el tiempo y el esfuerzo cuando migras cargas de trabajo a BigQuery. Este documento está dirigido a usuarios familiarizados con la consola deGoogle Cloud .

Si tu ubicación es compatible, puedes usar la función de reglas de traducción para personalizar la forma en que el traductor interactivo de SQL traduce SQL.

Antes de comenzar

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

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

    Ir a la API de BigQuery Migration

  2. Haz clic en Habilitar.

Permisos y roles

En esta sección se describen los permisos de Identity and Access Management (IAM) que necesitarás para usar el traductor interactivo de SQL y las funciones predefinidas de IAM que otorgan esos permisos. En la sección, también se describen los permisos necesarios para establecer parámetros de configuración de traducción adicionales.

Permisos para usar el traductor interactivo de SQL

Para obtener los permisos que necesitas para usar el traductor interactivo, pídele a tu administrador que te otorgue el rol de IAM de editor de MigrationWorkflow (roles/bigquerymigration.editor) en el recurso parent. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para usar el traductor interactivo. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para usar el traductor interactivo:

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get

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

Permisos para establecer opciones de configuración de traducción adicionales

Puedes establecer configuraciones de traducción adicionales mediante los campos ID de configuración de traducción y Ubicación del origen de la configuración de traducción en la configuración de traducción. Para establecer esta configuración de traducción, necesitas los siguientes permisos:

  • bigquerymigration.workflows.get
  • bigquerymigration.workflows.list

El siguiente rol predefinido de IAM proporciona los permisos que necesitas para establecer opciones de configuración de traducción adicionales:

  • roles/bigquerymigration.viewer

Para obtener más información sobre IAM de BigQuery, consulta Control de acceso con IAM.

Dialectos de SQL compatibles

El traductor de SQL interactivo de BigQuery puede traducir los siguientes dialectos de SQL a GoogleSQL:

  • SQL de Amazon Redshift
  • Apache HiveQL y Beeline CLI
  • SQL de IBM Netezza y NZPLSQL
  • Teradata y Teradata Vantage:
    • SQL
    • Consulta básica de Teradata (BTEQ)
    • Teradata Parallel Transport (TPT)

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

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

Cómo controlar funciones de SQL no compatibles con UDF de ayuda

Cuando se traduce SQL de un dialecto de origen a BigQuery, es posible que algunas funciones no tengan un equivalente directo. Para abordar este problema, el servicio de migración de BigQuery (y la comunidad más amplia de BigQuery) proporcionan funciones definidas por el usuario (UDF) de ayuda que replican el comportamiento de estas funciones de dialecto de origen no compatibles.

Estas UDF suelen encontrarse en el conjunto de datos públicos 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().

Consideraciones importantes para los entornos de producción:

Si bien bqutil ofrece un acceso conveniente a estas UDF de ayuda 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 UDF, lo que significa que sus definiciones pueden cambiar con el tiempo. Si dependes directamente de bqutil, es posible que se produzca un comportamiento inesperado o que se produzcan cambios en tus consultas de producción si se actualiza la lógica de una UDF.
  2. Aislamiento de dependencias: La implementación de UDF en tu propio proyecto aísla tu entorno de producción de los cambios externos.
  3. Personalización: Es posible que debas modificar o optimizar estas UDF para que se adapten mejor a tu lógica empresarial o a tus requisitos de rendimiento específicos. Esto solo es posible si se encuentran dentro de tu propio proyecto.
  4. Seguridad y administración: Es posible que las políticas de seguridad de tu organización restrinjan el acceso directo a conjuntos de datos públicos, como bqutil, para el procesamiento de datos de producción. Copiar UDF a tu entorno controlado se alinea con esas políticas.

Implementa UDF de ayuda en tu proyecto:

Para un uso de producción confiable y estable, debes implementar estas UDF de ayuda en tu propio proyecto y conjunto de datos. Esto te brinda un control total sobre su versión, personalización y acceso. Para obtener instrucciones detalladas sobre cómo implementar estas UDF, consulta la guía de implementación de UDF en GitHub. En esta guía, se proporcionan las secuencias de comandos y los pasos necesarios para copiar las UDF en tu entorno.

Ubicaciones

El traductor interactivo de SQL está disponible en las siguientes ubicaciones de procesamiento:

Descripción de la región Nombre de la región Detalles
Asia-Pacífico
Delhi 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 ícono de hoja CO2 bajo
Berlín europe-west10 ícono de hoja CO2 bajo
UE multirregión eu
Finlandia europe-north1 ícono de hoja CO2 bajo
Fráncfort europe-west3 ícono de hoja CO2 bajo
Londres europe-west2 ícono de hoja CO2 bajo
Madrid europe-southwest1 ícono de hoja CO2 bajo
Milán europe-west8
Países Bajos europe-west4 ícono de hoja CO2 bajo
París europe-west9 ícono de hoja CO2 bajo
Estocolmo europe-north2 ícono de hoja CO2 bajo
Turín europe-west12
Varsovia europe-central2
Zúrich europe-west6 ícono de hoja CO2 bajo
América
Columbus, Ohio us-east5
Dallas us-south1 ícono de hoja CO2 bajo
Iowa us-central1 ícono de hoja CO2 bajo
Las Vegas us-west4
Los Ángeles us-west2
México northamerica-south1
Virginia del Norte us-east4
Oregón us-west1 ícono de hoja CO2 bajo
Quebec northamerica-northeast1 ícono de hoja CO2 bajo
São Paulo southamerica-east1 ícono de hoja CO2 bajo
Salt Lake City us-west3
Santiago southamerica-west1 ícono de hoja CO2 bajo
Carolina del Sur us-east1
Toronto northamerica-northeast2 ícono de hoja CO2 bajo
EE.UU. multirregión us
África
Johannesburgo africa-south1
MiddleEast
Dammam me-central2
Doha me-central1
Israel me-west1

De forma predeterminada, la función regla de traducción está disponible en las siguientes ubicaciones de procesamiento:

  • us (EE.UU. multirregión)
  • eu (UE multirregión)
  • us-central1 (Iowa)
  • europe-west4 (Países Bajos)

Las configuraciones de traducción basadas en Gemini solo están disponibles en ubicaciones de procesamiento específicas. Para obtener más información, consulta Ubicaciones de los extremos de los modelos de Google.

Traduce una consulta a GoogleSQL

Sigue estos pasos para traducir una consulta a GoogleSQL:

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

    Ir a BigQuery

  2. En el panel Editor, haz clic en Más y, luego, selecciona Configuración de traducción.

  3. En Dialecto de origen, selecciona el dialecto de SQL que deseas traducir.

  4. Opcional. En Ubicación de procesamiento, selecciona la ubicación en la que deseas que se ejecute el trabajo de traducción. Por ejemplo, si estás en Europa y no quieres que tus datos pasen ningún límite de ubicación, selecciona la región eu.

  5. Haz clic en Guardar.

  6. En el panel Editor, haz clic en Más y, luego, selecciona Habilitar la traducción de SQL.

    El panel Editor se divide en dos paneles.

  7. En el panel izquierdo, ingresa la consulta que deseas traducir.

  8. Haz clic en Traducir.

    BigQuery traduce tu consulta en GoogleSQL y la muestra en el panel derecho. Por ejemplo, en la siguiente captura de pantalla se muestra SQL de Teradata traducido:

    Muestra una consulta de SQL de Teradata traducida a GoogleSQL.

  9. Opcional: Para ejecutar la consulta de GoogleSQL traducida, haz clic en Ejecutar.

  10. Para volver al editor de SQL, haz clic en Más y, luego, selecciona Inhabilitar la traducción de SQL (opcional).

    El panel del Editor regresa a un solo panel.

Usa Gemini con el traductor interactivo de SQL

Puedes configurar el traductor de SQL interactivo para ajustar la forma en que este traduce tu SQL de origen. Para ello, proporciona tus propias reglas para usar con Gemini en un archivo de configuración de YAML o proporciona un archivo de configuración de YAML que contenga metadatos de objetos SQL o información de asignación de objetos.

Crea y aplica reglas de traducción mejoradas con Gemini

Puedes personalizar la forma en que el traductor interactivo de SQL traduce SQL creando reglas de traducción. El traductor de SQL interactivo ajusta sus traducciones según las reglas de traducción de SQL mejoradas con Gemini que le asignes, lo que te permite personalizar los resultados de la traducción según tus necesidades de migración. Esta función solo se admite en ciertas ubicaciones.

Para crear una regla de traducción de SQL mejorada con Gemini, puedes crearla en la consola o crear un archivo YAML de configuración y subirlo a Cloud Storage.

Console

Para crear una regla de traducción de SQL mejorada con Gemini para la entrada SQL, escribe una consulta en SQL en el editor de consultas y, luego, haz clic en ASSIST > Customize. (Versión preliminar)

Personaliza la entrada de traducción

De manera similar, para crear una regla de traducción de SQL mejorada con Gemini para el SQL de salida, ejecuta una traducción interactiva y, luego, haz clic en ASSIST > Customize this translation.

Personaliza el resultado de la traducción

Cuando aparezca el menú Personalizar, continúa con los siguientes pasos.

  1. Usa una o ambas de las siguientes instrucciones para crear una regla de traducción:

    • En el mensaje Buscar y reemplazar un patrón, especifica un patrón de SQL que desees reemplazar en el campo Reemplazar y un patrón SQL para reemplazar en el campo Con.

      Un patrón de SQL puede contener cualquier cantidad de instrucciones, cláusulas o funciones en una secuencia de comandos de SQL. Cuando creas una regla con esta instrucción, la traducción de SQL mejorada con Gemini identifica cualquier instancia de ese patrón de SQL en la consulta en SQL y la reemplaza de forma dinámica por otro patrón de SQL. Por ejemplo, puedes usar esta instrucción para crear una regla que reemplace todas las ocurrencias de months_between (X,Y) por date_diff(X,Y,MONTH).

    • En el campo Describe un cambio en el resultado, escribe un cambio en el resultado de la traducción de SQL en lenguaje natural.

      Cuando creas una regla con esta instrucción, la traducción de SQL mejorada con Gemini identifica la solicitud y realiza el cambio especificado en la consulta en SQL.

  2. Haz clic en Vista previa.

  3. En el diálogo Sugerencias generadas por Gemini, revisa los cambios que realizó la traducción de SQL mejorada por Gemini en la consulta en SQL según tu regla.

    Aplica los cambios del archivo YAML de configuración basado en Gemini

  4. Opcional: Para agregar esta regla a fin de usarla con traducciones futuras, selecciona la casilla de verificación Guardar esta instrucción….

    Las reglas se guardan en el archivo YAML de configuración predeterminado o __default.ai_config.yaml. Este archivo YAML de configuración se guarda en la carpeta de Cloud Storage como se especifica en el campo Ubicación del origen de la configuración de traducción en la configuración de traducción. Si aún no se configuró la Ubicación de la fuente de configuración de traducción, aparecerá un navegador de carpetas que te permitirá seleccionar una. Un archivo YAML de configuración está sujeto a limitaciones de tamaño de archivo de configuración.

  5. Para aplicar los cambios sugeridos a la consulta en SQL, haz clic en Aplicar.

YAML

Para crear una regla de traducción de SQL mejorada con Gemini, puedes crear un archivo YAML de configuración basado en Gemini y subirlo a Cloud Storage. Para obtener más información, consulta Crea un archivo YAML de configuración basado en Gemini.

Una vez que hayas subido una regla de traducción de SQL mejorada con Gemini a Cloud Storage, puedes aplicarla siguiendo estos pasos:

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

    Ir a BigQuery

  2. En el editor de consultas, haz clic en Más > Configuración de traducción.

  3. En el campo Ubicación del origen de la configuración de traducción, especifica la ruta de acceso al archivo YAML basado en Gemini almacenado en una carpeta de Cloud Storage.

  4. Haz clic en Guardar.

    Una vez guardado, ejecuta una traducción interactiva. El traductor interactivo sugiere cambios en tus traducciones según las reglas de tu archivo YAML de configuración, si hay uno disponible.

Si hay una sugerencia de Gemini disponible para la entrada según tu regla, aparecerá el diálogo Vista previa de cambios sugeridos, que muestra los posibles cambios en la entrada de traducción. (Vista previa)

Si hay una sugerencia de Gemini disponible para el resultado según tu regla, aparecerá un banner de notificación en el editor de código. Para revisar y aplicar estas sugerencias, haz lo siguiente:

  1. Haz clic en Assist > View suggestions a ambos lados del editor de código para revisar los cambios sugeridos en la consulta correspondiente.

    Aplica los cambios del archivo YAML de configuración basado en Gemini

  2. En el diálogo Sugerencias generadas por Gemini, revisa los cambios que Gemini realizó en la consulta en SQL según tu regla de traducción.

  3. Para aplicar los cambios sugeridos al resultado de la traducción, haz clic en Aplicar.

Actualiza el archivo YAML de configuración basado en Gemini

Para actualizar un archivo YAML de configuración existente, haz lo siguiente:

  1. En el diálogo Sugerencias generadas en Gemini, haz clic en Ver el archivo de configuración de reglas de Gemini.

  2. Cuando aparezca el editor de configuración, selecciona el archivo de configuración YAML que desees editar.

  3. Realiza el cambio y haz clic en Guardar.

  4. Haz clic en Listo para cerrar el editor de YAML.

  5. Ejecuta una traducción interactiva para aplicar la regla actualizada.

Explica una traducción

Después de ejecutar una traducción interactiva, puedes solicitar una explicación de texto generada por Gemini. El texto generado incluye un resumen de la consulta en SQL traducida. Gemini también identifica diferencias y discrepancias de traducción entre la consulta en SQL de origen y la consulta de GoogleSQL traducida.

Para obtener una explicación de la traducción de SQL generada por Gemini, haz lo siguiente:

  1. Para crear una explicación de traducción de SQL generada por Gemini, haz clic en Asistencia y, luego, en Explicar esta traducción.

    Botón para explicar la traducción.

Traduce con un ID de configuración de traducción por lotes

Puedes ejecutar una consulta interactiva con las mismas configuraciones de traducción que un trabajo de traducción por lotes si proporcionas un ID de configuración de traducción por lotes.

  1. En el editor de consultas, haz clic en Más > Configuración de traducción.

  2. En el campo ID de configuración de traducción, proporciona un ID de configuración de traducción por lotes para aplicar la misma configuración de traducción a partir de un trabajo de migración por lotes de BigQuery completado.

    Para encontrar el ID de configuración de la traducción por lotes de un trabajo, selecciona un trabajo de traducción por lotes de la página Traducción de SQL y haz clic en la pestaña Configuración de traducción. El ID de configuración de traducción por lotes se muestra como Nombre del recurso.

  3. Haz clic en Guardar.

Cómo traducir con parámetros de configuración adicionales

Puedes ejecutar una consulta interactiva con configuraciones de traducción adicionales si especificas archivos YAML de configuración almacenados en una carpeta de Cloud Storage. Las configuraciones de traducción pueden incluir metadatos de objeto SQL o información de asignación de objetos de la base de datos de origen que puedan mejorar la calidad de la traducción. Por ejemplo, incluye información o esquemas de DDL de la base de datos de origen para mejorar la calidad de la traducción interactiva de SQL.

Para especificar configuraciones de traducción, proporciona una ubicación a los archivos de origen de configuración de traducción y haz lo siguiente:

  1. En el editor de consultas, haz clic en Más > Configuración de traducción.

  2. En la sección Ubicación del origen de la configuración de traducción, especifica la ruta a un archivo de configuración de traducción almacenado en una carpeta de Cloud Storage.

    El traductor interactivo de SQL de BigQuery admite archivos ZIP de metadatos que contienen metadatos de traducción y asignación de nombres de objetos. Para obtener información sobre cómo subir archivos a Cloud Storage, consulta Carga objetos desde un sistema de archivos.

  3. Haz clic en Guardar.

Para almacenar información de los archivos de metadatos que genera la herramienta dwh-migration-dumper en el backend de BigQuery, haz lo siguiente:

  1. En el editor de consultas, haz clic en Más > Configuración de traducción.
  2. Haz clic en la casilla de verificación Habilitar el almacenamiento en caché de metadatos. En el caso de los trabajos con archivos de metadatos grandes, este proceso reduce significativamente la latencia de traducción para las solicitudes posteriores. Los metadatos almacenados en caché están activos durante un máximo de 7 días. Esta función está en vista previa. Para solicitar asistencia o enviar comentarios sobre esta función, comunícate con bq-edw-migration-support@google.com.
  3. Haz clic en Guardar.

Limitaciones del tamaño del archivo de configuración

Cuando usas un archivo de configuración de traducción con el traductor interactivo de SQL de BigQuery, el tamaño del archivo de metadatos comprimido o del archivo de configuración YAML debe ser inferior a 50 MB. Si el tamaño del archivo supera los 50 MB, el traductor interactivo omite ese archivo de configuración durante la traducción y produce un mensaje de error similar al siguiente:

CONFIG ERROR: Skip reading file "gs://metadata-file.zip". File size (150,000,000 bytes) exceeds limit (50 MB).

Un método que permite reducir el tamaño del archivo de metadatos es usar las marcas --database o --schema para extraer solo los metadatos de las bases de datos o los esquemas que son relevantes para las consultas de entrada de traducción. Para obtener más información sobre el uso de estas marcas cuando generas archivos de metadatos, consulta Marcas globales.

Soluciona problemas de errores de traducción

Los siguientes son errores comunes que se encuentran cuando se usa el traductor interactivo de SQL.

Problemas de traducción de RelationNotFound o AttributeNotFound

Para garantizar la traducción más precisa, ingresa las declaraciones del lenguaje de definición de datos (DDL) de todas las tablas usadas en una consulta antes de la consulta. Por ejemplo, si deseas traducir la consulta select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id; de Amazon Redshift, debes ingresar las siguientes instrucciones de SQL en el traductor interactivo de SQL:

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

Precios

No se aplican cargos por usar el traductor interactivo de SQL. Sin embargo, se aplican las tarifas normales al almacenamiento que se usa para almacenar archivos de entrada y salida. Para obtener más información, consulta los precios de almacenamiento.

¿Qué sigue?

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