Memigrasikan kode dengan penerjemah SQL batch

Dokumen ini menjelaskan cara menggunakan penerjemah SQL batch di BigQuery untuk menerjemahkan skrip yang ditulis dalam dialek SQL lainnya ke dalam kueri GoogleSQL. Anda dapat mengirimkan dan meninjau hasil tugas terjemahan dari konsol Google Cloud atau dari command line.

Catatan: Untuk membuat integrasi software kustom, pipeline CI/CD otomatis, atau alur kerja terprogram lainnya, sebaiknya panggil BigQuery Migration API secara langsung.

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 Anda untuk memberi Anda peran IAM berikut pada resource parent:

• Melihat dan memantau tugas migrasi: Pelihat MigrationWorkflow (roles/bigquerymigration.viewer)
• Mengirimkan tugas migrasi: MigrationWorkflow Editor (roles/bigquerymigration.editor)
• Akses bucket dan file Cloud Storage untuk input: 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 interaktif, 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.

Mengumpulkan file sumber

File sumber harus berupa file teks yang berisi SQL yang valid untuk dialek sumber. File sumber juga dapat menyertakan komentar. Lakukan yang terbaik untuk memastikan bahwa SQL valid, menggunakan metode apa pun yang tersedia.

Membuat file metadata

Untuk membantu layanan memberikan hasil terjemahan yang lebih akurat, sebaiknya Anda menyediakan file metadata. Namun, hal ini tidak wajib.

Anda dapat menggunakan alat ekstraksi command line dwh-migration-dumper untuk menghasilkan informasi metadata. Setelah menyiapkan file metadata, Anda dapat menyertakannya bersama dengan file sumber dalam folder sumber terjemahan. Penerjemah otomatis mendeteksinya dan memanfaatkannya untuk menerjemahkan file sumber. Anda tidak perlu mengonfigurasi setelan tambahan untuk mengaktifkannya.

Untuk menghasilkan informasi metadata menggunakan alat dwh-migration-dumper, lihat Membuat metadata untuk terjemahan.

Membuat file YAML konfigurasi

Jika ingin, Anda dapat membuat dan menggunakan file YAML konfigurasi untuk menyesuaikan terjemahan batch. File ini dapat digunakan untuk mengubah output terjemahan dengan berbagai cara. Misalnya, Anda dapat membuat file YAML konfigurasi untuk mengubah huruf objek SQL selama penerjemahan.

Gunakan salah satu opsi berikut untuk menyertakan file YAML konfigurasi dalam tugas terjemahan Anda.

Konsol

Upload file YAML konfigurasi ke direktori Cloud Storage yang berisi file sumber Anda. Saat Anda memilih direktori tersebut sebagai lokasi input, tugas terjemahan akan menyertakan file YAML konfigurasi secara otomatis.

gcloud

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.

Flag yang Anda gunakan dengan perintah gcloud alpha bq translation translate-batch bergantung pada tempat file YAML konfigurasi disimpan:

• Jika file YAML konfigurasi berada di direktori yang sama dengan file sumber, Anda tidak memerlukan flag tambahan. Saat Anda menyetel direktori tersebut di flag --source-gcs-uris atau --source-local-dirs, tugas akan menyertakan file YAML konfigurasi secara otomatis.
• Jika file YAML konfigurasi disimpan secara terpisah di mesin lokal Anda, gunakan flag --source-local-files untuk menguploadnya dan menambahkannya ke tugas.
• Jika file YAML konfigurasi disimpan secara terpisah di Cloud Storage, gunakan tanda --source-gcs-files untuk menambahkannya ke tugas.

Misalnya, perintah berikut mengupload file sumber dan file YAML konfigurasi yang disimpan secara terpisah dari komputer lokal Anda, lalu menjalankan tugas terjemahan:

gcloud alpha bq translation translate-batch \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-local-dirs=LOCAL_DIR=SOURCE_URI \
  --source-local-files=LOCAL_CONFIG_YAML=CONFIG_YAML_URI \
  --target-gcs-path=TARGET_URI

Ganti kode berikut:

• LOCAL_CONFIG_YAML: jalur lokal ke file YAML konfigurasi, seperti ./configs/change-case.config.yaml.
• CONFIG_YAML_URI: Cloud Storage URI tempat perintah mengupload file YAML konfigurasi, seperti gs://my_data_bucket/teradata/configs/change-case.config.yaml. URI ini harus berada di luar direktori SOURCE_URI.

Untuk mengetahui deskripsi placeholder lainnya, lihat Mengirimkan tugas terjemahan.

Mengupload file input ke Cloud Storage

Upload file sumber yang berisi kueri dan skrip yang ingin Anda terjemahkan ke Cloud Storage. Anda juga dapat mengupload file metadata apa pun atau file YAML konfigurasi ke bucket Cloud Storage dan direktori yang sama yang berisi file sumber. Untuk mengetahui informasi selengkapnya tentang membuat bucket dan mengupload file ke Cloud Storage, lihat Membuat bucket dan Mengupload objek dari sistem file.

Pilih cara mengirimkan tugas terjemahan

Anda memiliki dua opsi untuk mengirimkan tugas terjemahan batch:

• KonsolGoogle Cloud : Mengonfigurasi dan mengirimkan tugas menggunakan antarmuka pengguna. Pendekatan ini mengharuskan Anda mengupload file sumber ke Cloud Storage.

• Google Cloud CLI: Kirimkan tugas dari command line menggunakan gcloud CLI. Perintah translate-batch menerima lokasi sumber dan target Anda sebagai tanda, dan dapat mengupload direktori dan file lokal ke Cloud Storage untuk Anda. Untuk mengetahui informasi selengkapnya, lihat Mengirimkan tugas terjemahan.

Kedua opsi mengharuskan file sumber Anda dapat diakses di Cloud Storage, dan keduanya membuat jenis tugas terjemahan yang sama. Tugas yang Anda kirimkan dari command line masih muncul dalam daftar tugas terjemahan di Google Cloud konsol.

Mengirim tugas terjemahan

Gunakan salah satu opsi berikut untuk memulai tugas terjemahan dan melihat progresnya. Untuk meninjau hasilnya setelahnya, lihat Menjelajahi output terjemahan.

Konsol

Langkah-langkah ini mengasumsikan bahwa Anda telah mengupload file sumber ke bucket Cloud Storage.

Untuk menggunakan konsol Google Cloud guna mengirimkan tugas terjemahan batch, lakukan langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman SQL Translation.

   Buka Terjemahan SQL

2. Di panel SQL translation, klik Start translation.

3. Untuk Konfigurasi terjemahan, masukkan yang berikut:

   1. Untuk Nama tampilan, masukkan nama untuk tugas terjemahan. Nama tersebut dapat berisi huruf, angka, atau garis bawah.
   2. Untuk Processing location, pilih lokasi tempat Anda ingin menjalankan tugas terjemahan. Misalnya, jika Anda berada di Eropa dan tidak ingin data Anda melewati batas lokasi, pilih region eu. Tugas terjemahan akan memiliki performa terbaik jika Anda memilih lokasi yang sama dengan bucket file sumber.
   3. Untuk Source dialect, pilih dialek SQL yang ingin Anda terjemahkan.
   4. Untuk Target dialect, pilih GoogleSQL.

4. Klik Berikutnya.

5. Untuk Detail lokasi file, tentukan jalur Cloud Storage yang akan digunakan untuk input dan output terjemahan. Anda dapat memasukkan jalur dalam format bucket_name/folder_name/ atau menggunakan opsi Browse untuk membuka folder.

   1. Untuk Output directory location, tentukan jalur ke folder Cloud Storage tujuan untuk file yang diterjemahkan. Direktori ini berfungsi sebagai direktori root untuk semua output terjemahan.
   2. Pilih satu atau beberapa Lokasi direktori input yang berisi jalur ke file SQL yang akan diterjemahkan.
   3. Setiap direktori input dapat diberi nama subdirektori Output di bawah direktori output root jika diperlukan.

6. Klik Berikutnya.

7. Pilih setelan opsional yang diperlukan untuk menyesuaikan metadata dan output terjemahan tambahan.

8. Opsional: Untuk menyesuaikan perilaku terjemahan lebih lanjut, buat file YAML konfigurasi dan tempatkan file ini di bucket Cloud Storage input. File ini dapat digunakan untuk mengganti nama objek, mengaktifkan pengoptimalan, meningkatkan kualitas terjemahan dengan Gemini, dan banyak lagi. Untuk mengetahui informasi selengkapnya tentang file YAML konfigurasi, lihat Membuat file YAML konfigurasi.

9. Klik Create untuk memulai tugas terjemahan.

   Setelah membuat tugas terjemahan, Anda dapat melihat statusnya di daftar tugas terjemahan.

gcloud

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.

Untuk mengirimkan tugas terjemahan batch, gunakan perintah gcloud alpha bq translation translate-batch. Flag yang Anda gunakan untuk mengidentifikasi file sumber bergantung pada apakah file tersebut ada di Cloud Storage atau di komputer lokal Anda.

Menerjemahkan file SQL di Cloud Storage

Untuk menerjemahkan file SQL yang telah diupload ke Cloud Storage, identifikasi direktori sumber dengan tanda --source-gcs-uris. Jika ingin menyertakan file yang tidak ada di --source-gcs-uris, Anda dapat menggunakan flag --source-gcs-files:

gcloud alpha bq translation translate-batch \
    --source-dialect=SOURCE_DIALECT \
    --target-dialect=TARGET_DIALECT \
    --location=LOCATION \
    --source-gcs-uris=SOURCE_URI \
    --target-gcs-path=TARGET_URI

Ganti kode berikut:

• SOURCE_DIALECT: dialek file SQL sumber, seperti teradata. Untuk mengetahui nilai yang didukung, lihat Dialek SQL yang didukung.
• TARGET_DIALECT: dialek untuk menerjemahkan file sumber. Contoh, bigquery.
• LOCATION: lokasi yang memproses tugas, seperti us.
• SOURCE_URI: direktori Cloud Storage yang berisi file sumber, seperti gs://my_data_bucket/teradata/input/.
• TARGET_URI: direktori Cloud Storage yang menerima file terjemahan, seperti gs://my_data_bucket/teradata/output/.

Menerjemahkan file SQL di komputer lokal

Untuk menerjemahkan file yang ada di komputer lokal Anda, petakan setiap direktori lokal ke Cloud Storage URI dengan tanda --source-local-dirs. Perintah ini mengupload direktori ke URI tersebut, lalu menyertakan URI dalam tugas terjemahan, sehingga Anda tidak perlu mengupload file sendiri:

gcloud alpha bq translation translate-batch \
    --source-dialect=SOURCE_DIALECT \
    --target-dialect=TARGET_DIALECT \
    --location=LOCATION \
    --source-local-dirs=LOCAL_DIR=SOURCE_URI \
    --target-gcs-path=TARGET_URI

Ganti LOCAL_DIR dengan direktori lokal yang berisi file sumber, seperti ./teradata_queries. Untuk deskripsi placeholder lainnya, lihat Menerjemahkan file SQL di Cloud Storage.

Untuk memetakan file satu per satu, bukan direktori, gunakan flag --source-local-files.

Menambahkan flag opsional

Untuk membuat saran Gemini bersama dengan SQL yang diterjemahkan, tambahkan tanda --enable-ai-suggestion.

Secara default, perintah akan menunggu hingga tugas terjemahan selesai. Untuk mengirimkan tugas dan langsung kembali, tambahkan tanda --async. Kemudian, perintah akan mencetak ID terjemahan yang dapat Anda teruskan ke perintah gcloud alpha bq translation describe untuk memeriksa status tugas:

gcloud alpha bq translation describe TRANSLATION_ID \
    --location=LOCATION

Mengambil file output

Tugas terjemahan menulis hasilnya ke direktori Cloud Storage yang Anda tetapkan di flag --target-gcs-path. Direktori target ini menyimpan file yang diterjemahkan, laporan ringkasan terjemahan, dan file saran AI.

Untuk menyalin output ke komputer lokal, gunakan perintah berikut:

gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY

Ganti kode berikut:

• TARGET_URI: URI dasar target Anda, seperti gs://my_data_bucket/teradata/output/.
• LOCAL_DIRECTORY: direktori lokal yang menerima file.

Tugas Anda juga muncul dalam daftar tugas terjemahan di konsolGoogle Cloud , meskipun Anda mengirimkannya dari command line. Untuk meninjau kualitas output terjemahan, lihat Mempelajari output terjemahan.

Menerjemahkan metadata

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.

Selain menerjemahkan skrip SQL, Anda dapat menerjemahkan metadata yang menjelaskan data warehouse sumber Anda. Tugas terjemahan metadata membaca file metadata yang Anda ekstrak dari sistem sumber dan menulis pernyataan bahasa definisi data (DDL) GoogleSQL yang membuat ulang objek tersebut di BigQuery.

Inputnya adalah satu atau beberapa file ZIP metadata. Untuk mempelajari cara membuat file ini dengan alat dwh-migration-dumper, lihat Membuat metadata untuk terjemahan.

Anda dapat menerjemahkan metadata menggunakan konsol Google Cloud atau gcloud CLI. Pilih salah satu opsi berikut:

Konsol

Terjemahan metadata adalah opsi output pada tugas terjemahan reguler:

1. Ikuti langkah-langkah di Mengirimkan tugas terjemahan untuk mengonfigurasi tugas, menggunakan direktori Cloud Storage yang berisi file ZIP metadata Anda sebagai lokasi input.
2. Di Setelan opsional, pilih DDL.
3. Klik Buat untuk membuat tugas.

Tugas ini menulis pernyataan DDL yang diterjemahkan ke direktori output Anda, bersama dengan SQL yang diterjemahkan.

gcloud

Anda dapat menerjemahkan metadata sebagai tugasnya sendiri, atau sebagai output tambahan dari tugas terjemahan SQL batch.

Menerjemahkan metadata secara terpisah

Gunakan perintah gcloud alpha bq translation translate-metadata jika input Anda adalah file ZIP metadata dan Anda tidak memiliki SQL untuk diterjemahkan:

gcloud alpha bq translation translate-metadata \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI

Ganti kode berikut:

• SOURCE_DIALECT: dialek metadata sumber, seperti teradata. Untuk mengetahui nilai yang didukung, lihat Dialek SQL yang didukung.
• TARGET_DIALECT: dialek tabel target. Contoh, bigquery.
• LOCATION: lokasi yang memproses tugas, seperti us.
• SOURCE_URI: direktori Cloud Storage yang berisi file ZIP metadata, seperti gs://my_data_bucket/teradata/metadata/.
• TARGET_URI: direktori Cloud Storage yang menerima pernyataan DDL yang diterjemahkan, seperti gs://my_data_bucket/teradata/ddl_output/.

Untuk menunjuk ke setiap file ZIP metadata, bukan direktori, gunakan flag --source-gcs-files. Untuk mengupload file metadata dari komputer lokal sebagai bagian dari tugas, gunakan flag --source-local-dirs atau --source-local-files.

Seperti tugas terjemahan batch, perintah menunggu hingga tugas selesai. Tambahkan flag --async untuk mengirimkan tugas dan segera menampilkan ID terjemahan.

Menerjemahkan metadata sebagai bagian dari terjemahan SQL batch

Jika input terjemahan batch Anda sudah menyertakan file ZIP metadata, Anda tidak memerlukan tugas kedua. Tambahkan metadata ke output terjemahan tugas batch dengan tanda --target-types, dan tugas akan menulis SQL yang diterjemahkan dan pernyataan DDL dalam satu kali eksekusi:

gcloud alpha bq translation translate-batch \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI \
  --target-types=sql,metadata

Untuk tanda lainnya yang diterima perintah translate-batch, lihat Mengirimkan tugas terjemahan.

Buat DDL sumber

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.

Jika SQL sumber Anda mereferensikan tabel yang definisinya tidak Anda miliki, penerjemah tidak selalu dapat me-resolve objek, yang menyebabkan masalah RelationNotFound atau AttributeNotFound.

Cara terbaik untuk mengatasi masalah ini adalah dengan memberikan definisi sebenarnya dari objek sumber Anda. Jalankan alat dwh-migration-dumper terhadap sistem sumber Anda dan sertakan file ZIP metadata yang dihasilkan dalam input terjemahan. Untuk mengetahui petunjuknya, lihat Membuat metadata untuk terjemahan. Metadata yang diekstrak menjelaskan objek Anda secara persis, sehingga penerjemah dapat menyelesaikannya tanpa perlu menebak-nebak.

Jika Anda tidak dapat mengekstrak metadata, misalnya saat Anda tidak lagi memiliki akses ke sistem sumber, Anda dapat meminta Gemini menyimpulkan pernyataan DDL yang hilang dari SQL sumber Anda. Gemini menyimpulkan pernyataan DDL ini dari cara objek digunakan dalam kueri Anda, jadi selalu tinjau dan verifikasi pernyataan ini sebelum menggunakannya.

Anda dapat membuat DDL sumber untuk terjemahan menggunakan KonsolGoogle Cloud atau gcloud CLI. Pilih salah satu opsi berikut:

Konsol

Gemini menghasilkan saran DDL sumber sebagai bagian dari tugas terjemahan reguler:

1. Ikuti langkah-langkah di Mengirimkan tugas terjemahan untuk mengonfigurasi tugas.
2. Di Setelan opsional, pilih Saran AI Gemini.
3. Klik Buat untuk membuat tugas.

Jika terjemahan menghasilkan masalah RelationNotFound atau AttributeNotFound, tugas akan membuat pernyataan DDL sumber yang disarankan untuk objek yang belum terselesaikan. Tugas ini juga menerjemahkan SQL Anda, sehingga Anda tidak memerlukan tugas terpisah.

gcloud

Perintah gcloud alpha bq translation generate-source-ddl membaca SQL sumber Anda dan menampilkan pernyataan DDL sumber yang disarankan:

gcloud alpha bq translation generate-source-ddl \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI

Ganti SOURCE_URI dengan direktori Cloud Storage yang berisi file SQL sumber, dan TARGET_URI dengan direktori Cloud Storage yang menerima pernyataan DDL yang dihasilkan. Placeholder lainnya sama dengan yang dijelaskan dalam Menerjemahkan metadata.

Untuk membuat saran sebagai bagian dari tugas terjemahan, tambahkan flag --enable-ai-suggestion ke perintah translate-batch.

Kemudian, Anda dapat memberikan pernyataan DDL yang dihasilkan sebagai input ke tugas terjemahan selanjutnya untuk meningkatkan kualitas terjemahan. Untuk mengetahui informasi selengkapnya, lihat masalah terjemahan RelationNotFound atau AttributeNotFound.

Pelajari output terjemahan

Anda dapat meninjau hasil tugas terjemahan di konsol Google Cloud , terlepas dari apakah tugas dikirimkan dari command line atau konsol Google Cloud . Penerjemah SQL batch menghasilkan file berikut ke tujuan yang ditentukan:

• File yang diterjemahkan.
• Laporan ringkasan terjemahan dalam format CSV.
• File saran AI.

Output konsolGoogle Cloud

Untuk melihat detail tugas terjemahan, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman SQL Translation.

   Buka Terjemahan SQL

2. Dalam daftar tugas terjemahan, temukan tugas yang ingin Anda lihat detail terjemahannya. Kemudian, klik nama tugas terjemahan. Anda dapat melihat visualisasi Sankey yang menggambarkan kualitas keseluruhan tugas, jumlah baris kode input (tidak termasuk baris kosong dan komentar), dan daftar masalah yang terjadi selama proses terjemahan. Anda harus memprioritaskan perbaikan dari kiri ke kanan. Masalah pada tahap awal dapat menyebabkan masalah tambahan pada tahap berikutnya.

3. Arahkan kursor ke error atau peringatan, dan tinjau saran untuk menentukan langkah berikutnya dalam men-debug tugas terjemahan.

4. Pilih tab Ringkasan Log untuk melihat ringkasan masalah terjemahan, termasuk kategori masalah, tindakan yang disarankan, dan seberapa sering setiap masalah terjadi. Anda dapat mengklik batang visualisasi Sankey untuk memfilter masalah. Anda juga dapat memilih kategori masalah untuk melihat pesan log yang terkait dengan kategori masalah tersebut.

5. Pilih tab Pesan Log untuk melihat detail selengkapnya tentang setiap masalah terjemahan, termasuk kategori masalah, pesan masalah tertentu, dan link ke file tempat masalah terjadi. Anda dapat mengklik batang visualisasi Sankey untuk memfilter masalah. Anda dapat memilih masalah di tab Log Message untuk membuka tab Kode yang menampilkan file input dan output jika berlaku.

6. Klik tab Job details untuk melihat detail konfigurasi tugas terjemahan.

Laporan ringkasan

Laporan ringkasan adalah file CSV yang berisi tabel yang memuat semua pesan peringatan dan error yang ditemukan selama tugas terjemahan.

Untuk melihat file ringkasan di konsol Google Cloud , ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman SQL Translation.

   Buka Terjemahan SQL

2. Dalam daftar tugas terjemahan, temukan tugas yang Anda minati, lalu klik nama tugas atau klik Opsi lainnya > Tampilkan detail.

3. Di tab Job details, di bagian Translation report, klik translation_report.csv.

4. Di halaman Object details, klik nilai di baris Authenticated URL untuk melihat file di browser Anda.

Tabel berikut menjelaskan kolom file ringkasan:

Kolom	Deskripsi
Stempel waktu	Stempel waktu saat masalah terjadi.
FilePath	Jalur ke file sumber yang terkait dengan masalah.
FileName	Nama file sumber yang terkait dengan masalah.
ScriptLine	Nomor baris tempat masalah terjadi.
ScriptColumn	Nomor kolom tempat masalah terjadi.
TranspilerComponent	Komponen internal mesin terjemahan tempat peringatan atau error terjadi. Kolom ini mungkin kosong.
Lingkungan	Lingkungan dialek terjemahan yang terkait dengan peringatan atau error. Kolom ini mungkin kosong.
ObjectName	Objek SQL dalam file sumber yang terkait dengan peringatan atau error. Kolom ini mungkin kosong.
Keseriusan	Tingkat keparahan masalah, baik berupa peringatan maupun error.
Kategori	Kategori masalah terjemahan.
SourceType	Sumber masalah ini. Nilai dalam kolom ini dapat berupa SQL, yang menunjukkan masalah dalam file SQL input, atau METADATA, yang menunjukkan masalah dalam paket metadata.
Pesan	Pesan error atau peringatan masalah terjemahan.
ScriptContext	Cuplikan SQL dalam file sumber yang terkait dengan masalah.
Tindakan	Tindakan yang kami sarankan untuk Anda lakukan guna menyelesaikan masalah.

Tab Kode

Tab kode memungkinkan Anda meninjau informasi lebih lanjut tentang file input dan output untuk tugas terjemahan tertentu. Di tab kode, Anda dapat memeriksa file yang digunakan dalam tugas terjemahan, meninjau perbandingan berdampingan antara file input dan terjemahannya untuk menemukan ketidakakuratan, serta melihat ringkasan dan pesan log untuk file tertentu dalam tugas.

Untuk mengakses tab kode, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman SQL Translation.

   Buka Terjemahan SQL

2. Dalam daftar tugas terjemahan, temukan tugas yang Anda minati, lalu klik nama tugas atau klik Opsi lainnya > Tampilkan detail.

3. Pilih Tab kode. Tab kode terdiri dari panel berikut:

   

   • Penjelajah file: Berisi semua file SQL yang digunakan untuk terjemahan. Klik file untuk melihat input dan output terjemahannya, serta masalah terjemahan dari terjemahannya.
   • Input yang ditingkatkan Gemini: Input SQL yang diterjemahkan oleh mesin terjemahan. Jika Anda telah menentukan aturan penyesuaian Gemini untuk SQL sumber dalam konfigurasi Gemini, maka penerjemah akan mengubah input asli terlebih dahulu, lalu menerjemahkan input yang ditingkatkan Gemini. Untuk melihat input asli, klik Lihat input asli.
   • Output terjemahan: Hasil terjemahan. Jika Anda telah menentukan aturan penyesuaian Gemini untuk SQL target di konfigurasi Gemini, maka transformasi diterapkan pada hasil terjemahan sebagai output yang ditingkatkan Gemini. Jika output yang ditingkatkan Gemini tersedia, Anda dapat mengklik tombol Saran Gemini untuk meninjau output yang ditingkatkan Gemini.

4. Opsional: Untuk melihat file input dan file outputnya di penerjemah SQL interaktif BigQuery, klik Edit. Anda dapat mengedit file dan menyimpan file output kembali ke Cloud Storage.

Catatan: Anda dapat melihat ringkasan dan pesan log untuk tugas terjemahan secara keseluruhan dari halaman Hasil

Tab konfigurasi

Anda dapat menambahkan, mengganti nama, melihat, atau mengedit file YAML konfigurasi di tab Konfigurasi. Schema Explorer menampilkan dokumentasi untuk jenis konfigurasi yang didukung guna membantu Anda menulis file YAML konfigurasi. Setelah mengedit file YAML konfigurasi, Anda dapat menjalankan ulang tugas untuk menggunakan konfigurasi baru.

Untuk mengakses tab konfigurasi, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman SQL Translation.

   Buka Terjemahan SQL

2. Dalam daftar tugas terjemahan, temukan tugas yang Anda minati, lalu klik nama tugas atau klik Opsi lainnya > Tampilkan detail.

3. Di jendela Detail terjemahan, klik tab Konfigurasi.

Untuk menambahkan file konfigurasi baru:

1. Klik more_vert Opsi lainnya > Buat file YAML konfigurasi.
2. Panel akan muncul tempat Anda dapat memilih jenis, lokasi, dan nama file YAML konfigurasi baru.
3. Klik Create.

Untuk mengedit file konfigurasi yang ada:

1. Klik file YAML konfigurasi.
2. Edit file, lalu klik Simpan.
3. Klik Jalankan ulang untuk menjalankan tugas terjemahan baru yang menggunakan file YAML konfigurasi yang telah diedit.

Anda dapat mengganti nama file konfigurasi yang ada dengan mengklik more_vert Opsi lainnya > Ganti nama.

File yang diterjemahkan

Untuk setiap file sumber, file output yang sesuai akan dihasilkan di jalur tujuan. File output berisi kueri yang diterjemahkan.

Penting: Terjemahan dilakukan berdasarkan upaya terbaik. Jika memungkinkan, validasi kueri yang diterjemahkan.

Menangani fungsi SQL yang tidak didukung dengan UDF pembantu

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) pembantu yang mereplikasi perilaku fungsi dialek sumber yang tidak didukung ini.

UDF ini sering ditemukan di set data publik bqutil, sehingga kueri yang diterjemahkan dapat merujuknya terlebih dahulu menggunakan format bqutil.<dataset>.<function>(). Misalnya, bqutil.fn.cw_count().

Pertimbangan untuk lingkungan produksi

Meskipun bqutil menawarkan akses mudah ke UDF helper ini untuk terjemahan dan pengujian awal, pengandalan langsung pada bqutil untuk workload produksi tidak direkomendasikan karena alasan berikut:

1. Kontrol versi: Project bqutil menghosting versi terbaru UDF ini, yang berarti definisinya dapat berubah seiring waktu. Mengandalkan bqutil secara langsung 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 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 mereka 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 dikontrol sesuai dengan kebijakan tersebut.

Men-deploy UDF helper ke project Anda

Untuk memberi Anda kontrol penuh atas versi, penyesuaian, dan akses UDF, kami merekomendasikan deployment UDF pembantu ke project dan set data Anda sendiri untuk penggunaan produksi yang andal dan stabil. Untuk mengetahui informasi selengkapnya tentang skrip dan langkah-langkah yang diperlukan untuk men-deploy UDF pembantu ke lingkungan Anda, lihat Men-deploy UDF.

Pemecahan masalah

Bagian ini menjelaskan cara men-debug kueri satu per satu dan cara mengatasi error terjemahan yang paling umum.

Men-debug kueri SQL yang diterjemahkan batch dengan penerjemah SQL interaktif

Anda dapat menggunakan penerjemah SQL interaktif BigQuery untuk meninjau atau men-debug kueri SQL menggunakan metadata atau informasi pemetaan objek yang sama seperti database sumber Anda. Setelah Anda menyelesaikan tugas terjemahan batch, BigQuery akan membuat ID konfigurasi terjemahan yang berisi informasi tentang metadata tugas, pemetaan objek, atau jalur penelusuran skema, sebagaimana yang berlaku untuk kueri tersebut. Gunakan ID konfigurasi terjemahan batch dengan penerjemah SQL interaktif untuk menjalankan kueri SQL dengan konfigurasi yang ditentukan.

Anda dapat men-debug kueri SQL yang diterjemahkan secara batch menggunakan konsolGoogle Cloud atau gcloud CLI. Pilih salah satu opsi berikut:

Konsol

Untuk memulai terjemahan SQL interaktif menggunakan ID konfigurasi terjemahan batch, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman SQL Translation.

   Buka Terjemahan SQL

2. Dalam daftar tugas terjemahan, temukan tugas yang Anda minati, lalu klik More Options > Open Interactive Translation.

   Penerjemah SQL interaktif BigQuery kini terbuka dengan ID konfigurasi terjemahan batch yang sesuai. Guna melihat ID konfigurasi terjemahan untuk terjemahan interaktif, klik Alat > Terjemahan kueri > Setelan terjemahan di penerjemah SQL interaktif.

Untuk men-debug file terjemahan batch di penerjemah SQL interaktif, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman SQL Translation.

   Buka Terjemahan SQL

2. Dalam daftar tugas terjemahan, temukan tugas yang Anda minati, lalu klik nama tugas atau klik More options > Show details.

3. Di jendela Translation details, klik tab Code.

4. Di file explorer, klik nama file Anda untuk membuka file.

5. Di samping nama file output, klik Edit untuk membuka file di penerjemah SQL interaktif (Pratinjau).

   Anda akan melihat file input dan output diisi di penerjemah SQL interaktif yang kini menggunakan ID konfigurasi terjemahan batch yang sesuai.

6. Untuk menyimpan file output yang telah diedit kembali ke Cloud Storage, di penerjemah SQL interaktif, klik Simpan > Simpan Ke GCS.

gcloud

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.

Untuk menerjemahkan ulang dan memeriksa satu kueri tanpa membuka konsolGoogle Cloud , gunakan perintah gcloud alpha bq translation translate. Hal ini berguna saat Anda telah mempersempit masalah terjemahan batch menjadi satu kueri dan ingin melakukan iterasi secara lokal.

gcloud alpha bq translation translate \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --input-file=INPUT_FILE \
  --output-file=OUTPUT_FILE \
  --translation-log-file=LOG_FILE \
  --explanation-output-file=EXPLANATION_FILE

Ganti kode berikut:

• INPUT_FILE: file lokal yang berisi kueri yang akan diterjemahkan. Jika Anda menghapus tanda ini, perintah akan membaca kueri dari input standar.
• OUTPUT_FILE: file lokal yang menerima kueri yang diterjemahkan. Jika Anda menghapus tanda ini, perintah akan menulis kueri ke output standar.
• LOG_FILE: file YAML lokal yang menerima log terjemahan, yang berisi pesan masalah yang sama dengan yang ditampilkan konsolGoogle Cloud di tab Pesan Log.
• EXPLANATION_FILE: file lokal yang menerima penjelasan terjemahan yang dihasilkan Gemini.

Untuk menggunakan kembali metadata dari tugas batch Anda sehingga kueri menyelesaikan objek yang sama, tambahkan tanda --metadata-gcs-uri. Untuk mengetahui informasi selengkapnya, lihat bagian Menerjemahkan kueri ke GoogleSQL.

Memecahkan masalah error terjemahan

Bagian berikut menjelaskan error umum yang terjadi saat menggunakan penerjemah SQL batch.

Masalah terjemahan RelationNotFound atau AttributeNotFound

Setelah menerjemahkan kueri menggunakan penerjemah SQL batch, Anda mungkin mengalami kegagalan terjemahan dengan error RelationNotFound atau AttributeNotFound.

Anda dapat menemukan terjemahan yang gagal dengan membuka halaman Detail terjemahan di BigQuery di konsol Google Cloud dan membuka tab Pesan Log.

Terjemahan berfungsi paling baik dengan DDL metadata. Jika definisi objek SQL tidak dapat ditemukan, mesin terjemahan akan menimbulkan masalah RelationNotFound atau AttributeNotFound. Sebaiknya gunakan ekstraktor metadata untuk membuat paket metadata guna memastikan semua definisi objek ada. Menambahkan metadata adalah langkah pertama yang direkomendasikan untuk mengatasi sebagian besar error terjemahan, karena langkah ini sering kali memperbaiki banyak error lain yang disebabkan secara tidak langsung oleh kurangnya metadata.

Untuk mengetahui informasi selengkapnya, lihat Membuat metadata untuk terjemahan dan penilaian.

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 menyelesaikan masalah ini:

1. Buka halaman Detail terjemahan dan buka tab Pesan Log.
2. Klik kueri yang memiliki pesan RelationNotFound atau AttributeNotFound di kolom Kategori.

3. Untuk membuka file dan baris yang berisi error di tab kode, klik

   pesan error.

4. Di kolom Tindakan, klik Perbaikan yang disarankan.

5. Pilih salah satu opsi berikut, Terapkan atau Terapkan dan jalankan ulang:

   • Untuk menyalin file skema yang dihasilkan dari direktori output ke direktori input, klik Terapkan.
   • Untuk menyalin file skema yang dihasilkan dari direktori output ke direktori input dan membuka jendela jalankan ulang, klik Terapkan dan jalankan ulang.

Kuota dan batas

• Kuota BigQuery Migration API berlaku.
• Setiap project dapat memiliki maksimal 10 tugas terjemahan aktif.
• Meskipun tidak ada batasan pasti untuk jumlah total file sumber dan metadata, sebaiknya pertahankan jumlah file tersebut agar tetap kurang dari 1.000 untuk mendapatkan performa yang lebih baik.

Harga

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

Alat command line alur kerja migrasi alternatif

Anda juga dapat mengirimkan tugas terjemahan batch menggunakan file konfigurasi terjemahan dengan Google Cloud CLI (gcloud bq migration-workflows) atau dengan alat command line bq.

Langkah-langkah ini mengasumsikan bahwa Anda telah mengupload file sumber ke bucket Cloud Storage.

Membuat file konfigurasi terjemahan

File konfigurasi terjemahan menentukan jalur ke file sumber, tujuan output, serta dialek sumber dan target terjemahan Anda. Anda dapat menulis file ini dalam format YAML atau JSON.

Catatan: File konfigurasi terjemahan tidak sama dengan file YAML konfigurasi. File konfigurasi terjemahan menentukan tugas itu sendiri. File YAML konfigurasi menyesuaikan cara penerjemah mentransformasi SQL Anda.

Contoh berikut menunjukkan file YAML konfigurasi terjemahan untuk terjemahan Teradata ke BigQuery:

tasks:
  translation_task:
    type: Teradata2BigQuery_Translation
    translationDetails:
      sourceTargetMapping:
      - sourceSpec:
          baseUri: gs://bq-translations/input
        targetSpec:
          relativePath: output
      targetBaseUri: gs://bq-translations
      targetTypes:
      - sql
      sourceEnvironment:
        defaultDatabase: default_db
        schemaSearchPath:
        - foo

Contoh berikut menunjukkan file JSON konfigurasi terjemahan untuk terjemahan Teradata ke BigQuery:

{
  "tasks": {
    "translation_task": {
      "type": "Teradata2BigQuery_Translation",
      "translationDetails": {
        "sourceTargetMapping": [
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 1",
                "relativePath": "my_input_1"
              },
              "encoding": "UTF-8"
            }
          },
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 2",
                "relativePath": "my_input_2"
              },
              "encoding": "UTF-8"
            }
          }
        ],
        "targetReturnLiterals": [
          "sql/my_input_1",
          "sql/my_input_2"
        ]
      }
    }
  }
}

Mengirim dan mengelola tugas terjemahan

Gunakan salah satu alat command line berikut untuk mengirim dan mengelola tugas terjemahan Anda.

gcloud

Untuk membuat tugas terjemahan dan menjalankan alur kerja, gunakan perintah berikut:

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE

Untuk membuat dan menjalankan alur kerja serta langsung menampilkan link ke alur kerja, tambahkan tanda --async:

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE --async

Untuk mencantumkan tugas terjemahan, gunakan perintah berikut:

gcloud bq migration-workflows list --location=LOCATION

Untuk melihat detail tugas terjemahan tertentu, gunakan perintah berikut:

gcloud bq migration-workflows describe projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Ganti kode berikut:

• LOCATION: lokasi Google Cloud project yang menjalankan tugas terjemahan ini.
• CONFIG_FILE: jalur ke file konfigurasi terjemahan Anda.
• PROJECT_ID: ID Google Cloud project yang menjalankan tugas terjemahan ini.
• WORKFLOW_ID: ID tugas terjemahan.

bq

Untuk menjalankan tugas terjemahan, gunakan perintah berikut:

bq mk --migration_workflow --location=LOCATION --config_file=CONFIG_FILE

Untuk mencantumkan semua tugas terjemahan Anda, gunakan perintah berikut:

bq ls --migration_workflow --location=LOCATION

Untuk melihat detail tentang tugas terjemahan tertentu, gunakan perintah berikut:

bq show --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Untuk menghapus tugas terjemahan dari daftar, gunakan perintah berikut:

bq rm --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Ganti kode berikut:

• LOCATION: lokasi Google Cloud project yang menjalankan tugas terjemahan ini.
• CONFIG_FILE: jalur ke file konfigurasi terjemahan Anda.
• PROJECT_ID: ID Google Cloud project yang menjalankan tugas terjemahan ini.
• WORKFLOW_ID: ID tugas terjemahan.

Mengambil file output

Untuk mendownload file output setelah tugas selesai, gunakan gcloud storage cp seperti yang dijelaskan dalam Mengambil file output. Untuk meninjau tugas di konsol Google Cloud , lihat Menjelajahi output terjemahan.

Langkah berikutnya

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

• Ringkasan migrasi
• Penilaian migrasi
• Ringkasan skema dan transfer data
• Pipeline data
• Terjemahan SQL interaktif
• Tata kelola dan keamanan data
• Alat validasi data