Migra código con el traductor de SQL por lotes

En este documento, se describe cómo usar el traductor de SQL por lotes en BigQuery para traducir secuencias de comandos escritas en otros dialectos de SQL a consultas de GoogleSQL. Puedes enviar y revisar los resultados de un trabajo de traducción desde la consola de Google Cloud o desde la línea de comandos.

Nota: Para compilar una integración de software personalizada, una canalización de CI/CD automatizada o otro flujo de trabajo programático, te recomendamos que llames a la API de BigQuery Migration directamente.

Para obtener una lista de los dialectos de SQL que admite este traductor de SQL, consulta Dialectos de SQL compatibles.

Para obtener una lista de las ubicaciones de procesamiento compatibles, consulta Ubicaciones.

Antes de comenzar

Antes de enviar un trabajo de traducción, sigue estos pasos.

Habilita las traducciones de SQL

Habilita la API requerida y obtén los permisos necesarios para usar un traductor de SQL de BigQuery. Para obtener más información, consulta Habilita las traducciones de SQL.

Permisos necesarios

Para obtener los permisos que necesitas para crear trabajos de traducción con el traductor interactivo, la API de Translation o el traductor de SQL por lotes, pídele a tu administrador que te otorgue los siguientes roles de IAM en el recurso parent:

• Visualiza y supervisa los trabajos de migración: Visualizador de MigrationWorkflow (roles/bigquerymigration.viewer)
• Envío de trabajos de migración: Editor de MigrationWorkflow (roles/bigquerymigration.editor)
• Accede a los buckets de Cloud Storage para archivos y entradas: Administrador de objetos de Storage (roles/storage.objectAdmin) en el bucket de Cloud Storage de origen y destino.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para crear trabajos de traducción con el traductor interactivo, la API de Translation o el traductor de SQL por lotes. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear trabajos de traducción con el traductor interactivo, la API de Translation o el traductor de SQL por lotes:

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

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

Recopila los archivos de origen

Los archivos de origen deben ser archivos de texto que contengan 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 SQL sea válido a través del uso de los métodos disponibles para ti.

Crea archivos de metadatos

Para ayudar a que el servicio genere resultados de traducción más precisos, te recomendamos que proporciones archivos de metadatos. Sin embargo, esto no es obligatorio.

Puedes usar la herramienta de extracción de línea de comandos dwh-migration-dumper para generar la información de metadatos. Una vez que prepares los archivos de metadatos, puedes 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 archivos de origen; no necesitas establecer ninguna configuración adicional para habilitar esto.

Si deseas generar información de metadatos a través de la herramienta dwh-migration-dumper, consulta Genera metadatos para la traducción.

Crea archivos YAML de configuración

De forma opcional, puedes crear y usar archivos YAML de configuración de configuración para personalizar tus traducciones por lotes. Estos archivos se pueden usar para transformar el resultado de la traducción de varias maneras. Por ejemplo, puedes crear un archivo YAML de configuración para cambiar el caso de un objeto SQL durante la traducción.

Usa una de las siguientes opciones para incluir un archivo YAML de configuración en tu trabajo de traducción.

Console

Sube el archivo YAML de configuración al directorio de Cloud Storage que contiene tus archivos de origen. Cuando seleccionas ese directorio como una ubicación de entrada, el trabajo de traducción incluye el archivo YAML de configuración de forma automática.

gcloud

Vista previa

Este producto o función está sujeto a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Las marcas que usas con el comando gcloud alpha bq translation translate-batch dependen de dónde se almacena el archivo YAML de configuración:

• Si el archivo YAML de configuración se encuentra en el mismo directorio que los archivos de origen, no necesitas ninguna marca adicional. Cuando configuras ese directorio en la marca --source-gcs-uris o --source-local-dirs, el trabajo incluye el archivo YAML de configuración de forma automática.
• Si el archivo YAML de configuración se almacena por separado en tu máquina local, usa la marca --source-local-files para subirlo y agregarlo al trabajo.
• Si el archivo YAML de configuración se almacena por separado en Cloud Storage, usa la marca --source-gcs-files para agregarlo al trabajo.

Por ejemplo, con el siguiente comando, se suben tus archivos de origen y un archivo YAML de configuración almacenado por separado desde tu máquina local y, luego, se ejecuta el trabajo de traducción:

gcloud alpha bq translation translate-batch \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-local-dirs=LOCAL_DIR=SOURCE_URI \
  --source-local-files=LOCAL_CONFIG_YAML=CONFIG_YAML_URI \
  --target-gcs-path=TARGET_URI

Reemplaza lo siguiente:

• LOCAL_CONFIG_YAML: Es la ruta de acceso local al archivo YAML de configuración, como ./configs/change-case.config.yaml.
• CONFIG_YAML_URI: Es el URI de Cloud Storage al que el comando sube el archivo YAML de configuración, como gs://my_data_bucket/teradata/configs/change-case.config.yaml. Este URI debe estar fuera del directorio SOURCE_URI.

Para obtener descripciones de los otros marcadores de posición, consulta Envía un trabajo de traducción.

Sube archivos de entrada a Cloud Storage

Sube los archivos de origen que contienen las consultas y las secuencias de comandos que deseas traducir a Cloud Storage. También puedes subir cualquier archivo de metadatos o archivos YAML de configuración al mismo bucket de Cloud Storage y directorio que contiene los archivos de origen. Para obtener más información sobre la creación de buckets y la carga de archivos a Cloud Storage, consulta Crea buckets y Sube objetos desde un sistema de archivos.

Elige cómo enviar el trabajo de traducción

Tienes dos opciones para enviar un trabajo de traducción por lotes:

• Consola deGoogle Cloud : Configura y envía un trabajo a través de una interfaz de usuario. Este enfoque requiere que subas los archivos de origen a Cloud Storage.

• Google Cloud CLI: Envía un trabajo desde la línea de comandos con la gcloud CLI. El comando translate-batch acepta tus ubicaciones de origen y destino como marcas, y puede subir directorios y archivos locales a Cloud Storage por ti. Para obtener más información, consulta Envía un trabajo de traducción.

Ambas opciones requieren que se pueda acceder a tus archivos de origen en Cloud Storage y ambas crean el mismo tipo de trabajo de traducción. Un trabajo que envías desde la línea de comandos sigue apareciendo en la lista de trabajos de traducción en la consola deGoogle Cloud .

Envía un trabajo de traducción

Usa una de las siguientes opciones para iniciar un trabajo de traducción y ver su progreso. Para revisar los resultados después, consulta Explora el resultado de la traducción.

Console

En estos pasos, se da por sentado que ya subiste archivos de origen a un bucket de Cloud Storage.

Para usar la consola de Google Cloud y enviar un trabajo de traducción por lotes, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página Traducción de SQL.

   Ir a Traducción de SQL

2. En el panel Traducción de SQL, haz clic en Iniciar traducción.

3. En Configuración de traducción, ingresa lo siguiente:

   1. En Nombre visible, escribe un nombre para el trabajo de traducción. El nombre puede contener letras, números o guiones bajos.
   2. 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. El trabajo de traducción tiene un mejor rendimiento cuando eliges la misma ubicación que tu bucket de archivos de origen.
   3. En Dialecto de origen, selecciona el dialecto de SQL que deseas traducir.
   4. En Dialecto de destino, selecciona GoogleSQL.

4. Haz clic en Siguiente.

5. En Detalles de la ubicación del archivo, especifica las rutas de acceso de Cloud Storage que se usarán para la entrada y salida de la traducción. Puedes ingresar las rutas en el formato bucket_name/folder_name/ o usar la opción Explorar para navegar a una carpeta.

   1. En Ubicación del directorio de salida, especifica una ruta de acceso a la carpeta de Cloud Storage de destino de los archivos traducidos. Este sirve como directorio raíz para todos los resultados de la traducción.
   2. Elige una o más ubicaciones de directorio de entrada que contengan la ruta de acceso a los archivos SQL que se traducirán.
   3. Si es necesario, a cada directorio de entrada se le puede asignar un nombre de subdirectorio de salida debajo del directorio de salida raíz.

6. Haz clic en Siguiente.

7. Selecciona cualquier parámetro de configuración opcional que necesites para personalizar los metadatos y cualquier resultado de traducción adicional.

8. Opcional: Para personalizar aún más el comportamiento de la traducción, crea archivos YAML de configuración y colócalos en el bucket de entrada de Cloud Storage. Estos archivos se pueden usar para cambiar el nombre de los objetos, habilitar optimizaciones, mejorar las traducciones con Gemini y mucho más. Para obtener más información sobre los archivos YAML de configuración, consulta Crea un archivo YAML de configuración.

9. Haz clic en Crear para iniciar el trabajo de traducción.

   Después de crear el trabajo de traducción, puedes ver su estado en la lista de trabajos de traducción.

gcloud

Vista previa

Este producto o función está sujeto a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para enviar un trabajo de traducción por lotes, usa el comando gcloud alpha bq translation translate-batch. Las marcas que usas para identificar tus archivos de origen dependen de si los archivos están en Cloud Storage o en tu máquina local.

Traduce archivos SQL en Cloud Storage

Para traducir archivos SQL que ya subiste a Cloud Storage, identifica los directorios de origen con la marca --source-gcs-uris. Si deseas incluir archivos que no están en --source-gcs-uris, puedes usar la marca --source-gcs-files:

gcloud alpha bq translation translate-batch \
    --source-dialect=SOURCE_DIALECT \
    --target-dialect=TARGET_DIALECT \
    --location=LOCATION \
    --source-gcs-uris=SOURCE_URI \
    --target-gcs-path=TARGET_URI

Reemplaza lo siguiente:

• SOURCE_DIALECT: Es el dialecto de los archivos SQL de origen, como teradata. Para conocer los valores admitidos, consulta Dialectos de SQL admitidos.
• TARGET_DIALECT: Es el dialecto al que se traducirán los archivos de origen. Por ejemplo, bigquery
• LOCATION: Es la ubicación que procesa el trabajo, como us.
• SOURCE_URI: Es el directorio de Cloud Storage que contiene los archivos de origen, como gs://my_data_bucket/teradata/input/.
• TARGET_URI: Es el directorio de Cloud Storage que recibe los archivos traducidos, como gs://my_data_bucket/teradata/output/.

Traduce archivos SQL en tu máquina local

Para traducir archivos que se encuentran en tu máquina local, asigna cada directorio local a un URI de Cloud Storage con la marca --source-local-dirs. El comando sube el directorio a ese URI y, luego, incluye el URI en el trabajo de traducción, por lo que no necesitas subir los archivos por tu cuenta:

gcloud alpha bq translation translate-batch \
    --source-dialect=SOURCE_DIALECT \
    --target-dialect=TARGET_DIALECT \
    --location=LOCATION \
    --source-local-dirs=LOCAL_DIR=SOURCE_URI \
    --target-gcs-path=TARGET_URI

Reemplaza LOCAL_DIR por el directorio local que contiene los archivos de origen, como ./teradata_queries. Para obtener descripciones de los otros marcadores de posición, consulta Traduce archivos SQL en Cloud Storage.

Para asignar archivos individuales en lugar de directorios, usa la marca --source-local-files.

Agrega marcas opcionales

Para generar sugerencias de Gemini junto con el SQL traducido, agrega la marca --enable-ai-suggestion.

De forma predeterminada, el comando espera a que finalice el trabajo de traducción. Para enviar el trabajo y regresar de inmediato, agrega la marca --async. Luego, el comando imprime un ID de traducción que puedes pasar al comando gcloud alpha bq translation describe para verificar el estado del trabajo:

gcloud alpha bq translation describe TRANSLATION_ID \
    --location=LOCATION

Recupera los archivos de salida

El trabajo de traducción escribe sus resultados en el directorio de Cloud Storage que estableciste en la marca --target-gcs-path. Este directorio de destino contiene los archivos traducidos, el informe de resumen de la traducción y los archivos de sugerencias de IA.

Para copiar el resultado en tu máquina local, usa el siguiente comando:

gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY

Reemplaza lo siguiente:

• TARGET_URI: Es el URI base de destino, como gs://my_data_bucket/teradata/output/.
• LOCAL_DIRECTORY: Es el directorio local que recibe los archivos.

Tu trabajo también aparece en la lista de trabajos de traducción en la consola deGoogle Cloud , aunque lo hayas enviado desde la línea de comandos. Para revisar la calidad de un resultado de traducción, consulta Explora el resultado de la traducción.

Traduce los metadatos

Vista previa

Este producto o función está sujeto a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Además de traducir las secuencias de comandos de SQL, puedes traducir los metadatos que describen tu almacén de datos de origen. Un trabajo de traducción de metadatos lee los archivos de metadatos que extrajiste de tu sistema de origen y escribe instrucciones del lenguaje de definición de datos (DDL) de GoogleSQL que vuelven a crear esos objetos en BigQuery.

La entrada es uno o más archivos ZIP de metadatos. Para aprender a producir estos archivos con la herramienta dwh-migration-dumper, consulta Genera metadatos para la traducción.

Puedes traducir metadatos con la consola de Google Cloud o la gcloud CLI. Selecciona una de las siguientes opciones:

Console

La traducción de metadatos es una opción de salida en un trabajo de traducción normal:

1. Sigue los pasos que se indican en Envía un trabajo de traducción para configurar un trabajo con el directorio de Cloud Storage que contiene tus archivos ZIP de metadatos como ubicación de entrada.
2. En Configuración opcional, selecciona DDL.
3. Haz clic en Crear para crear el trabajo.

El trabajo escribe las declaraciones de DDL traducidas en tu directorio de salida, junto con cualquier SQL traducido.

gcloud

Puedes traducir metadatos como un trabajo propio o como un resultado adicional de un trabajo de traducción de SQL por lotes.

Traduce los metadatos por separado

Usa el comando gcloud alpha bq translation translate-metadata cuando tus entradas sean archivos ZIP de metadatos y no tengas SQL para traducir:

gcloud alpha bq translation translate-metadata \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI

Reemplaza lo siguiente:

• SOURCE_DIALECT: Es el dialecto de los metadatos de origen, como teradata. Para conocer los valores admitidos, consulta Dialectos de SQL admitidos.
• TARGET_DIALECT: Es el dialecto de las tablas de destino. Por ejemplo, bigquery
• LOCATION: Es la ubicación que procesa el trabajo, como us.
• SOURCE_URI: Es el directorio de Cloud Storage que contiene los archivos ZIP de metadatos, como gs://my_data_bucket/teradata/metadata/.
• TARGET_URI: Es el directorio de Cloud Storage que recibe las declaraciones de DDL traducidas, como gs://my_data_bucket/teradata/ddl_output/.

Para apuntar a archivos ZIP de metadatos individuales en lugar de a un directorio, usa la marca --source-gcs-files. Para subir archivos de metadatos desde tu máquina local como parte del trabajo, usa la marca --source-local-dirs o --source-local-files.

Al igual que con un trabajo de traducción por lotes, el comando espera a que finalice el trabajo. Agrega la marca --async para enviar el trabajo y devolver un ID de traducción de inmediato.

Traduce metadatos como parte de una traducción de SQL por lotes

Si tus entradas de traducción por lotes ya incluyen tus archivos ZIP de metadatos, no necesitas un segundo trabajo. Agrega metadata a los resultados de la traducción del trabajo por lotes con la marca --target-types, y el trabajo escribirá las sentencias de SQL y DDL traducidas en una sola ejecución:

gcloud alpha bq translation translate-batch \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI \
  --target-types=sql,metadata

Para conocer las otras marcas que acepta el comando translate-batch, consulta Envía un trabajo de traducción.

Genera el DDL de origen

Vista previa

Este producto o función está sujeto a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Cuando tu SQL de origen hace referencia a tablas cuyas definiciones no tienes, el traductor no siempre puede resolver los objetos, lo que genera problemas de RelationNotFound o AttributeNotFound.

La mejor manera de resolver estos problemas es proporcionar las definiciones reales de tus objetos de origen. Ejecuta la herramienta dwh-migration-dumper en tu sistema de origen y, luego, incluye el archivo ZIP de metadatos resultante en las entradas de traducción. Para obtener instrucciones, consulta Genera metadatos para la traducción. Los metadatos extraídos describen tus objetos con exactitud, por lo que el traductor los resuelve sin suposiciones.

Si no puedes extraer metadatos, por ejemplo, cuando ya no tienes acceso al sistema de origen, puedes pedirle a Gemini que infiera las declaraciones de DDL faltantes de tu SQL de origen. Gemini infiere estas sentencias de DDL a partir de cómo se usan los objetos en tus consultas, por lo que siempre debes revisar y verificar estas sentencias antes de usarlas.

Puedes generar el DDL de origen para tus traducciones con la consola deGoogle Cloud o gcloud CLI. Selecciona una de las siguientes opciones:

Console

Gemini genera sugerencias de DDL de origen como parte de un trabajo de traducción normal:

1. Sigue los pasos que se indican en Envía un trabajo de traducción para configurar un trabajo.
2. En Configuración opcional, selecciona Sugerencias de IA de Gemini.
3. Haz clic en Crear para crear el trabajo.

Si la traducción produce problemas de RelationNotFound o AttributeNotFound, el trabajo genera sentencias de DDL de origen sugeridas para los objetos no resueltos. El trabajo también traduce tu SQL, por lo que no necesitas un trabajo independiente.

gcloud

El comando gcloud alpha bq translation generate-source-ddl lee tu SQL de origen y devuelve las declaraciones de DDL de origen sugeridas:

gcloud alpha bq translation generate-source-ddl \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI

Reemplaza SOURCE_URI por el directorio de Cloud Storage que contiene los archivos SQL de origen y TARGET_URI por el directorio de Cloud Storage que recibe las declaraciones de DDL generadas. Los otros marcadores de posición son los mismos que se describen en Traduce metadatos.

Para generar sugerencias como parte de un trabajo de traducción, agrega la marca --enable-ai-suggestion al comando translate-batch.

Luego, puedes proporcionar las declaraciones de DDL generadas como entrada para un trabajo de traducción posterior y, así, mejorar la calidad de la traducción. Para obtener más información, consulta Problemas de traducción de RelationNotFound o AttributeNotFound.

Explora el resultado de la traducción

Puedes revisar los resultados de un trabajo de traducción en la consola de Google Cloud , independientemente de si el trabajo se envió desde la línea de comandos o la consola de Google Cloud . El traductor de SQL por lotes genera los siguientes archivos en el destino especificado:

• Los archivos traducidos
• El informe de resumen de traducción en formato CSV
• Son los archivos de sugerencias de IA.

Resultado de la consola deGoogle Cloud

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

1. En la consola de Google Cloud , ve a la página Traducción de SQL.

   Ir a Traducción de SQL

2. En la lista de trabajos de traducción, busca el trabajo del que deseas ver los detalles de la traducción. Luego, haz clic en el nombre del trabajo de traducción. Puedes ver una visualización de Sankey que ilustra la calidad general del trabajo, la cantidad de líneas de código de entrada (sin incluir las líneas en blanco ni los comentarios) y una lista de problemas que ocurrieron durante el proceso de traducción. Debes priorizar las correcciones de izquierda a derecha. Los problemas en una etapa inicial pueden causar problemas adicionales en las etapas posteriores.

3. Mantén el puntero sobre las barras de error o advertencia, y revisa las sugerencias para determinar los próximos pasos para depurar el trabajo de traducción.

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

5. Selecciona la pestaña Mensajes de registro para ver más detalles sobre cada problema de traducción, incluida la categoría de problema, el mensaje de problema específico y un vínculo al archivo en el que se produjo el problema. Puedes hacer clic en las barras de visualización de Sankey para filtrar los problemas. Puedes seleccionar un problema en la pestaña Mensaje de registro para abrir la pestaña Código que muestra el archivo de entrada y salida si es aplicable.

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

Informe de resumen

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

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

1. En la consola de Google Cloud , ve a la página Traducción de SQL.

   Ir a Traducción de SQL

2. En la lista de trabajos de traducción, busca el que te interesa y, luego, haz clic en su nombre o en Más opciones > Mostrar detalles.

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

4. En la página Detalles del objeto, haz clic en el valor de la fila URL autenticada para ver el archivo en tu navegador.

En la siguiente tabla, se describen las columnas de archivos de resumen:

Columna	Descripción
Marca de tiempo	La marca de tiempo en la que ocurrió el problema.
FilePath	La ruta de acceso al archivo de origen con el que está asociado el problema.
Nombre del archivo	El nombre del archivo de origen con el que está asociado el problema.
ScriptLine	El número de línea en la que ocurrió el problema.
ScriptColumn	El número de columna en la que ocurrió el problema.
TranspilerComponent	El componente interno del motor de traducción en el que se produjo la advertencia o el error. Esta columna puede estar vacía.
Entorno	Es el entorno del dialecto de traducción asociado con la advertencia o el error. Esta columna puede estar vacía.
ObjectName	Es el objeto de SQL en el archivo de origen que está asociado con la advertencia o el error. Esta columna puede estar vacía.
Gravedad	La gravedad del problema, ya sea una advertencia o un error.
Categoría	La categoría del problema de traducción.
SourceType	Es la fuente de este problema. El valor de esta columna puede ser SQL, que indica un problema en los archivos SQL de entrada, o METADATA, que indica un problema en el paquete de metadatos.
Mensaje	Es el mensaje de advertencia o de error del problema de traducción.
ScriptContext	El fragmento de SQL en el archivo de origen que está asociado con el problema.
Acción	La acción que te recomendamos que realices para resolver el problema.

Pestaña Código

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

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

1. En la consola de Google Cloud , ve a la página Traducción de SQL.

   Ir a Traducción de SQL

2. En la lista de trabajos de traducción, busca el que te interesa y, luego, haz clic en su nombre o en Más opciones > Mostrar detalles.

3. Seleccionar 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. Haz clic en un archivo para ver su entrada y salida de traducción, y cualquier problema de traducción de su traducción.
   • Entrada mejorada con Gemini: Es el SQL de entrada que tradujo el motor de traducción. Si especificaste 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, luego, traduce la entrada mejorada con Gemini. Para ver la entrada original, haz clic en Ver entrada original.
   • Resultado de la traducción: Es el resultado de la traducción. Si especificaste reglas de personalización de Gemini para el SQL de destino en la configuración de Gemini, la transformación se aplica al resultado traducido como un resultado mejorado con Gemini. Si hay un resultado mejorado por Gemini disponible, puedes hacer clic en el botón Sugerencia de Gemini para revisarlo.

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

Nota: Puedes ver resúmenes de resumen y mensajes del trabajo de traducción general desde el Página de resultados

Pestaña Configuración

Puedes agregar, 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 configuración nueva.

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

1. En la consola de Google Cloud , ve a la página Traducción de SQL.

   Ir a Traducción de SQL

2. En la lista de trabajos de traducción, busca el que te interesa y, luego, haz clic en su nombre o en Más opciones > Mostrar detalles.

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

Para agregar un archivo de configuración nuevo, haz lo siguiente:

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 existente, sigue estos pasos:

1. Haz clic en el archivo YAML de configuración.
2. Edita el archivo y, luego, haz clic en Guardar.
3. Haz clic en Volver a ejecutar para ejecutar un nuevo trabajo de traducción que use los archivos YAML de configuración editados.

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

Archivos traducidos

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

Importante: La traducción se realiza según el criterio del mejor esfuerzo. Siempre que sea posible, valida las consultas traducidas.

Controla las funciones de SQL no compatibles con las UDF auxiliares

Cuando se traduce SQL de un dialecto de origen a BigQuery, es posible que algunas funciones no tengan un equivalente directo. Para solucionar este problema, el Servicio de migración de BigQuery (y la comunidad de BigQuery en general) proporcionan funciones auxiliares definidas por el usuario (UDF) 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 para entornos de producción

Si bien bqutil ofrece un acceso conveniente a estas UDF 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 los siguientes 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. Confiar directamente en bqutil podría generar un comportamiento inesperado o cambios rotundos en tus consultas de producción si se actualiza la lógica de una UDF.
2. Aislamiento de dependencias: Implementar las 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 tus requisitos específicos de lógica empresarial o rendimiento. Esto solo es posible si están 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 las UDF en tu entorno controlado se alinea con esas políticas.

Implementa las UDF auxiliares en tu proyecto

Para darte control total sobre la versión, la personalización y el acceso de las UDF, te recomendamos implementar UDF auxiliares en tu propio proyecto y conjunto de datos para un uso de producción confiable y estable. Para obtener más información sobre las secuencias de comandos y los pasos necesarios para implementar las UDF auxiliares en tu entorno, consulta Implementa las UDF.

Soluciona problemas

En esta sección, se describe cómo depurar consultas individuales y cómo resolver los errores de traducción más comunes.

Depura consultas en SQL traducidas por lotes con el traductor interactivo de SQL

Puedes usar el traductor interactivo de SQL de BigQuery para revisar o depurar una consulta en SQL con los mismos metadatos o la misma información de asignación de objetos que la base de datos de origen. Después de completar un trabajo de traducción por lotes, BigQuery genera un ID de configuración de traducción que contiene información sobre los metadatos del trabajo, la asignación de objetos o la ruta de búsqueda del esquema, según corresponda para la consulta. Usa el ID de configuración de traducción por lotes con el traductor interactivo de SQL para ejecutar consultas en SQL con la configuración especificada.

Puedes depurar las consultas en SQL traducidas por lotes con la consola deGoogle Cloud o gcloud CLI. Selecciona una de las siguientes opciones:

Console

Para iniciar una traducción interactiva de SQL a través de un ID de configuración de traducción por lotes, sigue estos pasos:

1. En la consola de Google Cloud , ve a la página Traducción de SQL.

   Ir a Traducción de SQL

2. En la lista de trabajos de traducción, busca el trabajo que te interesa y, luego, haz clic en Más opciones > Abrir la 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 traducción de la traducción interactiva, haz clic en Herramientas > Traducción de consultas > Configuración de traducción en el traductor de SQL interactivo.

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

1. En la consola de Google Cloud , ve a la página Traducción de SQL.

   Ir a Traducción de SQL

2. En la lista de trabajos de traducción, busca el que te interesa y, luego, haz clic en su nombre o en Más opciones > Mostrar detalles.

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

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

5. Junto al nombre del archivo de salida, haz clic en Editar para abrir los archivos en el traductor de SQL interactivo (versión preliminar).

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

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

gcloud

Vista previa

Este producto o función está sujeto a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para volver a traducir y, luego, inspeccionar una sola consulta sin abrir la consola deGoogle Cloud , usa el comando gcloud alpha bq translation translate. Esto es útil cuando redujiste un problema de traducción por lotes a una consulta y quieres iterar en ella de forma local.

gcloud alpha bq translation translate \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --input-file=INPUT_FILE \
  --output-file=OUTPUT_FILE \
  --translation-log-file=LOG_FILE \
  --explanation-output-file=EXPLANATION_FILE

Reemplaza lo siguiente:

• INPUT_FILE: Es el archivo local que contiene la consulta que se traducirá. Si omites esta marca, el comando lee la consulta desde la entrada estándar.
• OUTPUT_FILE: Es el archivo local que recibe la consulta traducida. Si omites esta marca, el comando escribe la consulta en la salida estándar.
• LOG_FILE: Es el archivo YAML local que recibe los registros de traducción, que contienen los mismos mensajes de problemas que la consola deGoogle Cloud muestra en la pestaña Mensajes de registro.
• EXPLANATION_FILE: Es el archivo local que recibe una explicación de la traducción generada por Gemini.

Para volver a usar los metadatos de tu trabajo por lotes de modo que la consulta resuelva los mismos objetos, agrega la marca --metadata-gcs-uri. Para obtener más información, consulta Traduce una consulta a GoogleSQL.

Soluciona problemas de errores de traducción

En las siguientes secciones, se describen los errores que se encuentran con frecuencia cuando se usa el traductor de SQL por lotes.

Problemas de traducción de RelationNotFound o AttributeNotFound

Después de traducir una consulta con el traductor de SQL por lotes, es posible que encuentres una traducción con errores con el error RelationNotFound o AttributeNotFound.

Para encontrar las traducciones con errores, ve a la página Detalles de la traducción en BigQuery en la consola de Google Cloud y abre la pestaña Mensajes de registro.

La traducción funciona mejor con DDL de metadatos. Cuando no se pueden encontrar definiciones de objetos SQL, el motor de traducción genera problemas RelationNotFound o AttributeNotFound. Recomendamos usar el extractor de metadatos para generar paquetes de metadatos para garantizar que todas las definiciones de objetos estén presentes. Agregar metadatos es el primer paso recomendado para resolver la mayoría de los errores de traducción, ya que este paso suele corregir muchos otros errores que se generan de forma indirecta por la falta de metadatos.

Si deseas obtener más información, consulta Genera metadatos para la traducción y la evaluación.

Cómo corregir problemas de traducción con Gemini

Vista previa

Este producto o función está sujeto a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Nota: Para solicitar comentarios o asistencia sobre esta función, comunícate con [e-mail].

Para corregir los trabajos de traducción con errores RelationNotFound o AttributeNotFound, también puedes usar Gemini para resolver estos problemas:

1. Ve a la página Detalles de la traducción y abre la pestaña Mensajes de registro.
2. Haz clic en la consulta que tiene el mensaje RelationNotFound o AttributeNotFound en la columna Categoría.

3. Para ir al archivo y a la línea que contienen el error en la pestaña de código, haz clic en el

   mensaje de error.

4. En la columna Acción, haz clic en Corrección sugerida.

5. Selecciona una de las siguientes opciones, Aplicar o Aplicar y volver a ejecutar:

   • Para copiar el archivo de esquema generado del directorio de salida al directorio de entrada, haz clic en Aplicar.
   • Para copiar el archivo de esquema generado del directorio de salida al directorio de entrada y abrir una ventana de nueva ejecución, haz clic en Apply and rerun.

Cuota y límites

• Se aplican las cuotas de la API de BigQuery Migration.
• Cada proyecto puede tener como máximo 10 tareas de traducción activas.
• Si bien no existe un límite estricto en la cantidad total de archivos de origen y de metadatos, recomendamos mantener la cantidad de archivos por debajo de 1,000 para obtener un mejor rendimiento.

Precios

No se aplican cargos por usar el traductor de SQL por lotes. 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.

Herramientas de línea de comandos de flujos de trabajo de migración alternativos

También puedes enviar un trabajo de traducción por lotes con un archivo de configuración de traducción con Google Cloud CLI (gcloud bq migration-workflows) o con la herramienta de línea de comandos de bq.

En estos pasos, se da por sentado que ya subiste archivos de origen a un bucket de Cloud Storage.

Crea un archivo de configuración de traducción

Un archivo de configuración de traducción define la ruta de acceso a los archivos de origen, el destino de salida y los dialectos de origen y destino de tu traducción. Puedes escribir este archivo en YAML o JSON.

Nota: Un archivo de configuración de traducción no es lo mismo que un archivo YAML de configuración. Un archivo de configuración de traducción define el trabajo en sí. Un archivo YAML de configuración personaliza la forma en que el traductor transforma tu SQL.

En el siguiente ejemplo, se muestra un archivo YAML de configuración de traducción para una traducción de Teradata a BigQuery:

tasks:
  translation_task:
    type: Teradata2BigQuery_Translation
    translationDetails:
      sourceTargetMapping:
      - sourceSpec:
          baseUri: gs://bq-translations/input
        targetSpec:
          relativePath: output
      targetBaseUri: gs://bq-translations
      targetTypes:
      - sql
      sourceEnvironment:
        defaultDatabase: default_db
        schemaSearchPath:
        - foo

En el siguiente ejemplo, se muestra un archivo JSON de configuración de traducción para una traducción de Teradata a BigQuery:

{
  "tasks": {
    "translation_task": {
      "type": "Teradata2BigQuery_Translation",
      "translationDetails": {
        "sourceTargetMapping": [
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 1",
                "relativePath": "my_input_1"
              },
              "encoding": "UTF-8"
            }
          },
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 2",
                "relativePath": "my_input_2"
              },
              "encoding": "UTF-8"
            }
          }
        ],
        "targetReturnLiterals": [
          "sql/my_input_1",
          "sql/my_input_2"
        ]
      }
    }
  }
}

Envía y administra trabajos de traducción

Usa una de las siguientes herramientas de línea de comandos para enviar y administrar tus trabajos de traducción.

gcloud

Para crear un trabajo de traducción y ejecutar el flujo de trabajo, usa el siguiente comando:

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE

Para crear y ejecutar el flujo de trabajo, y regresar de inmediato con un vínculo al flujo de trabajo, agrega la marca --async:

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE --async

Para enumerar tus trabajos de traducción, usa el siguiente comando:

gcloud bq migration-workflows list --location=LOCATION

Para ver los detalles de un trabajo de traducción específico, usa el siguiente comando:

gcloud bq migration-workflows describe projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Reemplaza lo siguiente:

• LOCATION: Es la ubicación del proyecto de Google Cloud que ejecuta este trabajo de traducción.
• CONFIG_FILE: Es la ruta de acceso al archivo de configuración de traducción.
• PROJECT_ID: Es el ID del proyecto de Google Cloud que ejecuta este trabajo de traducción.
• WORKFLOW_ID: Es el ID del trabajo de traducción.

bq

Para ejecutar el trabajo de traducción, usa el siguiente comando:

bq mk --migration_workflow --location=LOCATION --config_file=CONFIG_FILE

Para enumerar todos tus trabajos de traducción, usa el siguiente comando:

bq ls --migration_workflow --location=LOCATION

Para ver los detalles de un trabajo de traducción específico, usa el siguiente comando:

bq show --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Para quitar un trabajo de traducción de la lista, usa el siguiente comando:

bq rm --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Reemplaza lo siguiente:

• LOCATION: Es la ubicación del proyecto de Google Cloud que ejecuta este trabajo de traducción.
• CONFIG_FILE: Es la ruta de acceso al archivo de configuración de traducción.
• PROJECT_ID: Es el ID del proyecto de Google Cloud que ejecuta este trabajo de traducción.
• WORKFLOW_ID: Es el ID del trabajo de traducción.

Recupera archivos de salida

Para descargar los archivos de salida después de que se complete el trabajo, usa gcloud storage cp como se describe en Recupera los archivos de salida. Para revisar el trabajo en la consola de Google Cloud , consulta Explora el resultado de la traducción.

¿Qué sigue?

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

• Descripción general de la migración
• Evaluación de la migración
• Descripción general de transferencia de datos y esquemas
• Canalizaciones de datos
• Traducción de SQL interactiva
• Seguridad y administración de los datos
• Herramienta de validación de datos