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 memigrasikan beban kerja ke BigQuery.

Sebelum memulai

Sebelum Anda mengirimkan tugas terjemahan, selesaikan langkah-langkah berikut:

1. Pastikan Anda memiliki semua izin yang diperlukan.
2. Mengaktifkan BigQuery Migration API.
3. Mengumpulkan file sumber yang berisi skrip dan kueri SQL yang akan diterjemahkan.
4. Mengupload file sumber ke Cloud Storage.

Izin yang diperlukan

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

Peran bawaan ini berisi izin yang diperlukan untuk membuat tugas terjemahan menggunakan API terjemahan. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat tugas terjemahan menggunakan translation API:

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

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

Mengaktifkan BigQuery Migration API

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

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

   Buka BigQuery Migration API

2. Klik Enable.

Catatan: API ini diaktifkan secara otomatis untuk project yang dibuat setelah 15 Februari 2022.

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

Jenis tugas yang didukung

API terjemahan dapat menerjemahkan dialek SQL berikut ke dalam GoogleSQL:

• Amazon Redshift SQL - Redshift2BigQuery_Translation
• Apache HiveQL dan Beeline CLI - HiveQL2BigQuery_Translation
• Apache Spark SQL - SparkSQL2BigQuery_Translation
• Azure Synapse T-SQL - AzureSynapse2BigQuery_Translation
• Greenplum SQL - Greenplum2BigQuery_Translation
• IBM Db2 SQL - Db22BigQuery_Translation
• IBM Netezza SQL dan NZPLSQL - Netezza2BigQuery_Translation
• MySQL SQL - MySQL2BigQuery_Translation
• Oracle SQL, PL/SQL, Exadata - Oracle2BigQuery_Translation
• PostgreSQL SQL - Postgresql2BigQuery_Translation
• Presto atau Trino SQL - Presto2BigQuery_Translation
• Snowflake SQL - Snowflake2BigQuery_Translation
• SQLite - SQLite2BigQuery_Translation
• SQL Server T-SQL - SQLServer2BigQuery_Translation
• Teradata dan Teradata Vantage - Teradata2BigQuery_Translation
• Vertica SQL - Vertica2BigQuery_Translation

Lokasi

API terjemahan tersedia di lokasi pemrosesan berikut:

	Deskripsi region	Nama region	Detail
Asia Pasifik
	Tokyo	asia-northeast1
	Mumbai	asia-south1
	Singapura	asia-southeast1
	Sydney	australia-southeast1
Eropa
	Multi-region Uni Eropa	eu
	Warsawa	europe-central2
	Finlandia	europe-north1	CO Rendah2
	Madrid	europe-southwest1	CO Rendah2
	Belgia	europe-west1	CO Rendah2
	London	europe-west2	CO Rendah2
	Frankfurt	europe-west3	CO Rendah2
	Belanda	europe-west4	CO Rendah2
	Zürich	europe-west6	CO Rendah2
	Paris	europe-west9	CO2 Rendah
	Turin	europe-west12
Amerika
	Quebec	northamerica-northeast1	CO2 Rendah
	Sao Paulo	southamerica-east1	CO Rendah2
	Multi-region AS	us
	Iowa	us-central1	CO Rendah2
	South Carolina	us-east1
	Northern Virginia	us-east4
	Columbus, Ohio	us-east5
	Dallas	us-south1	CO2 Rendah
	Oregon	us-west1	CO Rendah2
	Los Angeles	us-west2
	Salt Lake City	us-west3

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 tugas dikirim, Anda dapat mengeluarkan kueri untuk mendapatkan hasil.

Membuat terjemahan batch

Perintah curl berikut membuat tugas terjemahan batch tempat 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 output terjemahan.
• BASE: URI dasar untuk semua file yang dibaca sebagai sumber 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 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/"
             }
          },
       }
    }
  }
}

Catatan: String "task_name" dalam contoh ini adalah ID untuk tugas terjemahan dan dapat ditetapkan ke nilai apa pun yang Anda inginkan.

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 terbaru alur kerja, jalankan kueri GET. Tugas akan mengirimkan output ke Cloud Storage seiring berjalannya tugas. state tugas 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

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: API terjemahan dapat memanggil Gemini menggunakan integrasi BigQuery Vertex AI untuk menghasilkan saran ke kueri SQL terjemahan berdasarkan file YAML konfigurasi AI Anda.

Contoh berikut menerjemahkan skrip Teradata SQL yang berada 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",
       }
    }
  }
}

Catatan: Untuk membuat saran AI, direktori sumber Cloud Storage harus berisi setidaknya satu file YAML konfigurasi dengan akhiran .ai_config.yaml. Untuk mempelajari cara menulis file YAML konfigurasi untuk saran AI, lihat Membuat file YAML konfigurasi berbasis Gemini.

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

Membuat tugas terjemahan interaktif dengan input dan output string literal

Perintah curl berikut membuat tugas terjemahan dengan input dan output 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: 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. 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 dihasilkan, 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 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 mengkueri 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",
    }
  }
}

Catatan: String "task_name" dalam contoh ini adalah ID untuk tugas terjemahan dan dapat ditetapkan ke nilai apa pun yang Anda inginkan.

Anda dapat menggunakan relative_path yang diinginkan 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. 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 terbaru alur kerja, 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.

Responsnya 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 pada endpoint ini untuk memeriksa status alur kerja.