Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Mengubah terjemahan SQL dengan YAML

File YAML konfigurasi memungkinkan Anda menyesuaikan cara BigQuery menerjemahkan kode SQL dari database sumber selama migrasi. BigQuery Migration Service mendukung dua jenis file YAML konfigurasi: file konfigurasi terjemahan *.config.yaml yang memberikan aturan deterministik kepada mesin terjemahan, dan file konfigurasi berbasis Gemini *.ai_config.yaml yang memberikan aturan bahasa alami kepada Gemini.

Untuk menyesuaikan terjemahan SQL dengan file YAML konfigurasi, lakukan hal berikut:

Membuat file konfigurasi: Buat file konfigurasi terjemahan *.config.yaml deterministik, file konfigurasi berbasis Gemini *.ai_config.yaml, atau kedua jenis file konfigurasi untuk menggabungkan aturan struktural dengan penyesuaian Gemini.
Menyediakan file ke tugas terjemahan: Kirim file konfigurasi saat Anda menerjemahkan satu kueri atau file SQL batch.
Tinjau output terjemahan: Temukan SQL yang diterjemahkan dan saran Gemini dalam respons saat Anda menerjemahkan satu kueri, atau di Cloud Storage saat Anda menerjemahkan file SQL batch.

Jenis file YAML konfigurasi

Tabel berikut membandingkan dua jenis file YAML konfigurasi:

Fitur	Konfigurasi terjemahan (`*.config.yaml`)	Konfigurasi berbasis Gemini (`*.ai_config.yaml`)
Penerapan aturan	Aturan diterapkan oleh mesin terjemahan sebagai aturan deterministik pada SQL yang diurai, sehingga input dan konfigurasi yang sama selalu menghasilkan output yang sama.	Aturan diterapkan oleh Gemini sebagai petunjuk dan contoh bahasa alami yang diterapkan ke teks SQL. Output dapat bervariasi di antara operasi, jadi selalu tinjau dan verifikasi saran sebelum menggunakannya.
Hal yang dapat diubah	Mesin terjemahan dapat mengubah objek atau setelan apa pun yang dikenali. Hal ini mencakup nama dan jenis database, skema, tabel, kolom, dan fungsi, properti tabel seperti partisi, pengelompokan, dan masa berlaku, default sesi, tanda tangan UDF, pengoptimalan, dan output pernyataan seperti gaya `GROUP BY` dan `SELECT *`.	Gemini dapat mengubah transformasi SQL apa pun yang dapat Anda deskripsikan dalam bahasa alami. Hal ini mencakup pemformatan dan komentar, mengganti pola, menulis ulang konstruksi yang tidak diterjemahkan oleh mesin sesuai keinginan Anda, dan membuat penjelasan terjemahan.
Persyaratan	SQL input harus diurai dalam dialek sumber. Aturan tidak dapat bertindak pada teks dalam SQL input yang tidak dikenali oleh parser, seperti placeholder `${VAR}` atau sintaksis template. Gunakan aturan `SOURCE_SQL` dalam file `*.ai_config.yaml` atau pra-pemrosesan Anda sendiri untuk menghapus teks tersebut terlebih dahulu.	Anda harus mengaktifkan saran AI Gemini untuk lowongan. Tugas harus dijalankan di lokasi pemrosesan yang didukung. Penggunaan Gemini gratis hingga batas tertentu.
Tempat hasil muncul	Hasilnya akan muncul di SQL yang diterjemahkan, seperti dalam respons terjemahan atau di direktori output `sql/` di Cloud Storage.	Hasilnya akan muncul sebagai saran Gemini terpisah di konsol Google Cloud , di kolom saran atau file output terpisah di Google Cloud CLI dan server MCP, atau di direktori output `*_suggestion/` terpisah di Cloud Storage. Untuk mengetahui informasi selengkapnya, lihat Tempat menemukan output terjemahan.
Nama file	Nama file harus diakhiri dengan `.config.yaml`—misalnya, `rename-tables.config.yaml`.	Nama file harus diakhiri dengan `.ai_config.yaml`—misalnya, `style-rules.ai_config.yaml`.
Nama file	Layanan terjemahan mengabaikan file YAML apa pun dalam input yang tidak diakhiri dengan `.config.yaml` atau `.ai_config.yaml` dan melaporkan file yang diabaikan dalam log terjemahan.
Referensi	Untuk informasi selengkapnya, lihat Panduan untuk membuat file YAML konfigurasi dan Contoh YAML konfigurasi di halaman ini.	Untuk mengetahui informasi selengkapnya, lihat Membuat file YAML konfigurasi berbasis Gemini di halaman ini.

Cara penerapan kedua jenis aturan

Tugas terjemahan menerapkan aturan konfigurasi dalam urutan berikut:

Gemini menerapkan aturan SOURCE_SQL dalam file *.ai_config.yaml ke SQL input asli untuk menghasilkan SQL sumber yang ditulis ulang.
Mesin terjemahan menerjemahkan SQL sumber yang ditulis ulang dari langkah sebelumnya—atau SQL input asli jika tidak ada aturan SOURCE_SQL yang berlaku—dan menerapkan aturan apa pun dalam file *.config.yaml untuk menghasilkan SQL yang diterjemahkan.
Gemini menerapkan aturan TARGET_SQL dalam file *.ai_config.yaml ke SQL yang diterjemahkan dari langkah sebelumnya untuk menghasilkan SQL target yang ditulis ulang. Jika file *.ai_config.yaml Anda menyertakan aturan TRANSLATION_EXPLANATION, Gemini juga akan membuat penjelasan teks dari SQL yang diterjemahkan.

Sebaiknya gunakan aturan *.config.yaml untuk perubahan struktural yang dapat diulang, seperti mengganti nama objek, memetakan jenis, dan menetapkan partisi. Sebaiknya gunakan aturan *.ai_config.yaml untuk perubahan yang tidak dapat dinyatakan oleh mesin, atau untuk membersihkan input yang tidak diurai. Anda dapat menggunakan kedua jenis file konfigurasi dalam tugas yang sama.

Menyediakan file konfigurasi ke terjemahan

Konsol Google Cloud , gcloud CLI, BigQuery Migration API, dan server MCP BigQuery Migration Service mendukung penggunaan beberapa file konfigurasi dalam satu tugas terjemahan. Untuk mengetahui informasi selengkapnya, lihat Menerapkan beberapa konfigurasi YAML.

Untuk menyediakan file konfigurasi ke tugas terjemahan, pilih salah satu opsi berikut:

Konsol

Untuk menggunakan file konfigurasi saat menerjemahkan satu kueri, tentukan file tersebut dalam setelan terjemahan penerjemah interaktif:
- *.config.yaml: Di kolom Translation Configuration Source Location di setelan terjemahan, tentukan jalur Cloud Storage ke file konfigurasi.
- *.ai_config.yaml: Buat aturan penyesuaian, yang disimpan ke __default.ai_config.yaml, atau tentukan jalur Cloud Storage.
Untuk menggunakan file konfigurasi saat menerjemahkan file SQL secara batch, lakukan hal berikut:
- *.config.yaml: Upload file konfigurasi di direktori Cloud Storage input, lalu di setelan terjemahan, tentukan jalur ke direktori di kolom File location details.
- *.ai_config.yaml: Upload file konfigurasi di direktori Cloud Storage input, lalu di setelan terjemahan, pilih Setelan opsional > Saran AI Gemini.

gcloud

Saat menggunakan perintah gcloud alpha bq migration translate, gunakan flag --translation-config-files untuk menentukan file *.config.yaml atau *.ai_config.yaml.
Saat menggunakan perintah gcloud alpha bq migration translate-batch, lakukan salah satu hal berikut:
- *.config.yaml: Sertakan file dalam direktori input yang Anda teruskan ke --source-gcs-uris atau --source-local-dirs, atau teruskan file satu per satu dengan flag --source-gcs-files atau --source-local-files.
- *.ai_config.yaml: Sertakan file dalam direktori input yang Anda teruskan ke --source-gcs-uris atau --source-local-dirs, atau teruskan file satu per satu dengan flag --source-gcs-files atau --source-local-files, dan tambahkan flag --enable-ai-suggestion.

API

Di BigQuery Migration API, baik Anda menerjemahkan satu kueri atau file SQL batch, lakukan hal berikut:

*.config.yaml: Upload file di jalur input di source_spec.base_uri, teruskan entri gcs_file_path di source_spec jika file tidak berada di base_uri, atau teruskan entri literal inline di source_spec.
*.ai_config.yaml: Berikan file di source_spec di bagian base_uri, sebagai entri gcs_file_path jika file tidak berada di bagian base_uri, atau sebagai entri literal inline, dan sertakan "suggestion" di target_types—misalnya, "target_types": ["sql", "suggestion"].

MCP

Di server MCP BigQuery Migration Service:

Untuk menerjemahkan satu kueri (translate_query), lakukan hal berikut:
- *.config.yaml: Teruskan entri translationConfigs inline.
- *.ai_config.yaml: Teruskan entri aiSuggestionConfigs inline.
Untuk menerjemahkan file SQL batch (translate_batch_queries), lakukan hal berikut:
- *.config.yaml: Upload file di bagian sourceBaseUri, atau cantumkan dalam configurationFilePaths jika tidak ada di bagian sourceBaseUri.
- *.ai_config.yaml: Upload file di bagian sourceBaseUri, atau cantumkan dalam configurationFilePaths jika tidak ada di bagian sourceBaseUri, dan tetapkan enableAiSuggestions ke true.

Tempat menemukan output terjemahan

Bergantung pada file konfigurasi yang Anda berikan, tugas terjemahan dapat menghasilkan output berikut:

SQL yang diterjemahkan dari mesin terjemahan setelah menerapkan aturan apa pun dalam file *.config.yaml.
SQL sumber yang ditulis ulang dari Gemini setelah menerapkan aturan SOURCE_SQL dalam file *.ai_config.yaml.
SQL target yang ditulis ulang dari Gemini setelah menerapkan aturan TARGET_SQL dalam file *.ai_config.yaml.
Penjelasan terjemahan dari Gemini saat file *.ai_config.yaml Anda menyertakan aturan TRANSLATION_EXPLANATION, atau saat Anda meminta penjelasan sesuai permintaan.

Tempat Anda menemukan output ini bergantung pada cara Anda menjalankan terjemahan:

Untuk menemukan output saat Anda menerjemahkan satu kueri di konsolGoogle Cloud atau gcloud CLI, lihat Mempelajari output terjemahan dalam panduan penerjemah SQL interaktif.
Untuk menemukan output saat Anda menerjemahkan file SQL batch di Cloud Storage atau meninjaunya di konsol Google Cloud , lihat Mempelajari output terjemahan dalam panduan penerjemah SQL batch.
Untuk menemukan output saat Anda menggunakan BigQuery Migration API, lihat Mengambil hasil di panduan BigQuery Migration API. Untuk terjemahan kueri tunggal, tambahkan jalur output yang Anda inginkan—sql/<var>PATH</var>, source_sql_query_customization_suggestion/<var>PATH</var>, target_sql_query_customization_suggestion/<var>PATH</var>, atau translation_explanation_suggestion/<var>PATH</var>—ke target_return_literals untuk menerimanya di translatedLiterals.
Untuk menemukan output saat Anda menggunakan server MCP BigQuery Migration Service, lihat Menggunakan server MCP BigQuery Migration Service. Alat translate_query dan get_translation menampilkan translatedQuery, sourceSqlSuggestion, dan targetSqlSuggestion, sedangkan alat explain_translation menampilkan penjelasan terjemahan.

Persyaratan file terjemahan `*.config.yaml`

File *.config.yaml terjemahan harus memenuhi persyaratan berikut agar kompatibel dengan BigQuery Migration Service:

Saat Anda mengupload file *.config.yaml di jalur Cloud Storage input untuk tugas terjemahan batch, file konfigurasi yang ditempatkan di mana pun di jalur input akan berlaku untuk seluruh tugas. File tersebut tidak perlu berada di level root atau disalin ke setiap subdirektori. 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 *.config.yaml tidak boleh melebihi 1 MB.
Ukuran total file semua file *.config.yaml 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 konfigurasi terjemahan harus diakhiri dengan .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 *.config.yaml harus menyertakan header type level teratas yang menentukan kategori aturan konfigurasi dalam file:

object_rewriter: menulis ulang properti relation—seperti temporary, ephemeral, partitionLifetime, external, description, partition, dan clustering—dan jenis data attribute (type).
experimental_object_rewriter: menulis ulang nama objek output dengan outputName di seluruh global, database, schema, relation, attribute, function, index, sequence, variable, dan projection, serta mengonversi jenis data secara global dengan global.typeConvert. Untuk mengetahui informasi selengkapnya, lihat Pemetaan nama output dan Konversi jenis global.
environment: menetapkan default tingkat sesi di bagian session, seperti defaultDatabase, schemaSearchPath, dan dateFormat.
metadata: mendeklarasikan tanda tangan fungsi yang ditentukan pengguna (UDF) (udfs) dan menghapus awalan, akhiran, atau pola ekspresi reguler nama input selama pencarian metadata (nameAlias).
statement_rewriter: menyesuaikan output pernyataan seperti perluasan SELECT *, pemformatan GROUP BY dan ORDER BY (select), serta ketatnya presisi desimal atau string (common).
input_formats: menentukan encoding karakter file SQL input (formats).
optimizer: mengaktifkan, menonaktifkan, atau mengonfigurasi pengoptimalan kueri opsional (transformations).

Contoh berikut menggunakan jenis experimental_object_rewriter untuk mengonversi semua nama objek output menjadi huruf besar:

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

Pemilihan entity

Untuk melakukan transformasi khusus entity, tentukan entity SQL sumber di file konfigurasi. Semua properti match bersifat opsional; hanya gunakan properti match yang diperlukan untuk transformasi. Kolom match dibandingkan dengan nama objek sumber setelah menyelesaikan defaultDatabase dan schemaSearchPath yang dikonfigurasi, kecuali dalam aturan outputName saat global.outputName juga dikonfigurasi. Untuk mengetahui informasi selengkapnya, lihat Pemetaan nama output. 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: cocok dengan nama database sumber, yang sesuai dengan komponen project_id di BigQuery.
schema: cocok dengan nama skema sumber, yang sesuai dengan komponen dataset di BigQuery.
relation: cocok dengan nama tabel atau tampilan sumber.
attribute: cocok dengan nama kolom sumber. Properti ini hanya valid untuk pilihan attribute.
databaseRegex atau dbRegex: mencocokkan seluruh nama database dengan ekspresi reguler yang tidak peka huruf besar/kecil.
schemaRegex: mencocokkan seluruh nama schema dengan ekspresi reguler yang tidak peka huruf besar/kecil.
relationRegex: mencocokkan seluruh nama relation dengan ekspresi reguler yang tidak peka huruf besar/kecil.
attributeRegex: mencocokkan seluruh nama attribute dengan ekspresi reguler yang tidak peka huruf besar/kecil. Properti ini hanya valid untuk pilihan attribute.

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

File YAML konfigurasi juga menerima key sebagai alias untuk match. key dan match mendukung subkolom komponen nama eksplisit serta sintaksis string pendek "database.schema.relation" atau "database.schema.relation.attribute" yang dipisahkan titik. Berdasarkan konvensi, key sering digunakan dengan sintaksis string pendek dan match digunakan dengan subkolom eksplisit.

Database bawaan

Beberapa dialek SQL input, terutama Teradata, tidak mendukung nama database dalam ID yang memenuhi syarat (schema.table). Dalam hal ini, gunakan objek match dan hapus properti database. Atau, konfigurasikan defaultDatabase—misalnya, di bagian type: environment—sehingga Anda dapat mencocokkan dengan database default tersebut dalam aturan match objek atau string pendek.

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 Apache Hive sebagai dialek SQL input dan BigQuery SQL sebagai dialek output.

Mengubah kapitalisasi nama objek

YAML konfigurasi berikut mengubah huruf nama objek SQL menjadi UPPERCASE atau LOWERCASE. Anda dapat menetapkan case pada objek all atau menggantinya untuk jenis objek tertentu (database, schema, relation, attribute, function, sequence, index, variable, atau projection):

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

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

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

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 testdb.testschema.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 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) );

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

Mengubah lokasi atau format eksternal untuk tabel

YAML konfigurasi berikut mengubah lokasi dan format 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 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' ] );

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 testdb.testschema.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 menggunakan add, remove, atau set, dengan set menggantikan kolom partisi yang ada:

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

YAML konfigurasi berikut mengubah skema partisi tabel sehingga dipartisi berdasarkan bucket rentang:

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

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

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

Menetapkan atau mengubah pengelompokan tabel

YAML konfigurasi berikut mengubah skema pengelompokan tabel menggunakan add, remove, atau set, dengan set menggantikan kolom pengelompokan yang ada:

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

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

Jika tidak ada transmisi langsung antara jenis sumber dan target—misalnya, saat mengonversi kolom INT yang menyimpan tanggal YYYYMMDD menjadi kolom DATE—berikan ekspresi konversi sourceToTarget dan targetToSource GoogleSQL. Gunakan ? sebagai placeholder untuk nilai kolom atau ekspresi. Contoh:

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

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

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
    ;

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:
-
  match: "testdb.testschema.x"
  external:
    connection_id: "connection_test"

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

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

Mengubah encoding karakter file input

Secara default, BigQuery Migration Service akan mencoba mendeteksi encoding karakter file input secara otomatis. 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. Anda dapat mencocokkan file input menggunakan jalur yang tepat (path), pola glob (pathGlob), atau ekspresi reguler (pathRegex):

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

Konversi jenis global

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

Layanan terjemahan mendukung konversi jenis data berikut:

DATETIME ke TIMESTAMP
TIMESTAMP hingga DATETIME (menerima zona waktu opsional)
TIMESTAMP WITH TIME ZONE (timestamptz) ke DATETIME (menerima zona waktu opsional)
CHAR ke VARCHAR (menerima precisionAction dan comparisonBehavior opsional)
VARCHAR hingga VARCHAR (menerima precisionAction dan comparisonBehavior opsional)

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

type: experimental_object_rewriter
global:
  typeConvert:
    timestamp: DATETIME

Mengonversi jenis `CHAR` dan `VARCHAR`

Dalam dialek seperti Teradata, nilai CHAR(N) diisi di sebelah kanan dengan spasi, dan penulisan string dipotong sesuai panjang kolom yang dideklarasikan. Perbandingan string tidak peka huruf besar/kecil (NOT CASESPECIFIC) secara default dan mengabaikan spasi di akhir. Secara default, mesin terjemahan mengemulasi semantik ini di BigQuery. Ini menambahkan wrapper padding kanan (CONCAT) dan pemotongan (SUBSTR) pada transmisi dan penulisan, wrapper UPPER dan RTRIM pada perbandingan, dan wrapper UPPER pada kunci GROUP BY.

Anda dapat mengonfigurasi kolom char dan varchar di bagian global.typeConvert dengan properti berikut:

target: harus ditetapkan ke VARCHAR. Mengonfigurasi target: VARCHAR di char akan menghapus padding kanan CHAR (CONCAT) meskipun precisionAction adalah PRESERVE.
precisionAction: mengontrol presisi panjang karakter dan wrapper pemotongan SUBSTR:
- PRESERVE (default): mempertahankan presisi panjang karakter pada ekspresi dan memunculkan wrapper pemotongan SUBSTR saat mentransmisikan atau menyisipkan ke dalam kolom CHAR(N) atau VARCHAR(N). Untuk juga memunculkan panjang kolom STRING(N) dalam DDL CREATE TABLE, lihat Menetapkan ketatnya presisi string.
- DROP: menghapus presisi panjang karakter pada ekspresi dan menghilangkan wrapper pemotongan SUBSTR.
comparisonBehavior: mengontrol wrapper RTRIM dan UPPER untuk perbandingan dan kunci GROUP BY. Menetapkan nilai selain STRICT pada char atau varchar akan berlaku di kedua jenis, jadi tetapkan nilai yang sama pada kedua kunci saat mengonfigurasi keduanya:
- STRICT (default): mengemulasi padding spasi di akhir (RTRIM) dan kolasi yang tidak peka huruf besar/kecil (UPPER).
- PADDING_AWARE: hanya mengemulasi padding spasi di akhir (RTRIM) dan menghilangkan UPPER.
- CASE_AWARE: hanya mengemulasi pemeriksaan yang tidak peka huruf besar/kecil (UPPER) dan menghilangkan RTRIM.
- NONE: menghilangkan wrapper RTRIM dan UPPER, sehingga output menggunakan perbandingan langsung dan ekspresi GROUP BY.

YAML konfigurasi berikut mengonversi CHAR menjadi VARCHAR dan menghapus wrapper pemotongan (SUBSTR), spasi di akhir (RTRIM), dan tidak peka huruf besar/kecil (UPPER) untuk kolom CHAR dan VARCHAR:

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

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

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

Menetapkan zona waktu default

Dialek database memiliki semantik dan nama yang bervariasi untuk berbagai jenis data terkait tanggal dan waktu. Layanan terjemahan menstandarkan terminologi berikut dalam konfigurasi YAML-nya, terlepas dari nama jenis data dialek input:

datetime adalah kombinasi Y-M-D H:M:S yang tidak ditetapkan ke zona waktu tertentu. datetime mewakili waktu jam dinding, bukan waktu tertentu.
timestamp mewakili waktu instan tertentu atau absolut dan oleh karena itu, secara implisit ditetapkan ke zona waktu tertentu, yang mungkin merupakan setelan tingkat sesi atau database.
timestamptz mewakili momen tertentu seperti timestamp, tetapi tidak seperti timestamp, membawa offset zona waktu tertentu. Meskipun mewakili instan yang sama, 2019-06-01 12:00:00+4 dan 2019-06-01 06:00:00-2 dianggap sebagai nilai timestamptz yang berbeda.

Dalam dialek seperti Teradata, fungsi terkait tanggal dan waktu seperti current_date, current_time, atau current_timestamp menampilkan stempel waktu berdasarkan parameter zona waktu sesi yang dikonfigurasi secara implisit. Di sisi lain, BigQuery selalu menampilkan stempel waktu dalam UTC. Untuk memastikan perilaku yang konsisten antara kedua dialek, Anda mungkin perlu mengonfigurasi zona waktu dengan tepat.

Sebaiknya tentukan zona waktu default untuk terjemahan jika database sumber Anda memiliki default yang bukan UTC. Tindakan ini akan memastikan perilaku kueri terjemahan yang benar dengan mempertahankan zona waktu.

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

Untuk mengetahui nilai zona waktu string yang valid, lihat Zona waktu.

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:

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

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

Secara default, TIMESTAMPTZ dikonversi ke TIMESTAMP tanpa memerlukan konfigurasi.

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

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

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

Pilih modifikasi pernyataan

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

Kolom select.starProjection mendukung nilai berikut:

ALLOW: memunculkan SELECT * saat kueri sumber menggunakan SELECT * atau mencantumkan semua kolom tabel secara berurutan.
PRESERVE (default): memunculkan SELECT * hanya jika kueri sumber menggunakan SELECT *.
EXPAND: memperluas SELECT * menjadi referensi kolom individual saat metadata tabel tersedia.

Kolom select.groupBy dan select.orderBy mendukung nilai berikut:

EXPRESSION: memformat item GROUP BY atau ORDER BY sebagai ekspresi lengkap.
ALIAS: memformat item GROUP BY atau ORDER BY menggunakan alias kolom SELECT jika tersedia.
INDEX: memformat item GROUP BY atau ORDER BY menggunakan posisi kolom berbasis 1, seperti GROUP BY 1.

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

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

Spesifikasi UDF

Dalam sebagian besar kasus, penerjemah SQL BigQuery dapat otomatis mengurai bahasa definisi data (DDL) dari fungsi yang ditentukan pengguna (UDF) eksternal untuk menentukan jenis data input dan output-nya, meskipun isi UDF ditulis dalam bahasa eksternal. Namun, untuk dialek sumber tertentu, penerjemah mungkin tidak dapat mengompilasi tanda tangan UDF secara otomatis. Untuk memastikan bahwa pernyataan SQL yang mereferensikan UDF ini diterjemahkan secara akurat tanpa harus menyediakan DDL asli, Anda dapat menggunakan file konfigurasi YAML untuk mendaftarkan tanda tangan UDF secara eksplisit.

YAML konfigurasi berikut menentukan tanda tangan fungsi yang ditentukan pengguna (UDF) yang digunakan dalam skrip sumber. Tentukan setiap tanda tangan dalam dialek sumber sebagai RETURN_TYPE FUNCTION_NAME(ARG_NAME ARG_TYPE, ...), termasuk nama untuk setiap parameter. 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(dt), interval 1 DAY) FROM x ;

Beberapa dialek sumber mendukung UDF yang menggunakan nama yang sama di berbagai tanda tangan argumen, yang terkadang disebut UDF yang kelebihan beban. Untuk UDF yang kelebihan beban, tentukan udf dan name target yang berbeda sehingga setiap tanda tangan dipetakan ke nama fungsi unik di BigQuery:

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

Menghapus pola ID selama pencarian metadata

Skrip SQL input mungkin mereferensikan objek atau kolom dengan awalan, akhiran, atau pola penamaan yang tidak ada dalam definisi metadata Anda—misalnya, mereferensikan a_dt saat DDL metadata menentukan kolom dt. Dalam hal ini, gunakan nameAlias di bagian type: metadata agar mesin terjemahan menghapus pola saat mencari nama objek dalam metadata. ID asli dipertahankan dalam SQL output.

Kolom nameAlias mendukung properti berikut. Setiap properti menerima satu string atau daftar string, dan entri pertama yang cocok di setiap daftar akan berlaku:

stripPrefix: menghapus awalan literal sebelum mencari metadata.
stripSuffix: menghapus akhiran literal sebelum mencari metadata.
stripRegex: mencocokkan ekspresi reguler peka huruf besar/kecil dan mengganti setiap substring yang cocok dengan grup tangkapan pertamanya (...) saat mencari metadata. Tautkan pola—misalnya, ^a_(.*)$—agar hanya cocok dengan awalan atau ID lengkap.

YAML konfigurasi berikut menghapus awalan a_ di awal dari ID saat mencari nama objek dalam metadata:

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

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

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

Menetapkan ketatnya 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 ketatnya presisi untuk mempertahankan presisi desimal pernyataan sumber.

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

Menetapkan ketatnya presisi string

Secara default, BigQuery Migration Service menghilangkan presisi string saat menerjemahkan kolom CHAR dan VARCHAR. Hal ini dapat membantu mencegah error pemotongan saat nilai ditulis. Beberapa dialek SQL, seperti Teradata, memotong nilai yang melebihi presisi maksimum saat penulisan, sedangkan BigQuery menampilkan error dalam skenario ini.

Jika aplikasi Anda tidak mengandalkan perilaku pemotongan dialek sumber, pertimbangkan untuk mempertahankan presisi kolom dalam definisi jenis yang diterjemahkan.

YAML konfigurasi berikut mengganti perilaku ini dengan mengonfigurasi ketatnya presisi untuk mempertahankan presisi string pernyataan sumber.

type: statement_rewriter
common:
  stringPrecision: STRICT

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

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

Pemetaan nama output

Anda dapat menggunakan type: experimental_object_rewriter dalam file YAML konfigurasi untuk memetakan nama objek SQL (database, schema, relation, attribute, function, sequence, index, variable, atau projection) secara statis atau dinamis:

Setiap jenis objek hanya memperluas nama dan placeholder hierarki induknya sendiri dari ${database}, ${schema}, ${relation}, ${attribute}, ${function}, ${sequence}, ${index}, ${variable}, dan ${projection}. Misalnya, aturan schema memperluas ${database} dan ${schema}, sedangkan aturan relation memperluas ${database}, ${schema}, dan ${relation}.
Jika beberapa aturan dari jenis objek yang sama dengan kriteria match yang berbeda cocok dengan suatu objek, aturan terakhir yang cocok dalam daftar akan diterapkan.
Aturan replace dan case global di bagian global.outputName dijalankan sebelum aturan outputName khusus objek. Aturan khusus objek cocok dan dapat mengganti nama objek yang diubah secara global. Untuk aturan attribute, match membandingkan dengan nama attribute yang ditransformasi secara global bersama dengan nama database, schema, dan relation sumber. Untuk mengetahui informasi selengkapnya, lihat Penulisan ulang nama output global.

Untuk mengetahui informasi selengkapnya tentang cara kerja aturan pemetaan nama di seluruh tingkat database, skema, relasi, fungsi, dan atribut, lihat Memetakan nama objek SQL untuk terjemahan.

Pemetaan nama statis

Gunakan pemetaan nama statis untuk memetakan nama entity. Jika Anda hanya ingin mengubah bagian tertentu dari nama sambil mempertahankan bagian lain dari nama tersebut, 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 sekaligus, 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 ) ;

Pemetaan nama kolom

Gunakan bagian attribute di bagian type: experimental_object_rewriter untuk mengganti nama kolom di definisi tabel dan referensi kueri:

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

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

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

Menentukan jalur penelusuran skema dan database 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 mydb.mytable; SELECT * FROM table1;
`bq-output.sql`	SELECT * FROM myproject.mydb.mytable; SELECT * FROM myproject.myschema1.table1;

Menetapkan `NLS_DATE_FORMAT`

YAML konfigurasi berikut menetapkan parameter NLS_DATE_FORMAT ke format DD/MM/YYYY. Sebaiknya tentukan NLS_DATE_FORMAT untuk penggunaan implisit format dan transmisi tanggal. Jika tidak ditetapkan, format default untuk terjemahan, DD-MON-RR, akan digunakan.

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

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

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

Penulisan ulang nama output global

YAML konfigurasi berikut menggunakan aturan replace di bagian global.outputName untuk menulis ulang nama output semua objek (all) atau jenis objek tertentu (database, schema, relation, attribute, function, sequence, index, variable, atau projection). Setiap aturan mencocokkan ekspresi reguler peka huruf besar/kecil dan mengganti kecocokan dengan teks baru, termasuk $0, $1, dan grup tangkapan lainnya.

Transformasi outputName global (replace diikuti dengan case) berjalan sebelum aturan outputName khusus objek, seperti schema, relation, atau attribute. Aturan khusus objek cocok dan dapat mengganti nama objek yang diubah secara global. Untuk aturan attribute, match membandingkan dengan nama attribute yang ditransformasi secara global bersama dengan nama database, schema, dan relation sumber:

type: experimental_object_rewriter
global:
  outputName:
    all:
      replace:
        - regex: '\s'
          replaceWith: '_'
        - regex: '>='
          replaceWith: 'gte'
        - regex: '^[^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_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 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. Setiap entri dalam daftar transformations mendukung kolom berikut:

name: nama pengoptimalan.
enabled (opsional): boolean yang ditetapkan secara default ke true. Tetapkan enabled ke false untuk menonaktifkan pengoptimalan yang diaktifkan secara default untuk dialek sumber.
parameters (opsional): peta parameter khusus pengoptimalan.

type: 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`, klausa `PROJECTION`, atau keduanya dengan variabel yang telah dihitung sebelumnya. Penulisan ulang ini mengubah ekspresi menjadi predikat statis yang dapat mengurangi jumlah data yang dibaca. Parameter `scope` menerima daftar yang berisi `PREDICATE`, `PROJECTION`, atau keduanya. Jika `parameters` dihilangkan, `scope` akan ditetapkan secara default ke `[PREDICATE]`, yang mencakup klausa `WHERE` dan `JOIN ON`. Mengekstrak subkueri skalar ke pernyataan `DECLARE` akan membuat predikat asli menjadi statis sehingga 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 setidaknya `N` referensi ke CTE yang sama. Penulisan ulang ini mengurangi kompleksitas kueri dan memaksa eksekusi tunggal CTE. Jika `N` dihilangkan, nilai defaultnya adalah `4`. Sebaiknya gunakan pengoptimalan ini saat CTE non-trivial direferensikan beberapa kali. Memperkenalkan tabel sementara memiliki overhead yang mungkin lebih besar daripada eksekusi berulang 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 Anda 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, atau kode yang mengharapkan nilai numerik. Terjemahan Snowflake mengaktifkan pengoptimalan ini untuk numerik skala nol hingga presisi 38 secara default. Pengoptimalan ini memastikan bahwa `INTEGER` Snowflake, yang secara implisit direpresentasikan sebagai `NUMBER(38,0)` di Snowflake, diterjemahkan ke `INT64` BigQuery, bukan `BIGNUMERIC(38)`. Jika aplikasi Anda menggunakan angka dengan presisi lebih dari 18, sebaiknya nonaktifkan fungsi ini untuk memastikan BigQuery dapat memproses berbagai nilai yang diperlukan oleh aplikasi Anda.
`DROP_TEMP_TABLE`		Menambahkan pernyataan `DROP TABLE` untuk semua tabel sementara yang dibuat dalam skrip dan tidak dihapus di akhir skrip. Tindakan ini akan mengurangi periode penagihan penyimpanan untuk tabel sementara dari 24 jam menjadi waktu berjalan skrip. Sebaiknya gunakan pengoptimalan ini jika tabel sementara tidak diakses untuk pemrosesan lebih lanjut setelah eksekusi skrip berakhir. Pengoptimalan ini akan memperkenalkan pernyataan SQL baru.
`REGEXP_CONTAINS_TO_LIKE`		Menulis ulang beberapa kategori pola pencocokan `REGEXP_CONTAINS` menjadi 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.
`APPROXIMATE_RANGE_PARTITIONS`		Memperkirakan skema partisi bilangan bulat yang tidak berdekatan atau tidak reguler dengan mengonversinya menjadi rentang partisi yang berdekatan dan berukuran sama yang didukung oleh BigQuery. Secara default, skema partisi tersebut tidak memengaruhi skema partisi tabel dalam pernyataan DDL yang diterjemahkan. Sebaiknya gunakan pengoptimalan ini jika tabel sumber menggunakan fungsi partisi yang tidak berdekatan seperti fungsi `RANGE_N` Teradata dan akan mendapatkan manfaat dari skema partisi berukuran sama di BigQuery.

Contoh pengoptimalan

Pengoptimalan berikut mengonversi jenis numerik skala nol dengan presisi kurang dari atau sama dengan 38 menjadi INT64 di 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

Terjemahan SQL dengan pengoptimalan ini mungkin terlihat seperti berikut:

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

Konfigurasi berikut menonaktifkan pengoptimalan dalam dialek, seperti Snowflake, yang diaktifkan secara default. Konfigurasi ini mengonversi jenis numerik menjadi NUMERIC atau BIGNUMERIC, bergantung pada presisi input, bukan default INT64.

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

Terjemahan SQL dengan pengoptimalan ini mungkin terlihat seperti berikut:

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

Membuat file YAML konfigurasi berbasis Gemini

Untuk membuat output AI, berikan setidaknya satu file *.ai_config.yaml dan aktifkan saran AI Gemini saat antarmuka memerlukannya. Untuk mengetahui informasi selengkapnya, lihat Menyediakan file konfigurasi untuk terjemahan.

Persyaratan

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

Kolom yang didukung

Tidak seperti file *.config.yaml, file *.ai_config.yaml tidak menyertakan header type. Sebagai gantinya, file tersebut berisi daftar translation_rules tingkat teratas, dengan setiap aturan mendukung kolom berikut:

suggestion_type (opsional): Tentukan jenis saran AI yang akan dibuat. Jenis saran berikut didukung:
- QUERY_CUSTOMIZATION (default): Membuat saran AI untuk kode SQL berdasarkan aturan terjemahan yang ditentukan dalam file *.ai_config.yaml.
- TRANSLATION_EXPLANATION: Menghasilkan teks yang menyertakan ringkasan kueri GoogleSQL yang diterjemahkan serta perbedaan dan inkonsistensi antara kueri SQL sumber dan kueri GoogleSQL yang diterjemahkan.
rewrite_target (opsional): Tentukan SOURCE_SQL untuk menerapkan aturan ke SQL input asli sebelum mesin terjemahan berjalan, atau TARGET_SQL untuk menerapkan aturan ke SQL yang diterjemahkan yang dihasilkan mesin terjemahan. Nilai defaultnya adalah TARGET_SQL. Untuk mengetahui informasi selengkapnya, lihat Cara penerapan kedua jenis aturan.
instruction (opsional): Menjelaskan dalam bahasa alami perubahan yang akan diterapkan pada SQL input atau SQL yang diterjemahkan untuk aturan QUERY_CUSTOMIZATION, atau penjelasan yang akan dibuat untuk aturan TRANSLATION_EXPLANATION.
examples (opsional): Berikan daftar pasangan SQL input dan output yang menunjukkan cara Anda ingin mengubah pola SQL.

Anda dapat menambahkan translation_rules dan examples tambahan sesuai kebutuhan.

Contoh

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

Menghapus fungsi upper 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"
  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

Menghapus komentar SQL dari kueri input terjemahan

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

Membuat penjelasan terjemahan menggunakan perintah LLM default

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

translation_rules:
- suggestion_type: "TRANSLATION_EXPLANATION"

Membuat penjelasan terjemahan menggunakan perintah bahasa alami Anda sendiri

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

Beberapa jenis saran dalam satu file YAML konfigurasi

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

Menerapkan beberapa konfigurasi YAML

Saat menerjemahkan satu kueri atau file SQL batch, Anda dapat memberikan 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 testdb.testschema.x(a int);
`bq-output.sql`	CREATE TEMPORARY TABLE x ( a NUMERIC(31, 2) ) ;

Mengubah terjemahan SQL dengan YAML

Jenis file YAML konfigurasi

Cara penerapan kedua jenis aturan

Menyediakan file konfigurasi ke terjemahan

Konsol

gcloud

API

MCP

Tempat menemukan output terjemahan

Persyaratan file terjemahan *.config.yaml

Panduan untuk membuat file YAML konfigurasi

Header

Pemilihan entity

Database bawaan

Jenis atribut target yang didukung

Contoh YAML konfigurasi

Mengubah kapitalisasi nama objek

Membuat tabel menjadi sementara

Membuat tabel menjadi efemeral

Menetapkan akhir masa berlaku partisi

Mengubah lokasi atau format eksternal untuk tabel

Menetapkan atau mengubah deskripsi tabel

Menetapkan atau mengubah partisi tabel

Menetapkan atau mengubah pengelompokan tabel

Mengubah jenis atribut kolom

Menambahkan koneksi ke data lake eksternal

Mengubah encoding karakter file input

Konversi jenis global

Mengonversi jenis CHAR dan VARCHAR

Menetapkan zona waktu default

Pilih modifikasi pernyataan

Spesifikasi UDF

Menghapus pola ID selama pencarian metadata

Menetapkan ketatnya presisi desimal

Menetapkan ketatnya presisi string

Pemetaan nama output

Pemetaan nama statis

Pemetaan nama dinamis

Pemetaan nama kolom

Menentukan jalur penelusuran skema dan database default

Menetapkan NLS_DATE_FORMAT

Penulisan ulang nama output global

Mengoptimalkan dan meningkatkan performa SQL yang diterjemahkan

Contoh pengoptimalan

Membuat file YAML konfigurasi berbasis Gemini

Persyaratan

Kolom yang didukung

Contoh

Menghapus fungsi upper dalam kueri output terjemahan default

Membuat beberapa aturan terjemahan untuk menyesuaikan output terjemahan

Menghapus komentar SQL dari kueri input terjemahan

Membuat penjelasan terjemahan menggunakan perintah LLM default

Membuat penjelasan terjemahan menggunakan perintah bahasa alami Anda sendiri

Beberapa jenis saran dalam satu file YAML konfigurasi

Menerapkan beberapa konfigurasi YAML

Persyaratan file terjemahan `*.config.yaml`

Mengonversi jenis `CHAR` dan `VARCHAR`

Menetapkan `NLS_DATE_FORMAT`