Traduce consultas en SQL con la API de Translation

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

Para obtener una lista de los dialectos de SQL compatibles con este traductor de SQL y una lista de las ubicaciones de procesamiento compatibles, consulta Dialectos de SQL compatibles y Ubicaciones.

Antes de comenzar

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

Habilitar traducciones

Habilita la API de BigQuery Migration requerida. 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:

  • Visualización y supervisión de trabajos de migración: Visualizador de MigrationWorkflow (roles/bigquerymigration.viewer)
  • Envío de trabajos de migración: Editor de MigrationWorkflow (roles/bigquerymigration.editor)
  • Acceso a los buckets de Cloud Storage para archivos de entrada y salida: 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 requeridos

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 otros roles predefinidos.

Sube archivos de entrada a Cloud Storage

Si deseas usar la Google Cloud consola o la API de BigQuery Migration para realizar un trabajo de traducción, debes subir los archivos de origen que contienen las consultas y 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 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.

Controla las funciones de SQL no compatibles con 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 BigQuery Migration (y la comunidad más amplia de BigQuery) proporcionan funciones definidas por el usuario (UDF) auxiliares que replican el comportamiento de estas funciones de dialecto de origen no compatibles.

Estas UDF suelen encontrarse 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().

Consideraciones importantes para los entornos de producción

Si bien bqutil ofrece acceso conveniente a estas UDF auxiliares para la traducción y las pruebas iniciales, no se recomienda la dependencia directa 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, podrías provocar 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: 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 requisitos de rendimiento específicos. Esto solo es posible si están dentro de tu propio proyecto.
  4. Seguridad y gobernanza: 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 auxiliares en tu proyecto

Para un uso de producción confiable y estable, debes implementar estas UDF auxiliares en tu propio proyecto y conjunto de datos. Esto te brinda 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. Esta guía proporciona las secuencias de comandos y los pasos necesarios para copiar las UDF en tu entorno.

Envía un trabajo de traducción

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

Una vez que se envía el trabajo, puedes emitir una consulta para obtener resultados.

Crea una traducción por lotes

Con el siguiente comando de curl, se crea un trabajo de traducción por lotes en el que los archivos de entrada y salida se almacenan en Cloud Storage. El campo source_target_mapping contiene una lista que asigna las entradas literal de origen a una ruta relativa opcional para el resultado de destino.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
            \"target_base_uri\": \"TARGET_BASE\",
            \"source_target_mapping\": {
              \"source_spec\": {
                  \"base_uri\": \"BASE\"
              }
            },
            \"target_types\": \"TARGET_TYPES\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Reemplaza lo siguiente:

  • TYPE: el tipo de tarea de la traducción, que determina el dialecto de origen y objetivo.
  • TARGET_BASE: Es el URI base para todos los resultados de traducción.
  • BASE: el URI base para todos los archivos leídos como fuentes de traducción.

  • TARGET_TYPES (opcional): Son los tipos de salida generados. Si no se especifica, se genera SQL.

    • sql (predeterminado): Son los archivos de consulta en SQL traducidos.
    • suggestion: Son las sugerencias generadas por IA.

    El resultado se almacena en una subcarpeta del directorio de salida. La subcarpeta se nombra según el valor de TARGET_TYPES.

  • TOKEN: Es el token para la autenticación. Para generar un token, usa el comando gcloud auth print-access-token o la zona de pruebas de OAuth 2.0 (usa el permiso https://www.googleapis.com/auth/cloud-platform).

  • PROJECT_ID: es el proyecto que procesará la traducción.

  • LOCATION: la ubicación en la que se procesa el trabajo.

El comando anterior muestra 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 de Teradata SQL en el 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 mostrará un mensaje que contiene el ID del flujo de trabajo creado en el "name" campo:

{
  "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. El trabajo envía resultados a Cloud Storage a medida que avanza. El state del trabajo cambia a COMPLETED después de que se generan todos los target_types solicitados. Si la tarea se realiza correctamente, puedes encontrar la consulta en 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 de Teradata SQL ubicadas en el directorio de Cloud Storage gs://my_data_bucket/teradata/input/ y se almacenan los resultados en el directorio de Cloud Storage gs://my_data_bucket/teradata/output/ 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 ejecuta correctamente, las sugerencias de IA se pueden encontrar en el directorio de Cloud Storage gs://my_data_bucket/teradata/output/suggestion.

Crea un trabajo de traducción interactivo con entradas y salidas literales de cadena

Con el siguiente comando de curl, se crea un trabajo de traducción con entradas y salidas literales de cadena. El campo source_target_mapping contiene una lista que asigna los directorios de origen a una ruta de acceso relativa opcional para el resultado de destino.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
        \"source_target_mapping\": {
            \"source_spec\": {
              \"literal\": {
              \"relative_path\": \"PATH\",
              \"literal_string\": \"STRING\"
              }
            }
        },
        \"target_return_literals\": \"TARGETS\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Reemplaza lo siguiente:

  • TYPE: el tipo de tarea de la traducción, que determina el dialecto de origen y objetivo.
  • PATH: el identificador de la entrada literal, similar a un nombre de archivo o una ruta de acceso.
  • STRING: Es la string de datos de entrada literales que se traducirán (por ejemplo, SQL).
  • TARGETS: Son los objetivos esperados que el usuario desea que se muestren directamente en la respuesta en el formato literal. Deben estar en el formato del URI de destino (por ejemplo, GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). Todo lo que no esté en esta lista no se mostrará en la respuesta. El directorio generado, GENERATED_DIR para las traducciones de SQL generales es sql/.
  • TOKEN: Es el token para la autenticación. Para generar un token, usa el comando gcloud auth print-access-token o la zona de pruebas de OAuth 2.0 (usa el permiso https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: es el proyecto que procesará la traducción.
  • LOCATION: la ubicación en la que se procesa el trabajo.

El comando anterior muestra 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 intercalado translation_literals en la respuesta después de que se complete el flujo de trabajo.

Ejemplo de traducción interactiva

Para traducir la cadena de Hive SQL 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 desees 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 cuyo caso cada una de sus rutas relativas debe incluirse en target_return_literals.

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

{
  "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. El trabajo se completa cuando "state" cambia a COMPLETED. Si la tarea se realiza correctamente, encontrará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"
}

Explora el resultado de la traducción

Después de ejecutar el trabajo de traducción, recupera los resultados mediante la especificación del 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

Reemplaza lo siguiente:

  • TOKEN: Es el token para la autenticación. Para generar un token, usa el comando gcloud auth print-access-token o la zona de pruebas de OAuth 2.0 (usa el permiso https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: es el proyecto que procesará la traducción.
  • LOCATION: la ubicación en la que se procesa el trabajo.
  • WORKFLOW_ID: el ID que se genera cuando creas 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 extremo para verificar el estado de tu flujo de trabajo.