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:
- Crea archivos de configuración: Crea archivos de configuración de traducción de
*.config.yamldeterministas, archivos de configuración basados en Gemini de*.ai_config.yamlo ambos tipos de archivos de configuración para combinar reglas estructurales con la personalización de Gemini. - 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.
- 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 |
|
|
| 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:
- Gemini aplica reglas de
SOURCE_SQLen archivos*.ai_config.yamlal SQL de entrada original para producir SQL de origen reescrito. - 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.yamlpara producir el SQL traducido. - Gemini aplica las reglas de
TARGET_SQLen los archivos de*.ai_config.yamlal SQL traducido del paso anterior para producir un SQL de destino reescrito. Si tus archivos*.ai_config.yamlincluyen reglasTRANSLATION_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:
*.config.yaml: En el campo Ubicación del origen de la configuración de traducción de la configuración de traducción, especifica una ruta de acceso de Cloud Storage al archivo de configuración.*.ai_config.yaml: Crea reglas de personalización, que se guardan en__default.ai_config.yaml, o especifica una ruta de acceso de Cloud Storage.
- Para usar archivos de configuración mientras traduces archivos SQL por lotes, haz lo
siguiente:
*.config.yaml: Sube los archivos de configuración en el directorio de entrada de Cloud Storage y, luego, en la configuración de traducción, especifica una ruta de acceso al directorio en el campo Detalles de la ubicación del archivo.*.ai_config.yaml: Sube los archivos de configuración en el directorio de entrada de Cloud Storage y, luego, en la configuración de traducción, selecciona Configuración opcional > Sugerencias de IA de Gemini.
gcloud
- Cuando uses el
comando
gcloud alpha bq migration translate, usa la marca--translation-config-filespara especificar archivos*.config.yamlo*.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-uriso--source-local-dirs, o pasa archivos individuales con la marca--source-gcs-fileso--source-local-files.*.ai_config.yaml: Incluye los archivos en el directorio de entrada que pasas a--source-gcs-uriso--source-local-dirs, o pasa archivos individuales con la marca--source-gcs-fileso--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 ensource_spec.base_uri, pasa una entradagcs_file_pathensource_speccuando el archivo no esté enbase_urio pasa una entradaliteralintercalada ensource_spec.*.ai_config.yaml: Proporciona los archivos ensource_specenbase_uri, como una entradagcs_file_pathcuando el archivo no está enbase_uri, o como una entradaliteralintercalada, y, además, incluye"suggestion"entarget_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 entradastranslationConfigsintercaladas.*.ai_config.yaml: Pasa entradasaiSuggestionConfigsintercaladas.
- Para traducir archivos SQL por lotes (
translate_batch_queries), haz lo siguiente:*.config.yaml: Sube los archivos ensourceBaseUrio inclúyelos enconfigurationFilePathscuando no estén ensourceBaseUri.*.ai_config.yaml: Sube los archivos ensourceBaseUrio enuméralos enconfigurationFilePathscuando no estén ensourceBaseUriy estableceenableAiSuggestionsentrue.
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_SQLen los archivos*.ai_config.yaml. - Es el SQL de destino reescrito de Gemini después de que aplica las reglas de
TARGET_SQLen los archivos*.ai_config.yaml. - Una explicación de la traducción de Gemini cuando tus
archivos
*.ai_config.yamlincluyen reglasTRANSLATION_EXPLANATIONo 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>otranslation_explanation_suggestion/<var>PATH</var>) atarget_return_literalspara recibirlas entranslatedLiterals. - 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_queryyget_translationdevuelventranslatedQuery,sourceSqlSuggestionytargetSqlSuggestion, y la herramientaexplain_translationdevuelve 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.yamlen 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.yamlno debe superar 1 MB. - El tamaño total de todos los archivos
*.config.yamlque se usan en un solo trabajo de traducción de SQL no debe exceder los 4 MB. - Si usas la sintaxis
regexpara 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.yamlpor 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:
Encabezado
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 derelation, comotemporary,ephemeral,partitionLifetime,external,description,partitionyclustering, y los tipos de datos deattribute(type).experimental_object_rewriter: Reescribe los nombres de los objetos de salida conoutputNameenglobal,database,schema,relation,attribute,function,index,sequence,variableyprojection, y convierte los tipos de datos de forma global conglobal.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 ensession, comodefaultDatabase,schemaSearchPathydateFormat.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 deSELECT *, el formato deGROUP BYyORDER 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:
databaseodb: Coincide con el nombre de la base de datos de origen, que corresponde al componenteproject_iden BigQuery.schema: Coincide con el nombre del esquema de origen, que corresponde al componentedataseten 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 deattribute.databaseRegexodbRegex: Coincide con todo el nombre dedatabasecon una expresión regular que no distingue mayúsculas de minúsculas.schemaRegex: Coincide con todo el nombre deschemacon una expresión regular que no distingue mayúsculas de minúsculas.relationRegex: Coincide con todo el nombre derelationcon una expresión regular que no distingue mayúsculas de minúsculas.attributeRegex: Coincide con todo el nombre deattributecon una expresión regular que no distingue mayúsculas de minúsculas. Esta propiedad solo es válida para la selección deattribute.
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:
BOOLEANTINYINTSMALLINTINTEGERBIGINTFLOATDOUBLENUMERIC(admite precisión y escala opcionales, comoNUMERIC(18, 2))TIMETIMETZDATEDATETIMETIMESTAMPTIMESTAMPTZCHAR(admite precisión opcional, comoCHAR(42))VARCHAR(admite precisión opcional, comoVARCHAR(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
DATETIMEaTIMESTAMP - De
TIMESTAMPaDATETIME(acepta una zona horaria opcional) - De
TIMESTAMP WITH TIME ZONE(timestamptz) aDATETIME(acepta una zona horaria opcional) - De
CHARaVARCHAR(aceptaprecisionActionycomparisonBehavioropcionales) - De
VARCHARaVARCHAR(aceptaprecisionActionycomparisonBehavioropcionales)
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 comoVARCHAR. Configurartarget: VARCHARencharquita el padding derecho deCHAR(CONCAT) incluso cuandoprecisionActionesPRESERVE.precisionAction: Controla la precisión de la longitud de los caracteres y los wrappers de truncamiento deSUBSTR:PRESERVE(predeterminado): Conserva la precisión de la longitud de caracteres en las expresiones y emite wrappers de truncamientoSUBSTRcuando se convierte o se inserta en columnasCHAR(N)oVARCHAR(N). Para emitir también longitudes de columnaSTRING(N)en DDL deCREATE 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 deSUBSTR.
comparisonBehavior: Controla los wrappersRTRIMyUPPERpara las comparaciones y las clavesGROUP BY. Si estableces un valor que no seaSTRICTencharovarchar, 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 omiteUPPER.CASE_AWARE: emula solo la intercalación que no distingue mayúsculas de minúsculas (UPPER) y omiteRTRIM.NONE: Omite los wrappersRTRIMyUPPER, por lo que el resultado usa comparaciones directas y expresionesGROUP 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
datetimees una combinación deY-M-D H:M:Sque no se fija a ninguna zona horaria en particular.datetimerepresenta una hora de reloj y no un instante en particular. - Un
timestamprepresenta 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
timestamptzrepresenta un instante en particular, como untimestamp, pero, a diferencia de untimestamp, incluye una diferencia de zona horaria específica. Si bien representan el mismo instante,2019-06-01 12:00:00+4y2019-06-01 06:00:00-2se consideran valorestimestamptzdiferentes.
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: emiteSELECT *cuando la consulta de origen usaSELECT *o enumera todas las columnas de la tabla en orden.PRESERVE(predeterminado): EmiteSELECT *solo cuando la consulta de origen usaSELECT *.EXPAND: ExpandeSELECT *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 elementosGROUP BYoORDER BYcomo expresiones completas.ALIAS: Aplica formato a los elementosGROUP BYoORDER BYcon alias de columnaSELECTcuando están disponibles.INDEX: Aplica formato a los elementosGROUP BYoORDER BYcon posiciones de columna basadas en 1, comoGROUP 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 reglaschemaexpande${database}y${schema}, mientras que una reglarelationexpande${database},${schema}y${relation}. - Cuando varias reglas del mismo tipo de objeto con criterios
matchdistintos coinciden con un objeto, se aplica la última regla coincidente de la lista. - Las reglas globales
replaceycaseenglobal.outputNamese ejecutan antes de las reglasoutputNameespecí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 deattribute,matchcompara con el nombre deattributetransformado de forma global junto con los nombres dedatabase,schemayrelationde 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 entrue. Estableceenabledenfalsepara 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): EspecificaSOURCE_SQLpara aplicar la regla al SQL de entrada original antes de que se ejecute el motor de traducción oTARGET_SQLpara aplicar la regla al SQL traducido que produce el motor de traducción. El valor predeterminado esTARGET_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 reglasQUERY_CUSTOMIZATION, o la explicación que se generará para las reglasTRANSLATION_EXPLANATION.examples(opcional): Proporciona una lista de pares de SQLinputyoutputque 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) ) ; |