Traduce consultas en SQL con la API de Translation

En este documento, se describe cómo usar la API de BigQuery Migration en BigQuery para traducir secuencias de comandos escritas en otros dialectos de SQL a consultas de GoogleSQL.

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, completa los siguientes pasos.

Elige un modo de traducción

La API de BigQuery Migration admite dos modos de traducción. Ambos modos usan el mismo método de API y se ejecutan como trabajos asíncronos. Los modos difieren en la forma en que proporcionas el SQL de origen y en la que recibes el SQL traducido:

  • Traducción por lotes: La API lee los archivos de origen de Cloud Storage y escribe los archivos traducidos y los informes en Cloud Storage. Usa la traducción por lotes para traducir muchos archivos a la vez, por ejemplo, cuando migras todo un código base.
  • Traducción interactiva: Pasas tu código SQL como literales de cadena en el cuerpo de la solicitud y lees el código SQL traducido de la respuesta del flujo de trabajo. No es necesario que almacenes tu código SQL ni el resultado de la traducción en Cloud Storage. Usa la traducción interactiva para traducir consultas individuales a pedido, por ejemplo, cuando traduzcas consultas desde una aplicación o una herramienta para desarrolladores.

Habilitar traducciones

Habilita la API de BigQuery Migration requerida. Para obtener más información, consulta Cómo habilitar 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)
  • Accede a los buckets y archivos de Cloud Storage: 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.

Sube archivos de entrada a Cloud Storage

En el caso de los trabajos de traducción por lotes, 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.

Funciones de SQL no compatibles

Si tus consultas de origen hacen referencia a funciones de SQL que no tienen equivalentes directos en GoogleSQL, puedes usar funciones definidas por el usuario (UDF) auxiliares. Para obtener más información, consulta Cómo controlar funciones de SQL no compatibles con UDF auxiliares.

Envía un trabajo de traducción

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

Después de enviar el trabajo, puedes consultar su estado.

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 los directorios de origen a una ruta de acceso 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/v2/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 traducidas.
    • suggestion: Sugerencias generadas por IA.

    El resultado se almacena en una subcarpeta del directorio de salida. El nombre de la subcarpeta se basa en el valor de TARGET_TYPES.

  • TOKEN: 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 SQL de Teradata en el directorio gs://my_data_bucket/teradata/input/ de Cloud Storage y almacenar los resultados en el directorio gs://my_data_bucket/teradata/output/ de Cloud Storage, puedes usar la siguiente consulta:

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
       }
    }
  }
}

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

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

Para obtener el estado actualizado del flujo de trabajo, ejecuta una consulta GET. A medida que avanza el trabajo, se envían los resultados a Cloud Storage. El trabajo state cambia a COMPLETED después de que se generan todos los target_types solicitados. Si la tarea se realiza correctamente, encontrarás 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 gs://my_data_bucket/teradata/output/suggestion de Cloud Storage.

Crea una traducción interactiva

Con el siguiente comando de curl, se crea un trabajo de traducción interactivo con entradas y salidas literales de cadena. 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\": {
        \"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/v2/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.

Después de crear el flujo de trabajo, verifica el estado del trabajo para ver los resultados.

Ejemplo de traducción interactiva

Para traducir la cadena de SQL de Apache Hive select 1 de forma interactiva, puedes usar la siguiente consulta:

"tasks": {
  string: {
    "type": "HiveQL2BigQuery_Translation",
    "translation_details": {
      "source_target_mapping": {
        "source_spec": {
          "literal": {
            "relative_path": "input_file",
            "literal_string": "select 1"
          }
        }
      },
      "target_return_literals": "sql/input_file",
    }
  }
}

Puedes usar cualquier relative_path que 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 devolverá un mensaje que contiene el ID del flujo de trabajo creado en el campo "name":

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

Para obtener el estado actualizado del flujo de trabajo, verifica el estado del trabajo. 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"
}

Verifica el estado del trabajo

Los trabajos de traducción se ejecutan de forma asíncrona. Después de enviar un flujo de trabajo, recupera su estado enviando una solicitud GET con el ID del flujo de trabajo:

curl \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer TOKEN" \
  -X GET https://bigquerymigration.googleapis.com/v2/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 ejecuta el trabajo de traducción.
  • LOCATION: la ubicación en la que se procesa el trabajo.
  • WORKFLOW_ID: Es el ID del flujo de trabajo que se devolvió cuando creaste el flujo de trabajo de traducción.

Estados del flujo de trabajo

La respuesta incluye un campo state que indica el estado actual del flujo de trabajo:

  • STATE_UNSPECIFIED: El estado del flujo de trabajo no está especificado.
  • RUNNING: El flujo de trabajo se está ejecutando de forma activa. Sondea el extremo periódicamente hasta que cambie el estado.
  • PAUSED: El flujo de trabajo está pausado.
  • COMPLETED: El flujo de trabajo finalizó correctamente. Ahora puedes recuperar los resultados.
  • FAILED: El flujo de trabajo encontró errores. Inspecciona los campos taskResult y reportLogMessages en la respuesta para obtener detalles del error.

Cuando el flujo de trabajo state llega a COMPLETED o FAILED, puedes detener la sondeo.

Recupera resultados

La forma en que recuperas los resultados depende de si enviaste una traducción por lotes o una traducción interactiva:

  • Traducciones por lotes: Los archivos traducidos, los informes de resumen y las sugerencias de IA se escriben en el directorio de destino de Cloud Storage que especificaste en target_base_uri. Puedes leer estos archivos directamente desde Cloud Storage con los comandos de almacenamiento de gcloud CLI, las bibliotecas cliente de Cloud Storage o la API de REST:

    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.

    Para obtener detalles sobre los archivos generados en el bucket de destino, consulta Explora el resultado de la traducción.

  • Traducciones interactivas: Para los trabajos configurados con entradas literales de cadena y target_return_literals, la búsqueda traducida se devuelve directamente en la respuesta del flujo de trabajo en el campo translatedLiterals:

    "taskResult": {
  "translationTaskResult": {
    "translatedLiterals": [
      {
        "relativePath": "sql/input_file",
        "literalString": "SELECT 1;\n"
      }
    ]
  }
}

    Extrae el campo literalString para cada entrada en translatedLiterals para obtener la búsqueda traducida.