Menerjemahkan kueri SQL dengan Translation API

Dokumen ini menjelaskan cara menggunakan API terjemahan di BigQuery untuk menerjemahkan skrip yang ditulis dalam dialek SQL lainnya ke dalam kueri GoogleSQL. API terjemahan dapat menyederhanakan proses migrasi beban kerja ke BigQuery.

Untuk mengetahui daftar dialek SQL yang didukung oleh penerjemah SQL ini, dan daftar lokasi pemrosesan yang didukung, lihat Dialek SQL yang didukung dan Lokasi.

Sebelum memulai

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

Aktifkan terjemahan

Aktifkan BigQuery Migration API yang diperlukan. 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 pekerjaan migrasi: Penampil Alur Kerja Migrasi (roles/bigquerymigration.viewer)
  • Mengirimkan tugas migrasi: MigrationWorkflow Editor (roles/bigquerymigration.editor)
  • Akses bucket Cloud Storage untuk input dan file: Admin Objek Penyimpanan (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.

Mengupload file input ke Cloud Storage

Jika ingin menggunakan Konsol Google Cloud atau BigQuery Migration API untuk melakukan tugas terjemahan, Anda harus mengupload file sumber yang berisi kueri dan skrip yang ingin diterjemahkan ke Cloud Storage. Anda juga dapat mengunggah file metadata apa pun atau file YAML konfigurasi ke bucket Cloud Storage yang sama yang berisi file sumber. Untuk mengetahui informasi selengkapnya tentang cara membuat bucket dan mengupload file ke Cloud Storage, lihat Membuat bucket dan Mengupload objek dari sistem file.

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 dataset publik bqutil, memungkinkan kueri yang diterjemahkan untuk awalnya merujuknya menggunakan format bqutil.<dataset>.<function>(). Misalnya, bqutil.fn.cw_count().

Pertimbangan penting untuk lingkungan produksi

Meskipun bqutil menawarkan akses mudah ke UDF pembantu ini untuk penerjemahan dan pengujian awal, ketergantungan langsung pada bqutil untuk beban kerja produksi tidak disarankan karena beberapa alasan:

  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 mungkin 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 penggunaan produksi yang andal dan stabil, Anda harus menerapkan UDF pembantu ini ke dalam proyek dan dataset Anda sendiri. Tindakan 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.

Mengirim tugas terjemahan

Untuk mengirimkan tugas terjemahan menggunakan Translation API, gunakan metode projects.locations.workflows.create dan berikan instance resource MigrationWorkflow dengan jenis tugas yang didukung.

Setelah pekerjaan dikirimkan, Anda dapat mengeluarkan kueri untuk mendapatkan hasil.

Membuat terjemahan batch

Perintah curl berikut membuat pekerjaan terjemahan batch di mana file input dan output disimpan di Cloud Storage. Kolom source_target_mapping berisi daftar yang memetakan entri literal sumber ke jalur relatif opsional untuk output target.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
            \"target_base_uri\": \"TARGET_BASE\",
            \"source_target_mapping\": {
              \"source_spec\": {
                  \"base_uri\": \"BASE\"
              }
            },
            \"target_types\": \"TARGET_TYPES\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Ganti kode berikut:

  • TYPE: jenis tugas terjemahan, yang menentukan dialek sumber dan target.
  • TARGET_BASE: URI dasar untuk semua keluaran terjemahan.
  • BASE: URI dasar untuk semua file yang dibaca sebagai sumber untuk terjemahan.

  • TARGET_TYPES (opsional): tipe keluaran yang dihasilkan. Jika tidak ditentukan, SQL akan dibuat.

    • sql (default): File kueri SQL yang telah diterjemahkan.
    • suggestion: Saran yang dihasilkan oleh AI.

    Output disimpan dalam subfolder di direktori output. Subfolder diberi nama berdasarkan nilai di TARGET_TYPES.

  • TOKEN: token untuk autentikasi. Untuk membuat token, gunakan perintah gcloud auth print-access-token atau OAuth 2.0 playground (gunakan cakupan https://www.googleapis.com/auth/cloud-platform).

  • PROJECT_ID: project untuk memproses terjemahan.

  • LOCATION: lokasi tempat tugas diproses.

Perintah sebelumnya menampilkan respons yang menyertakan ID alur kerja yang ditulis dalam format projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Contoh terjemahan batch

Untuk menerjemahkan skrip SQL Teradata di direktori Cloud Storage gs://my_data_bucket/teradata/input/ dan menyimpan hasilnya di direktori Cloud Storage gs://my_data_bucket/teradata/output/, Anda dapat menggunakan kueri berikut:

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
       }
    }
  }
}

Panggilan ini akan menampilkan pesan yang berisi ID alur kerja yang dibuat di kolom "name":

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Untuk mendapatkan status alur kerja yang diperbarui, jalankan kueri GET. Proses ini mengirimkan output ke Cloud Storage seiring berjalannya waktu. Tugas state berubah menjadi COMPLETED setelah semua target_types yang diminta dibuat. Jika tugas berhasil, Anda dapat menemukan kueri SQL yang diterjemahkan di gs://my_data_bucket/teradata/output.

Contoh terjemahan massal dengan saran AI.

Contoh berikut menerjemahkan skrip SQL Teradata yang terletak di direktori Cloud Storage gs://my_data_bucket/teradata/input/ dan menyimpan hasilnya di direktori Cloud Storage gs://my_data_bucket/teradata/output/ dengan saran AI tambahan:

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
          "target_types": "suggestion",
       }
    }
  }
}

Setelah tugas berjalan sukses, saran AI dapat ditemukan di direktori gs://my_data_bucket/teradata/output/suggestion Cloud Storage.

Buat tugas penerjemahan interaktif dengan input dan output literal string.

Perintah curl berikut membuat tugas penerjemahan dengan input dan output berupa literal string. Kolom source_target_mapping berisi daftar yang memetakan direktori sumber ke jalur relatif opsional untuk output target.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
        \"source_target_mapping\": {
            \"source_spec\": {
              \"literal\": {
              \"relative_path\": \"PATH\",
              \"literal_string\": \"STRING\"
              }
            }
        },
        \"target_return_literals\": \"TARGETS\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Ganti kode berikut:

  • TYPE: jenis tugas terjemahan, yang menentukan dialek sumber dan target.
  • PATH: pengidentifikasi entri literal, mirip dengan nama file atau jalur.
  • STRING: string data input literal (misalnya, SQL) yang akan diterjemahkan.
  • TARGETS: target yang diharapkan yang ingin dikembalikan langsung oleh pengguna dalam respons dalam format literal. Nilai ini harus dalam format URI target (misalnya, GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). Apa pun yang tidak ada dalam daftar ini tidak akan ditampilkan dalam respons. Direktori yang dibuat, GENERATED_DIR untuk terjemahan SQL umum adalah sql/.
  • TOKEN: token untuk autentikasi. Untuk membuat token, gunakan perintah gcloud auth print-access-token atau OAuth 2.0 playground (gunakan cakupan https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: project untuk memproses terjemahan.
  • LOCATION: lokasi tempat pekerjaan diproses.

Perintah sebelumnya menampilkan respons yang menyertakan ID alur kerja yang ditulis dalam format projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

Setelah tugas selesai, Anda dapat melihat hasilnya dengan membuat kueri tugas dan memeriksa kolom translation_literals inline dalam respons setelah alur kerja selesai.

Contoh Terjemahan Interaktif

Untuk menerjemahkan string Hive SQL select 1 secara interaktif, Anda dapat menggunakan kueri berikut:

"tasks": {
  string: {
    "type": "HiveQL2BigQuery_Translation",
    "translation_details": {
      "source_target_mapping": {
        "source_spec": {
          "literal": {
            "relative_path": "input_file",
            "literal_string": "select 1"
          }
        }
      },
      "target_return_literals": "sql/input_file",
    }
  }
}

Anda dapat menggunakan relative_path apa pun yang Anda inginkan untuk literal, tetapi literal yang diterjemahkan hanya akan muncul di hasil jika Anda menyertakan sql/$relative_path dalam target_return_literals. Anda juga dapat menyertakan beberapa literal dalam satu kueri, yang dalam hal ini setiap jalur relatifnya harus disertakan dalam target_return_literals.

Panggilan ini akan menampilkan pesan yang berisi ID alur kerja yang dibuat di kolom "name":

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

Untuk mendapatkan status alur kerja yang diperbarui, jalankan kueri GET. Tugas selesai saat "state" berubah menjadi COMPLETED. Jika tugas berhasil, Anda akan menemukan SQL yang diterjemahkan dalam pesan respons:

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "string": {
      "id": "0fedba98-7654-3210-1234-56789abcdef",
      "type": "HiveQL2BigQuery_Translation",
      /* ... */
      "taskResult": {
        "translationTaskResult": {
          "translatedLiterals": [
            {
              "relativePath": "sql/input_file",
              "literalString": "-- Translation time: 2023-10-05T21:50:49.885839Z\n-- Translation job ID: projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00\n-- Source: input_file\n-- Translated from: Hive\n-- Translated to: BigQuery\n\nSELECT\n    1\n;\n"
            }
          ],
          "reportLogMessages": [
            ...
          ]
        }
      },
      /* ... */
    }
  },
  "state": "COMPLETED",
  "createTime": "2023-10-05T21:50:49.543221Z",
  "lastUpdateTime": "2023-10-05T21:50:50.462758Z"
}

Pelajari output terjemahan

Setelah menjalankan tugas terjemahan, ambil hasilnya dengan menentukan ID alur kerja tugas terjemahan menggunakan perintah berikut:

curl \
-H "Content-Type:application/json" \
-H "Authorization:Bearer TOKEN" -X GET https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Ganti kode berikut:

  • TOKEN: token untuk autentikasi. Untuk membuat token, gunakan perintah gcloud auth print-access-token atau OAuth 2.0 playground (gunakan cakupan https://www.googleapis.com/auth/cloud-platform).
  • PROJECT_ID: project untuk memproses terjemahan.
  • LOCATION: lokasi tempat tugas diproses.
  • WORKFLOW_ID: ID yang dibuat saat Anda membuat alur kerja terjemahan.

Respons tersebut berisi status alur kerja migrasi Anda, dan file yang telah selesai di target_return_literals.

Respons akan berisi status alur kerja migrasi Anda, dan file yang telah selesai di target_return_literals. Anda dapat melakukan polling endpoint ini untuk memeriksa status alur kerja Anda.