Menerjemahkan kueri SQL dengan Translation API

Dokumen ini menjelaskan cara menggunakan BigQuery Migration API di BigQuery untuk menerjemahkan skrip yang ditulis dalam dialek SQL lainnya ke dalam kueri GoogleSQL.

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, selesaikan langkah-langkah berikut.

Memilih mode terjemahan

BigQuery Migration API mendukung dua mode terjemahan. Kedua mode menggunakan metode API yang sama dan berjalan sebagai tugas asinkron. Mode ini berbeda dalam cara Anda memberikan SQL sumber dan cara Anda menerima SQL yang diterjemahkan:

  • Terjemahan batch: API membaca file sumber dari Cloud Storage dan menulis file serta laporan yang diterjemahkan ke Cloud Storage. Gunakan terjemahan batch untuk menerjemahkan banyak file sekaligus, misalnya, saat Anda memigrasikan seluruh codebase.
  • Terjemahan interaktif: Anda meneruskan SQL sebagai literal string di isi permintaan dan membaca SQL yang diterjemahkan dari respons alur kerja. Anda tidak perlu menyimpan SQL atau output terjemahan di Cloud Storage. Gunakan terjemahan interaktif untuk menerjemahkan kueri individual sesuai permintaan — misalnya, saat menerjemahkan kueri dari aplikasi atau alat developer.

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

Mengupload file input ke Cloud Storage

Untuk tugas terjemahan batch, Anda harus mengupload file sumber yang berisi kueri dan skrip yang ingin diterjemahkan ke Cloud Storage. Anda juga dapat mengupload file metadata apa pun atau file YAML konfigurasi ke bucket Cloud Storage 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.

Fungsi SQL yang tidak didukung

Jika kueri sumber Anda mereferensikan fungsi SQL yang tidak memiliki padanan langsung di GoogleSQL, Anda dapat menggunakan fungsi yang ditentukan pengguna (UDF) pembantu. Untuk mengetahui informasi selengkapnya, lihat Menangani fungsi SQL yang tidak didukung dengan UDF pembantu.

Mengirim tugas terjemahan

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

Setelah mengirimkan tugas, Anda dapat melakukan polling untuk status tugas.

Membuat terjemahan batch

Perintah curl berikut membuat tugas terjemahan batch dengan file input dan output disimpan di Cloud Storage. 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\": {
            \"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/v2/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 output terjemahan.
  • BASE: URI dasar untuk semua file yang dibaca sebagai sumber untuk terjemahan.

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

    • sql (default): File kueri SQL yang diterjemahkan.
    • suggestion: Saran yang dibuat 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 di atas 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. Tugas mengirimkan output ke Cloud Storage saat berjalan. 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 batch dengan saran AI

Contoh berikut menerjemahkan skrip Teradata SQL yang ada 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 berhasil dijalankan, saran AI dapat ditemukan di direktori Cloud Storage gs://my_data_bucket/teradata/output/suggestion.

Membuat terjemahan interaktif

Perintah curl berikut membuat tugas terjemahan interaktif dengan input dan output literal string. 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\": {
        \"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/v2/projects/PROJECT_ID/locations/LOCATION/workflows

Ganti kode berikut:

  • TYPE: jenis tugas terjemahan, yang menentukan dialek sumber dan target.
  • PATH: ID entri literal, mirip dengan nama file atau jalur.
  • STRING: string data input literal (misalnya, SQL) yang akan diterjemahkan.
  • TARGETS: target yang diharapkan yang ingin ditampilkan 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 tugas diproses.

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

Setelah alur kerja dibuat, lihat hasilnya dengan memeriksa status tugas.

Contoh terjemahan interaktif

Untuk menerjemahkan string SQL Apache Hive 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 dalam 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, periksa status tugas. 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"
}

Memeriksa status tugas

Tugas terjemahan berjalan secara asinkron. Setelah mengirimkan alur kerja, ambil statusnya dengan mengirimkan permintaan GET dengan ID alur kerja:

curl \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer TOKEN" \
  -X GET https://bigquerymigration.googleapis.com/v2/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 yang menjalankan tugas terjemahan.
  • LOCATION: lokasi tempat tugas diproses.
  • WORKFLOW_ID: ID alur kerja yang ditampilkan saat Anda membuat alur kerja terjemahan.

Status alur kerja

Respons mencakup kolom state yang menunjukkan status alur kerja saat ini:

  • STATE_UNSPECIFIED: Status alur kerja tidak ditentukan.
  • RUNNING: Alur kerja sedang berjalan aktif. Polling endpoint secara berkala hingga status berubah.
  • PAUSED: Alur kerja dijeda.
  • COMPLETED: Alur kerja berhasil diselesaikan. Anda kini dapat mengambil hasilnya.
  • FAILED: Alur kerja mengalami error. Periksa kolom taskResult dan reportLogMessages dalam respons untuk mengetahui detail error.

Saat alur kerja state mencapai COMPLETED atau FAILED, Anda dapat menghentikan polling.

Mengambil hasil

Cara Anda mengambil hasil bergantung pada apakah Anda mengirimkan terjemahan batch atau terjemahan interaktif:

  • Terjemahan batch: File yang diterjemahkan, laporan ringkasan, dan saran AI apa pun ditulis ke direktori tujuan Cloud Storage yang Anda tentukan di target_base_uri. Anda dapat membaca file ini secara langsung dari Cloud Storage menggunakan perintah penyimpanan gcloud CLI, library klien Cloud Storage, atau REST API:

    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.

    Untuk mengetahui detail file yang dihasilkan di bucket tujuan, lihat Menjelajahi output terjemahan.

  • Terjemahan interaktif: Untuk tugas yang dikonfigurasi dengan input literal string dan target_return_literals, kueri yang diterjemahkan akan ditampilkan langsung dalam respons alur kerja di kolom translatedLiterals:

    "taskResult": {
  "translationTaskResult": {
    "translatedLiterals": [
      {
        "relativePath": "sql/input_file",
        "literalString": "SELECT 1;\n"
      }
    ]
  }
}

    Ekstrak kolom literalString untuk setiap entri di translatedLiterals untuk mendapatkan kueri yang diterjemahkan.