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 Google Cloud konsol.

Anda dapat menggunakan fitur aturan terjemahan untuk menyesuaikan cara penerjemah SQL interaktif menerjemahkan SQL.

Untuk mengetahui daftar dialek SQL yang didukung oleh penerjemah SQL ini, lihat Dialek SQL yang didukung.

Untuk mengetahui daftar lokasi pemrosesan yang didukung, lihat Lokasi.

Sebelum memulai

Sebelum Anda mengirimkan tugas terjemahan, lakukan langkah-langkah berikut.

Mengaktifkan terjemahan SQL

Aktifkan API yang diperlukan, dan dapatkan izin yang diperlukan untuk menggunakan penerjemah SQL BigQuery. Untuk mengetahui informasi selengkapnya, lihat Mengaktifkan terjemahan SQL.

Izin yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk membuat tugas terjemahan dengan penerjemah interaktor, Translation API, atau penerjemah SQL batch, minta administrator untuk memberi Anda peran IAM berikut pada resource parent:

• Melihat dan memantau tugas migrasi: MigrationWorkflow Viewer (roles/bigquerymigration.viewer)
• Mengirimkan tugas migrasi: MigrationWorkflow Editor (roles/bigquerymigration.editor)
• Mengakses bucket Cloud Storage untuk file input dan output: Storage Object Admin (roles/storage.objectAdmin) - di bucket Cloud Storage sumber dan tujuan.

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk membuat tugas terjemahan dengan penerjemah interaktor, Translation API, atau penerjemah SQL batch. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat tugas terjemahan dengan penerjemah interaktor, Translation API, atau penerjemah SQL batch:

• bigquerymigration.workflows.create
• bigquerymigration.workflows.get
• bigquerymigration.workflows.list
• bigquerymigration.workflows.delete
• bigquerymigration.subtasks.get
• bigquerymigration.subtasks.list
• storage.objects.get
• storage.objects.list
• storage.objects.create

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

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 di set data publik bqutil, sehingga kueri yang diterjemahkan dapat awalnya mereferensikannya menggunakan format bqutil.<dataset>.<function>(). Misalnya, bqutil.fn.cw_count().

Pertimbangan penting untuk lingkungan produksi:

Meskipun bqutil menawarkan akses mudah ke UDF helper ini untuk terjemahan dan pengujian awal, pengandalan 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 melanggar dalam kueri produksi Anda jika logika UDF diperbarui.
2. Isolasi dependensi: Men-deploy UDF ke project Anda sendiri akan mengisolasi lingkungan produksi Anda 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 UDF 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 yang Anda kontrol selaras 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. Hal ini memberi Anda kontrol penuh atas versi, penyesuaian, dan aksesnya. Untuk mengetahui 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 hanya tersedia di lokasi pemrosesan tertentu. Untuk mengetahui informasi selengkapnya, lihat Lokasi.

Konfigurasi terjemahan berbasis Gemini hanya tersedia di lokasi pemrosesan tertentu. Untuk mengetahui 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 Tools > 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 Tools > 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:

   

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

10. Opsional: Untuk kembali ke editor SQL, klik More > 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 dapat melakukannya dengan memberikan aturan Anda sendiri untuk digunakan dengan Gemini dalam file konfigurasi YAML, atau dengan memberikan file YAML konfigurasi yang berisi metadata objek SQL atau informasi pemetaan objek.

Membuat dan menerapkan aturan terjemahan yang ditingkatkan Gemini

Catatan: Untuk mendapatkan dukungan dan memberikan masukan untuk fitur pratinjau, hubungi [e-mail].

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 Anda.

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 input SQL, tulis kueri SQL input di editor kueri, lalu klik ASSIST > Customize. (Pratinjau)

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

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

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

   • Di perintah Find and replace a pattern, tentukan pola SQL yang ingin Anda ganti di kolom Replace, dan pola SQL untuk menggantinya di kolom With.

     Pola SQL dapat berisi sejumlah pernyataan, klausa, atau fungsi dalam skrip SQL. Saat Anda membuat aturan menggunakan perintah ini, terjemahan SQL yang ditingkatkan Gemini akan mengidentifikasi semua 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 mengganti 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 Preview.

3. Di dialog Suggestions generated by Gemini, tinjau perubahan yang dibuat oleh terjemahan SQL yang ditingkatkan Gemini pada kueri SQL berdasarkan aturan Anda.

   

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 Translation Configuration Source Location belum ditetapkan, browser folder akan muncul dan memungkinkan Anda memilih salah satu. File YAML konfigurasi tunduk pada batasan ukuran file konfigurasi.

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

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 Tools > Translation settings.

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

4. Klik Save.

   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 Preview suggested changes 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.

   

2. Di dialog Suggestions generated by Gemini, tinjau perubahan yang dibuat oleh Gemini pada kueri SQL berdasarkan aturan terjemahan Anda.

3. Untuk menerapkan perubahan yang disarankan pada output terjemahan, klik Apply.

Memperbarui file YAML konfigurasi berbasis Gemini

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

1. Di dialog Suggestions generated in Gemini, klik View Gemini rule config file.

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

3. Buat perubahan dan klik Save.

4. Tutup editor YAML dengan mengklik Done.

5. Jalankan terjemahan interaktif untuk menerapkan aturan yang diperbarui.

Menjelaskan terjemahan

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Catatan: Dengan terjemahan SQL yang ditingkatkan Gemini, Anda dapat membuat penjelasan teks untuk skrip Anda dengan model Gemini. Terjemahan SQL yang ditingkatkan Gemini diizinkan menggunakan Gemini dalam jumlah terbatas tanpa biaya. Penggunaan ini cukup untuk sebagian besar project migrasi. Untuk meminta peningkatan batas ini, atau untuk mendapatkan dukungan dan memberikan masukan untuk fitur Pratinjau ini, hubungi [e-mail].

Setelah menjalankan terjemahan interaktif, Anda dapat meminta penjelasan teks yang dibuat Gemini. Teks yang dihasilkan mencakup 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 dibuat Gemini, lakukan hal berikut:

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

   

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 Tools > 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 Save.

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 Tools > 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 Save.

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 Anda membuat file metadata, lihat Flag global.

Memecahkan masalah error terjemahan

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

Masalah terjemahan RelationNotFound atau AttributeNotFound

Setelah menerjemahkan kueri menggunakan penerjemah SQL interaktif, Anda mungkin mengalami terjemahan yang gagal dengan error RelationNotFound atau AttributeNotFound.

Anda dapat menemukan terjemahan yang gagal dengan membuka halaman Translation details dan membuka tab Log Messages.

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;

Memperbaiki masalah terjemahan dengan Gemini

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Catatan: Untuk meminta masukan atau dukungan terkait fitur ini, hubungi [e-mail].

Untuk memperbaiki tugas terjemahan yang gagal dengan error RelationNotFound atau AttributeNotFound, Anda juga dapat menggunakan Gemini untuk mencoba menyelesaikan masalah ini dengan langkah-langkah berikut.

1. Buka halaman Translation details dan buka tab Log Messages.

2. Klik kueri yang memiliki pesan RelationNotFound atau AttributeNotFound di kolom Category.

3. Klik Suggested fix.

4. Klik Apply.

5. Klik Translate untuk menerjemahkan kembali kueri.

Harga

Tidak ada biaya untuk menggunakan penerjemah SQL interaktif. Namun, penyimpanan yang digunakan untuk menyimpan file input dan output dikenakan biaya normal. Untuk mengetahui informasi selengkapnya, lihat Harga penyimpanan.

Langkah berikutnya

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

• Ringkasan migrasi
• Penilaian migrasi
• Ringkasan skema dan transfer data
• Terjemahan batch SQL
• Data pipelines
• Tata kelola dan keamanan data
• Alat validasi data