Menggunakan Agen Data Engineering untuk membangun dan mengubah pipeline data

Dokumen ini menunjukkan cara menggunakan Agen Data Engineering di BigQuery dan Dataform untuk membuat dan mengubah pipeline data.

Agen Data Engineering memungkinkan Anda membangun, mengubah, dan mengelola pipeline data untuk memuat dan memproses data di BigQuery. Dengan Agen Data Engineering, Anda dapat menggunakan perintah bahasa natural untuk membuat pipeline data dari berbagai sumber data atau mengadaptasi pipeline data yang ada agar sesuai dengan kebutuhan data engineering Anda.

Agen ini membuat dan mengatur kode pipeline data langsung dalam repositori Dataform. Agen ini beroperasi di ruang kerja Dataform, sehingga pipeline Dataform otomatis tersedia untuk agen.

Untuk contoh perintah lainnya yang dapat Anda gunakan dengan Agen Data Engineering, lihat Contoh perintah.

Anda juga dapat menggunakan Data Engineering Agent API, yang menggunakan protokol A2A, untuk berinteraksi dengan agen.

Batasan

Agen Data Engineering memiliki batasan berikut:

• Agen Data Engineering tidak mendukung perintah bahasa natural untuk jenis file berikut:
  • Notebook
  • Persiapan data
• Agen Data Engineering tidak dapat menjalankan pipeline. Anda harus meninjau dan menjalankan atau menjadwalkan pipeline.
• Agen Data Engineering tidak dapat menelusuri link web atau URL yang diberikan melalui petunjuk atau perintah langsung.
• Saat mengimpor file dalam file petunjuk agen , sintaksis impor @ hanya mendukung jalur yang dimulai dengan ./, /, atau huruf.
• Fitur pratinjau data hanya didukung untuk tabel, deklarasi, atau kueri dengan flag hasOutput yang ditetapkan ke true.
• Agen Data Engineering tunduk pada batasan umum teknologi AI.
• Saat membuat pipeline di tabel eksternal Apache Iceberg yang dikelola oleh katalog runtime Lakehouse (sebelumnya metastore BigLake), semua batasan katalog runtime Lakehouse berlaku. Terutama, agen tidak dapat membuat mutasi tulis (seperti INSERT, UPDATE, DELETE, atau MERGE) atau pernyataan DDL (seperti CREATE TABLE atau DROP TABLE) pada tabel Iceberg. Untuk mengetahui informasi selengkapnya, lihat Konsep endpoint katalog REST Apache Iceberg.

Sebelum memulai

Sebelum menggunakan Agen Data Engineering, lakukan langkah-langkah di bagian ini.

Mengaktifkan Gemini di BigQuery

Pastikan Gemini di BigQuery diaktifkan untuk Google Cloud project Anda. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan Gemini di BigQuery.

Mengaktifkan API yang diperlukan

gcloud services enable geminidataanalytics.googleapis.com --project=PROJECT_ID
gcloud services enable cloudaicompanion.googleapis.com --project=PROJECT_ID
gcloud services enable bigquery.googleapis.com --project=PROJECT_ID

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk menggunakan Agen Data Engineering, minta administrator Anda untuk memberi Anda peran IAM berikut di project:

• Editor Kode Dataform (roles/dataform.codeEditor)
• Pengguna Tugas BigQuery (roles/bigquery.jobUser)
• Pengguna Chat Tanpa Status Gemini Data Analytics (roles/geminidataanalytics.dataAgentStatelessUser)

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

Peran bawaan ini berisi izin geminidataanalytics.locations.useDataEngineeringAgent , yang diperlukan untuk menggunakan Agen Data Engineering.

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

Untuk mengetahui detail peran yang diperlukan untuk membuat kueri tabel Apache Iceberg, lihat Peran yang diperlukan untuk dukungan Lakehouse Apache Iceberg.

Prasyarat integrasi Knowledge Catalog

Untuk mendapatkan izin yang diperlukan untuk mengintegrasikan Agen Data Engineering dengan Knowledge Catalog, minta administrator Anda untuk memberi Anda peran IAM Editor Katalog Dataplex (roles/dataplex.catalogEditor) di project. Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin geminidataanalytics.locations.useDataEngineeringAgent , yang diperlukan untuk mengintegrasikan Agen Data Engineering dengan Knowledge Catalog.

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

Anda juga harus mengaktifkan Knowledge Catalog API.

Mengenkripsi data dengan kunci Cloud Key Management Service

Anda dapat mengenkripsi data di tingkat set data atau project dengan kunci Cloud Key Management Service yang dikelola pelanggan default di BigQuery. Untuk mengetahui informasi selengkapnya, lihat Menetapkan kunci default set data dan Menetapkan kunci default project.

Anda dapat mengenkripsi kode pipeline di tingkat project dengan menetapkan kunci Cloud Key Management Service Dataform default.

Mengonfigurasi perimeter Kontrol Layanan VPC

Jika menggunakan Kontrol Layanan VPC, Anda harus mengonfigurasi perimeter untuk melindungi Dataform, BigQuery, dan Conversational Analytics API. Untuk mengetahui informasi selengkapnya, lihat Dataform, BigQuery, dan Conversational Analytics API.

Membuat pipeline data dengan Agen Data Engineering

Untuk menggunakan Agen Data Engineering di BigQuery, pilih salah satu opsi berikut:

Mengedit pipeline data

Untuk mengedit pipeline data, klik Tanya agen, lalu masukkan perintah yang menyarankan perubahan pada pipeline data.

Tinjau perubahan yang diusulkan oleh Agen Data Engineering, lalu klik Terapkan untuk menerapkan perubahan.

Anda juga dapat mengedit kueri SQLX secara manual dengan memilih node pipeline, lalu mengklik Buka.

Meninjau pipeline data

Anda dapat mengklik node pipeline di pipeline data yang dibuat oleh Agen Data Engineering untuk meninjaunya.

• Tab Konfigurasi menampilkan kueri SQLX yang dibuat dan terkait dengan node.
• Tab Pratinjau data menampilkan tabel input dan output file. Anda dapat melihat pratinjau transformasi data melalui node ini dengan mengklik Jalankan tugas untuk menjalankan tugas dengan atau tanpa dependensi.

Memecahkan masalah error pipeline data

Jika Anda mengalami error selama pembuatan pipeline data, pastikan Anda telah menyelesaikan semua prasyarat untuk menjalankan Agen Data Engineering. Untuk mengetahui informasi selengkapnya, lihat Sebelum memulai.

Menjalankan investigasi Gemini Cloud Assist

Untuk pemecahan masalah pipeline lebih lanjut, Anda dapat menggunakan Agen Data Engineering untuk menjalankan analisis penyebab utama dan menyarankan rekomendasi pemecahan masalah.

Fitur ini menggunakan investigasi Gemini Cloud Assist (Pratinjau) dan hanya tersedia untuk pengguna dengan Dukungan Premium kontrak. Untuk mengetahui informasi selengkapnya tentang cara mengaktifkan investigasi Gemini Cloud Assist, lihat Memecahkan masalah dengan Investigasi Gemini Cloud Assist.

Anda dapat menggunakan Agen Data Engineering untuk memecahkan masalah error pipeline data dengan langkah-langkah berikut:

1. Di pipeline atau ruang kerja pengembangan, klik tab Eksekusi.

2. Dari daftar eksekusi, temukan eksekusi pipeline data yang gagal. Anda dapat mengidentifikasi eksekusi yang gagal di kolom Status.

   

3. Arahkan kursor ke ikon, lalu klik Selidiki. Agen Data Engineering menjalankan analisis penyebab utama (RCA) pada eksekusi pipeline data Anda untuk error.

   

4. Setelah analisis selesai, Agen Data Engineering akan membuat laporan di bagian Pengamatan dan Hipotesis. Laporan ini mencakup hal berikut:

   • Pengamatan dan titik data yang diekstrak dari log eksekusi pipeline data.
   • Kemungkinan penyebab kegagalan.
   • Serangkaian langkah atau rekomendasi yang dapat ditindaklanjuti untuk mengatasi masalah yang teridentifikasi.

Dengan laporan pemecahan masalah dari Agen Data Engineering, Anda dapat menerapkan rekomendasi secara manual. Anda juga dapat menginstruksikan Agen Data Engineering untuk menerapkan perbaikan bagi Anda dengan melakukan langkah-langkah berikut:

1. Salin saran dalam laporan pemecahan masalah.
2. Kembali ke Agen Data Engineering:
   1. Jika Anda menggunakan pipeline BigQuery, buka halaman pipeline, lalu klik Tanya agen.
   2. Jika Anda menggunakan Dataform, klik Tanya agen.
3. Tempel saran ke dalam perintah, lalu instruksikan Agen Data Engineering untuk melakukan perbaikan langsung ke pipeline data Anda.
4. Klik Kirim.

Membuat petunjuk agen

Petunjuk agen adalah petunjuk bahasa natural untuk Agen Data Engineering yang memungkinkan Anda menyimpan petunjuk persisten sehingga agen mengikuti serangkaian aturan kustom yang telah ditentukan. Gunakan petunjuk agen jika Anda ingin hasil agen konsisten di seluruh organisasi Anda—misalnya, dengan konvensi penamaan atau untuk menerapkan panduan gaya.

Anda dapat membuat file konteks GEMINI.MD sebagai file petunjuk agen untuk Agen Data Engineering. Anda dapat membuat file petunjuk agen untuk digunakan di ruang kerja lokal, atau Anda dapat menggunakan file petunjuk yang sama di beberapa pipeline data dengan repositori eksternal.

Untuk membuat petunjuk agen, lakukan hal berikut:

1. Di bagian Tanya agen, klik Petunjuk pipeline.
2. Di panel Petunjuk untuk pipeline, klik Buat file petunjuk.

3. Di file GEMINI.MD yang muncul, masukkan petunjuk Anda dalam bahasa natural.

   Contoh berikut menunjukkan file petunjuk agen dengan beberapa aturan:

     1. All event-specific tables MUST be prefixed with `cs_event_`.
     2. The primary key for any player activity table is a composite key of `player_id` and `event_timestamp_micros`.
     3. Filter out any player actions where `mana_spent` is greater than `max_mana_pool`. This is considered a data anomaly.
   

4. Klik Simpan.

Untuk mengetahui informasi tentang cara terbaik menyusun file petunjuk agen, lihat Praktik terbaik dengan file petunjuk agen.

Memuat petunjuk agen dari repositori eksternal

Untuk menggunakan kembali serangkaian petunjuk agen di beberapa pipeline data, tautkan repositori eksternal:

1. Di bagian Tanya agen, klik Petunjuk pipeline.
2. Di bagian Repositori eksternal, pilih Gunakan petunjuk dari repositori eksternal.
3. Di kolom yang disediakan, tentukan repositori yang berisi petunjuk agen yang ingin Anda gunakan dengan pipeline data Anda.
4. Klik Simpan.

Contoh perintah

Bagian berikut memberikan contoh perintah yang dapat Anda gunakan dengan Agen Data Engineering untuk mengembangkan pipeline data Anda.

Mengagregasi data yang ada ke dalam tabel baru

Dengan perintah ini, Agen Data Engineering menggunakan skema dan sampel untuk menyimpulkan pengelompokan data berdasarkan kunci. Agen biasanya menyiapkan konfigurasi tabel baru dengan deskripsi tabel dan kolom.

  Create a daily sales report from the
  bigquery-public-data.thelook_ecommerce.order_items table into a
  reporting.daily_sales_aggregation table.

Membuat kolom turunan baru dan menambahkan pemeriksaan kualitas data ke tabel baru

Perintah ini menunjukkan cara menambahkan tabel dan kolom, serta menentukan pemeriksaan kualitas ke tabel secara bersamaan:

  Create a new table named staging.products from
  bigquery-public-data.thelook_ecommerce.products and add a calculated column
  named gross_profit, which is the retail_price minus the cost.


  Also, add the following assertions: ID must not be null and must be unique.
  The retail_price must be greater than or equal to the cost. The department
  column can only contain 'Men' or 'Women'.

Membuat UDF sebagai bagian dari definisi model

Agen Data Engineering juga dapat menyiapkan DDL untuk membuat fungsi yang ditentukan pengguna (UDF). Meskipun agen tidak akan benar-benar membuat UDF, Anda dapat membuat UDF dengan menjalankan pipeline data. UDF ini dapat digunakan dalam definisi model di pipeline data Anda.

  Create a user-defined function (UDF) named get_age_group that takes an integer
  age as input and returns a string representing the age group ('Gen Z',
  'Millennial', 'Gen X', 'Baby Boomer').


  Use this UDF on the age column from the
  bigquery-public-data.thelook_ecommerce.users table to create a new view called
  reporting.user_age_demographics that includes user_id, age, and the calculated
  age_group.

Praktik terbaik

Untuk meningkatkan hasil saat menggunakan Agen Data Engineering dan Dataform, sebaiknya lakukan hal berikut:

Gunakan petunjuk agen untuk permintaan umum. Jika Anda biasanya menerapkan teknik tertentu, atau jika Anda sering melakukan koreksi yang sama kepada agen, gunakan petunjuk agen sebagai lokasi terpusat untuk menyimpan petunjuk dan permintaan umum.

Manfaatkan rencana agen. Rencana agen dapat membantu memecah tugas pipeline yang kompleks. Rencana agen juga dapat menunjukkan asumsi dan niat agen, jadi sebaiknya tinjau rencana tersebut untuk memastikan agen diberi konteks yang benar.

Setelah meninjau rencana, Anda dapat mengedit rencana dengan meminta Agen Data Engineering untuk memberikan masukan dan perubahan. Contoh:

In the plan, ensure that all of the intermediate tables are views.

Dalam beberapa kasus, sebaiknya minta agen untuk membuat rencana yang tidak memerlukan persetujuan eksplisit Anda. Tindakan membuat rencana agen akan memaksa Agen Data Engineering untuk memecah tindakannya, yang sering kali menghasilkan hasil yang lebih baik. Anda dapat memaksa agen untuk membuat rencana dan menjalankannya secara otomatis. Contoh:

Create a plan for a pipeline that finds the
top N pick up and drop off locations in NYC. You have my explicit pre-approval
to go ahead and execute this plan.

Tulis dengan jelas. Nyatakan permintaan Anda dengan jelas dan hindari ketidakjelasan. Jika memungkinkan, berikan sumber data sumber dan tujuan saat meminta, seperti yang ditunjukkan dalam contoh berikut:

  Extract data from the sales.customers table in the us_west_1 region, and load
  it into the reporting.dim_customers table in BigQuery. Match the schema of the
  destination table.

Berikan permintaan langsung dan dalam cakupan. Ajukan satu pertanyaan dalam satu waktu, dan buat perintah tetap ringkas. Untuk perintah dengan lebih dari satu pertanyaan, buat daftar setiap bagian pertanyaan yang berbeda untuk meningkatkan kejelasan, seperti yang ditunjukkan dalam contoh berikut:

  1. Create a new table named staging.events_cleaned. Use raw.events as the
     source. This new table should filter out any records where the user_agent
     matches the pattern '%bot%'. All original columns should be included.

  2. Next, create a table named analytics.user_sessions. Use
     staging.events_cleaned as the source. This table should calculate the
     duration for each session by grouping by session_id and finding the
     difference between the MAX(event_timestamp) and MIN(event_timestamp).

Berikan petunjuk eksplisit dan tekankan istilah utama. Anda dapat menambahkan penekanan pada istilah atau konsep utama dalam perintah dan memberi label persyaratan tertentu sebagai penting, seperti yang ditunjukkan dalam contoh berikut:

  When creating the staging.customers table, it is *VERY IMPORTANT* that you
  transform the email column from the source table bronze.raw_customers.
  Coalesce any NULL values in the email column to an empty string ''.

Tentukan urutan operasi. Untuk tugas yang diurutkan, susun perintah Anda dalam daftar, dengan item yang tercantum dibagi menjadi langkah-langkah kecil yang terfokus, seperti yang ditunjukkan dalam contoh berikut:

  Create a pipeline with the following steps:
  1. Extract data from the ecomm.orders table.
  2. Join the extracted data with the marts.customers table on customer_id.
  3. Load the final result into the reporting.customer_orders table.

Sempurnakan dan lakukan iterasi. Terus coba frasa dan pendekatan yang berbeda untuk melihat mana yang menghasilkan hasil terbaik. Jika agen membuat SQL yang tidak valid atau kesalahan lainnya, pandu agen dengan contoh atau dokumentasi publik.

  The previous query was incorrect because it removed the timestamp. Please
  correct the SQL. Use the TIMESTAMP_TRUNC function to truncate the
  event_timestamp to the nearest hour, instead of casting it as a DATE. For
  example: TIMESTAMP_TRUNC(event_timestamp, HOUR).