Cómo traducir 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.

Antes de comenzar

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

1. Asegúrate de tener todos los permisos necesarios.
2. Habilita la API de BigQuery Migration.
3. Recopila los archivos de origen que contienen las secuencias de comandos y las consultas de SQL que se deben traducir.
4. Sube los archivos de origen a Cloud Storage.

Permisos necesarios

Para obtener los permisos que necesitas para crear trabajos de traducción con la API de traducción, pídele a tu administrador que te otorgue el rol de IAM 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 crear trabajos de traducción con la API de traducción. 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 la API de traducción:

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

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

Habilita la API de BigQuery Migration

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.

Nota: Los proyectos creados después del 15 de febrero de 2022 tienen esta API habilitada automáticamente.

Sube archivos de entrada a Cloud Storage

Si deseas usar la consola de Google Cloud 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.

Tipos de tareas compatibles

La API de Translation puede traducir los siguientes dialectos de SQL a GoogleSQL:

• SQL de Amazon Redshift: Redshift2BigQuery_Translation
• Apache HiveQL y Beeline CLI: HiveQL2BigQuery_Translation
• SQL de Apache Spark: SparkSQL2BigQuery_Translation
• T-SQL de Azure Synapse: AzureSynapse2BigQuery_Translation
• Greenplum SQL: Greenplum2BigQuery_Translation
• SQL de IBM Db2: Db22BigQuery_Translation
• SQL de IBM Netezza y NZPLSQL: Netezza2BigQuery_Translation
• SQL de MySQL: MySQL2BigQuery_Translation
• SQL de Oracle, PL/SQL, Exadata: Oracle2BigQuery_Translation
• SQL de PostgreSQL: Postgresql2BigQuery_Translation
• SQL de Presto o Trino: Presto2BigQuery_Translation
• SQL de Snowflake: Snowflake2BigQuery_Translation
• SQLite: SQLite2BigQuery_Translation
• T-SQL de SQL Server: SQLServer2BigQuery_Translation
• Teradata y Teradata Vantage: Teradata2BigQuery_Translation
• SQL de Vertica: Vertica2BigQuery_Translation

Ubicaciones

La API de Translation está disponible en las siguientes ubicaciones de procesamiento:

	Descripción de la región	Nombre de la región	Detalles
Asia-Pacífico
	Tokio	asia-northeast1
	Bombay	asia-south1
	Singapur	asia-southeast1
	Sídney	australia-southeast1
Europa
	UE multirregión	eu
	Varsovia	europe-central2
	Finlandia	europe-north1	CO2 bajo
	Madrid	europe-southwest1	CO2 bajo
	Bélgica	europe-west1	CO2 bajo
	Londres	europe-west2	CO2 bajo
	Fráncfort	europe-west3	CO2 bajo
	Países Bajos	europe-west4	CO2 bajo
	Zúrich	europe-west6	CO2 bajo
	París	europe-west9	CO2 bajo
	Turín	europe-west12
América
	Quebec	northamerica-northeast1	CO2 bajo
	São Paulo	southamerica-east1	CO2 bajo
	EE.UU. multirregión	us
	Iowa	us-central1	CO2 bajo
	Carolina del Sur	us-east1
	Virginia del Norte	us-east4
	Columbus, Ohio	us-east5
	Dallas	us-south1	CO2 bajo
	Oregón	us-west1	CO2 bajo
	Los Ángeles	us-west2
	Salt Lake City	us-west3

Envía un trabajo de traducción

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

Una vez que se envíe 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): Los tipos de salida generados. Si no se especifica, se genera SQL.

  • sql (predeterminado): Son los archivos de consulta en SQL traducidos.
  • suggestion: Son 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 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/"
             }
          },
       }
    }
  }
}

Nota: La cadena "task_name" en este ejemplo es un identificador para la tarea de traducción y se puede establecer como el valor que prefieras.

Esta llamada mostrará 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. El trabajo envía resultados a Cloud Storage a medida que avanza. El trabajo state 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

Vista previa

Este producto o función está sujeto a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones específicas del Servicio. Los productos y las funciones que se encuentran en la fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Nota: La API de traducción puede llamar a Gemini mediante la integración de BigQuery con Vertex AI para generar sugerencias para tu consulta en SQL traducida según tu archivo YAML de configuración de IA.

En el siguiente ejemplo, se traducen las secuencias de comandos de Teradata SQL que se encuentran en el directorio gs://my_data_bucket/teradata/input/ de Cloud Storage y se almacenan los resultados en el directorio gs://my_data_bucket/teradata/output/ de Cloud Storage 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",
       }
    }
  }
}

Nota: Para generar sugerencias de IA, el directorio del código fuente de Cloud Storage debe contener al menos un archivo YAML de configuración con el sufijo .ai_config.yaml. Para aprender a escribir el archivo YAML de configuración para las sugerencias de IA, consulta Cómo crear un archivo YAML de configuración basado en Gemini.

Una vez que la tarea se ejecute de forma correcta, 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 translation_literals intercalado en la respuesta después de que se complete el flujo de trabajo.

Ejemplo de traducción interactiva

Para traducir la cadena SQL de 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",
    }
  }
}

Nota: La cadena "task_name" en este ejemplo es un identificador para la tarea de traducción y se puede establecer como el valor que prefieras.

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 de acceso relativas se debe incluir en target_return_literals.

Esta llamada mostrará 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. 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 mediante 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.