Menerjemahkan kueri dengan penerjemah SQL interaktif

Dokumen ini menjelaskan cara menerjemahkan kueri dari dialek SQL yang berbeda ke dalam kueri GoogleSQL menggunakan penerjemah SQL interaktif BigQuery. Penerjemah SQL interaktif dapat membantu mengurangi waktu dan upaya saat Anda memigrasikan beban kerja ke BigQuery. Dokumen ini ditujukan bagi pengguna yang sudah memahami konsolGoogle Cloud .

Jika lokasi Anda didukung, Anda dapat menggunakan fitur aturan terjemahan untuk menyesuaikan cara penerjemah SQL interaktif menerjemahkan SQL.

Sebelum memulai

Jika project Google Cloud CLI Anda dibuat sebelum 15 Februari 2022, aktifkan BigQuery Migration API seperti berikut:

  1. Di Google Cloud konsol, buka halaman BigQuery Migration API.

    Buka BigQuery Migration API

  2. Klik Enable.

Izin dan peran

Bagian ini menjelaskan izin Identity and Access Management (IAM) yang Anda perlukan untuk menggunakan penerjemah SQL interaktif, termasuk peran IAM bawaan yang memberikan izin tersebut. Bagian ini juga menjelaskan izin yang diperlukan untuk mengonfigurasi konfigurasi terjemahan tambahan.

Izin untuk menggunakan penerjemah SQL interaktif

Untuk mendapatkan izin yang diperlukan guna menggunakan penerjemah interaktif, minta administrator untuk memberi Anda MigrationWorkflow Editor (roles/bigquerymigration.editor) peran IAM pada resource parent. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran yang telah ditentukan ini berisi izin yang diperlukan untuk menggunakan penerjemah interaktif. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk menggunakan penerjemah interaktif:

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Izin untuk mengonfigurasi konfigurasi terjemahan tambahan

Anda dapat mengonfigurasi konfigurasi terjemahan tambahan menggunakan kolom Translation Config ID dan Translation Configuration Source Location di setelan terjemahan. Untuk mengonfigurasi konfigurasi terjemahan ini, Anda memerlukan izin berikut:

  • bigquerymigration.workflows.get
  • bigquerymigration.workflows.list

Peran IAM bawaan berikut memberikan izin yang diperlukan untuk mengonfigurasi konfigurasi terjemahan tambahan:

  • roles/bigquerymigration.viewer

Untuk informasi selengkapnya tentang IAM BigQuery, lihat Kontrol akses dengan IAM.

Dialek SQL yang didukung

Penerjemah SQL interaktif BigQuery dapat menerjemahkan dialek SQL berikut ke dalam GoogleSQL:

  • Amazon Redshift SQL
  • Apache HiveQL dan Beeline CLI
  • IBM Netezza SQL dan NZPLSQL
  • Teradata dan Teradata Vantage:
    • SQL
    • Basic Teradata Query (BTEQ)
    • Teradata Parallel Transport (TPT)

Selain itu, terjemahan dialek SQL berikut didukung di pratinjau:

  • Apache Spark SQL
  • Azure Synapse T-SQL
  • Greenplum SQL
  • IBM DB2 SQL
  • MySQL SQL
  • Oracle SQL, PL/SQL, Exadata
  • PostgreSQL SQL
  • Trino atau PrestoSQL
  • Snowflake SQL
  • SQL Server T-SQL
  • SQLite
  • Vertica SQL

Menangani fungsi SQL yang tidak didukung dengan UDF helper

Saat menerjemahkan SQL dari dialek sumber ke BigQuery, beberapa fungsi mungkin tidak memiliki padanan langsung. Untuk mengatasi hal ini, BigQuery Migration Service (dan komunitas BigQuery yang lebih luas) menyediakan fungsi yang ditentukan pengguna (UDF) helper yang mereplikasi perilaku fungsi dialek sumber yang tidak didukung ini.

UDF ini sering ditemukan dalam set data publik bqutil, sehingga kueri yang diterjemahkan dapat mereferensikannya pada awalnya menggunakan format bqutil.<dataset>.<function>(). Misalnya, bqutil.fn.cw_count().

Pertimbangan penting untuk lingkungan produksi:

Meskipun bqutil menawarkan akses yang mudah ke UDF helper ini untuk terjemahan dan pengujian awal, bergantung langsung pada bqutil untuk beban kerja produksi tidak direkomendasikan karena beberapa alasan:

  1. Kontrol versi: Project bqutil menghosting versi terbaru UDF ini, yang berarti definisinya dapat berubah dari waktu ke waktu. Bergantung langsung pada bqutil dapat menyebabkan perilaku yang tidak terduga atau perubahan yang merusak dalam kueri produksi Anda jika logika UDF diperbarui.
  2. Isolasi dependensi: Men-deploy UDF ke project Anda sendiri akan mengisolasi lingkungan produksi dari perubahan eksternal.
  3. Penyesuaian: Anda mungkin perlu mengubah atau mengoptimalkan UDF ini agar lebih sesuai dengan logika bisnis atau persyaratan performa tertentu. Hal ini hanya dapat dilakukan jika berada dalam project Anda sendiri.
  4. Keamanan dan tata kelola: Kebijakan keamanan organisasi Anda mungkin membatasi akses langsung ke set data publik seperti bqutil untuk pemrosesan data produksi. Menyalin UDF ke lingkungan terkontrol Anda sesuai dengan kebijakan tersebut.

Men-deploy UDF helper ke project Anda:

Untuk penggunaan produksi yang andal dan stabil, Anda harus men-deploy UDF helper ini ke project dan set data Anda sendiri. Tindakan ini memberi Anda kontrol penuh atas versi, penyesuaian, dan aksesnya. Untuk petunjuk mendetail tentang cara men-deploy UDF ini, lihat panduan deployment UDF di GitHub. Panduan ini menyediakan skrip dan langkah-langkah yang diperlukan untuk menyalin UDF ke lingkungan Anda.

Lokasi

Penerjemah SQL interaktif tersedia di lokasi pemrosesan berikut:

Deskripsi region Nama region Detail
Asia Pasifik
Delhi asia-south2
Hong Kong asia-east2
Jakarta asia-southeast2
Melbourne australia-southeast2
Mumbai asia-south1
Osaka asia-northeast2
Seoul asia-northeast3
Singapura asia-southeast1
Sydney australia-southeast1
Taiwan asia-east1
Tokyo asia-northeast1
Eropa
Belgia europe-west1 ikon daun CO Rendah2
Berlin europe-west10 ikon daun CO Rendah2
Multi-region Uni Eropa eu
Finlandia europe-north1 ikon daun CO Rendah2
Frankfurt europe-west3 ikon daun CO Rendah2
London europe-west2 ikon daun CO Rendah2
Madrid europe-southwest1 ikon daun CO Rendah2
Milan europe-west8
Belanda europe-west4 ikon daun CO Rendah2
Paris europe-west9 ikon daun CO Rendah2
Stockholm europe-north2 ikon daun CO2 Rendah
Turin europe-west12
Warsawa europe-central2
Zürich europe-west6 ikon daun CO Rendah2
Amerika
Columbus, Ohio us-east5
Dallas us-south1 ikon daun CO Rendah2
Iowa us-central1 ikon daun CO2 Rendah
Las Vegas us-west4
Los Angeles us-west2
Meksiko northamerica-south1
Northern Virginia us-east4
Oregon us-west1 ikon daun CO Rendah2
Quebec northamerica-northeast1 ikon daun CO2 Rendah
Sao Paulo southamerica-east1 ikon daun CO2 Rendah
Salt Lake City us-west3
Santiago southamerica-west1 ikon daun CO Rendah2
South Carolina us-east1
Toronto northamerica-northeast2 ikon daun CO Rendah2
Multi-region AS us
Afrika
Johannesburg africa-south1
MiddleEast
Dammam me-central2
Doha me-central1
Israel me-west1

Secara default, fitur aturan terjemahan tersedia di lokasi pemrosesan berikut:

  • us (multi-region AS)
  • eu (multi-region Uni Eropa)
  • us-central1 (Iowa)
  • europe-west4 (Belanda)

Konfigurasi terjemahan berbasis Gemini hanya tersedia di lokasi pemrosesan tertentu. Untuk informasi selengkapnya, lihat Lokasi endpoint model Google

Menerjemahkan kueri ke GoogleSQL

Ikuti langkah-langkah ini untuk menerjemahkan kueri ke GoogleSQL:

  1. Di Google Cloud konsol, buka halaman BigQuery.

    Buka BigQuery

  2. Di panel Editor, klik More, lalu pilih Translation settings.

  3. Untuk Source dialect, pilih dialek SQL yang ingin Anda terjemahkan.

  4. Opsional. Untuk Processing location, pilih lokasi tempat Anda ingin menjalankan tugas terjemahan. Misalnya, jika Anda berada di Eropa dan tidak ingin data melewati batas lokasi mana pun, pilih region eu.

  5. Klik Save.

  6. Di panel Editor, klik More, lalu pilih Enable SQL translation.

    Panel Editor dibagi menjadi dua panel.

  7. Di panel kiri, masukkan kueri yang ingin Anda terjemahkan.

  8. Klik Translate.

    BigQuery menerjemahkan kueri Anda ke GoogleSQL dan menampilkannya di panel kanan. Misalnya, screenshot berikut menunjukkan Teradata SQL yang telah diterjemahkan:

    Menampilkan kueri Teradata SQL yang diterjemahkan ke GoogleSQL

  9. Opsional: Untuk menjalankan kueri GoogleSQL yang diterjemahkan, klik Run.

  10. Opsional: Untuk kembali ke editor SQL, klik More, lalu pilih Disable SQL translation.

    Panel Editor akan kembali ke satu panel.

Menggunakan Gemini dengan penerjemah SQL interaktif

Anda dapat mengonfigurasi penerjemah SQL interaktif untuk menyesuaikan cara penerjemah SQL interaktif menerjemahkan SQL sumber Anda. Anda dapat melakukannya dengan menyediakan aturan Anda sendiri untuk digunakan dengan Gemini dalam file konfigurasi YAML, atau dengan menyediakan file YAML konfigurasi yang berisi metadata objek SQL atau informasi pemetaan objek.

Membuat dan menerapkan aturan terjemahan yang ditingkatkan dengan Gemini

Anda dapat menyesuaikan cara penerjemah SQL interaktif menerjemahkan SQL dengan membuat aturan terjemahan. Penerjemah SQL interaktif menyesuaikan terjemahannya berdasarkan aturan terjemahan SQL yang ditingkatkan Gemini yang Anda tetapkan, sehingga Anda dapat menyesuaikan hasil terjemahan berdasarkan kebutuhan migrasi. Fitur ini hanya didukung di lokasi tertentu.

Untuk membuat aturan terjemahan SQL yang ditingkatkan Gemini, Anda dapat membuatnya di konsol, atau membuat file YAML konfigurasi dan menguploadnya ke Cloud Storage.

Konsol

Untuk membuat aturan terjemahan SQL yang ditingkatkan Gemini untuk SQL input, tulis kueri SQL input di editor kueri, lalu klik ASSIST > Customize. (Pratinjau)

Menyesuaikan input terjemahan

Demikian pula, untuk membuat aturan terjemahan SQL yang ditingkatkan Gemini untuk SQL output, jalankan terjemahan interaktif, lalu klik ASSIST > Customize this translation.

Menyesuaikan output terjemahan

Saat menu Sesuaikan muncul, lanjutkan dengan langkah-langkah berikut.

  1. Gunakan salah satu atau kedua perintah berikut untuk membuat aturan terjemahan:

    • Pada perintah Cari dan ganti pola, tentukan pola SQL yang ingin Anda ganti di kolom Ganti, dan pola SQL untuk menggantinya di kolom Dengan.

      Pola SQL dapat berisi sejumlah pernyataan, klausa, atau fungsi dalam skrip SQL. Saat Anda membuat aturan menggunakan perintah ini, terjemahan SQL Gemini yang ditingkatkan akan mengidentifikasi instance pola SQL tersebut dalam kueri SQL dan menggantinya secara dinamis dengan pola SQL lain. Misalnya, Anda dapat menggunakan perintah ini untuk membuat aturan yang menggantikan semua kemunculan months_between (X,Y) dengan date_diff(X,Y,MONTH).

    • Di kolom Describe a change to the output, ketik perubahan pada output terjemahan SQL dalam bahasa alami.

      Saat Anda membuat aturan menggunakan perintah ini, terjemahan SQL yang ditingkatkan Gemini akan mengidentifikasi permintaan dan membuat perubahan yang ditentukan pada kueri SQL.

  2. Klik Pratinjau.

  3. Di dialog Saran yang dihasilkan oleh Gemini, tinjau perubahan yang dilakukan oleh terjemahan SQL yang ditingkatkan Gemini ke kueri SQL berdasarkan aturan Anda.

    Menerapkan perubahan dari file YAML konfigurasi berbasis Gemini

  4. Opsional: Untuk menambahkan aturan ini agar dapat digunakan dengan terjemahan mendatang, centang kotak Save this prompt....

    Aturan disimpan dalam file YAML konfigurasi default, atau __default.ai_config.yaml. File YAML konfigurasi ini disimpan ke folder Cloud Storage seperti yang ditentukan di kolom Translation Configuration Source Location di setelan terjemahan. Jika Lokasi Sumber Konfigurasi Terjemahan belum ditetapkan, browser folder akan muncul dan memungkinkan Anda memilihnya. File YAML konfigurasi tunduk pada batasan ukuran file konfigurasi.

  5. Untuk menerapkan perubahan yang disarankan ke kueri SQL, klik Terapkan.

YAML

Untuk membuat aturan terjemahan SQL yang ditingkatkan Gemini, Anda dapat membuat file YAML konfigurasi berbasis Gemini dan menguploadnya ke Cloud Storage. Untuk mengetahui informasi selengkapnya, lihat Membuat file YAML konfigurasi berbasis Gemini.

Setelah mengupload aturan terjemahan SQL yang ditingkatkan Gemini dan menguploadnya ke Cloud Storage, Anda dapat menerapkan aturan tersebut dengan melakukan hal berikut:

  1. Di Google Cloud konsol, buka halaman BigQuery.

    Buka BigQuery

  2. Di editor kueri, klik More > Translation settings.

  3. Di kolom Translation Configuration Source Location, tentukan jalur ke file YAML berbasis Gemini yang disimpan di folder Cloud Storage.

  4. Klik Simpan.

    Setelah disimpan, jalankan terjemahan interaktif. Penerjemah interaktif menyarankan perubahan pada terjemahan Anda berdasarkan aturan dalam file YAML konfigurasi jika tersedia.

Jika saran Gemini tersedia untuk input berdasarkan aturan Anda, dialog Pratinjau perubahan yang disarankan akan muncul dan menampilkan kemungkinan perubahan pada input terjemahan. (Pratinjau)

Jika saran Gemini tersedia untuk output berdasarkan aturan Anda, banner notifikasi akan muncul di editor kode. Untuk meninjau dan menerapkan saran ini, lakukan hal berikut:

  1. Klik Assist > View suggestions di kedua sisi editor kode untuk meninjau kembali perubahan yang disarankan pada kueri yang sesuai.

    Menerapkan perubahan dari file YAML konfigurasi berbasis Gemini

  2. Di dialog Saran yang dihasilkan oleh Gemini, tinjau perubahan yang dilakukan oleh Gemini pada kueri SQL berdasarkan aturan terjemahan Anda.

  3. Untuk menerapkan perubahan yang disarankan ke output terjemahan, klik Terapkan.

Memperbarui file YAML konfigurasi berbasis Gemini

Untuk memperbarui file YAML konfigurasi yang ada, lakukan langkah berikut:

  1. Pada dialog Saran yang dihasilkan di Gemini, klik Lihat file konfigurasi aturan Gemini.

  2. Saat editor konfigurasi muncul, pilih file YAML konfigurasi yang ingin Anda edit.

  3. Lakukan perubahan, lalu klik Simpan.

  4. Tutup editor YAML dengan mengklik Selesai.

  5. Jalankan terjemahan interaktif untuk menerapkan aturan yang diperbarui.

Menjelaskan terjemahan

Setelah menjalankan terjemahan interaktif, Anda dapat meminta penjelasan teks yang dibuat Gemini. Teks yang dihasilkan menyertakan ringkasan kueri SQL yang diterjemahkan. Gemini juga mengidentifikasi perbedaan dan inkonsistensi terjemahan antara kueri SQL sumber dan kueri GoogleSQL yang diterjemahkan.

Untuk mendapatkan penjelasan terjemahan SQL yang dihasilkan Gemini, lakukan hal berikut:

  1. Untuk membuat penjelasan terjemahan SQL yang dihasilkan Gemini, klik Assist, lalu klik Explain this translation.

    Jelaskan tombol terjemahan.

Menerjemahkan dengan ID konfigurasi terjemahan batch

Anda dapat menjalankan kueri interaktif dengan konfigurasi terjemahan yang sama seperti tugas terjemahan batch dengan memberikan ID konfigurasi terjemahan batch.

  1. Di editor kueri, klik More > Translation settings.

  2. Di kolom Translation Configuration ID, berikan ID konfigurasi terjemahan batch untuk menerapkan konfigurasi terjemahan yang sama dari tugas migrasi batch BigQuery yang telah selesai.

    Untuk menemukan ID konfigurasi terjemahan batch tugas, pilih tugas terjemahan batch dari halaman SQL translation, lalu klik tab Translation Configuration. ID konfigurasi terjemahan batch dicantumkan sebagai Resource name.

  3. Klik Simpan.

Menerjemahkan dengan konfigurasi tambahan

Anda dapat menjalankan kueri interaktif dengan konfigurasi terjemahan tambahan dengan menentukan file YAML konfigurasi yang disimpan di folder Cloud Storage. Konfigurasi terjemahan mungkin menyertakan metadata objek SQL atau informasi pemetaan objek dari database sumber yang dapat meningkatkan kualitas terjemahan. Misalnya, sertakan informasi atau skema DDL dari database sumber untuk meningkatkan kualitas terjemahan SQL interaktif.

Untuk menentukan konfigurasi terjemahan dengan memberikan lokasi ke file sumber konfigurasi terjemahan, lakukan hal berikut:

  1. Di editor kueri, klik More > Translation settings.

  2. Di kolom Translation Configuration Source Location, tentukan jalur ke file konfigurasi terjemahan yang disimpan di folder Cloud Storage.

    Penerjemah SQL interaktif BigQuery mendukung file ZIP metadata yang berisi metadata terjemahan dan pemetaan nama objek. Untuk informasi tentang cara mengupload file ke Cloud Storage, lihat Mengupload objek dari sistem file.

  3. Klik Simpan.

Untuk menyimpan informasi dari file metadata yang dihasilkan oleh alat dwh-migration-dumper di backend BigQuery, lakukan hal berikut:

  1. Di editor kueri, klik More > Translation settings.
  2. Klik kotak centang Enable metadata caching. Untuk tugas dengan file metadata besar, proses ini secara signifikan mengurangi latensi terjemahan untuk permintaan berikutnya. Metadata dalam cache aktif hingga 7 hari. Fitur ini berada dalam pratinjau. Untuk meminta dukungan atau memberikan masukan untuk fitur ini, hubungi bq-edw-migration-support@google.com.
  3. Klik Simpan.

Batasan ukuran file konfigurasi

Saat Anda menggunakan file konfigurasi terjemahan dengan penerjemah SQL interaktif BigQuery, file metadata yang dikompresi atau file konfigurasi YAML harus lebih kecil dari 50 MB. Jika ukuran file lebih dari 50 MB, penerjemah interaktif akan melewati file konfigurasi tersebut selama penerjemahan dan menghasilkan pesan error yang mirip dengan berikut ini:

CONFIG ERROR: Skip reading file "gs://metadata-file.zip". File size (150,000,000 bytes) exceeds limit (50 MB).

Salah satu metode untuk mengurangi ukuran file metadata adalah menggunakan flag --database atau --schema agar hanya mengekstrak metadata untuk database atau skema yang relevan untuk kueri input terjemahan. Untuk informasi selengkapnya tentang penggunaan flag ini saat membuat file metadata, lihat Flag global.

Memecahkan masalah error terjemahan

Berikut adalah error umum yang terjadi saat menggunakan penerjemah SQL interaktif.

Masalah terjemahan RelationNotFound atau AttributeNotFound

Untuk memastikan terjemahan yang paling akurat, Anda dapat memasukkan pernyataan bahasa definisi data (DDL) untuk tabel apa pun yang digunakan dalam kueri sebelum kueri itu sendiri. Misalnya, jika ingin menerjemahkan kueri Amazon Redshift select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id;, Anda harus memasukkan pernyataan SQL berikut ke dalam penerjemah SQL interaktif:

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

Harga

Penggunaan penerjemah SQL interaktif tidak dikenai biaya. Namun, penyimpanan yang digunakan untuk menyimpan file input dan output dikenai biaya normal. Untuk mengetahui informasi selengkapnya, lihat Harga penyimpanan.

Langkah berikutnya

Pelajari lebih lanjut langkah-langkah berikut dalam migrasi data warehouse: