Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Trasforma le traduzioni SQL con YAML

I file YAML di configurazione consentono di personalizzare il modo in cui BigQuery traduce il codice SQL dal database di origine durante una migrazione. BigQuery Migration Service supporta due tipi di file YAML di configurazione: i file di configurazione della traduzione *.config.yaml, che forniscono al motore di traduzione regole deterministiche, e i file di configurazione basati su Gemini *.ai_config.yaml, che forniscono a Gemini regole in linguaggio naturale.

Per personalizzare una traduzione SQL con i file YAML di configurazione, segui questi passaggi:

Crea file di configurazione: crea file di configurazione della traduzione *.config.yaml deterministici, file di configurazione basati su Gemini *.ai_config.yaml o entrambi i tipi di file di configurazione per combinare le regole strutturali con la personalizzazione di Gemini.
Fornisci i file a un job di traduzione: invia i file di configurazione quando traduci una singola query o file SQL batch.
Esamina gli output della traduzione: individua l'SQL tradotto e i suggerimenti di Gemini nella risposta quando traduci una singola query o in Cloud Storage quando traduci file SQL batch.

Tipi di file YAML di configurazione

La tabella seguente mette a confronto i due tipi di file YAML di configurazione:

Funzionalità	Configurazione della traduzione (`*.config.yaml`)	Configurazione basata su Gemini (`*.ai_config.yaml`)
Come vengono applicate le regole	Le regole vengono applicate dal motore di traduzione come regole deterministiche sull'SQL analizzato, pertanto lo stesso input e la stessa configurazione producono sempre lo stesso output.	Le regole vengono applicate da Gemini come istruzioni ed esempi in linguaggio naturale applicati al testo SQL. L'output può variare tra un'esecuzione e l'altra, quindi rivedi e verifica sempre i suggerimenti prima di utilizzarli.
Cosa può essere trasformato	Il motore di traduzione può trasformare qualsiasi oggetto o impostazione che riconosce. Sono inclusi nomi e tipi di database, schema, tabella, colonna e funzione, proprietà della tabella come partizionamento, clustering e scadenza, valori predefiniti della sessione, firme delle funzioni definite dall'utente, ottimizzazioni e output delle istruzioni come lo stile `GROUP BY` e `SELECT *`.	Gemini può modificare qualsiasi trasformazione SQL che puoi descrivere in linguaggio naturale. Sono inclusi la formattazione e i commenti, la sostituzione dei pattern, la riscrittura dei costrutti che il motore non traduce come vorresti e la generazione di una spiegazione della traduzione.
Requisiti	L'SQL di input deve essere analizzato nel dialetto di origine. Le regole non possono agire sul testo nell'SQL di input che l'analizzatore non riconosce, ad esempio i segnaposto `${VAR}` o la sintassi del modello. Utilizza una regola `SOURCE_SQL` nei file `*.ai_config.yaml` o la tua pre-elaborazione per rimuovere prima questo testo.	Devi attivare i suggerimenti di Gemini AI per il job. Il job deve essere eseguito in una località di elaborazione supportata. L'utilizzo di Gemini è senza costi fino a un certo limite.
Dove viene visualizzato il risultato	Il risultato viene visualizzato nell'SQL tradotto, ad esempio nella risposta alla traduzione o nella directory di output `sql/` in Cloud Storage.	Il risultato viene visualizzato come suggerimenti Gemini separati nella console Google Cloud , in campi di suggerimento o file di output separati in Google Cloud CLI e nel server MCP o in directory di output `*_suggestion/` separate in Cloud Storage. Per saperne di più, consulta Dove trovare gli output della traduzione.
Nome file	I nomi file devono terminare con `.config.yaml`, ad esempio `rename-tables.config.yaml`.	I nomi file devono terminare con `.ai_config.yaml`, ad esempio `style-rules.ai_config.yaml`.
Nome file	Il servizio di traduzione ignora qualsiasi file YAML nell'input che non termina con `.config.yaml` o `.ai_config.yaml` e segnala il file ignorato nel log di traduzione.
Riferimento	Per ulteriori informazioni, consulta le linee guida per creare un file YAML di configurazione e gli esempi di file YAML di configurazione in questa pagina.	Per saperne di più, consulta la sezione Crea un file YAML di configurazione basato su Gemini in questa pagina.

Come vengono applicati i due tipi di regole

Un job di traduzione applica le regole di configurazione nel seguente ordine:

Gemini applica SOURCE_SQL regole in *.ai_config.yaml file all'SQL di input originale per produrre l'SQL di origine riscritto.
Il motore di traduzione traduce l'SQL di origine riscritto dal passaggio precedente o l'SQL di input originale se non si applicano regole SOURCE_SQL e applica le regole nei file *.config.yaml per produrre l'SQL tradotto.
Gemini applica TARGET_SQL regole in *.ai_config.yaml file all'SQL tradotto del passaggio precedente per produrre l'SQL di destinazione riscritto. Se i file *.ai_config.yaml includono regole TRANSLATION_EXPLANATION, Gemini genera anche una spiegazione testuale del codice SQL tradotto.

Ti consigliamo di utilizzare le regole *.config.yaml per modifiche strutturali ripetibili, come la ridenominazione degli oggetti, la mappatura dei tipi e l'impostazione del partizionamento. Ti consigliamo di utilizzare le regole *.ai_config.yaml per le modifiche che il motore non può esprimere o per ripulire l'input che non viene analizzato. Puoi utilizzare entrambi i tipi di file di configurazione nello stesso job.

Fornisci i file di configurazione per una traduzione

La console Google Cloud , gcloud CLI, l'API BigQuery Migration e il server MCP di BigQuery Migration Service supportano l'utilizzo di più file di configurazione in un singolo job di traduzione. Per saperne di più, consulta Applicazione di più configurazioni YAML.

Per fornire i file di configurazione a un job di traduzione, seleziona una delle seguenti opzioni:

Console

Per utilizzare i file di configurazione durante la traduzione di una singola query, specificali nelle impostazioni di traduzione del traduttore interattivo:
- *.config.yaml: nel campo Posizione di origine della configurazione di traduzione nelle impostazioni di traduzione, specifica un percorso Cloud Storage per il file di configurazione.
- *.ai_config.yaml: crea regole di personalizzazione, che vengono salvate in __default.ai_config.yaml, o specifica un percorso Cloud Storage.
Per utilizzare i file di configurazione durante la traduzione batch dei file SQL, segui questi passaggi:
- *.config.yaml: carica i file di configurazione nella directory Cloud Storage di input, quindi nelle impostazioni di traduzione, specifica un percorso della directory nel campo Dettagli posizione file.
- *.ai_config.yaml: carica i file di configurazione nella directory di input di Cloud Storage, quindi nelle impostazioni di traduzione seleziona Impostazioni facoltative > Suggerimenti di Gemini AI.

gcloud

Quando utilizzi il comando gcloud alpha bq migration translate, utilizza il flag --translation-config-files per specificare i file *.config.yaml o *.ai_config.yaml.
Quando utilizzi il comando gcloud alpha bq migration translate-batch, esegui una delle seguenti operazioni:
- *.config.yaml: includi i file nella directory di input che passi a --source-gcs-uris o --source-local-dirs oppure passa singoli file con il flag --source-gcs-files o --source-local-files.
- *.ai_config.yaml: includi i file nella directory di input che passi a --source-gcs-uris o --source-local-dirs oppure passa singoli file con il flag --source-gcs-files o --source-local-files e aggiungi il flag --enable-ai-suggestion.

API

Nell'API BigQuery Migration, indipendentemente dal fatto che tu traduca una singola query o file SQL batch, segui questi passaggi:

*.config.yaml: carica i file nel percorso di input in source_spec.base_uri, passa una voce gcs_file_path in source_spec quando il file non si trova in base_uri o passa una voce literal in linea in source_spec.
*.ai_config.yaml: fornisci i file in source_spec in base_uri, come voce gcs_file_path quando il file non è in base_uri o come voce literal incorporata e includi "suggestion" in target_types, ad esempio "target_types": ["sql", "suggestion"].

MCP

Nel server MCP di BigQuery Migration Service:

Per tradurre una singola query (translate_query), segui questi passaggi:
- *.config.yaml: passa le voci translationConfigs in linea.
- *.ai_config.yaml: passa le voci aiSuggestionConfigs in linea.
Per tradurre i file SQL batch (translate_batch_queries), segui questi passaggi:
- *.config.yaml: carica i file in sourceBaseUri o elencali in configurationFilePaths se non si trovano in sourceBaseUri.
- *.ai_config.yaml: carica i file in sourceBaseUri o elencali in configurationFilePaths se non si trovano in sourceBaseUri e imposta enableAiSuggestions su true.

Dove trovare gli output della traduzione

A seconda dei file di configurazione forniti, un job di traduzione può produrre i seguenti output:

SQL tradotto dal motore di traduzione dopo l'applicazione di eventuali regole nei file *.config.yaml.
SQL di origine riscritto da Gemini dopo l'applicazione di SOURCE_SQL regole in *.ai_config.yaml file.
SQL di destinazione riscritto da Gemini dopo l'applicazione delle regole TARGET_SQL nei file *.ai_config.yaml.
Una spiegazione della traduzione da parte di Gemini quando i file *.ai_config.yaml includono regole TRANSLATION_EXPLANATION o quando richiedi una spiegazione on demand.

La posizione di questi output dipende da come esegui la traduzione:

Per trovare gli output quando traduci una singola query nella consoleGoogle Cloud o in gcloud CLI, consulta Esplora l'output della traduzione nella guida del traduttore SQL interattivo.
Per trovare gli output quando traduci file SQL batch in Cloud Storage o li esamini nella console Google Cloud , consulta Esplora l'output della traduzione nella guida al traduttore SQL batch.
Per trovare gli output quando utilizzi l'API BigQuery Migration, consulta Recupera i risultati nella guida dell'API BigQuery Migration. Per le traduzioni di singole query, aggiungi i percorsi di output che preferisci (sql/<var>PATH</var>, source_sql_query_customization_suggestion/<var>PATH</var>, target_sql_query_customization_suggestion/<var>PATH</var> o translation_explanation_suggestion/<var>PATH</var>) a target_return_literals per riceverli in translatedLiterals.
Per trovare gli output quando utilizzi il server MCP di BigQuery Migration Service, consulta Utilizza il server MCP di BigQuery Migration Service. Gli strumenti translate_query e get_translation restituiscono translatedQuery, sourceSqlSuggestion e targetSqlSuggestion, mentre lo strumento explain_translation restituisce una spiegazione della traduzione.

Requisiti dei file di traduzione `*.config.yaml`

Un file di traduzione *.config.yaml deve soddisfare i seguenti requisiti per essere compatibile con BigQuery Migration Service:

Quando carichi i file *.config.yaml nel percorso Cloud Storage di input per un job di traduzione batch, i file di configurazione posizionati in qualsiasi punto del percorso di input si applicano all'intero job. Non è necessario che si trovino a livello di directory principale o che vengano copiati in ogni sottodirectory. Per informazioni su come creare bucket e caricare file su Cloud Storage, consulta Crea bucket e Carica oggetti da un file system.
Le dimensioni di un singolo file *.config.yaml non devono superare 1 MB.
Le dimensioni totali di tutti i file *.config.yaml utilizzati in un singolo job di traduzione SQL non devono superare i 4 MB.
Se utilizzi la sintassi regex per la corrispondenza dei nomi, utilizza RE2/J.
Tutti i nomi dei file di configurazione della traduzione devono terminare con .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 *.config.yaml deve includere un'intestazione type di primo livello che specifica la categoria delle regole di configurazione nel file:

object_rewriter: riscrive le proprietà relation, ad esempio temporary, ephemeral, partitionLifetime, external, description, partition e clustering, e i tipi di dati attribute (type).
experimental_object_rewriter: riscrive i nomi degli oggetti di output con outputName in global, database, schema, relation, attribute, function, index, sequence, variable e projection e converte i tipi di dati a livello globale con global.typeConvert. Per saperne di più, consulta Mappatura dei nomi di output e Conversione dei tipi globali.
environment: imposta i valori predefiniti a livello di sessione in session, ad esempio defaultDatabase, schemaSearchPath e dateFormat.
metadata: dichiara le firme funzione definita dall'utente dall'utente (UDF) (udfs) e rimuove i prefissi, i suffissi o i pattern di espressioni regolari dei nomi di input durante la ricerca dei metadati (nameAlias).
statement_rewriter: personalizza l'output dell'istruzione, ad esempio l'espansione di SELECT *, la formattazione di GROUP BY e ORDER BY (select) e la precisione decimale o della stringa (common).
input_formats: specifica la codifica dei caratteri dei file SQL di input (formats).
optimizer: attiva, disattiva o configura le ottimizzazioni delle query facoltative (transformations).

L'esempio seguente utilizza il tipo experimental_object_rewriter per convertire tutti i nomi degli oggetti di output in lettere maiuscole:

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

Selezione delle entità

Per eseguire trasformazioni specifiche per le entità, specifica l'entità SQL di origine nel file di configurazione. Tutte le proprietà match sono facoltative; utilizza solo le proprietà match necessarie per una trasformazione. Il campo match viene confrontato con i nomi degli oggetti di origine dopo aver risolto eventuali defaultDatabase e schemaSearchPath configurati, ad eccezione delle regole outputName quando è configurato anche global.outputName. Per saperne di più, consulta Mappatura dei nomi di output. Il seguente YAML di configurazione espone le proprietà da abbinare 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: corrisponde al nome del database di origine, che corrisponde al componente project_id in BigQuery.
schema: corrisponde al nome dello schema di origine, che corrisponde al componente dataset in BigQuery.
relation: : corrisponde al nome della tabella o della vista di origine.
attribute: corrisponde al nome della colonna di origine. Questa proprietà è valida solo per la selezione di attribute.
databaseRegex o dbRegex: confronta l'intero nome database con un'espressione regolare senza distinzione tra maiuscole e minuscole.
schemaRegex: confronta l'intero nome schema con un'espressione regolare senza distinzione tra maiuscole e minuscole.
relationRegex: confronta l'intero nome relation con un'espressione regolare senza distinzione tra maiuscole e minuscole.
attributeRegex: confronta l'intero nome attribute con un'espressione regolare senza distinzione tra maiuscole e minuscole. Questa proprietà è valida solo per la selezione di attribute.

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

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, purché il nome inizi con tmp_:

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

La corrispondenza delle proprietà letterali e regex viene trovata senza distinzione tra maiuscole e minuscole. Puoi applicare la corrispondenza sensibile alle maiuscole utilizzando un regex con un flag i disattivato, come mostrato nell'esempio seguente:

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

Puoi anche specificare entità con nome completo 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 quindi interpretati internamente come se fossero passati rispettivamente come database, schema, relation e attribute. Ciò significa che i nomi vengono abbinati letteralmente, pertanto le espressioni regolari non sono consentite nella sintassi breve. L'esempio seguente mostra l'utilizzo della sintassi di stringa breve per specificare un'entità con nome completo in un file YAML di configurazione:

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

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

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

Un file YAML di configurazione accetta anche key come alias per match. Sia key che match supportano i campi secondari espliciti dei componenti del nome, nonché la sintassi della stringa breve "database.schema.relation" o "database.schema.relation.attribute" delimitata da punti. Per convenzione, key viene spesso utilizzato con la sintassi della stringa breve e match con i campi secondari espliciti.

Database predefinito

Alcuni dialetti SQL di input, in particolare Teradata, non supportano un nome di database negli identificatori qualificati (schema.table). In questo caso, utilizza un oggetto match e ometti la proprietà database. In alternativa, configura defaultDatabase, ad esempio in type: environment, in modo da poter eseguire la corrispondenza con il database predefinito nelle regole match di oggetti o stringhe brevi.

Tipi di attributi target supportati

Puoi utilizzare il file YAML di configurazione per eseguire trasformazioni del tipo di attributo, in cui trasformi 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 precisione e 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, insieme 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 BigQuery.

I seguenti esempi utilizzano Teradata o Apache Hive come dialetto SQL di input e BigQuery SQL come dialetto di output.

Modifica maiuscole/minuscole del nome dell'oggetto

Il seguente file YAML di configurazione modifica le maiuscole/minuscole dei nomi degli oggetti SQL in UPPERCASE o LOWERCASE. Puoi impostare case sugli oggetti all o eseguirne l'override per tipi di oggetti specifici (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 traduzione SQL con questo file YAML di configurazione potrebbe avere il seguente aspetto:

`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 ;

Rendi temporanea la tabella

Il seguente YAML di configurazione modifica una tabella normale in una tabella temporanea:

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 testdb.testschema.x(a int);
`bq-output.sql`	CREATE TEMPORARY TABLE x ( a INT64 ) ;

Rendi la tabella temporanea

Il seguente YAML di configurazione modifica una tabella normale in una tabella temporanea con una 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 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) );

Imposta la scadenza della partizione

Il seguente YAML di configurazione modifica la scadenza di una tabella partizionata 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 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 );

Modifica la posizione o il formato esterno di una tabella

La seguente configurazione YAML modifica la posizione e il formato esterni di 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 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' ] );

Imposta o modifica la descrizione della tabella

Il seguente 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 testdb.testschema.x(a int);
`bq-output.sql`	CREATE TABLE testdb.testschema.x ( a INT64 ) OPTIONS( description='Example description.' );

Imposta o modifica il partizionamento delle tabelle

Il seguente YAML di configurazione modifica lo schema di partizionamento di una tabella utilizzando add, remove o set, dove set sostituisce le colonne di partizione esistenti:

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 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
    )
    ;

Il seguente YAML di configurazione modifica lo schema di partizionamento di una tabella in modo che venga partizionato per bucket di intervallo:

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

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
      );

Imposta o modifica il clustering delle tabelle

Il seguente YAML di configurazione modifica lo schema di clustering di una tabella utilizzando add, remove o set, dove set sostituisce le colonne di clustering esistenti:

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 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
    )
    ;

Modifica il tipo di un attributo di colonna

Il seguente YAML di configurazione modifica il tipo di dati per 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 qualsiasi dei tipi di attributi di destinazione supportati.

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

`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) ) ;

Quando non esiste un cast diretto tra i tipi di origine e di destinazione, ad esempio quando converti una colonna INT che memorizza date YYYYMMDD in una colonna DATE, fornisci espressioni di conversione GoogleSQL sourceToTarget e targetToSource. Utilizza ? come segnaposto per il valore della colonna o dell'espressione. Ad esempio:

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

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
    ;

Aggiungi connessione al data lake esterno

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

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

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

`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( );

Modifica 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 potrebbe 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 dei caratteri esplicita del file di input come ISO-8859-1. Puoi trovare corrispondenze per i file di input utilizzando un percorso esatto (path), un pattern glob (pathGlob) o un'espressione regolare (pathRegex):

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

Conversione del tipo globale

Il seguente 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 transpilato. Questa opzione è diversa dalla configurazione Modifica il tipo di un attributo di colonna, in cui viene modificato solo il tipo di dati per un singolo attributo.

Il servizio di traduzione supporta le seguenti conversioni dei tipi di dati:

Da DATETIME a TIMESTAMP
Da TIMESTAMP a DATETIME (accetta il fuso orario facoltativo)
TIMESTAMP WITH TIME ZONE (timestamptz) fino a DATETIME (accetta il fuso orario facoltativo)
CHAR a VARCHAR (accetta precisionAction e comparisonBehavior facoltativi)
Da VARCHAR a VARCHAR (accetta precisionAction e comparisonBehavior facoltativi)

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

type: experimental_object_rewriter
global:
  typeConvert:
    timestamp: DATETIME

Converti i tipi `CHAR` e `VARCHAR`

In dialetti come Teradata, i valori CHAR(N) vengono completati a destra con spazi e le scritture di stringhe vengono troncate alla lunghezza della colonna dichiarata. I confronti tra stringhe non fanno distinzione tra maiuscole e minuscole (NOT CASESPECIFIC) per impostazione predefinita e ignorano gli spazi finali. Per impostazione predefinita, il motore di traduzione emula questa semantica in BigQuery. Aggiunge wrapper di spaziatura interna a destra (CONCAT) e troncamento (SUBSTR) su cast e scritture, wrapper UPPER e RTRIM su confronti e wrapper UPPER su chiavi GROUP BY.

Puoi configurare i campi char e varchar in global.typeConvert con le seguenti proprietà:

target: deve essere impostato su VARCHAR. La configurazione di target: VARCHAR su char rimuove il padding a destra di CHAR (CONCAT) anche quando precisionAction è PRESERVE.
precisionAction: controlla la precisione della lunghezza dei caratteri e i wrapper di troncamento SUBSTR:
- PRESERVE (valore predefinito): mantiene la precisione della lunghezza dei caratteri nelle espressioni ed emette wrapper di troncamento SUBSTR durante la conversione o l'inserimento in colonne CHAR(N) o VARCHAR(N). Per generare anche le lunghezze delle colonne STRING(N) nel DDL CREATE TABLE, consulta Impostazione della severità della precisione delle stringhe.
- DROP: elimina la precisione della lunghezza dei caratteri nelle espressioni e omette i wrapper di troncamento SUBSTR.
comparisonBehavior: controlla i wrapper RTRIM e UPPER per i confronti e le chiavi GROUP BY. L'impostazione di un valore diverso da STRICT su char o varchar si applica a entrambi i tipi, quindi imposta lo stesso valore su entrambe le chiavi quando configuri entrambe:
- STRICT (predefinito): emula sia la spaziatura interna con spazi finali (RTRIM) sia la regole di confronto senza distinzione tra maiuscole e minuscole (UPPER).
- PADDING_AWARE: emula solo la spaziatura interna con spazi finali (RTRIM) e omette UPPER.
- CASE_AWARE: emula solo la regole di confronto senza distinzione tra maiuscole e minuscole (UPPER) e omette RTRIM.
- NONE: omette i wrapper RTRIM e UPPER, quindi l'output utilizza confronti diretti ed espressioni GROUP BY.

Il seguente YAML di configurazione converte CHAR in VARCHAR e rimuove i wrapper di troncamento (SUBSTR), spazio finale (RTRIM) e senza distinzione tra maiuscole e minuscole (UPPER) per le colonne CHAR e VARCHAR:

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

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

`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 ;

Impostazione del fuso orario predefinito

I dialetti dei database hanno semantiche e nomi diversi per i vari tipi di dati relativi a data e ora. Il servizio di traduzione standardizza la seguente terminologia nella configurazione YAML, indipendentemente dal nome del tipo di dati del dialetto di input:

Un datetime è una combinazione di Y-M-D H:M:S che non è fissata a un fuso orario specifico. datetime rappresenta un'ora dell'orologio e non un istante specifico.
Un timestamp rappresenta un istante di tempo particolare o assoluto e, in quanto tale, è implicitamente fissato a un fuso orario particolare, che potrebbe essere un'impostazione a livello di sessione o di database.
Un timestamptz rappresenta un istante particolare come un timestamp, ma, a differenza di un timestamp, porta con sé un offset di fuso orario particolare. Anche se rappresentano lo stesso istante, 2019-06-01 12:00:00+4 e 2019-06-01 06:00:00-2 sono considerati valori timestamptz diversi.

In dialetti come Teradata, le funzioni relative a data e ora come current_date, current_time o current_timestamp restituiscono timestamp basati su un parametro del fuso orario della sessione configurato in modo implicito. BigQuery, invece, restituisce sempre i timestamp in UTC. Per garantire un comportamento coerente tra i due dialetti, potrebbe essere necessario configurare un fuso orario di conseguenza.

Ti consigliamo di specificare il fuso orario predefinito per la traduzione se il tuo database di origine ha un valore predefinito diverso da UTC. In questo modo, il comportamento della query tradotta sarà corretto, poiché il fuso orario verrà conservato.

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

Per i valori di stringa validi per i fusi orari, consulta Fusi orari.

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:

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')
      ;

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

Per impostazione predefinita, TIMESTAMPTZ viene convertito in TIMESTAMP senza che sia necessaria alcuna configurazione.

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

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

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()
      ;

Seleziona la modifica dell'estratto conto

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

Il campo select.starProjection supporta i valori seguenti:

ALLOW: genera SELECT * quando la query di origine utilizza SELECT * o elenca tutte le colonne della tabella in ordine.
PRESERVE (predefinito): genera SELECT * solo quando la query di origine utilizza SELECT *.
EXPAND: espande SELECT * in singoli riferimenti di colonna quando sono disponibili i metadati della tabella.

I campi select.groupBy e select.orderBy supportano i valori seguenti:

EXPRESSION: formatta GROUP BY o ORDER BY elementi come espressioni complete.
ALIAS: formatta GROUP BY o ORDER BY elementi utilizzando gli alias di colonna SELECT, se disponibili.
INDEX: formatta gli elementi GROUP BY o ORDER BY utilizzando le posizioni delle colonne basate su 1, ad esempio GROUP BY 1.

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

type: 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 TIMESTAMP ) ; SELECT x.a, x.b FROM x ;

Specifica UDF

Nella maggior parte dei casi, il traduttore SQL di BigQuery può analizzare automaticamente il linguaggio di definizione dei dati (DDL) delle funzioni definite dall'utente (UDF) esterne per determinare i tipi di dati di input e output, anche se il corpo della UDF è scritto in un linguaggio esterno. Tuttavia, per alcuni dialetti di origine, il traduttore potrebbe non essere in grado di compilare automaticamente la firma della funzione definita dall'utente. Per garantire che le istruzioni SQL che fanno riferimento a queste funzioni definite dall'utente vengano tradotte in modo accurato senza dover fornire il DDL originale, puoi utilizzare un file di configurazione YAML per registrare esplicitamente le firme delle funzioni definite dall'utente.

Il seguente YAML di configurazione specifica la firma delle funzioni definite dall'utente (UDF) utilizzate negli script di origine. Specifica ogni firma nel dialetto di origine come RETURN_TYPE FUNCTION_NAME(ARG_NAME ARG_TYPE, ...), incluso un nome per ogni parametro. Analogamente ai file ZIP dei metadati, le definizioni delle funzioni definite dall'utente possono aiutare 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(dt), interval 1 DAY) FROM x ;

Alcuni dialetti di origine supportano le funzioni definite dall'utente che condividono un nome tra diverse firme di argomenti, a volte chiamate funzioni definite dall'utente sovraccaricate. Per le funzioni definite dall'utente sovraccaricate, specifica udf e un name di destinazione distinto in modo che ogni firma venga mappata a un nome di funzione univoco in BigQuery:

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

Rimuovi i pattern degli identificatori durante la ricerca dei metadati

Gli script SQL di input potrebbero fare riferimento a oggetti o colonne con un prefisso, un suffisso o un pattern di denominazione che non è presente nelle definizioni dei metadati, ad esempio facendo riferimento a a_dt quando il DDL dei metadati definisce la colonna dt. In questo caso, utilizza nameAlias in type: metadata in modo che il motore di traduzione rimuova il pattern durante la ricerca dei nomi degli oggetti nei metadati. L'identificatore originale viene conservato nell'SQL di output.

Il campo nameAlias supporta le seguenti proprietà. Ogni proprietà accetta una singola stringa o un elenco di stringhe e viene applicata la prima voce corrispondente in ogni elenco:

stripPrefix: rimuove un prefisso letterale prima di cercare i metadati.
stripSuffix: rimuove un suffisso letterale prima di cercare i metadati.
stripRegex: corrisponde a un'espressione regolare sensibile alle maiuscole e sostituisce ogni sottostringa corrispondente con il primo gruppo Capture (...) durante la ricerca al volo dei metadati. Ancora il pattern, ad esempio ^a_(.*)$, in modo che corrisponda solo a un prefisso o all'identificatore completo.

Il seguente file YAML di configurazione rimuove la dicitura a_ iniziale dagli identificatori durante la ricerca al volo dei nomi degli oggetti nei metadati:

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

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

`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 ;

Impostazione della precisione decimale

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

type: 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) ) ;

Impostazione della precisione delle stringhe

Per impostazione predefinita, BigQuery Migration Service omette la precisione delle stringhe durante la traduzione delle colonne CHAR e VARCHAR. In questo modo, puoi evitare errori di troncamento durante la scrittura dei valori. Alcuni dialetti SQL, come Teradata, troncano i valori che superano la precisione massima in scrittura, mentre BigQuery restituisce un errore in questo scenario.

Se la tua applicazione non si basa sul comportamento di troncamento del dialetto di origine, valuta la possibilità di preservare la precisione della colonna nella definizione del tipo tradotto.

Il seguente YAML di configurazione esegue l'override di questo comportamento configurando la severità della precisione in modo da mantenere la precisione della stringa dell'istruzione di origine.

type: statement_rewriter
common:
  stringPrecision: STRICT

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

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

Mappatura dei nomi di output

Puoi utilizzare type: experimental_object_rewriter in un file YAML di configurazione per mappare i nomi degli oggetti SQL (database, schema, relation, attribute, function, sequence, index, variable o projection) in modo statico o dinamico:

Ogni tipo di oggetto espande solo i segnaposto del proprio nome e della gerarchia principale da ${database}, ${schema}, ${relation}, ${attribute}, ${function}, ${sequence}, ${index}, ${variable} e ${projection}. Ad esempio, una regola schema espande ${database} e ${schema}, mentre una regola relation espande ${database}, ${schema} e ${relation}.
Quando più regole dello stesso tipo di oggetto con criteri match distinti corrispondono a un oggetto, viene applicata l'ultima regola corrispondente nell'elenco.
Le regole globali replace e case in global.outputName vengono eseguite prima delle regole outputName specifiche per l'oggetto. Una regola specifica per l'oggetto corrisponde e può eseguire l'override del nome trasformato a livello globale del relativo oggetto. Per le regole attribute, match esegue il confronto con il nome attribute trasformato a livello globale insieme ai nomi database, schema e relation di origine. Per saperne di più, consulta Riscrittura del nome di output globale.

Per ulteriori informazioni sul funzionamento delle regole di mappatura dei nomi a livello di database, schema, relazione, funzione e attributo, consulta Mappa i nomi degli oggetti SQL per la traduzione.

Mappatura dei nomi statica

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

Il seguente YAML di configurazione modifica 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 funzione definita dall'utente bqutil.fn per utilizzare la regione europe_west2 anziché la multi-regione us predefinita:

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

Mappatura dinamica dei nomi

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

Il seguente YAML di configurazione modifica il nome di tutte le tabelle aggiungendo il prefisso stg_ a quelle che appartengono allo schema staging, quindi 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 ) ;

Mappatura dei nomi delle colonne

Utilizza la sezione attribute in type: experimental_object_rewriter per rinominare le colonne sia nelle definizioni delle tabelle sia nei riferimenti alle query:

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

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

`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 ;

Specifica del database predefinito e del percorso di ricerca dello schema

Il seguente 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 mydb.mytable; SELECT * FROM table1;
`bq-output.sql`	SELECT * FROM myproject.mydb.mytable; SELECT * FROM myproject.myschema1.table1;

Configurazione di `NLS_DATE_FORMAT` in corso…

Il seguente YAML di configurazione imposta il parametro NLS_DATE_FORMAT sul formato DD/MM/YYYY. Ti consigliamo di specificare NLS_DATE_FORMAT per gli utilizzi impliciti di formati e cast di date. Se non viene impostato, viene utilizzato il formato predefinito per la traduzione, DD-MON-RR.

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

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

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')
      ;

Riscrittura del nome dell'output globale

Il seguente YAML di configurazione utilizza le regole replace in global.outputName per riscrivere i nomi di output di tutti gli oggetti (all) o di tipi di oggetti specifici (database, schema, relation, attribute, function, sequence, index, variable o projection). Ogni regola corrisponde a un'espressione regolare sensibile alle maiuscole e sostituisce le corrispondenze con un nuovo testo, inclusi $0, $1 e altri gruppi Capture.

Le trasformazioni outputName globali (replace seguite da case) vengono eseguite prima delle regole outputName specifiche per l'oggetto, come schema, relation o attribute. Una regola specifica per un oggetto corrisponde al nome trasformato a livello globale dell'oggetto e può eseguirne l'override. Per le regole attribute, match esegue il confronto con il nome attribute trasformato a livello globale insieme ai nomi database, schema e relation di origine:

type: experimental_object_rewriter
global:
  outputName:
    all:
      replace:
        - regex: '\s'
          replaceWith: '_'
        - regex: '>='
          replaceWith: 'gte'
        - regex: '^[^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_gte_12 ( _42eid INT64, custom_column STRING ) ;

Ottimizza e migliora le prestazioni dell'SQL tradotto

È possibile applicare trasformazioni facoltative all'SQL tradotto per introdurre modifiche che possono migliorare le prestazioni o i costi. Queste ottimizzazioni dipendono rigorosamente dal caso e devono essere valutate rispetto all'output SQL non modificato per valutarne l'effetto effettivo sulle prestazioni.

Il seguente YAML di configurazione abilita le trasformazioni facoltative. Ogni voce nell'elenco transformations supporta i seguenti campi:

name: il nome dell'ottimizzazione.
enabled (facoltativo): un valore booleano il cui valore predefinito è true. Imposta enabled su false per disattivare un'ottimizzazione attivata per impostazione predefinita per il dialetto di origine.
parameters (facoltativo): una mappa di parametri specifici per l'ottimizzazione.

type: 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]`	Riscrive la query aggiungendo un'istruzione `DECLARE` per sostituire un'espressione nelle clausole `PREDICATE`, nelle clausole `PROJECTION` o in entrambe con una variabile precalcolata. Questa riscrittura trasforma l'espressione in un predicato statico che può ridurre la quantità di dati letti. Il parametro `scope` accetta un elenco contenente `PREDICATE`, `PROJECTION` o entrambi. Se `parameters` viene omesso, `scope` assume il valore predefinito `[PREDICATE]`, che copre le clausole `WHERE` e `JOIN ON`. Estrazione di una sottoquery scalare in un`DECLARE` L'istruzione renderà statico il predicato originale e quindi idoneo per una migliore pianificazione dell'esecuzione. Questa ottimizzazione introdurrà nuove istruzioni SQL.
`REWRITE_CTE_TO_TEMP_TABLE`	`threshold: N`	Riscrive le espressioni di tabella comuni (CTE) in tabelle temporanee quando sono presenti almeno `N` riferimenti alla stessa CTE. Questa riscrittura riduce la complessità della query e forza l'esecuzione singola della CTE. Se `N` viene omesso, il valore predefinito è `4`. Ti consigliamo di utilizzare questa ottimizzazione quando si fa riferimento più volte a CTE non banali. L'introduzione di tabelle temporanee comporta un overhead che potrebbe essere maggiore di eventuali esecuzioni multiple di una CTE a bassa complessità o bassa cardinalità. Questa ottimizzazione introdurrà nuove istruzioni SQL.
`REWRITE_ZERO_SCALE_NUMERIC_AS_INTEGER`	`bigint: N`	Riscrive gli attributi `NUMERIC/BIGNUMERIC` con scala zero nel tipo `INT64` se la precisione rientra in `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 di numeri interi. La modifica dei tipi di colonna richiede la revisione di tutti gli utilizzi downstream per la compatibilità dei tipi e le modifiche semantiche. Ad esempio, le divisioni frazionarie diventano divisioni intere o il codice prevede valori numerici. Le traduzioni di Snowflake hanno questa ottimizzazione per i valori numerici con scala zero fino alla precisione 38 abilitata per impostazione predefinita. Questa ottimizzazione garantisce che un `INTEGER` Snowflake, rappresentato implicitamente come `NUMBER(38,0)` in Snowflake, venga tradotto in un `INT64` BigQuery anziché in un `BIGNUMERIC(38)`. Se la tua applicazione utilizza numeri con precisioni superiori a 18, ti consigliamo di disattivare questa funzionalità per assicurarti che BigQuery possa elaborare l'intera gamma di valori necessari per la tua applicazione.
`DROP_TEMP_TABLE`		Aggiunge istruzioni `DROP TABLE` per tutte le tabelle temporanee create in uno script e non eliminate alla fine dello script. 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. Ti consigliamo di utilizzare questa ottimizzazione quando non viene eseguito l'accesso alle tabelle temporanee per ulteriori elaborazioni dopo il termine dell'esecuzione dello script. Questa ottimizzazione introdurrà nuove istruzioni SQL.
`REGEXP_CONTAINS_TO_LIKE`		Riscrive 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 di macro, si basa sulla conservazione invariata dei valori letterali del pattern di espressione regolare nell'SQL di output.
`ADD_DISTINCT_TO_SUBQUERY_IN_SET_COMPARISON`		Aggiunge la clausola `DISTINCT` alle sottoquery utilizzate come set di valori per l'operatore `[NOT] IN`. Ti consigliamo di utilizzare questa ottimizzazione quando la cardinalità (numero distinto di valori) del risultato della sottoquery è significativamente inferiore al numero di valori. Se questa precondizione non viene soddisfatta, questa trasformazione può avere effetti negativi sulle prestazioni.
`APPROXIMATE_RANGE_PARTITIONS`		Approssima gli schemi di partizionamento di numeri interi non contigui o non regolari convertendoli in intervalli di partizione contigui di dimensioni uguali supportati da BigQuery. Per impostazione predefinita, questi schemi di partizionamento non influiscono sullo schema di partizionamento della tabella nelle istruzioni DDL tradotte. Ti consigliamo di utilizzare questa ottimizzazione quando la tabella di origine utilizza una funzione di partizionamento non contigua come la funzione `RANGE_N` di Teradata e trarrebbe vantaggio da uno schema di partizione di dimensioni uguali in BigQuery.

Esempi di ottimizzazione

La seguente ottimizzazione converte i tipi numerici con scala zero e precisione inferiore o uguale a 38 in INT64 in 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 traduzione SQL con questa ottimizzazione potrebbe essere simile alla seguente:

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

La seguente configurazione disattiva l'ottimizzazione nei dialetti, come Snowflake, in cui è attivata per impostazione predefinita. Questa configurazione converte i tipi numerici in NUMERIC o BIGNUMERIC a seconda della precisione di input, anziché nel valore predefinito di INT64.

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

Una traduzione SQL con questa ottimizzazione potrebbe essere simile alla seguente:

`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 file YAML di configurazione basato su Gemini

Per generare l'output dell'AI, fornisci almeno un file *.ai_config.yaml e attiva i suggerimenti di Gemini AI quando l'interfaccia lo richiede. Per saperne di più, consulta Fornisci i file di configurazione per una traduzione.

Requisiti

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

Campi supportati

A differenza di un file *.config.yaml, un file *.ai_config.yaml non include un'intestazione type. Il file contiene invece un elenco translation_rules di primo livello, in cui ogni regola supporta i seguenti campi:

suggestion_type (facoltativo): specifica il tipo di suggerimento AI da generare. Sono supportati i seguenti tipi di suggerimenti:
- QUERY_CUSTOMIZATION (predefinito): genera suggerimenti AI per il codice SQL in base alle regole di traduzione specificate nel file *.ai_config.yaml.
- 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.
rewrite_target (facoltativo): specifica SOURCE_SQL per applicare la regola all'SQL di input originale prima dell'esecuzione del motore di traduzione o TARGET_SQL per applicare la regola all'SQL tradotto prodotto dal motore di traduzione. Il valore predefinito è TARGET_SQL. Per saperne di più, consulta Come vengono applicati i due tipi di regole.
instruction (facoltativo): descrivi in linguaggio naturale la modifica da applicare all'SQL di input o all'SQL tradotto per le regole QUERY_CUSTOMIZATION o la spiegazione da generare per le regole TRANSLATION_EXPLANATION.
examples (facoltativo): fornisci un elenco di coppie SQL input e output che mostrano come vuoi che venga modificato un pattern SQL.

Puoi aggiungere altri translation_rules e altri examples in base alle tue esigenze.

Esempi

I seguenti esempi creano file YAML di configurazione basati su Gemini che puoi utilizzare con le tue traduzioni SQL.

Rimuovi la funzione UPPER nella query di output della traduzione predefinita

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

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

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

Rimuovi i commenti SQL dalla query di input della traduzione

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

Genera spiegazioni della traduzione utilizzando il prompt LLM predefinito

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

translation_rules:
- suggestion_type: "TRANSLATION_EXPLANATION"

Genera spiegazioni delle traduzioni utilizzando i tuoi prompt in linguaggio naturale

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

Più tipi di suggerimenti in un unico file YAML di configurazione

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

Applicazione di più configurazioni YAML

Quando traduci una singola query o file SQL batch, puoi fornire più file YAML di configurazione in un singolo job di traduzione per riflettere più trasformazioni. Se più configurazioni sono in conflitto, una trasformazione potrebbe eseguire l'override di un'altra. Ti consigliamo di utilizzare tipi diversi di impostazioni di configurazione in ogni file per evitare trasformazioni in conflitto nello stesso job di traduzione.

L'esempio seguente elenca due file YAML di configurazione separati 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 testdb.testschema.x(a int);
`bq-output.sql`	CREATE TEMPORARY TABLE x ( a NUMERIC(31, 2) ) ;

Trasforma le traduzioni SQL con YAML

Tipi di file YAML di configurazione

Come vengono applicati i due tipi di regole

Fornisci i file di configurazione per una traduzione

Console

gcloud

API

MCP

Dove trovare gli output della traduzione

Requisiti dei file di traduzione *.config.yaml

Linee guida per creare un file YAML di configurazione

Intestazione

Selezione delle entità

Database predefinito

Tipi di attributi target supportati

Esempi di file YAML di configurazione

Modifica maiuscole/minuscole del nome dell'oggetto

Rendi temporanea la tabella

Rendi la tabella temporanea

Imposta la scadenza della partizione

Modifica la posizione o il formato esterno di una tabella

Imposta o modifica la descrizione della tabella

Imposta o modifica il partizionamento delle tabelle

Imposta o modifica il clustering delle tabelle

Modifica il tipo di un attributo di colonna

Aggiungi connessione al data lake esterno

Modifica la codifica dei caratteri di un file di input

Conversione del tipo globale

Converti i tipi CHAR e VARCHAR

Impostazione del fuso orario predefinito

Seleziona la modifica dell'estratto conto

Specifica UDF

Rimuovi i pattern degli identificatori durante la ricerca dei metadati

Impostazione della precisione decimale

Impostazione della precisione delle stringhe

Mappatura dei nomi di output

Mappatura dei nomi statica

Mappatura dinamica dei nomi

Mappatura dei nomi delle colonne

Specifica del database predefinito e del percorso di ricerca dello schema

Configurazione di NLS_DATE_FORMAT in corso…

Riscrittura del nome dell'output globale

Ottimizza e migliora le prestazioni dell'SQL tradotto

Esempi di ottimizzazione

Crea un file YAML di configurazione basato su Gemini

Requisiti

Campi supportati

Esempi

Rimuovi la funzione UPPER nella query di output della traduzione predefinita

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

Rimuovi i commenti SQL dalla query di input della traduzione

Genera spiegazioni della traduzione utilizzando il prompt LLM predefinito

Genera spiegazioni delle traduzioni utilizzando i tuoi prompt in linguaggio naturale

Più tipi di suggerimenti in un unico file YAML di configurazione

Applicazione di più configurazioni YAML

Requisiti dei file di traduzione `*.config.yaml`

Converti i tipi `CHAR` e `VARCHAR`

Configurazione di `NLS_DATE_FORMAT` in corso…