Trasforma le traduzioni SQL utilizzando i file YAML di configurazione

Questo documento mostra come utilizzare i file YAML di configurazione per trasformare il codice SQL durante la relativa migrazione a BigQuery. Fornisce linee guida per creare i tuoi file YAML di configurazione e fornisce esempi di varie trasformazioni di traduzione supportate da questa funzionalità.

Quando utilizzi il traduttore SQL interattivo di BigQuery, l'API BigQuery Migration o esegui una traduzione SQL batch, puoi fornire file YAML di configurazione per modificare una traduzione di query SQL. L'utilizzo di file YAML di configurazione consente un'ulteriore personalizzazione durante la traduzione delle query SQL dal database di origine.

Puoi specificare un file YAML di configurazione da utilizzare in una traduzione SQL nei modi seguenti:

Il traduttore SQL interattivo, l'API BigQuery Migration, il traduttore SQL batch e il client Python per la traduzione batch supportano l'utilizzo di più file YAML di configurazione in un unico job di traduzione. Per ulteriori informazioni, consulta Applicare più configurazioni YAML.

Requisiti del file YAML di configurazione

Prima di creare un file YAML di configurazione, esamina le seguenti informazioni per assicurarti che il file YAML sia compatibile con BigQuery Migration Service:

  • Devi caricare i file YAML di configurazione nella directory principale del bucket Cloud Storage contenente i file di input per la traduzione SQL. Per informazioni su come creare bucket e caricare file su Cloud Storage, consulta Creare bucket e Caricare oggetti da un file system.
  • Le dimensioni di un singolo file YAML di configurazione non devono superare 1 MB.
  • La dimensione totale di tutti i file YAML di configurazione utilizzati in un singolo job di traduzione SQL non deve superare i 4 MB.
  • Se utilizzi la sintassi regex per la corrispondenza dei nomi, utilizza RE2/J.
  • Tutti i nomi dei file di configurazione YAML devono includere un'estensione.config.yaml, ad esempio change-case.config.yaml.
    • config.yaml da solo non è un nome valido per il file di configurazione.

Linee guida per creare un file YAML di configurazione

Questa sezione fornisce alcune linee guida generali per creare un file YAML di configurazione:

Ogni file di configurazione deve contenere un'intestazione che specifica il tipo di configurazione. Il tipo object_rewriter viene utilizzato per specificare le traduzioni SQL in un file YAML di configurazione. L'esempio seguente utilizza il tipo object_rewriter per trasformare la maiuscola di un nome:

type: object_rewriter
global:
  case:
    all: UPPERCASE

Selezione di entità

Per eseguire trasformazioni specifiche per entità, specifica l'entità nel file di configurazione. Tutte le proprietà match sono facoltative; utilizza solo le proprietà match necessarie per una trasformazione. Il seguente file YAML di configurazione espone le proprietà da associare per selezionare entità specifiche:

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

Descrizione di ogni proprietà match:

  • database o db: il componente project_id.
  • schema: il componente del set di dati.
  • relation: il componente della tabella.
  • attribute: il componente della colonna. Valido solo per la selezione degli attributi
  • databaseRegex o dbRegex: corrisponde a una proprietà database con un'espressione regolare (Anteprima).
  • schemaRegex: abbina le proprietà schema a espressioni regolari (Anteprima).
  • relationRegex: abbina le proprietà relation con espressioni regolari (Anteprima).
  • attributeRegex: corrisponde alle proprietà attribute con espressioni regolari. Valido solo per la selezione degli attributi (Anteprima).

Ad esempio, il seguente file YAML di configurazione specifica le proprietà match per selezionare la tabella testdb.acme.employee per una trasformazione della tabella provvisoria.

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

Puoi utilizzare le proprietà databaseRegex, schemaRegex, relationRegex e attributeRegex per specificare espressioni regolari al fine di selezionare un sottoinsieme di entità. L'esempio seguente modifica tutte le relazioni dallo schema tmp_schema in testdb in temporanee, a condizione che il nome inizi con tmp_:

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

Le proprietà letterali e regex vengono associate senza distinzione tra maiuscole e minuscole. Puoi applicare la corrispondenza sensibile alle maiuscole utilizzando un regex con un flag i disabilitato, come nell'esempio seguente:

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

Puoi anche specificare entità completamente qualificate utilizzando una sintassi di stringa breve equivalente. Una sintassi di stringa breve prevede esattamente 3 (per la selezione della relazione) o 4 (per la selezione dell'attributo) segmenti di nome delimitati da punti, come nell'esempio testdb.acme.employee. I segmenti vengono poi interpretati internamente come se fossero stati trasmessi rispettivamente come database, schema, relation e attribute. Ciò significa che i nomi vengono associati in modo letterale, pertanto le espressioni regolari non sono consentite nella sintassi breve. L'esempio seguente mostra l'utilizzo della sintassi di stringhe brevi per specificare un'entità completamente qualificata in un file YAML di configurazione:

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

Se una tabella contiene un punto nel nome, non puoi specificare il nome utilizzando una sintassi breve. In questo caso, devi utilizzare una corrispondenza di oggetti. L'esempio seguente imposta la tabella testdb.acme.stg.employee come temporanea:

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

Il file YAML di configurazione accetta key come alias per match.

Database predefinito

Alcuni dialetti SQL di input, in particolare Teradata, non supportano database-name nel nome qualificato. In questo caso, il modo più semplice per associare le entità è omettere la proprietà database in match.

Tuttavia, puoi impostare la proprietà default_database di BigQuery Migration Service e utilizzare il database predefinito in match.

Tipi di attributi target supportati

Puoi utilizzare il file YAML di configurazione per eseguire trasformazioni del tipo di attributo, ovvero trasformare il tipo di dati di una colonna dal tipo di origine a un tipo di destinazione. Il file YAML di configurazione supporta i seguenti tipi di target:

  • BOOLEAN
  • TINYINT
  • SMALLINT
  • INTEGER
  • BIGINT
  • FLOAT
  • DOUBLE
  • NUMERIC (supporta la precisione e la scala facoltative, ad esempio NUMERIC(18, 2))
  • TIME
  • TIMETZ
  • DATE
  • DATETIME
  • TIMESTAMP
  • TIMESTAMPTZ
  • CHAR (supporta la precisione facoltativa, ad esempio CHAR(42))
  • VARCHAR (supporta la precisione facoltativa, ad esempio VARCHAR(42))

Esempi di file YAML di configurazione

Questa sezione fornisce esempi per creare vari file YAML di configurazione da utilizzare con le traduzioni SQL. Ogni esempio illustra la sintassi YAML per trasformare la traduzione SQL in modi specifici, oltre a una breve descrizione. Ogni esempio fornisce anche i contenuti di un file teradata-input.sql o hive-input.sql e di un file bq-output.sql in modo da poter confrontare gli effetti di un file YAML di configurazione su una traduzione di query SQL di BigQuery.

I seguenti esempi utilizzano Teradata o Hive come dialetto SQL di input e BigQuery SQL come dialetto di output. I seguenti esempi utilizzano anche testdb come database predefinito e testschema come percorso di ricerca dello schema.

Modificare le maiuscole/minuscole del nome dell'oggetto

Il seguente file YAML di configurazione modifica le lettere maiuscole o minuscole dei nomi degli oggetti:

type: object_rewriter
global:
  case:
    all: UPPERCASE
    database: LOWERCASE
    attribute: LOWERCASE

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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

Creare una tabella temporanea

Il seguente file YAML di configurazione trasforma una tabella normale in una tabella temporary:

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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

Crea una tabella temporanea

Il seguente file YAML di configurazione trasforma una tabella normale in una tabella temporanea con scadenza di 60 secondi.

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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

Imposta la scadenza della partizione

Il seguente file YAML di configurazione modifica la scadenza di una tabella partitioned in 1 giorno:

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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

Modificare la posizione o il formato esterno di una tabella

Il seguente file YAML di configurazione modifica la posizione e la formazione esterna per una tabella:

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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

Impostare o modificare la descrizione della tabella

Il seguente file YAML di configurazione imposta la descrizione di una tabella:

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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

Impostare o modificare la partizione della tabella

Il seguente file YAML di configurazione modifica lo schema di partizione di una tabella:

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

teradata-input.sql 
    create table x(a date, b int);
    create table 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
    )
    ;

Impostare o modificare il clustering delle tabelle

Il seguente file YAML di configurazione modifica lo schema di clustering di una tabella:

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

hive-input.sql 
    create table x(a int, b int);
    create table 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
    )
    ;

Modificare il tipo di un attributo di colonna

Il seguente file YAML di configurazione modifica il tipo di dati di un attributo di una colonna:

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

Puoi trasformare il tipo di dati di origine in uno dei tipi di attributi target supportati.

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

teradata-input.sql 
    create table 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)
    )
    ;

Aggiungi una connessione al lake di dati esterno

Il seguente file YAML di configurazione contrassegna la tabella di origine come tabella esterna che rimanda ai dati archiviati in un data lake esterno, specificato da una connessione al data lake.

type: object_rewriter
relation:
-
  key: "testdb.acme.employee"
  external:
    connection_id: "connection_test"

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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

Modificare la codifica dei caratteri di un file di input

Per impostazione predefinita, BigQuery Migration Service tenta di rilevare automaticamente la codifica dei caratteri dei file di input. Nei casi in cui il servizio di migrazione di BigQuery possa identificare erroneamente la codifica di un file, puoi utilizzare un file YAML di configurazione per specificare esplicitamente la codifica dei caratteri.

Il seguente file YAML di configurazione specifica la codifica esplicita dei caratteri del file di input come ISO-8859-1.

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

Conversione del tipo globale

Il seguente file YAML di configurazione modifica un tipo di dati in un altro in tutti gli script e specifica un tipo di dati di origine da evitare nello script transpiled. È diverso dalla configurazione Cambia il tipo di un attributo della colonna, in cui viene modificato solo il tipo di dati di un singolo attributo.

BigQuery supporta le seguenti conversioni di tipi di dati:

  • Da DATETIME a TIMESTAMP
  • TIMESTAMP a DATETIME (accetta il fuso orario facoltativo)
  • TIMESTAMP WITH TIME ZONE a DATETIME (accetta il fuso orario facoltativo)
  • Da CHAR a VARCHAR

Nel seguente esempio, il file YAML di configurazione converte un tipo di dati TIMESTAMP in DATETIME.

type: experimental_object_rewriter
global:
  typeConvert:
    timestamp: DATETIME

In dialetti come Teradata, le funzioni relative a data e ora come current_date, current_time o current_timestamp restituiscono i timestamp in base al fuso orario configurato, locale o della sessione. BigQuery, invece, restituisce sempre i timestamp in UTC. Per garantire un comportamento coerente tra i due dialetti, è necessario configurare il fuso orario di conseguenza.

Nell'esempio seguente, il file YAML di configurazione converte un tipo di dati TIMESTAMP e un tipo di dati TIMESTAMP WITH TIME ZONE in DATETIME, con il fuso orario di destinazione impostato su Europe/Paris.

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

teradata-input.sql 
      create table x(a timestamp);
      select a from x where a > current_timestamp(0);
bq-output.sql 
      CREATE TABLE x
      (
        a TIMESTAMP
      )
      ;
      SELECT
          x.a
        FROM
          test.x
        WHERE x.a > datetime_trunc(current_datetime('Europe/Paris'), SECOND)
      ;

Seleziona la modifica dell'estratto conto

Il seguente file YAML di configurazione modifica la proiezione a stella, le clausole GROUP BY e ORDER BY nelle istruzioni SELECT.

starProjection supporta le seguenti configurazioni:

  • ALLOW
  • PRESERVE (valore predefinito)
  • EXPAND

groupBy e orderBy supportano le seguenti configurazioni:

  • EXPRESSION
  • ALIAS
  • INDEX

Nell'esempio seguente, il file YAML di configurazione configura la proiezione stellata su EXPAND.

type: experimental_statement_rewriter
select:
  starProjection: EXPAND

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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

Specifiche delle funzioni definite dall'utente

Il seguente file YAML di configurazione specifica la firma delle funzioni definite dall'utente (UDF) utilizzate negli script di origine. Come i file ZIP dei metadati, le definizioni delle funzioni definite dall'utente possono contribuire a produrre una traduzione più accurata degli script di input.

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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(x.dt), interval 1 DAY)
        FROM
          x
      ;

Impostazione della severità della precisione decimale

Per impostazione predefinita, BigQuery Migration Service aumenta la precisione numerica fino alla massima precisione disponibile per una determinata scala. Il seguente file YAML di configurazione sostituisce questo comportamento configurando la severità della precisione in modo da mantenere la precisione decimale dell'istruzione di origine.

type: experimental_statement_rewriter
common:
  decimalPrecision: STRICT

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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

Mappatura dei nomi di output

Puoi utilizzare il file YAML di configurazione per mappare i nomi degli oggetti SQL. Puoi modificare diverse parti del nome a seconda dell'oggetto da mappare.

Mappatura dei nomi statici

Utilizza la mappatura dei nomi statici per mappare il nome di un'entità. Se vuoi modificare solo alcune parti del nome mantenendo invariate le altre, includi solo le parti che devono essere modificate.

Il seguente file YAML di configurazione cambia il nome della tabella da 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 traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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
      )

Puoi utilizzare la mappatura dei nomi statici per aggiornare la regione utilizzata dai nomi nelle funzioni pubbliche definite dall'utente.

L'esempio seguente modifica i nomi nella UDF bqutil.fn dall'utilizzo della regione multipla us predefinita all'utilizzo della regione europe_west2:

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

Mappatura dei nomi dinamica

Utilizza la mappatura dei nomi dinamica per modificare più oggetti contemporaneamente e creare nuovi nomi in base agli oggetti mappati.

Il seguente file YAML di configurazione modifica il nome di tutte le tabelle aggiungendo il prefisso stg_ a quelle che appartengono allo schema staging e poi sposta queste tabelle nello schema production.

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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

Specifica del percorso di ricerca dello schema e del database predefinito

Il seguente file YAML di configurazione specifica un database predefinito e un percorso di ricerca dello schema.

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

teradata-input.sql 
      SELECT * FROM database.table
      SELECT * FROM table1
bq-output.sql 
      SELECT * FROM myproject.database.table.
      SELECT * FROM myproject.myschema1.table1

Riscrivi nome output globale

Il seguente file YAML di configurazione modifica i nomi di output di tutti gli oggetti (database, schema, relazione e attributi) nello script in base alle regole configurate.

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

Una traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

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

Ottimizzare e migliorare le prestazioni del codice SQL tradotto

È possibile applicare trasformazioni facoltative al codice SQL tradotto per introdurre modifiche che possono migliorare la query in termini di prestazioni o costi. Queste ottimizzazioni sono strettamente dipendenti dal caso e devono essere valutate rispetto all'output SQL non modificato per valutare il loro effetto effettivo sul rendimento.

Il seguente file YAML di configurazione abilita le trasformazioni facoltative. La configurazione accetta un elenco di ottimizzazioni e, per le ottimizzazioni che accettano parametri, una sezione con valori facoltativi dei parametri.

type: experimental_optimizer
transformations:
  - name: PRECOMPUTE_INDEPENDENT_SUBSELECTS
  - name: REWRITE_CTE_TO_TEMP_TABLE
    parameters:
      threshold: 1
Ottimizzazione Parametro facoltativo Descrizione
PRECOMPUTE_INDEPENDENT_SUBSELECTS scope: [PREDICATE, PROJECTION] Riscrivi la query aggiungendo un'istruzione DECLARE per sostituire un'espressione nelle clausole PREDICATE o PROJECTION con una variabile precalcolata. Verrà identificato come un predicato statico che consente di ridurre la quantità di dati letti. Se l'ambito viene omesso, il valore predefinito è PREDICATE (ovvero clausole WHERE e JOIN-ON).

Se estrai una sottoquery scalare in un'istruzione DECLARE, il predicato originale diventerà statico e potrà quindi essere pianificato per un'esecuzione migliore. Questa ottimizzazione introdurrà nuove istruzioni SQL.
REWRITE_CTE_TO_TEMP_TABLE threshold: N Riscrivi le espressioni di tabella comune (CTE) in tabelle temporanee quando sono presenti più di N riferimenti alla stessa espressione di tabella comune. In questo modo si riduce la complessità della query e si forza l'esecuzione singola dell'espressione della tabella comune. Se N viene omesso, il valore predefinito è 4.

Ti consigliamo di utilizzare questa ottimizzazione quando i CTE non banali vengono richiamati più volte. L'introduzione di tabelle temporanee comporta un overhead che potrebbe essere maggiore rispetto alle eventuali molteplici esecuzioni di un'espressione a tabelle correlate dinamicamente di bassa complessità o cardinalità. Questa ottimizzazione introdurrà nuove istruzioni SQL.
REWRITE_ZERO_SCALE_NUMERIC_AS_INTEGER bigint: N Riscrivi gli attributi NUMERIC/BIGNUMERIC con scala zero in tipo INT64 se la precisione è compresa tra N. Se N viene omesso, il valore predefinito è 18.

Ti consigliamo di utilizzare questa ottimizzazione quando traduci da dialetti di origine che non hanno tipi interi. La modifica dei tipi di colonna richiede la revisione di tutti gli utilizzi a valle per verificare la compatibilità dei tipi e le modifiche semantiche. Ad esempio, le divisioni frazionarie diventano divisioni intere, il codice che si aspetta valori numerici
DROP_TEMP_TABLE Aggiunge istruzioni DROP TABLE per tutte le tabelle temporanee create in uno script e non eliminate al termine. In questo modo, il periodo di fatturazione dello spazio di archiviazione per la tabella temporanea viene ridotto da 24 ore al tempo di esecuzione dello script. Questa ottimizzazione introdurrà nuove istruzioni SQL.

Ti consigliamo di utilizzare questa ottimizzazione quando non viene eseguito alcun accesso alle tabelle temporanee per ulteriori elaborazioni al termine dell'esecuzione dello script. Questa ottimizzazione introdurrà nuove istruzioni SQL.
REGEXP_CONTAINS_TO_LIKE Riscrivi alcune categorie di pattern di corrispondenza REGEXP_CONTAINS in espressioni LIKE.

Ti consigliamo di utilizzare questa ottimizzazione quando nessun altro processo, ad esempio la sostituzione delle macro, si basa sul fatto che i literali dei pattern delle espressioni regolari vengano conservati invariati nell'output SQL.
ADD_DISTINCT_TO_SUBQUERY_IN_SET_COMPARISON Aggiunge la clausola DISTINCT alle sottoquery utilizzate come insieme di valori per l'operatore [NOT] IN.

Ti consigliamo di utilizzare questa ottimizzazione quando la cardinalità (numero distinto di valori) del risultato della sottoquery è notevolmente inferiore al numero di valori. Se questo precondizionatore non viene soddisfatto, la trasformazione può avere effetti negativi sul rendimento.

Crea un file YAML di configurazione basato su Gemini

Per generare l'output dell'AI, la directory di origine contenente l'input di traduzione SQL deve includere un file YAML di configurazione.

Requisiti

Il file YAML di configurazione per le uscite di AI deve avere il suffisso .ai_config.yaml. Ad esempio, rules_1.ai_config.yaml.

Campi supportati

suggestion_type: SUGGESTION_TYPE
rewrite_target: TARGET
instruction: NL_PROMPT
translation_rules:
- instruction: NL_RULE_1
  examples:
  - input: RULE_1_INPUT_1
    output: RULE_1_OUTPUT_1
  - input: RULE_1_INPUT_2
    output: RULE_1_OUTPUT_2
- instruction: NL_RULE_2
  examples:
  - input: RULE_2_INPUT_1
    output: RULE_2_OUTPUT_1
…
…

Per configurare l'output della traduzione con AI'IA, puoi sostituire le seguenti variabili:

  • SUGGESTION_TYPE (facoltativo): specifica il tipo di suggerimento dell'AI da generare. Sono supportati i seguenti tipi di suggerimenti:

    • QUERY_CUSTOMIZATION (valore predefinito): genera suggerimenti basati sull'IA per il codice SQL in base alle regole di traduzione specificate nel file YAML di configurazione.
    • TRANSLATION_EXPLANATION: genera un testo che include un riepilogo della query GoogleSQL tradotta e le differenze e le incoerenze tra la query SQL di origine e la query GoogleSQL tradotta.
    • CUSTOM_SUGGESTION: genera output SQL o di testo utilizzando gli elementi di traduzione. Gli utenti possono fare riferimento agli elementi della traduzione nei prompt che includono i segnaposto. Il servizio di traduzione aggiunge gli elementi corrispondenti al prompt LLM finale inviato a Gemini. I seguenti elementi di traduzione possono essere inclusi nel prompt:
      • {{SOURCE_DIALECT}}: da utilizzare per fare riferimento al dialetto SQL di origine.
      • {{SOURCE_SQL}}: da utilizzare per fare riferimento al codice SQL dell'origine della traduzione.
      • {{TARGET_SQL}}: da utilizzare per fare riferimento all'SQL tradotto predefinito.

  • TARGET (facoltativo): specifica se vuoi applicare la regola di traduzione al codice SQL di input, SOURCE_SQL, o al codice SQL di output, TARGET_SQL (valore predefinito).

  • NL_PROMPT (facoltativo): in linguaggio naturale, descrivi una modifica all'SQL di destinazione. La traduzione SQL migliorata da Gemini valuta la richiesta e apporta la modifica specificata.

  • NL_RULE_1 (facoltativo): in linguaggio naturale, descrivi una regola di traduzione.

  • RULE_1_INPUT_1 (facoltativo): un pattern SQL da sostituire.

  • RULE_1_OUTPUT_1 (facoltativo): il pattern SQL previsto dopo la sostituzione di input.

Puoi aggiungere altri translation_rules e altri examples se necessario.

Esempi

Gli esempi riportati di seguito creano file YAML di configurazione basati su Gemini che puoi utilizzare con le traduzioni SQL.

Rimuovi la funzione superiore nella query di output della traduzione predefinita

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

Creare più regole di traduzione per personalizzare l'output della traduzione

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

Rimuovi i commenti SQL dalla query di input della traduzione

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

Generare spiegazioni delle traduzioni utilizzando il prompt LLM predefinito

Questo esempio utilizza i prompt LLM predefiniti forniti dal servizio di traduzione per generare spiegazioni del testo:

suggestion_type: "TRANSLATION_EXPLANATION"

Genera spiegazioni delle traduzioni utilizzando i tuoi prompt in linguaggio naturale

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

Corregge l'errore di traduzione da MySQL a GoogleSQL: unsupported constraint on PRIMARY

suggestion_type: "CUSTOM_SUGGESTION"
instruction: "Add PRIMARY KEY (...) NOT ENFORCED to the target sql as a column constraint based on the source sql. Output sql without sql code block.\n\nsource sql: {{SOURCE_SQL}}\ntarget sql: {{TARGET_SQL}}"

Applicazione di più configurazioni YAML

Quando specifichi un file YAML di configurazione in una traduzione SQL batch o interattiva, puoi selezionare più file YAML di configurazione in un singolo job di traduzione per riflettere più trasformazioni. Se più configurazioni entrano in conflitto, una trasformazione potrebbe sostituire un'altra. Ti consigliamo di utilizzare diversi tipi di impostazioni di configurazione in ogni file per evitare trasformazioni in conflitto nella stessa attività di traduzione.

L'esempio seguente elenca due file YAML di configurazione distinti forniti per un singolo job di traduzione SQL, uno per modificare l'attributo di una colonna e l'altro per impostare la tabella come temporanea:

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 traduzione SQL con questi due file YAML di configurazione potrebbe avere il seguente aspetto:

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