Mentransformasi terjemahan SQL menggunakan file YAML konfigurasi

Dokumen ini menunjukkan cara menggunakan file YAML konfigurasi untuk mentransformasi kode SQL saat memigrasikannya ke BigQuery. Halaman ini memberikan panduan untuk membuat file YAML konfigurasi Anda sendiri, dan memberikan contoh untuk berbagai transformasi terjemahan yang didukung oleh fitur ini.

Saat menggunakan penerjemah SQL interaktif BigQuery, menggunakan BigQuery Migration API, atau melakukan terjemahan SQL batch, Anda dapat memberikan file YAML konfigurasi untuk mengubah terjemahan kueri SQL. Penggunaan file YAML konfigurasi memungkinkan penyesuaian lebih lanjut saat menerjemahkan kueri SQL dari database sumber.

Anda dapat menentukan file YAML konfigurasi untuk digunakan dalam terjemahan SQL dengan cara berikut:

Penerjemah SQL interaktif, BigQuery Migration API, penerjemah SQL batch, dan klien Python terjemahan batch mendukung penggunaan beberapa file YAML konfigurasi dalam satu tugas terjemahan. Lihat Menerapkan beberapa konfigurasi YAML untuk mengetahui informasi selengkapnya.

Persyaratan file YAML konfigurasi

Sebelum membuat file YAML konfigurasi, tinjau informasi berikut untuk memastikan bahwa file YAML kompatibel untuk digunakan dengan BigQuery Migration Service:

  • Anda harus mengupload file YAML konfigurasi ke direktori utama bucket Cloud Storage yang berisi file input terjemahan SQL. Untuk informasi tentang cara membuat bucket dan mengupload file ke Cloud Storage, lihat Membuat bucket dan Mengupload objek dari sistem file.
  • Ukuran file untuk satu file YAML konfigurasi tidak boleh melebihi 1 MB.
  • Ukuran total file semua file YAML konfigurasi yang digunakan dalam satu tugas terjemahan SQL tidak boleh melebihi 4 MB.
  • Jika Anda menggunakan sintaksis regex untuk pencocokan nama, gunakan RE2/J.
  • Semua nama file YAML konfigurasi harus menyertakan ekstensi .config.yaml—misalnya, change-case.config.yaml.
    • config.yaml saja bukan nama yang valid untuk file konfigurasi.

Panduan untuk membuat file YAML konfigurasi

Bagian ini memberikan beberapa panduan umum untuk membuat file YAML konfigurasi:

Setiap file konfigurasi harus berisi header yang menentukan jenis konfigurasi. Jenis object_rewriter digunakan untuk menentukan terjemahan SQL dalam file YAML konfigurasi. Contoh berikut menggunakan jenis object_rewriter untuk mengubah kapitalisasi nama:

type: object_rewriter
global:
  case:
    all: UPPERCASE

Pemilihan entity

Untuk melakukan transformasi khusus entity, tentukan entity di file konfigurasi. Semua properti match bersifat opsional; hanya gunakan properti match yang diperlukan untuk transformasi. YAML konfigurasi berikut mengekspos properti yang akan dicocokkan untuk memilih entity tertentu:

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

Deskripsi setiap properti match:

  • database atau db: komponen project_id.
  • schema: komponen set data.
  • relation: komponen tabel.
  • attribute: komponen kolom. Hanya valid untuk pemilihan atribut
  • databaseRegex atau dbRegex: mencocokkan properti database dengan ekspresi reguler (Pratinjau).
  • schemaRegex: mencocokkan properti schema dengan ekspresi reguler (Pratinjau).
  • relationRegex: mencocokkan properti relation dengan ekspresi reguler (Pratinjau).
  • attributeRegex: mencocokkan properti attribute dengan ekspresi reguler. Hanya valid untuk pemilihan atribut (Pratinjau).

Misalnya, YAML konfigurasi berikut menentukan properti match guna memilih tabel testdb.acme.employee untuk transformasi tabel sementara.

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

Anda dapat menggunakan properti databaseRegex, schemaRegex, relationRegex, dan attributeRegex untuk menentukan ekspresi reguler agar dapat memilih subset entity. Contoh berikut mengubah semua hubungan dari skema tmp_schema di testdb menjadi sementara, selama namanya dimulai dengan tmp_:

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

Properti literal dan regex dicocokkan tanpa peka huruf besar/kecil. Anda dapat menerapkan pencocokan peka huruf besar/kecil menggunakan regex dengan flag i yang dinonaktifkan, seperti yang terlihat dalam contoh berikut:

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

Anda juga dapat menentukan entity yang sepenuhnya memenuhi syarat menggunakan sintaksis string pendek yang setara. Sintaksis string pendek mengharapkan tepat 3 segmen nama (untuk pemilihan relasi) atau 4 (untuk pemilihan atribut) yang dipisahkan dengan titik, sebagai contoh testdb.acme.employee. Segmen ini kemudian ditafsirkan secara internal seolah-olah diteruskan sebagai database, schema, relation, dan attribute. Artinya, nama dicocokkan secara harfiah, sehingga ekspresi reguler tidak diizinkan dalam sintaksis singkat. Contoh berikut menunjukkan penggunaan sintaksis string pendek untuk menentukan entity yang sepenuhnya memenuhi syarat dalam file YAML konfigurasi:

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

Jika tabel berisi titik dalam nama tabel, Anda tidak dapat menentukan nama tersebut menggunakan sintaksis singkat. Dalam hal ini, Anda harus menggunakan pencocokan objek. Contoh berikut mengubah tabel testdb.acme.stg.employee menjadi sementara:

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

YAML konfigurasi menerima key sebagai alias untuk match.

Database bawaan

Beberapa dialek SQL input, terutama Teradata, tidak mendukung database-name dalam nama yang memenuhi syarat. Dalam hal ini, cara termudah untuk mencocokkan entity adalah dengan menghilangkan properti database di match.

Namun, Anda dapat menetapkan properti default_database dari BigQuery Migration Service dan menggunakan database default tersebut di match.

Jenis atribut target yang didukung

Anda dapat menggunakan file YAML konfigurasi untuk melakukan transformasi jenis atribut, yaitu ketika Anda mentransformasi jenis data kolom dari jenis sumber ke jenis target. File YAML konfigurasi mendukung jenis target berikut:

  • BOOLEAN
  • TINYINT
  • SMALLINT
  • INTEGER
  • BIGINT
  • FLOAT
  • DOUBLE
  • NUMERIC (Mendukung presisi dan skala opsional, seperti NUMERIC(18, 2))
  • TIME
  • TIMETZ
  • DATE
  • DATETIME
  • TIMESTAMP
  • TIMESTAMPTZ
  • CHAR (Mendukung presisi opsional, seperti CHAR(42))
  • VARCHAR (Mendukung presisi opsional, seperti VARCHAR(42))

Contoh YAML konfigurasi

Bagian ini menyediakan contoh untuk membuat berbagai file YAML konfigurasi untuk digunakan dengan terjemahan SQL. Setiap contoh menguraikan sintaks YAML untuk mentransformasi terjemahan SQL Anda dengan cara tertentu, beserta deskripsi singkat. Setiap contoh juga menyediakan konten file teradata-input.sql atau hive-input.sql dan file bq-output.sql, sehingga Anda dapat membandingkan efek YAML konfigurasi pada terjemahan kueri SQL BigQuery.

Contoh berikut menggunakan Teradata atau Hive sebagai dialek SQL input dan BigQuery SQL sebagai dialek output. Contoh berikut juga menggunakan testdb sebagai database default, dan testschema sebagai jalur penelusuran skema.

Mengubah kapitalisasi nama objek

YAML konfigurasi berikut mengubah huruf besar atau kecil pada nama objek:

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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
      ;

Membuat tabel menjadi sementara

YAML konfigurasi berikut mengubah tabel reguler menjadi tabel sementara:

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Membuat tabel menjadi efemeral

YAML konfigurasi berikut mengubah tabel reguler menjadi tabel efemeral dengan masa berlaku 60 detik.

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Menetapkan akhir masa berlaku partisi

YAML konfigurasi berikut mengubah akhir masa berlaku tabel berpartisi menjadi 1 hari:

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Mengubah lokasi atau format eksternal untuk tabel

YAML konfigurasi berikut mengubah lokasi dan formasi eksternal untuk tabel:

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Menetapkan atau mengubah deskripsi tabel

YAML konfigurasi berikut menetapkan deskripsi tabel:

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Menetapkan atau mengubah partisi tabel

YAML konfigurasi berikut mengubah skema partisi tabel:

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Menetapkan atau mengubah pengelompokan tabel

YAML konfigurasi berikut mengubah skema pengelompokan tabel:

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Mengubah jenis atribut kolom

YAML konfigurasi berikut mengubah jenis data untuk atribut kolom:

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

Anda dapat mengubah jenis data sumber ke salah satu jenis atribut target yang didukung.

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Menambahkan koneksi ke data lake eksternal

YAML konfigurasi berikut menandai tabel sumber sebagai tabel eksternal yang mengarah ke data yang disimpan di data lake eksternal, yang ditentukan oleh koneksi data lake.

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Mengubah encoding karakter file input

Secara default, BigQuery Migration Service akan otomatis mencoba mendeteksi enkode karakter file input. Jika BigQuery Migration Service mungkin salah mengidentifikasi encoding file, Anda dapat menggunakan YAML konfigurasi untuk menentukan encoding karakter secara eksplisit.

YAML konfigurasi berikut menentukan encoding karakter eksplisit file input sebagai ISO-8859-1.

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

Konversi jenis global

YAML konfigurasi berikut mengubah jenis data ke jenis lain di semua skrip, dan menentukan jenis data sumber yang akan dihindari dalam skrip yang ditranspilasikan. Hal ini berbeda dengan konfigurasi Mengubah jenis atribut kolom, yang hanya mengubah jenis data untuk satu atribut.

BigQuery mendukung konversi jenis data berikut:

  • DATETIME ke TIMESTAMP
  • TIMESTAMP hingga DATETIME (menerima zona waktu opsional)
  • TIMESTAMP WITH TIME ZONE hingga DATETIME (menerima zona waktu opsional)
  • CHAR ke VARCHAR

Dalam contoh berikut, YAML konfigurasi mengonversi jenis data TIMESTAMP menjadi DATETIME.

type: experimental_object_rewriter
global:
  typeConvert:
    timestamp: DATETIME

Dalam dialek seperti Teradata, fungsi terkait tanggal dan waktu seperti current_date, current_time, atau current_timestamp menampilkan stempel waktu berdasarkan zona waktu yang dikonfigurasi, baik lokal maupun sesi. Di sisi lain, BigQuery selalu menampilkan stempel waktu dalam UTC. Untuk memastikan perilaku yang konsisten antara kedua dialek, Anda perlu mengonfigurasi zona waktu sesuai kebutuhan.

Dalam contoh berikut, YAML konfigurasi mengonversi jenis data TIMESTAMP dan TIMESTAMP WITH TIME ZONE menjadi DATETIME, dengan zona waktu target ditetapkan ke Europe/Paris.

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Memilih perubahan laporan

YAML konfigurasi berikut mengubah proyeksi bintang, klausa GROUP BY, dan ORDER BY dalam pernyataan SELECT.

starProjection mendukung konfigurasi berikut:

  • ALLOW
  • PRESERVE (default)
  • EXPAND

groupBy dan orderBy mendukung konfigurasi berikut:

  • EXPRESSION
  • ALIAS
  • INDEX

Dalam contoh berikut, YAML konfigurasi mengonfigurasi proyeksi bintang ke EXPAND.

type: experimental_statement_rewriter
select:
  starProjection: EXPAND

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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
      ;

Spesifikasi UDF

YAML konfigurasi berikut menentukan tanda tangan fungsi yang ditentukan pengguna (UDF) yang digunakan dalam skrip sumber. Sama seperti file zip metadata, definisi UDF dapat membantu menghasilkan terjemahan skrip input yang lebih akurat.

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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
      ;

Menetapkan ketelitian presisi desimal

Secara default, BigQuery Migration Service meningkatkan presisi numerik hingga presisi tertinggi yang tersedia untuk skala tertentu. YAML konfigurasi berikut mengganti perilaku ini dengan mengonfigurasi ketepatan presisi untuk mempertahankan presisi desimal pernyataan sumber.

type: experimental_statement_rewriter
common:
  decimalPrecision: STRICT

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Pemetaan nama output

Anda dapat menggunakan YAML konfigurasi untuk memetakan nama objek SQL. Anda dapat mengubah berbagai bagian nama bergantung pada objek yang dipetakan.

Pemetaan nama statis

Gunakan pemetaan nama statis untuk memetakan nama entitas. Jika Anda hanya ingin mengubah bagian nama tertentu dengan mempertahankan bagian nama lainnya, maka hanya sertakan bagian yang perlu diubah.

YAML konfigurasi berikut mengubah nama tabel dari my_db.my_schema.my_table menjadi 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"

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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
      )

Anda dapat menggunakan pemetaan nama statis untuk memperbarui region yang digunakan oleh nama dalam fungsi yang ditentukan pengguna publik.

Contoh berikut mengubah nama di UDF bqutil.fn dari menggunakan multi-region us default menjadi menggunakan region europe_west2:

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

Pemetaan nama dinamis

Gunakan pemetaan nama dinamis untuk mengubah beberapa objek secara bersamaan, dan buat nama baru berdasarkan objek yang dipetakan.

YAML konfigurasi berikut mengubah nama semua tabel dengan menambahkan awalan stg_ ke tabel yang termasuk dalam skema staging, lalu memindahkan tabel tersebut ke skema production.

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Menentukan jalur penelusuran database dan skema default

YAML konfigurasi berikut menentukan database default dan jalur penelusuran skema.

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Penulisan ulang nama output global

YAML konfigurasi berikut mengubah nama output semua objek (database, skema, relasi, dan atribut) dalam skrip sesuai dengan aturan yang dikonfigurasi.

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

Terjemahan SQL dengan file YAML konfigurasi ini mungkin terlihat seperti berikut:

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

Mengoptimalkan dan meningkatkan performa SQL yang diterjemahkan

Transformasi opsional dapat diterapkan ke SQL yang diterjemahkan untuk memperkenalkan perubahan yang dapat meningkatkan kueri dalam hal performa atau biaya. Pengoptimalan ini sangat bergantung pada kasus dan harus dievaluasi terhadap output SQL yang tidak dimodifikasi untuk menilai efek sebenarnya terhadap performa.

YAML konfigurasi berikut mengaktifkan transformasi opsional. Konfigurasi ini menerima daftar pengoptimalan dan, untuk pengoptimalan yang menerima parameter, bagian dengan nilai parameter opsional.

type: experimental_optimizer
transformations:
  - name: PRECOMPUTE_INDEPENDENT_SUBSELECTS
  - name: REWRITE_CTE_TO_TEMP_TABLE
    parameters:
      threshold: 1
Pengoptimalan Parameter opsional Deskripsi
PRECOMPUTE_INDEPENDENT_SUBSELECTS scope: [PREDICATE, PROJECTION] Menulis ulang kueri dengan menambahkan pernyataan DECLARE untuk mengganti ekspresi dalam klausa PREDICATE atau PROJECTION dengan variabel yang telah dihitung sebelumnya. Hal ini akan diidentifikasi sebagai predikat statis yang memungkinkan pengurangan jumlah data yang dibaca. Jika cakupan dihilangkan, nilai defaultnya adalah PREDICATE (yaitu klausa WHERE dan JOIN-ON).

Mengekstrak subkueri skalar ke pernyataan DECLARE akan membuat predikat asli menjadi statis dan karenanya memenuhi syarat untuk perencanaan eksekusi yang lebih baik. Pengoptimalan ini akan memperkenalkan pernyataan SQL baru.
REWRITE_CTE_TO_TEMP_TABLE threshold: N Menulis ulang ekspresi tabel umum (CTE) ke tabel sementara jika ada lebih dari N referensi ke ekspresi tabel umum yang sama. Hal ini mengurangi kompleksitas kueri dan memaksa eksekusi tunggal ekspresi tabel umum. Jika N dihilangkan, nilai defaultnya adalah 4.

Sebaiknya gunakan pengoptimalan ini saat CTE non-trivial dirujuk beberapa kali. Memperkenalkan tabel sementara memiliki overhead yang mungkin lebih besar daripada beberapa eksekusi CTE dengan kompleksitas rendah atau kardinalitas rendah. Pengoptimalan ini akan memperkenalkan pernyataan SQL baru.
REWRITE_ZERO_SCALE_NUMERIC_AS_INTEGER bigint: N Menulis ulang atribut NUMERIC/BIGNUMERIC skala nol ke jenis INT64 jika presisinya berada dalam N. Jika N dihilangkan, nilai defaultnya adalah 18.

Sebaiknya gunakan pengoptimalan ini saat menerjemahkan dari dialek sumber yang tidak memiliki jenis bilangan bulat. Mengubah jenis kolom memerlukan peninjauan semua penggunaan downstream untuk kompatibilitas jenis dan perubahan semantik. Misalnya, pembagian pecahan menjadi pembagian bilangan bulat, kode yang mengharapkan nilai numerik
DROP_TEMP_TABLE Menambahkan pernyataan DROP TABLE untuk semua tabel sementara yang dibuat dalam skrip dan tidak dihapus pada akhir skrip. Hal ini akan mengurangi periode penagihan penyimpanan untuk tabel sementara dari 24 jam menjadi waktu eksekusi skrip. Pengoptimalan ini akan memperkenalkan pernyataan SQL baru.

Sebaiknya gunakan pengoptimalan ini jika tabel sementara tidak diakses untuk pemrosesan lebih lanjut setelah akhir eksekusi skrip. Pengoptimalan ini akan memperkenalkan pernyataan SQL baru.
REGEXP_CONTAINS_TO_LIKE Menulis ulang beberapa kategori pola pencocokan REGEXP_CONTAINS ke ekspresi LIKE.

Sebaiknya gunakan pengoptimalan ini jika tidak ada proses lain, seperti penggantian makro, yang mengandalkan literal pola ekspresi reguler yang dipertahankan tanpa perubahan dalam SQL output.
ADD_DISTINCT_TO_SUBQUERY_IN_SET_COMPARISON Menambahkan klausa DISTINCT ke subkueri yang digunakan sebagai kumpulan nilai untuk operator [NOT] IN.

Sebaiknya gunakan pengoptimalan ini jika kardinalitas (jumlah nilai yang berbeda) dari hasil subkueri jauh lebih rendah daripada jumlah nilai. Jika prasyarat ini tidak terpenuhi, transformasi ini dapat berdampak negatif pada performa.

Membuat file YAML konfigurasi berbasis Gemini

Untuk menghasilkan output AI, direktori sumber yang berisi input terjemahan SQL Anda harus menyertakan file YAML konfigurasi.

Persyaratan

File YAML konfigurasi untuk output AI harus memiliki akhiran .ai_config.yaml. Contoh, rules_1.ai_config.yaml.

Kolom yang didukung

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
…
…

Anda dapat mengganti variabel berikut untuk mengonfigurasi output terjemahan AI:

  • SUGGESTION_TYPE (opsional): Tentukan jenis saran AI yang akan dibuat. Jenis saran berikut didukung:

    • QUERY_CUSTOMIZATION (default): Menghasilkan saran AI untuk kode SQL berdasarkan aturan terjemahan yang ditentukan dalam file YAML konfigurasi.
    • TRANSLATION_EXPLANATION: Menghasilkan teks yang menyertakan ringkasan kueri GoogleSQL yang diterjemahkan serta perbedaan dan inkonsistensi antara kueri SQL sumber dan kueri GoogleSQL yang diterjemahkan.
    • CUSTOM_SUGGESTION: Menghasilkan output SQL atau teks menggunakan artefak terjemahan. Pengguna dapat merujuk ke artefak terjemahan dalam perintah yang menyertakan placeholder. Layanan terjemahan menambahkan artefak yang sesuai ke perintah LLM akhir yang dikirim ke Gemini. Artefak terjemahan berikut dapat disertakan dalam perintah:
      • {{SOURCE_DIALECT}}: digunakan untuk mereferensikan dialek SQL sumber.
      • {{SOURCE_SQL}}: digunakan untuk mereferensikan SQL sumber terjemahan.
      • {{TARGET_SQL}}: digunakan untuk mereferensikan SQL terjemahan default.

  • TARGET (opsional): Tentukan apakah Anda ingin menerapkan aturan terjemahan ke SQL input, SOURCE_SQL, atau SQL output, TARGET_SQL (default).

  • NL_PROMPT (opsional): Dalam bahasa alami, jelaskan perubahan pada SQL target. Terjemahan SQL yang ditingkatkan Gemini menilai permintaan dan membuat perubahan yang ditentukan.

  • NL_RULE_1 (opsional): Dalam bahasa alami, deskripsikan aturan terjemahan.

  • RULE_1_INPUT_1 (opsional): Pola SQL yang ingin Anda ganti.

  • RULE_1_OUTPUT_1 (opsional): Pola SQL yang diharapkan setelah input diganti.

Anda dapat menambahkan translation_rules tambahan dan examples tambahan sesuai kebutuhan.

Contoh

Contoh berikut membuat file YAML konfigurasi berbasis Gemini yang dapat Anda gunakan dengan terjemahan SQL.

Menghapus fungsi atas dalam kueri output terjemahan default

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

Membuat beberapa aturan terjemahan untuk menyesuaikan output terjemahan

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.

Menghapus komentar SQL dari kueri input terjemahan

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

Membuat penjelasan terjemahan menggunakan perintah LLM default

Contoh ini menggunakan perintah LLM default yang disediakan oleh layanan terjemahan untuk membuat penjelasan teks:

suggestion_type: "TRANSLATION_EXPLANATION"

Membuat penjelasan terjemahan menggunakan perintah bahasa alami Anda sendiri

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

Memperbaiki error terjemahan MySQL ke 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}}"

Menerapkan beberapa konfigurasi YAML

Saat menentukan file YAML konfigurasi dalam batch atau terjemahan SQL interaktif, Anda dapat memilih beberapa file YAML konfigurasi dalam satu tugas terjemahan untuk mencerminkan beberapa transformasi. Jika beberapa konfigurasi bertentangan, satu transformasi mungkin menggantikan transformasi lainnya. Sebaiknya gunakan berbagai jenis setelan konfigurasi di setiap file untuk menghindari transformasi yang bertentangan dalam tugas terjemahan yang sama.

Contoh berikut mencantumkan dua file YAML konfigurasi terpisah yang disediakan untuk satu tugas terjemahan SQL, satu untuk mengubah atribut kolom, dan satu lagi untuk menetapkan tabel sebagai sementara:

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

Terjemahan SQL dengan dua file YAML konfigurasi ini mungkin terlihat seperti berikut:

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