Transforma traducciones de SQL con YAML

Los archivos YAML de configuración te permiten personalizar la forma en que BigQuery traduce el código SQL de tu base de datos de origen durante una migración. El Servicio de migración de BigQuery admite dos tipos de archivos YAML de configuración: archivos de configuración de traducción *.config.yaml que proporcionan reglas determinísticas al motor de traducción y archivos de configuración basados en Gemini *.ai_config.yaml que proporcionan reglas de lenguaje natural a Gemini.

Para personalizar una traducción de SQL con archivos YAML de configuración, haz lo siguiente:

  1. Crea archivos de configuración: Crea archivos de configuración de traducción de *.config.yaml deterministas, archivos de configuración basados en Gemini de *.ai_config.yaml o ambos tipos de archivos de configuración para combinar reglas estructurales con la personalización de Gemini.
  2. Proporciona los archivos a un trabajo de traducción: Envía los archivos de configuración cuando traduzcas una sola consulta o archivos SQL por lotes.
  3. Revisa los resultados de la traducción: Busca el SQL traducido y las sugerencias de Gemini en la respuesta cuando traduzcas una sola consulta o en Cloud Storage cuando traduzcas archivos SQL por lotes.

Tipos de archivos YAML de configuración

En la siguiente tabla, se comparan los dos tipos de archivos YAML de configuración:

Función Configuración de traducción (*.config.yaml) Configuración basada en Gemini (*.ai_config.yaml)
Cómo se aplican las reglas El motor de traducción aplica las reglas como reglas determinísticas en el SQL analizado, por lo que la misma entrada y configuración siempre producen el mismo resultado. Gemini aplica las reglas como instrucciones y ejemplos en lenguaje natural al texto de SQL. El resultado puede variar entre ejecuciones, por lo que siempre debes revisar y verificar las sugerencias antes de usarlas.
Qué se puede transformar El motor de traducción puede transformar cualquier objeto o parámetro de configuración que reconozca. Esto incluye los nombres y tipos de bases de datos, esquemas, tablas, columnas y funciones, las propiedades de las tablas, como la partición, el agrupamiento en clústeres y el vencimiento, los valores predeterminados de las sesiones, las firmas de UDF, las optimizaciones y el resultado de las sentencias, como el estilo de GROUP BY y SELECT *. Gemini puede cambiar cualquier transformación de SQL que puedas describir en lenguaje natural. Esto incluye el formato y los comentarios, el reemplazo de patrones, la reescritura de construcciones que el motor no traduce de la manera que deseas y la generación de una explicación de la traducción.
Requisitos
  • El SQL de entrada debe analizarse en el dialecto de origen.
  • Las reglas no pueden actuar sobre el texto en el SQL de entrada que el analizador no reconoce, como los marcadores de posición ${VAR} o la sintaxis de la plantilla.
  • Usa una regla SOURCE_SQL en los archivos *.ai_config.yaml o tu propio procesamiento previo para quitar ese texto primero.
  • Debes habilitar las sugerencias de IA de Gemini para el trabajo.
  • El trabajo debe ejecutarse en una ubicación de procesamiento admitida.
  • El uso de Gemini es gratuito hasta un límite.
Dónde aparece el resultado El resultado aparece en el SQL traducido, como en la respuesta de traducción o en el directorio de salida sql/ en Cloud Storage. El resultado aparece como sugerencias de Gemini independientes en la consola de Google Cloud , en campos de sugerencias o archivos de salida independientes en Google Cloud CLI y el servidor de MCP, o en directorios de salida *_suggestion/ independientes en Cloud Storage. Para obtener más información, consulta Dónde encontrar los resultados de la traducción.
Nombre del archivo Los nombres de archivo deben terminar con .config.yaml, por ejemplo, rename-tables.config.yaml. Los nombres de archivo deben terminar con .ai_config.yaml, por ejemplo, style-rules.ai_config.yaml.
El servicio de traducción ignora cualquier archivo YAML en la entrada que no termine con .config.yaml o .ai_config.yaml, y lo informa en el registro de traducción.
Reference Para obtener más información, consulta los Lineamientos para crear un archivo YAML de configuración y los Ejemplos de YAML de configuración en esta página. Para obtener más información, consulta Crea un archivo YAML de configuración basado en Gemini en esta página.

Cómo se aplican los dos tipos de reglas

Un trabajo de traducción aplica reglas de configuración en el siguiente orden:

  1. Gemini aplica reglas de SOURCE_SQL en archivos *.ai_config.yaml al SQL de entrada original para producir SQL de origen reescrito.
  2. El motor de traducción traduce el SQL de origen reescrito del paso anterior, o el SQL de entrada original si no se aplican reglas de SOURCE_SQL, y aplica las reglas de los archivos *.config.yaml para producir el SQL traducido.
  3. Gemini aplica las reglas de TARGET_SQL en los archivos de *.ai_config.yaml al SQL traducido del paso anterior para producir un SQL de destino reescrito. Si tus archivos *.ai_config.yaml incluyen reglas TRANSLATION_EXPLANATION, Gemini también genera una explicación de texto del SQL traducido.

Te recomendamos que uses reglas de *.config.yaml para realizar cambios estructurales repetibles, como cambiar el nombre de los objetos, asignar tipos y configurar la partición. Te recomendamos que uses reglas *.ai_config.yaml para los cambios que el motor no puede expresar o para limpiar la entrada que no se analiza. Puedes usar ambos tipos de archivos de configuración en el mismo trabajo.

Proporciona archivos de configuración a una traducción

La consola de Google Cloud , gcloud CLI, la API de BigQuery Migration y el servidor de MCP del Servicio de migración de BigQuery admiten el uso de varios archivos de configuración en un solo trabajo de traducción. Para obtener más información, consulta Aplica varias opciones de configuración de YAML.

Para proporcionar archivos de configuración a un trabajo de traducción, selecciona una de las siguientes opciones:

Console

  • Para usar archivos de configuración cuando traduzcas una sola consulta, especifícalos en la configuración de traducción del traductor interactivo:
  • Para usar archivos de configuración mientras traduces archivos SQL por lotes, haz lo siguiente:

gcloud

  • Cuando uses el comando gcloud alpha bq migration translate, usa la marca --translation-config-files para especificar archivos *.config.yaml o *.ai_config.yaml.
  • Cuando uses el comando gcloud alpha bq migration translate-batch, haz lo siguiente:
    • *.config.yaml: Incluye los archivos en el directorio de entrada que pasas a --source-gcs-uris o --source-local-dirs, o pasa archivos individuales con la marca --source-gcs-files o --source-local-files.
    • *.ai_config.yaml: Incluye los archivos en el directorio de entrada que pasas a --source-gcs-uris o --source-local-dirs, o pasa archivos individuales con la marca --source-gcs-files o --source-local-files, y agrega la marca --enable-ai-suggestion.

API

En la API de BigQuery Migration, ya sea que traduzcas una sola consulta o archivos SQL por lotes, haz lo siguiente:

  • *.config.yaml: Sube los archivos en la ruta de acceso de entrada en source_spec.base_uri, pasa una entrada gcs_file_path en source_spec cuando el archivo no esté en base_uri o pasa una entrada literal intercalada en source_spec.
  • *.ai_config.yaml: Proporciona los archivos en source_spec en base_uri, como una entrada gcs_file_path cuando el archivo no está en base_uri, o como una entrada literal intercalada, y, además, incluye "suggestion" en target_types, por ejemplo, "target_types": ["sql", "suggestion"].

MCP

En el servidor de MCP del Servicio de migración de BigQuery, haz lo siguiente:

  • Para traducir una sola consulta (translate_query), haz lo siguiente:
    • *.config.yaml: Pasa entradas translationConfigs intercaladas.
    • *.ai_config.yaml: Pasa entradas aiSuggestionConfigs intercaladas.
  • Para traducir archivos SQL por lotes (translate_batch_queries), haz lo siguiente:
    • *.config.yaml: Sube los archivos en sourceBaseUri o inclúyelos en configurationFilePaths cuando no estén en sourceBaseUri.
    • *.ai_config.yaml: Sube los archivos en sourceBaseUri o enuméralos en configurationFilePaths cuando no estén en sourceBaseUri y establece enableAiSuggestions en true.

Dónde encontrar los resultados de la traducción

Según los archivos de configuración que proporciones, un trabajo de traducción puede producir los siguientes resultados:

  • Es el SQL traducido del motor de traducción después de que aplica cualquier regla en los archivos *.config.yaml.
  • Es el SQL de origen reescrito de Gemini después de que aplica las reglas de SOURCE_SQL en los archivos *.ai_config.yaml.
  • Es el SQL de destino reescrito de Gemini después de que aplica las reglas de TARGET_SQL en los archivos *.ai_config.yaml.
  • Una explicación de la traducción de Gemini cuando tus archivos *.ai_config.yaml incluyen reglas TRANSLATION_EXPLANATION o cuando solicitas una explicación a pedido.

Dónde encuentras estos resultados depende de cómo ejecutes la traducción:

  • Para encontrar resultados cuando traduces una sola consulta en la consola deGoogle Cloud o gcloud CLI, consulta Explora el resultado de la traducción en la guía del traductor de SQL interactivo.
  • Para encontrar resultados cuando traduces archivos SQL por lotes en Cloud Storage o los revisas en la consola de Google Cloud , consulta Explora el resultado de la traducción en la guía del traductor de SQL por lotes.
  • Para encontrar resultados cuando usas la API de BigQuery Migration, consulta Recupera resultados en la guía de la API de BigQuery Migration. Para las traducciones de una sola consulta, agrega las rutas de acceso de salida que desees (sql/<var>PATH</var>, source_sql_query_customization_suggestion/<var>PATH</var>, target_sql_query_customization_suggestion/<var>PATH</var> o translation_explanation_suggestion/<var>PATH</var>) a target_return_literals para recibirlas en translatedLiterals.
  • Para encontrar resultados cuando usas el servidor de MCP del Servicio de migración de BigQuery, consulta Usa el servidor de MCP del Servicio de migración de BigQuery. Las herramientas translate_query y get_translation devuelven translatedQuery, sourceSqlSuggestion y targetSqlSuggestion, y la herramienta explain_translation devuelve una explicación de la traducción.

Requisitos de los archivos de traducción de *.config.yaml

Un archivo *.config.yaml de traducción debe cumplir con los siguientes requisitos para ser compatible con el Servicio de migración de BigQuery:

  • Cuando subes archivos *.config.yaml en la ruta de acceso de entrada de Cloud Storage para un trabajo de traducción por lotes, los archivos de configuración que se colocan en cualquier lugar de la ruta de acceso de entrada se aplican a todo el trabajo. No es necesario que estén en el nivel raíz ni que se copien en cada subdirectorio. Si deseas obtener información para crear buckets y subir archivos a Cloud Storage, consulta Crea buckets y Sube objetos desde un sistema de archivos.
  • El tamaño de un solo archivo *.config.yaml no debe superar 1 MB.
  • El tamaño total de todos los archivos *.config.yaml que se usan en un solo trabajo de traducción de SQL no debe exceder los 4 MB.
  • Si usas la sintaxis regex para la coincidencia de nombres, usa RE2/J.
  • Todos los nombres de los archivos de configuración de traducción deben terminar con .config.yaml, por ejemplo, change-case.config.yaml. config.yaml por sí solo no es un nombre válido para el archivo de configuración.

Lineamientos para crear un archivo YAML de configuración

En esta sección, se proporcionan algunos lineamientos generales para crear un archivo YAML de configuración:

Cada archivo *.config.yaml debe incluir un encabezado type de nivel superior que especifique la categoría de las reglas de configuración del archivo:

  • object_rewriter: Reescribe las propiedades de relation, como temporary, ephemeral, partitionLifetime, external, description, partition y clustering, y los tipos de datos de attribute (type).
  • experimental_object_rewriter: Reescribe los nombres de los objetos de salida con outputName en global, database, schema, relation, attribute, function, index, sequence, variable y projection, y convierte los tipos de datos de forma global con global.typeConvert. Para obtener más información, consulta Asignación de nombres de salida y Conversión de tipos globales.
  • environment: Establece los valores predeterminados a nivel de sesión en session, como defaultDatabase, schemaSearchPath y dateFormat.
  • metadata: Declara firmas de función definida por el usuario (UDF) (udfs) y quita prefijos, sufijos o patrones de expresiones regulares de nombres de entrada durante la búsqueda de metadatos (nameAlias).
  • statement_rewriter: Personaliza el resultado de la sentencia, como la expansión de SELECT *, el formato de GROUP BY y ORDER BY (select), y el rigor de la precisión decimal o de cadena (common).
  • input_formats: Especifica la codificación de caracteres de los archivos SQL de entrada (formats).
  • optimizer: habilita, inhabilita o configura optimizaciones de consultas opcionales (transformations).

En el siguiente ejemplo, se usa el tipo experimental_object_rewriter para convertir todos los nombres de los objetos de salida a mayúsculas:

type: experimental_object_rewriter
global:
  outputName:
    all:
      case: UPPERCASE

Selección de entidad

Para llevar a cabo transformaciones específicas de la entidad, especifica la entidad de SQL de origen en el archivo de configuración. Todas las propiedades match son opcionales. Usa solo las propiedades match necesarias para una transformación. El campo match se compara con los nombres de los objetos de origen después de resolver cualquier defaultDatabase y schemaSearchPath configurados, excepto en las reglas outputName cuando también se configura global.outputName. Para obtener más información, consulta Asignación de nombres de salida. En la siguiente YAML de configuración, se exponen las propiedades que deben coincidir para elegir entidades específicas:

match:
  database: <literal_name>
  schema: <literal_name>
  relation: <literal_name>
  attribute: <literal_name>
  databaseRegex: <regex>
  schemaRegex: <regex>
  relationRegex: <regex>
  attributeRegex: <regex>

Descripción de cada propiedad match:

  • database o db: Coincide con el nombre de la base de datos de origen, que corresponde al componente project_id en BigQuery.
  • schema: Coincide con el nombre del esquema de origen, que corresponde al componente dataset en BigQuery.
  • relation: coincide con el nombre de la tabla o vista de origen.
  • attribute: coincide con el nombre de la columna de origen. Esta propiedad solo es válida para la selección de attribute.
  • databaseRegex o dbRegex: Coincide con todo el nombre de database con una expresión regular que no distingue mayúsculas de minúsculas.
  • schemaRegex: Coincide con todo el nombre de schema con una expresión regular que no distingue mayúsculas de minúsculas.
  • relationRegex: Coincide con todo el nombre de relation con una expresión regular que no distingue mayúsculas de minúsculas.
  • attributeRegex: Coincide con todo el nombre de attribute con una expresión regular que no distingue mayúsculas de minúsculas. Esta propiedad solo es válida para la selección de attribute.

Por ejemplo, el siguiente YAML de configuración especifica las propiedades match con el objetivo de seleccionar la tabla testdb.acme.employee para una transformación de tabla temporal.

type: object_rewriter
relation:
-
  match:
    database: testdb
    schema: acme
    relation: employee
  temporary: true

Puedes usar las propiedades databaseRegex, schemaRegex, relationRegex y attributeRegex para especificar expresiones regulares con el objetivo de seleccionar un subconjunto de entidades. En el siguiente ejemplo, se cambian todas las relaciones del esquema tmp_schema en testdb a temporal, siempre que su nombre comience con tmp_:

type: object_rewriter
relation:
-
  match:
    schema: tmp_schema
    relationRegex: "tmp_.*"
  temporary: true

Las propiedades literales y regex coinciden de manera que no distingue mayúsculas de minúsculas. Puedes aplicar la coincidencia que distingue mayúsculas de minúsculas mediante un regex con una marca i inhabilitada, como se ve en el siguiente ejemplo:

match:
  relationRegex: "(?-i:<actual_regex>)"

También puedes especificar entidades completamente calificadas mediante una sintaxis de string corta equivalente. Una sintaxis de string corta espera exactamente 3 segmentos de nombre (para la selección de relaciones) o 4 segmentos de nombre (para la selección de atributos) delimitados por puntos, como el ejemplo testdb.acme.employee. A continuación, los segmentos se interpretan de forma interna como si se hubieran pasado como database, schema, relation y attribute, respectivamente. Esto significa que los nombres coinciden de manera literal, por lo que las expresiones regulares no están permitidas en la sintaxis corta. En el siguiente ejemplo, se muestra el uso de la sintaxis de string corta para especificar una entidad completamente calificada en un archivo YAML de configuración:

type: object_rewriter
relation:
-
  match: "testdb.acme.employee"
  temporary: true

Si una tabla contiene un punto en el nombre, no puedes especificar el nombre con una sintaxis corta. En este caso, debes usar una coincidencia de objeto. En el siguiente ejemplo, se cambia la tabla testdb.acme.stg.employee a temporal:

type: object_rewriter
relation:
-
  match:
    database: testdb
    schema: acme
    relation: stg.employee
  temporary: true

Un archivo YAML de configuración también acepta key como un alias para match. Tanto key como match admiten subcampos de componentes de nombre explícitos, así como la sintaxis de cadena corta "database.schema.relation" o "database.schema.relation.attribute" delimitada por puntos. Por convención, key suele usarse con la sintaxis de cadena corta y match se usa con subcampos explícitos.

Base de datos predeterminada

Algunos dialectos de SQL de entrada, en particular Teradata, no admiten un nombre de base de datos en identificadores calificados (schema.table). En este caso, usa un objeto match y omite la propiedad database. Como alternativa, configura defaultDatabase, por ejemplo, en type: environment, para que puedas hacer coincidir esa base de datos predeterminada en las reglas de match de objetos o cadenas cortas.

Tipos de atributos de destino admitidos

Puedes usar el archivo YAML de configuración para realizar transformaciones de tipo de atributo, en las que transformas el tipo de datos de una columna del tipo de origen a un tipo de destino. El archivo YAML de configuración admite los siguientes tipos de destino:

  • BOOLEAN
  • TINYINT
  • SMALLINT
  • INTEGER
  • BIGINT
  • FLOAT
  • DOUBLE
  • NUMERIC (admite precisión y escala opcionales, como NUMERIC(18, 2))
  • TIME
  • TIMETZ
  • DATE
  • DATETIME
  • TIMESTAMP
  • TIMESTAMPTZ
  • CHAR (admite precisión opcional, como CHAR(42))
  • VARCHAR (admite precisión opcional, como VARCHAR(42))

Ejemplos de YAML de configuración

En esta sección, se proporcionan ejemplos a fin de crear varios archivos YAML de configuración para usar con tus traducciones de SQL. En cada ejemplo, se describe la sintaxis YAML para transformar tu traducción de SQL de maneras específicas, junto con una descripción breve. En cada ejemplo, también se proporciona el contenido de un archivo teradata-input.sql o hive-input.sql y del archivo bq-output.sql para que puedas comparar los efectos de un YAML de configuración en la traducción de una consulta en SQL de BigQuery.

En los siguientes ejemplos, se usa Teradata o Apache Hive como el dialecto de entrada de SQL y BigQuery SQL como el dialecto de salida.

Cambia mayúsculas y minúsculas del nombre del objeto

En el siguiente YAML de configuración, se cambia el uso de mayúsculas o minúsculas de los nombres de objetos SQL a UPPERCASE o LOWERCASE. Puedes establecer case en objetos all o anularlo para tipos de objetos específicos (database, schema, relation, attribute, function, sequence, index, variable o projection):

type: experimental_object_rewriter
global:
  outputName:
    all:
      case: UPPERCASE
    database:
      case: LOWERCASE
    attribute:
      case: LOWERCASE

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      create table TESTDB.testschema.x(A int);
      select * from TESTDB.testschema.x;
    
bq-output.sql
      CREATE TABLE testdb.TESTSCHEMA.X
      (
        a INT64
      )
      ;
      SELECT
          X.*
        FROM
          testdb.TESTSCHEMA.X
      ;
    

Haz que la tabla sea temporal

En el siguiente YAML de configuración, se cambia una tabla normal a una tabla temporal:

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    temporary: true

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
    create table testdb.testschema.x(a int);
    
bq-output.sql
    CREATE TEMPORARY TABLE x
    (
      a INT64
    )
    ;
    

Haz que la tabla sea efímera

En el siguiente YAML de configuración, se cambia una tabla normal a una tabla efímera con un vencimiento de 60 segundos.

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    ephemeral:
      expireAfterSeconds: 60

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
    create table testdb.testschema.x(a int);
    
bq-output.sql
    CREATE TABLE testdb.testschema.x
    (
      a INT64
    )
    OPTIONS(
      expiration_timestamp=timestamp_add(current_timestamp(), interval 60 SECOND)
    );
    

Establece el vencimiento de la partición

En el siguiente YAML de configuración, se cambia el vencimiento de una tabla particionada a 1 día:

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    partitionLifetime:
      expireAfterSeconds: 86400

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
    create table testdb.testschema.x(a date, b int) partition by (a);
    
bq-output.sql
    CREATE TABLE testdb.testschema.x
    (
      a DATE,
      b INT64
    )
    PARTITION BY a
    OPTIONS(
      partition_expiration_days=1
    );
    

Cambia la ubicación o el formato externos de una tabla

En el siguiente YAML de configuración, se cambia la ubicación externa y el formato de una tabla:

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    external:
      locations: "gs://path/to/department/files"
      format: ORC

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
    create table testdb.testschema.x(a int);
    
bq-output.sql
    CREATE EXTERNAL TABLE testdb.testschema.x
    (
      a INT64
    )
    OPTIONS(
      format='ORC',
      uris=[
        'gs://path/to/department/files'
      ]
    );
    

Configura o cambia la descripción de la tabla

En el siguiente YAML de configuración, se establece la descripción de una tabla:

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    description:
      text: "Example description."

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
    create table testdb.testschema.x(a int);
    
bq-output.sql
    CREATE TABLE testdb.testschema.x
    (
      a INT64
    )
    OPTIONS(
      description='Example description.'
    );
    

Configura o cambia la partición de la tabla

En el siguiente YAML de configuración, se cambia el esquema de partición de una tabla con add, remove o set, en el que set reemplaza cualquier columna de partición existente:

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    partition:
      simple:
        add: [a]
  -
    match: "testdb.testschema.y"
    partition:
      simple:
        remove: [a]

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
    create table testdb.testschema.x(a date, b int);
    create table testdb.testschema.y(a date, b int) partition by (a);
    
bq-output.sql
    CREATE TABLE testdb.testschema.x
    (
      a DATE,
      b INT64
    )
    PARTITION BY a;
    CREATE TABLE testdb.testschema.y
    (
      a DATE,
      b INT64
    )
    ;
    

En el siguiente YAML de configuración, se cambia el esquema de partición de una tabla para que se particione por bucket de rango:

type: object_rewriter
relation:
-
  match: "testdb.testschema.mytable"
  partition:
    range_bucket:
      column: "id"
      start: 0
      end: 100
      step: 10
      options:
        require_partition_filter: "TRUE"

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

snowflake-input.sql
      create table testdb.testschema.mytable (
        date timestamp_ntz,
        id number,
        content variant
      );
    
bq-output.sql
      CREATE TABLE TESTDB.TESTSCHEMA.MYTABLE
      (
        DATE DATETIME,
        ID INT64,
        CONTENT JSON
      )
      PARTITION BY RANGE_BUCKET(ID, generate_array(0, 100, 10))
      OPTIONS(
        require_partition_filter=TRUE
      );
    

Configura o cambia el agrupamiento en clústeres de la tabla

En el siguiente YAML de configuración, se cambia el esquema de agrupamiento en clústeres de una tabla con add, remove o set, en el que set reemplaza cualquier columna de agrupamiento en clústeres existente:

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    clustering:
      add: [a]
  -
    match: "testdb.testschema.y"
    clustering:
      remove: [b]

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

hive-input.sql
    create table testdb.testschema.x(a int, b int);
    create table testdb.testschema.y(a int, b int)
      clustered by (b) into 16 buckets;
    
bq-output.sql
    CREATE TABLE testdb.testschema.x
    (
      a INT64,
      b INT64
    )
    CLUSTER BY a;
    CREATE TABLE testdb.testschema.y
    (
      a INT64,
      b INT64
    )
    ;
    

Cambia el tipo de un atributo de columna

En el siguiente YAML de configuración, se cambia el tipo de datos para un atributo de una columna:

type: object_rewriter
attribute:
  -
    match:
      database: testdb
      schema: testschema
      attributeRegex: "a+"
    type:
      target: NUMERIC(10,2)

Puedes transformar el tipo de datos de origen a cualquiera de los tipos de atributos de destino admitidos.

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
    create table testdb.testschema.x(a int, b int, aa int);
    
bq-output.sql
    CREATE TABLE testdb.testschema.x
    (
      a NUMERIC(31, 2),
      b INT64,
      aa NUMERIC(31, 2)
    )
    ;
    

Cuando no existe una conversión directa entre los tipos de origen y de destino, por ejemplo, cuando se convierte una columna INT que almacena fechas YYYYMMDD en una columna DATE, proporciona expresiones de conversión sourceToTarget y targetToSource de GoogleSQL. Usa ? como marcador de posición para el valor de la columna o expresión. Por ejemplo:

type: object_rewriter
attribute:
  -
    match: "testdb.acme.employee.jd"
    type:
      target: DATE
      sourceToTarget: "parse_date('%Y%m%d', cast(? as string))"
      targetToSource: "cast(format_date('%Y%m%d', cast(? as date)) as int64)"

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
    create table testdb.acme.employee(eid int, jd int);
    insert into testdb.acme.employee select 42, 20011213;
    select eid, jd from testdb.acme.employee e where jd > 20010101;
    
bq-output.sql
    CREATE TABLE testdb.acme.employee
    (
      eid INT64,
      jd DATE
    )
    ;
    INSERT INTO testdb.acme.employee
      SELECT
          42,
          parse_date('%Y%m%d', CAST(20011213 as STRING))
    ;
    SELECT
        eid,
        CAST(format_date('%Y%m%d', jd) as INT64) AS jd
      FROM
        testdb.acme.employee AS e
      WHERE CAST(format_date('%Y%m%d', jd) as INT64) > 20010101
    ;
    

Agrega una conexión al data lake externo

En la siguiente configuración de YAML, se marca la tabla de origen como una tabla externa que apunta a los datos almacenados en un data lake externo, especificado por una conexión de data lake.

type: object_rewriter
relation:
-
  match: "testdb.testschema.x"
  external:
    connection_id: "connection_test"

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

hive-input.sql
    CREATE TABLE testdb.testschema.x
    (
      a VARCHAR(150),
      b INT
    );
    
bq-output.sql
    CREATE EXTERNAL TABLE testdb.testschema.x
    (
      a STRING,
      b INT64
    )
    WITH CONNECTION `connection_test`
    OPTIONS(
    );
    

Cambia la codificación de caracteres de un archivo de entrada

De forma predeterminada, el servicio de migración de BigQuery intenta detectar automáticamente la codificación de caracteres de los archivos de entrada. En los casos en los que el servicio de migración de BigQuery podría identificar de forma incorrecta la codificación de un archivo, puedes usar el YAML de configuración para especificar la codificación de caracteres de forma explícita.

El siguiente YAML de configuración especifica la codificación explícita de caracteres del archivo de entrada como ISO-8859-1. Puedes hacer coincidir los archivos de entrada con una ruta de acceso exacta (path), un patrón de glob (pathGlob) o una expresión regular (pathRegex):

type: input_formats
formats:
- source:
    pathGlob: "*.sql"
  contents:
    raw:
      charset: iso-8859-1

Conversión de tipo global

El siguiente YAML de configuración cambia un tipo de datos a otro en todas las secuencias de comandos y especifica un tipo de datos de origen para evitar en la secuencia de comandos transpilada. Esto es diferente de la configuración Cambiar el tipo de atributo de la columna, en la que solo se cambia el tipo de datos para un solo atributo.

El servicio de traducción admite las siguientes conversiones de tipo de datos:

  • De DATETIME a TIMESTAMP
  • De TIMESTAMP a DATETIME (acepta una zona horaria opcional)
  • De TIMESTAMP WITH TIME ZONE (timestamptz) a DATETIME (acepta una zona horaria opcional)
  • De CHAR a VARCHAR (acepta precisionAction y comparisonBehavior opcionales)
  • De VARCHAR a VARCHAR (acepta precisionAction y comparisonBehavior opcionales)

En el siguiente ejemplo, el YAML de configuración convierte TIMESTAMP en DATETIME.

type: experimental_object_rewriter
global:
  typeConvert:
    timestamp: DATETIME

Convierte los tipos CHAR y VARCHAR

En dialectos como Teradata, los valores CHAR(N) se rellenan a la derecha con espacios, y las escrituras de cadenas se truncan a la longitud de columna declarada. Las comparaciones de cadenas no distinguen mayúsculas de minúsculas (NOT CASESPECIFIC) de forma predeterminada y se ignoran los espacios finales. De forma predeterminada, el motor de traducción emula estas semánticas en BigQuery. Agrega wrappers de padding derecho (CONCAT) y truncamiento (SUBSTR) en conversiones y escrituras, wrappers UPPER y RTRIM en comparaciones y wrappers UPPER en claves GROUP BY.

Puedes configurar los campos char y varchar en global.typeConvert con las siguientes propiedades:

  • target: Se debe configurar como VARCHAR. Configurar target: VARCHAR en char quita el padding derecho de CHAR (CONCAT) incluso cuando precisionAction es PRESERVE.
  • precisionAction: Controla la precisión de la longitud de los caracteres y los wrappers de truncamiento de SUBSTR:
    • PRESERVE (predeterminado): Conserva la precisión de la longitud de caracteres en las expresiones y emite wrappers de truncamiento SUBSTR cuando se convierte o se inserta en columnas CHAR(N) o VARCHAR(N). Para emitir también longitudes de columna STRING(N) en DDL de CREATE TABLE, consulta Configura el rigor de la precisión de las cadenas.
    • DROP: Descarta la precisión de la longitud de caracteres en las expresiones y omite los wrappers de truncamiento de SUBSTR.
  • comparisonBehavior: Controla los wrappers RTRIM y UPPER para las comparaciones y las claves GROUP BY. Si estableces un valor que no sea STRICT en char o varchar, se aplicará a ambos tipos, por lo que debes establecer el mismo valor en ambas claves cuando configures ambas:
    • STRICT (predeterminado): Emula el relleno de espacio final (RTRIM) y la intercalación que no distingue mayúsculas de minúsculas (UPPER).
    • PADDING_AWARE: emula solo el padding de espacio final (RTRIM) y omite UPPER.
    • CASE_AWARE: emula solo la intercalación que no distingue mayúsculas de minúsculas (UPPER) y omite RTRIM.
    • NONE: Omite los wrappers RTRIM y UPPER, por lo que el resultado usa comparaciones directas y expresiones GROUP BY.

En el siguiente YAML de configuración, se convierte CHAR en VARCHAR y se quitan los wrappers de truncamiento (SUBSTR), espacio final (RTRIM) y no distingue mayúsculas de minúsculas (UPPER) para las columnas CHAR y VARCHAR:

type: experimental_object_rewriter
global:
  typeConvert:
    char:
      target: VARCHAR
      precisionAction: DROP
      comparisonBehavior: NONE
    varchar:
      target: VARCHAR
      precisionAction: DROP
      comparisonBehavior: NONE

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      create table r(a char(10), b varchar(20));
      select cast(b as char(5)) from r where a = b group by 1;
    
bq-output.sql
      CREATE TABLE r
      (
        a STRING,
        b STRING
      )
      ;
      SELECT
          b
        FROM
          r
        WHERE a = b
        GROUP BY 1
      ;
    

Configura la zona horaria predeterminada

Los dialectos de la base de datos tienen diferentes semánticas y nombres para los distintos tipos de datos relacionados con la fecha y la hora. El servicio de traducción estandariza la siguiente terminología en su configuración de YAML, independientemente del nombre del tipo de datos del dialecto de entrada:

  • Un datetime es una combinación de Y-M-D H:M:S que no se fija a ninguna zona horaria en particular. datetime representa una hora de reloj y no un instante en particular.
  • Un timestamp representa un instante de tiempo particular o absoluto y, como tal, se fija de forma implícita en una zona horaria particular, que puede ser un parámetro de configuración a nivel de la sesión o de la base de datos.
  • Un timestamptz representa un instante en particular, como un timestamp, pero, a diferencia de un timestamp, incluye una diferencia de zona horaria específica. Si bien representan el mismo instante, 2019-06-01 12:00:00+4 y 2019-06-01 06:00:00-2 se consideran valores timestamptz diferentes.

En dialectos como Teradata, las funciones relacionadas con la fecha y hora, como current_date, current_time o current_timestamp, devuelven marcas de tiempo basadas en un parámetro de zona horaria de sesión configurado de forma implícita. Por otro lado, BigQuery siempre devuelve marcas de tiempo en UTC. Para garantizar un comportamiento coherente entre los dos dialectos, es posible que sea necesario configurar una zona horaria según corresponda.

Te recomendamos que especifiques la zona horaria predeterminada para la traducción si tu base de datos de origen tiene una predeterminada que no es UTC. Esto garantizará el comportamiento correcto de la consulta traducida, ya que se conservará la zona horaria.

En el siguiente ejemplo, el YAML de configuración convierte un tipo de datos TIMESTAMP y TIMESTAMPTZ en DATETIME, con la zona horaria de destino establecida en Europe/Paris.

Para conocer los valores de zona horaria de cadena válidos, consulta Zonas horarias.

type: experimental_object_rewriter
global:
  typeConvert:
    timestamp:
      target: DATETIME
      timezone: Europe/Paris
    timestamptz:
      target: DATETIME
      timezone: Europe/Paris

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

snowflake-input.sql
      create table x(c_timestamp timestamp_ltz, c_timestamptz timestamp_tz, c_datetime timestamp_ntz);

      select c_timestamp from x where c_timestamp > current_timestamp(0);
      select c_timestamptz from x where c_timestamptz > cast(current_timestamp(0) as timestamp_tz);
      select c_datetime from x where c_datetime > cast(current_timestamp(0) as timestamp_ntz);
    
bq-output.sql
      CREATE TABLE X
      (
        C_TIMESTAMP DATETIME,
        C_TIMESTAMPTZ DATETIME,
        C_DATETIME DATETIME
      )
      ;
      SELECT
          C_TIMESTAMP
        FROM
          X
        WHERE C_TIMESTAMP > datetime(current_timestamp(), 'Europe/Paris')
      ;
      SELECT
          X.C_TIMESTAMPTZ
        FROM
          X
        WHERE X.C_TIMESTAMPTZ > datetime(current_timestamp(), 'Europe/Paris')
      ;
      SELECT
          C_DATETIME
        FROM
          X
        WHERE C_DATETIME > datetime(current_timestamp(), 'Europe/Paris')
      ;
    

En el siguiente ejemplo, el YAML de configuración convierte un tipo de datos DATETIME en TIMESTAMP.

De forma predeterminada, TIMESTAMPTZ se convierte en TIMESTAMP sin necesidad de configuración.

type: experimental_object_rewriter
global:
  typeConvert:
    datetime:
      target: TIMESTAMP

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

snowflake-input.sql
      create table x(c_timestamp timestamp_ltz, c_timestamptz timestamp_tz, c_datetime timestamp_ntz);

      select c_timestamp from x where c_timestamp > current_timestamp(0);
      select c_timestamptz from x where c_timestamptz > cast(current_timestamp(0) as timestamp_tz);
      select c_datetime from x where c_datetime > cast(current_timestamp(0) as timestamp_ntz);
    
bq-output.sql
      CREATE TABLE X
      (
        C_TIMESTAMP TIMESTAMP,
        C_TIMESTAMPTZ TIMESTAMP,
        C_DATETIME TIMESTAMP
      )
      ;
      SELECT
          C_TIMESTAMP
        FROM
          X
        WHERE C_TIMESTAMP > current_timestamp()
      ;
      SELECT
          C_TIMESTAMPTZ
        FROM
          X
        WHERE C_TIMESTAMPTZ > current_timestamp()
      ;
      SELECT
          X.C_DATETIME
        FROM
          X
        WHERE X.C_DATETIME > current_timestamp()
      ;
    

Elige la modificación de una sentencia

En el siguiente YAML de configuración, se cambia la proyección en estrella, las cláusulas GROUP BY y ORDER BY en las sentenciasSELECT.

El campo select.starProjection admite los siguientes valores:

  • ALLOW: emite SELECT * cuando la consulta de origen usa SELECT * o enumera todas las columnas de la tabla en orden.
  • PRESERVE (predeterminado): Emite SELECT * solo cuando la consulta de origen usa SELECT *.
  • EXPAND: Expande SELECT * en referencias de columnas individuales cuando los metadatos de la tabla están disponibles.

Los campos select.groupBy y select.orderBy admiten los siguientes valores:

  • EXPRESSION: Aplica formato a los elementos GROUP BY o ORDER BY como expresiones completas.
  • ALIAS: Aplica formato a los elementos GROUP BY o ORDER BY con alias de columna SELECT cuando están disponibles.
  • INDEX: Aplica formato a los elementos GROUP BY o ORDER BY con posiciones de columna basadas en 1, como GROUP BY 1.

En el siguiente ejemplo, el YAML de configuración configura la proyección en estrella en EXPAND.

type: statement_rewriter
select:
  starProjection: EXPAND

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      create table x(a int, b TIMESTAMP);
      select * from x;
    
bq-output.sql
      CREATE TABLE x
      (
        a INT64,
        b TIMESTAMP
      )
      ;
      SELECT
          x.a,
          x.b
        FROM
          x
      ;
    

Especificación de UDF

En la mayoría de los casos, el traductor de SQL de BigQuery puede analizar automáticamente el lenguaje de definición de datos (DDL) de las funciones definidas por el usuario (UDF) para determinar sus tipos de datos de entrada y salida, incluso si el cuerpo de la UDF está escrito en un lenguaje externo. Sin embargo, para ciertos dialectos de origen, es posible que el traductor no pueda compilar automáticamente la firma de la UDF. Para garantizar que las sentencias de SQL que hacen referencia a estas UDF se traduzcan con exactitud sin tener que proporcionar el DDL original, puedes usar un archivo de configuración YAML para registrar de forma explícita las firmas de las UDF.

En el siguiente YAML de configuración, se especifica la firma de las funciones definidas por el usuario (UDF) que se usan en las secuencias de comandos de origen. Especifica cada firma en el dialecto de origen como RETURN_TYPE FUNCTION_NAME(ARG_NAME ARG_TYPE, ...), incluido un nombre para cada parámetro. Al igual que los archivos ZIP de metadatos, las definiciones de UDF pueden ayudar a producir una traducción más precisa de las secuencias de comandos de entrada.

type: metadata
udfs:
  - "date parse_short_date(dt int)"

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      create table x(dt int);
      select parse_short_date(dt) + 1 from x;
    
bq-output.sql
      CREATE TABLE x
      (
        dt INT64
      )
      ;
      SELECT
          date_add(parse_short_date(dt), interval 1 DAY)
        FROM
          x
      ;
    

Algunos dialectos de origen admiten UDF que comparten un nombre en diferentes firmas de argumentos, a veces llamadas UDF sobrecargadas. Para las UDF sobrecargadas, especifica udf y un name de destino distinto para que cada firma se asigne a un nombre de función único en BigQuery:

type: metadata
udfs:
  - "int custom_substr(pos int)"
  - udf: "int custom_substr(pos int, len int)"
    name: "custom_substr_with_len"

Quita los patrones de identificador durante la búsqueda de metadatos

Las secuencias de comandos de SQL de entrada pueden hacer referencia a objetos o columnas con un prefijo, un sufijo o un patrón de nombres que no está en tus definiciones de metadatos, por ejemplo, hacer referencia a a_dt cuando el DDL de metadatos define la columna dt. En este caso, usa nameAlias en type: metadata para que el motor de traducción quite el patrón cuando busque nombres de objetos en los metadatos. El identificador original se conserva en el SQL de salida.

El campo nameAlias admite las siguientes propiedades. Cada propiedad acepta una sola cadena o una lista de cadenas, y se aplica la primera entrada coincidente de cada lista:

  • stripPrefix: Quita un prefijo literal antes de buscar metadatos.
  • stripSuffix: Quita un sufijo literal antes de buscar metadatos.
  • stripRegex: Coincide con una expresión regular que distingue mayúsculas de minúsculas y reemplaza cada subcadena coincidente por su primer grupo de captura (...) cuando se buscan metadatos. Ancla el patrón, por ejemplo, ^a_(.*)$, para que coincida solo con un prefijo o el identificador completo.

En el siguiente YAML de configuración, se quita el prefijo a_ inicial de los identificadores cuando se buscan nombres de objetos en los metadatos:

type: metadata
nameAlias:
  stripRegex: "^a_(.*)$"

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      create table t(dt date);
      select a_dt + 1 from t;
    
bq-output.sql
      CREATE TABLE t
      (
        dt DATE
      )
      ;
      SELECT
          date_add(a_dt, interval 1 DAY)
        FROM
          t
      ;
    

Configura la rigurosidad de precisión decimal

De forma predeterminada, el servicio de migración de BigQuery aumenta la precisión numérica a la precisión más alta disponible para una escala determinada. El siguiente YAML de configuración anula este comportamiento con la configuración de la rigurosidad de precisión para retener la precisión decimal de la declaración de origen.

type: statement_rewriter
common:
  decimalPrecision: STRICT

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      create table x(a decimal(3,0));
    
bq-output.sql
      CREATE TABLE x
      (
        a NUMERIC(3)
      )
      ;
    

Configura la rigurosidad de precisión de cadenas

De forma predeterminada, el Servicio de migración de BigQuery omite la precisión de las cadenas cuando traduce las columnas CHAR y VARCHAR. Esto puede ayudar a evitar errores de truncamiento cuando se escriben los valores. Algunos dialectos de SQL, como Teradata, truncan los valores que superan la precisión máxima en la escritura, mientras que BigQuery devuelve un error en esta situación.

Si tu aplicación no depende del comportamiento de truncamiento del dialecto de origen, considera conservar la precisión de la columna en la definición del tipo traducido.

El siguiente YAML de configuración anula este comportamiento con la configuración de la rigurosidad de precisión para retener la precisión de la cadena de la declaración de origen.

type: statement_rewriter
common:
  stringPrecision: STRICT

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      create table x(a varchar(3));
    
bq-output.sql
      CREATE TABLE x
      (
        a STRING(3)
      )
      ;
    

Asignación de nombre de salida

Puedes usar type: experimental_object_rewriter en un archivo YAML de configuración para asignar nombres de objetos SQL (database, schema, relation, attribute, function, sequence, index, variable o projection) de forma estática o dinámica:

  • Cada tipo de objeto expande solo sus propios marcadores de posición de nombre y jerarquía superior de ${database}, ${schema}, ${relation}, ${attribute}, ${function}, ${sequence}, ${index}, ${variable} y ${projection}. Por ejemplo, una regla schema expande ${database} y ${schema}, mientras que una regla relation expande ${database}, ${schema} y ${relation}.
  • Cuando varias reglas del mismo tipo de objeto con criterios match distintos coinciden con un objeto, se aplica la última regla coincidente de la lista.
  • Las reglas globales replace y case en global.outputName se ejecutan antes de las reglas outputName específicas del objeto. Una regla específica del objeto coincide con el nombre transformado de forma global de su objeto y puede anularlo. Para las reglas de attribute, match compara con el nombre de attribute transformado de forma global junto con los nombres de database, schema y relation de origen. Para obtener más información, consulta Reescritura del nombre del resultado global.

Para obtener más información sobre cómo funcionan las reglas de asignación de nombres en los niveles de base de datos, esquema, relación, función y atributo, consulta Asigna nombres de objetos SQL para la traducción.

Asignación de nombre estático

Usa la asignación de nombres estáticos para asignar el nombre de una entidad. Si solo deseas cambiar partes específicas del nombre y, al mismo tiempo, mantener otras partes del nombre iguales, incluye solo las partes que se deben cambiar.

El siguiente YAML de configuración cambia el nombre de la tabla de my_db.my_schema.my_table a my_new_db.my_schema.my_new_table.

type: experimental_object_rewriter
relation:
-
  match: "my_db.my_schema.my_table"
  outputName:
    database: "my_new_db"
    relation: "my_new_table"

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      create table my_db.my_schema.my_table(a int);
    
bq-output.sql
      CREATE TABLE my_new_db.my_schema.my_new_table
      (
        a INT64
      )
      ;
    

Puedes usar la asignación de nombres estáticos para actualizar la región que usan los nombres en las funciones públicas definidas por el usuario.

En el siguiente ejemplo, se cambian los nombres en la UDF bqutil.fn para que no usen la multirregión us predeterminada, sino la región europe_west2:

type: experimental_object_rewriter
function:
-
  match:
    database: bqutil
    schema: fn
  outputName:
    database: bqutil
    schema: fn_europe_west2

Asignación dinámica de nombres

Usa la asignación dinámica de nombres para cambiar varios objetos al mismo tiempo y crear nombres nuevos basados en los objetos asignados.

En el siguiente YAML de configuración, se cambia el nombre de todas las tablas cuando se agrega el prefijo stg_ a los que pertenecen al esquema staging y, luego, se mueven a esas tablas al esquema production.

type: experimental_object_rewriter
relation:
-
  match:
    schema: staging
  outputName:
    schema: production
    relation: "stg_${relation}"

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      create table staging.my_table(a int);
    
bq-output.sql
      CREATE TABLE production.stg_my_table
      (
        a INT64
      )
      ;
    

Asignación de nombres de columnas

Usa la sección attribute en type: experimental_object_rewriter para cambiar el nombre de las columnas en las definiciones de tablas y las referencias de consultas:

type: experimental_object_rewriter
attribute:
-
  match:
    relation: employee
    attributeRegex: "\\d.*"
  outputName:
    attribute: "col_${attribute}"

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      create table employee(eid int, "2name" varchar(10));
      select eid, "2name" from employee e;
    
bq-output.sql
      CREATE TABLE employee
      (
        eid INT64,
        col_2name STRING
      )
      ;
      SELECT
          eid,
          col_2name
        FROM
          employee AS e
      ;
    

Especifica la base de datos predeterminada y la ruta de búsqueda del esquema

El siguiente YAML de configuración especifica una base de datos predeterminada y una ruta de búsqueda de esquema.

type: environment
session:
  defaultDatabase: myproject
  schemaSearchPath: [myschema1, myschema2]

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      SELECT * FROM mydb.mytable;
      SELECT * FROM table1;
    
bq-output.sql
      SELECT * FROM myproject.mydb.mytable;
      SELECT * FROM myproject.myschema1.table1;
    

Configura NLS_DATE_FORMAT

En el siguiente YAML de configuración, se establece el parámetro NLS_DATE_FORMAT en el formato DD/MM/YYYY. Te recomendamos que especifiques NLS_DATE_FORMAT para los usos implícitos del formato de fecha y las conversiones. Si no se establece, se usa el formato predeterminado para la traducción, DD-MON-RR.

type: environment
session:
  dateFormat: DD/MM/YYYY

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

oracle-input.sql
    create table x(dt date default '31/12/1999');
    insert into x values ('01/01/2000');
    
bq-output.sql
      CREATE TABLE X
      (
        DT DATETIME DEFAULT DATETIME '1999-12-31 00:00:00'
      )
      ;
      INSERT INTO X
        VALUES (DATETIME '2000-01-01 00:00:00')
      ;
    

Reescritura del nombre del resultado global

El siguiente YAML de configuración usa reglas replace en global.outputName para reescribir los nombres de salida de todos los objetos (all) o tipos de objetos específicos (database, schema, relation, attribute, function, sequence, index, variable o projection). Cada regla coincide con una expresión regular que distingue mayúsculas de minúsculas y reemplaza las coincidencias por texto nuevo, incluidos $0, $1 y otros grupos de captura.

Las transformaciones globales de outputName (replace seguidas de case) se ejecutan antes de las reglas de outputName específicas de objetos, como schema, relation o attribute. Una regla específica de un objeto coincide con el nombre transformado de forma global de su objeto y puede anularlo. Para las reglas attribute, match compara con el nombre attribute transformado de forma global junto con los nombres database, schema y relation de origen:

type: experimental_object_rewriter
global:
  outputName:
    all:
      replace:
        - regex: '\s'
          replaceWith: '_'
        - regex: '>='
          replaceWith: 'gte'
        - regex: '^[^a-zA-Z_].*'
          replaceWith: '_$0'

Una traducción de SQL con este archivo YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
      create table "test special chars >= 12"("42eid" int, "custom column" varchar(10));
    
bq-output.sql
      CREATE TABLE test_special_chars_gte_12
      (
        _42eid INT64,
        custom_column STRING
      )
      ;
    

Optimiza y mejora el rendimiento de SQL traducido

Las transformaciones opcionales se pueden aplicar a SQL traducido para ingresar cambios que puedan mejorar el rendimiento o el costo. Estas optimizaciones dependen estrictamente del caso y deben evaluarse en función del resultado de SQL no modificado para evaluar su efecto real en el rendimiento.

El siguiente YAML de configuración habilita transformaciones opcionales. Cada entrada de la lista transformations admite los siguientes campos:

  • name: Es el nombre de la optimización.
  • enabled (opcional): Es un valor booleano que se establece de forma predeterminada en true. Establece enabled en false para inhabilitar una optimización que está habilitada de forma predeterminada para el dialecto de origen.
  • parameters (opcional): Es un mapa de parámetros específicos de la optimización.
type: optimizer
transformations:
  - name: PRECOMPUTE_INDEPENDENT_SUBSELECTS
  - name: REWRITE_CTE_TO_TEMP_TABLE
    parameters:
      threshold: 1
Optimización Parámetro opcional Descripción
PRECOMPUTE_INDEPENDENT_SUBSELECTS scope: [PREDICATE, PROJECTION] Vuelve a escribir la consulta agregando una sentencia DECLARE para reemplazar una expresión en cláusulas PREDICATE, cláusulas PROJECTION o ambas con una variable calculada previamente. Esta reescritura convierte la expresión en un predicado estático que puede reducir la cantidad de datos leídos. El parámetro scope acepta una lista que contiene PREDICATE, PROJECTION o ambos. Si se omite parameters, scope se establece de forma predeterminada en [PREDICATE], que abarca las cláusulas WHERE y JOIN ON.

Si extraes una subconsulta escalar a una sentencia DECLARE, el predicado original se volverá estático y, por lo tanto, se podrá planificar mejor la ejecución. Esta optimización introducirá nuevas sentencias de SQL.
REWRITE_CTE_TO_TEMP_TABLE threshold: N Vuelve a escribir expresiones de tabla comunes (CTE) en tablas temporales cuando hay al menos N referencias a la misma CTE. Esta reescritura reduce la complejidad de las consultas y fuerza la ejecución única de la CTE. Si se omite N, el valor predeterminado es 4.

Recomendamos usar esta optimización cuando se haga referencia a las CTE no triviales varias veces. La introducción de tablas temporales tiene una sobrecarga que podría ser mayor que las ejecuciones múltiples eventuales de una CTE de baja complejidad o baja cardinalidad. Esta optimización introducirá nuevas sentencias de SQL.
REWRITE_ZERO_SCALE_NUMERIC_AS_INTEGER bigint: N Reescribe los atributos NUMERIC/BIGNUMERIC de escala cero al tipo INT64 si la precisión está dentro de N. Si se omite N, el valor predeterminado es 18.

Recomendamos usar esta optimización cuando se traduce de dialectos de origen que no tienen tipos de número entero. Para cambiar los tipos de columna, se deben revisar todos los usos downstream para la compatibilidad de tipos y los cambios semánticos. Por ejemplo, las divisiones fraccionarias se convierten en divisiones de números enteros, o el código espera valores numéricos.

Las traducciones de Snowflake tienen esta optimización para valores numéricos de escala cero hasta la precisión 38 habilitada de forma predeterminada. Esta optimización garantiza que un INTEGER de Snowflake, que se representa de forma implícita como NUMBER(38,0) en Snowflake, se traduzca en un INT64 de BigQuery en lugar de un BIGNUMERIC(38).

Si tu aplicación usa números con precisiones superiores a 18, te recomendamos que inhabilites esta funcionalidad para garantizar que BigQuery pueda procesar el rango completo de valores que necesita tu aplicación.
DROP_TEMP_TABLE Agrega instrucciones DROP TABLE para todas las tablas temporales creadas en una secuencia de comandos y que no se descartaron al final. Esto reduce el período de facturación de almacenamiento de la tabla temporal de 24 horas al tiempo de ejecución de la secuencia de comandos.

Recomendamos usar esta optimización cuando no se acceda a las tablas temporales para ningún otro procesamiento después del final de la ejecución de la secuencia de comandos. Esta optimización introducirá nuevas sentencias de SQL.
REGEXP_CONTAINS_TO_LIKE Vuelve a escribir algunas categorías de patrones que coinciden de REGEXP_CONTAINS en expresiones LIKE.

Recomendamos usar esta optimización cuando ningún otro proceso, como el reemplazo de macros, dependa de que los literales de patrón de expresión regular se conserven sin cambios en el SQL de salida.
ADD_DISTINCT_TO_SUBQUERY_IN_SET_COMPARISON Agrega la cláusula DISTINCT a las subconsultas que se usan como conjunto de valores para el operador [NOT] IN.

Recomendamos usar esta optimización cuando la cardinalidad (cantidad distinta de valores) del resultado de la subconsulta sea significativamente menor que la cantidad de valores. Cuando no se cumple esta condición previa, esta transformación puede tener efectos negativos en el rendimiento.
APPROXIMATE_RANGE_PARTITIONS Aproxima los esquemas de partición de números enteros no contiguos o no regulares convirtiéndolos en rangos de partición contiguos y de igual tamaño admitidos por BigQuery. De forma predeterminada, estos esquemas de partición no influyen en el esquema de partición de tablas en las declaraciones de DDL traducidas.

Recomendamos usar esta optimización cuando la tabla de origen usa una función de partición no contigua, como la función RANGE_N de Teradata, y se beneficiaría de un esquema de partición de igual tamaño en BigQuery.

Ejemplos de optimización

La siguiente optimización convierte los tipos numéricos de escala cero con una precisión menor o igual que 38 en INT64 en BigQuery.

# An INTEGER is internally represented as NUMBER(38,0) in Snowflake.
# To convert Snowflake INTEGER to INT64 in BigQuery, enable the rewrite for precision <= 38.
# Note that this can produce incorrect results if your application logic uses more than 18 digits of precision.
#
# This configuration is enabled by default for the Snowflake Dialect.
type: optimizer
transformations:
  - name: REWRITE_ZERO_SCALE_NUMERIC_AS_INTEGER
    parameters:
      bigint: 38

Una traducción de SQL con esta optimización podría tener el siguiente aspecto:

snowflake-input.sql
      CREATE TABLE numbers(i INTEGER, n NUMERIC(10,0));
    
bq-output.sql
      CREATE TABLE NUMBERS
      (
        I INT64,
        N INT64
      )
      ;
    

La siguiente configuración inhabilita la optimización en dialectos, como Snowflake, en los que está habilitada de forma predeterminada. Esta configuración convierte los tipos numéricos en NUMERIC o BIGNUMERIC según la precisión de entrada, en lugar del valor predeterminado de INT64.

type: optimizer
transformations:
  - name: REWRITE_ZERO_SCALE_NUMERIC_AS_INTEGER
    enabled: false

Una traducción de SQL con esta optimización podría tener el siguiente aspecto:

snowflake-input.sql
      CREATE TABLE numbers(i INTEGER, n NUMERIC(10,0));
    
bq-output.sql
      CREATE TABLE NUMBERS
      (
        I BIGNUMERIC(38),
        N NUMERIC(29)
      )
      ;
    

Crea un archivo YAML de configuración basado en Gemini

Para generar un resultado de IA, proporciona al menos un archivo *.ai_config.yaml y habilita las sugerencias de la IA de Gemini cuando la interfaz lo requiera. Para obtener más información, consulta Proporciona archivos de configuración a una traducción.

Requisitos

El archivo YAML de configuración para los resultados de la IA debe tener el sufijo .ai_config.yaml. Por ejemplo, rules_1.ai_config.yaml

Campos disponibles

A diferencia de un archivo *.config.yaml, un archivo *.ai_config.yaml no incluye un encabezado type. En su lugar, el archivo contiene una lista translation_rules de nivel superior, en la que cada regla admite los siguientes campos:

  • suggestion_type (opcional): Especifica el tipo de sugerencia de IA que se generará. Se admiten los siguientes tipos de sugerencias:
    • QUERY_CUSTOMIZATION (predeterminado): Genera sugerencias de IA para el código SQL en función de las reglas de traducción especificadas en el archivo *.ai_config.yaml.
    • TRANSLATION_EXPLANATION: Genera texto que incluye un resumen de la consulta de GoogleSQL traducida y las diferencias y las inconsistencias entre la consulta en SQL de origen y la consulta de GoogleSQL traducida.
  • rewrite_target (opcional): Especifica SOURCE_SQL para aplicar la regla al SQL de entrada original antes de que se ejecute el motor de traducción o TARGET_SQL para aplicar la regla al SQL traducido que produce el motor de traducción. El valor predeterminado es TARGET_SQL. Para obtener más información, consulta Cómo se aplican los dos tipos de reglas.
  • instruction (opcional): Describe en lenguaje natural el cambio que se aplicará al SQL de entrada o al SQL traducido para las reglas QUERY_CUSTOMIZATION, o la explicación que se generará para las reglas TRANSLATION_EXPLANATION.
  • examples (opcional): Proporciona una lista de pares de SQL input y output que muestren cómo deseas que se modifique un patrón de SQL.

Puedes agregar translation_rules y examples adicionales según sea necesario.

Ejemplos

En los siguientes ejemplos, se crean archivos YAML de configuración basados en Gemini que puedes usar con tus traducciones de SQL.

Quita la función upper en la consulta de salida de traducción predeterminada

translation_rules:
- instruction: "Remove upper() function"
  examples:
  - input: "upper(X)"
    output: "X"

Crea varias reglas de traducción para personalizar el resultado de la traducción

translation_rules:
- instruction: "Remove upper() function"
  suggestion_type: QUERY_CUSTOMIZATION
  rewrite_target: TARGET_SQL
  examples:
  - input: "upper(X)"
    output: "X"
- instruction: "Insert a comment at the head that explains each statement in detail."
  suggestion_type: QUERY_CUSTOMIZATION
  rewrite_target: TARGET_SQL

Quita los comentarios de SQL de la consulta de entrada de traducción

translation_rules:
- instruction: "Remove all the sql comments in the input sql query."
  suggestion_type: QUERY_CUSTOMIZATION
  rewrite_target: SOURCE_SQL

Genera explicaciones de traducción con la instrucción predeterminada del LLM

En este ejemplo, se usan las instrucciones de LLM predeterminadas que proporciona el servicio de traducción para generar explicaciones de texto:

translation_rules:
- suggestion_type: "TRANSLATION_EXPLANATION"

Genera explicaciones de traducción con tus propias instrucciones en lenguaje natural.

translation_rules:
- suggestion_type: "TRANSLATION_EXPLANATION"
  instruction: "Explain the syntax differences between the source Teradata query and the translated GoogleSQL query."

Varios tipos de sugerencias en un solo archivo YAML de configuración

translation_rules:
- suggestion_type: "TRANSLATION_EXPLANATION"
  instruction: "Explain the syntax differences between the source Teradata query and the translated GoogleSQL query."
- instruction: "Remove upper() function"
  suggestion_type: QUERY_CUSTOMIZATION
  rewrite_target: TARGET_SQL
  examples:
  - input: "upper(X)"
    output: "X"
- instruction: "Remove all the sql comments in the input sql query."
  suggestion_type: QUERY_CUSTOMIZATION
  rewrite_target: SOURCE_SQL

Aplica varias opciones de configuración de YAML

Cuando traduces una sola consulta o archivos SQL por lotes, puedes proporcionar varios archivos YAML de configuración en un solo trabajo de traducción para reflejar varias transformaciones. Si varias opciones de configuración entran en conflicto, una transformación puede anular a otra. Recomendamos usar diferentes tipos de ajustes de configuración en cada archivo para evitar transformaciones conflictivas en el mismo trabajo de traducción.

En el siguiente ejemplo, se enumeran dos archivos YAML de configuración independientes que se proporcionaron para un solo trabajo de traducción de SQL, uno a fin de cambiar el atributo de una columna y el otro para configurar la tabla como temporal:

change-type-example.config.yaml:

type: object_rewriter
attribute:
  -
    match: "testdb.testschema.x.a"
    type:
      target: NUMERIC(10,2)

make-temp-example.config.yaml:

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    temporary: true

Una traducción de SQL con estos dos archivos YAML de configuración podría tener el siguiente aspecto:

teradata-input.sql
    create table testdb.testschema.x(a int);
    
bq-output.sql
    CREATE TEMPORARY TABLE x
    (
      a NUMERIC(31, 2)
    )
    ;