Menjalankan kueri SQL cerdas menggunakan fungsi AI

Fungsi AI AlloyDB mengintegrasikan Model Bahasa Besar (LLM) seperti Gemini secara langsung dengan data AlloyDB untuk PostgreSQL Anda untuk melakukan operasi data yang cerdas. Fitur ini mencakup fungsi bawaan untuk hal berikut:

Memfilter (ai.if)
Peringkat semantik (ai.rank)
Pembuatan teks (ai.generate)

Fungsi AI ini menggunakan mesin kueri AlloyDB AI untuk membantu aplikasi Anda memproses data menggunakan model kecerdasan buatan dalam berbagai skala, mulai dari respons satu baris hingga operasi database skala besar. Anda dapat menggunakan operator ai.if, ai.rank, dan ai.generate untuk menggabungkan bahasa alami dengan kueri SQL. AlloyDB AI mencadangkan dan membuat skema ai.

Ada tiga kategori fungsi AI yang berbeda berdasarkan cara menangani data input dan alokasi memori: fungsi skalar, berbasis array, dan kursor. Memilih fungsi AI yang tepat bergantung pada skala data dan persyaratan performa Anda. Gunakan tabel berikut untuk mempelajari fungsi ini dan kasus penggunaannya:

Kategori	Deskripsi	Kasus penggunaan yang direkomendasikan
Skalar	Dirancang untuk pemrosesan dasar satu lawan satu. Mengambil satu input dan menampilkan satu output.	Gunakan saat Anda menginginkan fungsi dasar yang memberikan performa yang dapat diterima untuk kueri yang membuat sejumlah kecil—kurang dari 50—panggilan fungsi skalar.
Berbasis array	Memproses data sebagai array baris dalam satu panggilan fungsi. Mengambil array sebagai input dan menampilkan array sebagai output.	Gunakan untuk set data kecil hingga sedang yang seluruh array baris yang memenuhi syaratnya dapat sesuai dengan batas memori. Hal ini memberikan throughput tinggi untuk operasi berbasis set.
Kursor	Mengambil kursor sebagai input dan menampilkan kursor sebagai output.	Gunakan untuk memproses sejumlah besar baris–misalnya, 10.000 baris.

Sebelum memulai

Pastikan ekstensi google_ml_integration telah diinstal dan Anda menggunakan versi 1.5.2 atau yang lebih baru. Untuk mendapatkan manfaat performa lebih lanjut dengan fungsi berbasis array, gunakan versi 1.5.4 atau yang lebih baru.
Verifikasi bahwa tanda google_ml_integration.enable_ai_query_engine ditetapkan ke on.
Berintegrasi dengan Vertex AI.
Gunakan model Gemini yang didukung di wilayah Anda. Gemini 2.0 Flash adalah model default mesin kueri AI. Jika Anda tidak menentukan model Gemini dalam kueri, model default mesin kueri AI akan dipilih untuk kueri.

Berintegrasi dengan Vertex AI dan menginstal ekstensi

Konfigurasi akses pengguna ke model Vertex AI.
Pastikan versi terbaru google_ml_integration sudah diinstal.
1. Untuk memeriksa versi yang diinstal, jalankan perintah berikut:
```
        SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
        extversion 
        ------------
        1.5.2
        (1 row)
      
```
2. Jika ekstensi tidak diinstal atau jika versi yang diinstal lebih lama dari 1.5.2, update ekstensi.
```
        CREATE EXTENSION IF NOT EXISTS google_ml_integration;
        ALTER EXTENSION google_ml_integration UPDATE;
      
```
  Jika Anda mengalami masalah saat menjalankan perintah di atas, atau jika ekstensi tidak diupdate ke versi 1.5.2 setelah Anda menjalankan perintah di atas, hubungi Google Cloud dukungan.
Untuk menggunakan fungsi mesin kueri AI AlloyDB, tetapkan flag google_ml_integration.enable_ai_query_engine ke on.
SQL
1. Mengaktifkan mesin kueri AI untuk sesi saat ini.
  SET google_ml_integration.enable_ai_query_engine = on;
2. Mengaktifkan fitur untuk database tertentu di seluruh sesi.
  ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_ai_query_engine = 'on';
3. Aktifkan mesin kueri AI untuk pengguna tertentu di seluruh sesi dan database.
  ALTER ROLE postgres SET google_ml_integration.enable_ai_query_engine = 'on';
Konsol

Untuk mengubah nilai flag google_ml_integration.enable_ai_query_engine, ikuti langkah-langkah di Mengonfigurasi flag database instance.
gcloud

Untuk menggunakan gcloud CLI, Anda dapat menginstal dan melakukan inisialisasi Google Cloud CLI, atau Anda dapat menggunakan Cloud Shell.

Anda dapat mengubah nilai tanda google_ml_integration.enable_ai_query_engine. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi flag database instance.
```
             gcloud alloydb instances update INSTANCE_ID \
               --database-flags google_ml_integration.enable_ai_query_engine=on \
               --region=REGION_ID \
               --cluster=CLUSTER_ID \
               --project=PROJECT_ID
            
```

Menggunakan model Gemini yang didukung di wilayah Anda

Jika cluster AlloyDB for PostgreSQL Anda berada di region yang tidak mendukung gemini-2.0-flash, Anda dapat menggunakan salah satu model Gemini lain yang tersedia di region Anda menggunakan model_id parameter.

Atau, Anda dapat mendaftarkan endpoint model Gemini dan memberikan ID model tersebut ke operator AI. Untuk mengetahui informasi selengkapnya, lihat Mendaftarkan dan memanggil model AI jarak jauh menggunakan pengelolaan endpoint model.

Contoh berikut menunjukkan cara mendaftarkan endpoint Gemini lainnya. Dalam contoh ini, endpoint Gemini kedua ini adalah endpoint global untuk gemini-2.0-flash. Anda dapat menggunakan model terdaftar ini dengan operator AI dengan meneruskan model_id =>gemini-2.5-flash-global` sebagai argumen tambahan.

CALL
  google_ml.create_model(
    model_id => 'gemini-2.5-flash-global',
    model_type => 'llm',
    model_provider => 'google',
    model_qualified_name => 'gemini-2.5-flash',
    model_request_url =>  'https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent',
    model_auth_type => 'alloydb_service_agent_iam'
);

Menggunakan model Gemini 3.0

Beberapa model Gemini, seperti gemini-3.0-pro-preview, hanya tersedia melalui endpoint global. Anda harus mendaftarkan model tersebut sebagai berikut:

CALL
  google_ml.create_model(
    model_id => 'gemini-3-preview-model',
    model_request_url => 'https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3-pro-preview:generateContent',
    model_qualified_name => 'gemini-3-pro-preview',
    model_provider => 'google',
    model_type => 'llm',
    model_auth_type => 'alloydb_service_agent_iam'
);

Ganti PROJECT_ID dengan ID project tempat model Vertex AI tersedia. Perhatikan bahwa akun layanan AlloyDB harus memiliki Peran Pengguna Vertex AI dalam project tersebut.

Setelah mendaftarkan model, Anda dapat menggunakannya dalam fungsi AI sebagai berikut:

SELECT ai.generate(prompt => 'What is AlloyDB?', model_id => 'gemini-3-preview-model');

Menggunakan filter dalam kueri

AlloyDB AI menawarkan fungsi SQL berteknologi AI yang memungkinkan Anda menggunakan pemrosesan bahasa alami dan LLM secara langsung dalam kueri database, termasuk operator ai.if dan ai.rank.

Melakukan pemfilteran menggunakan fungsi skalar

Untuk mengevaluasi apakah suatu kondisi yang dinyatakan dalam bahasa alami terpenuhi, gunakan operator ai.if/google_ml.if. Fungsi ini menampilkan nilai boolean true atau false, dan menampilkan false jika output tidak terdeteksi dengan jelas.

- Function signature
FUNCTION ai.if(prompt TEXT, model_id VARCHAR(100) DEFAULT NULL) RETURNS bool

Contoh berikut menunjukkan penggunaan operator ai.if sebagai filter untuk menemukan restoran dengan lebih dari 500 ulasan positif yang berlokasi di kota dengan populasi lebih dari 100.000. Contoh ini menggunakan restaurant_reviews dan berisi data seperti ulasan dan lokasi kota. Operator ai.if membantu Anda memahami sentimen ulasan dan menggabungkan lokasi dari database dengan pengetahuan umum Gemini tentang populasi di lokasi tersebut.

SELECT r.name, r.location_city
FROM restaurant_reviews r
WHERE
  AI.IF(r.location_city || ' has a population OF more than 100,000 AND the following is a positive review; Review: ' || r.review)
GROUP BY r.name, r.location_city
HAVING COUNT(*) > 500;

Berikut adalah contoh yang sama menggunakan model yang Anda daftarkan di Menggunakan model Gemini yang didukung di wilayah Anda.

SELECT r.name, r.location_city
FROM restaurant_reviews r
WHERE
  AI.IF(r.location_city || ' has a population of more than 100,000 AND the following is a positive review; Review: ' || r.review, model_id => 'gemini-2.5-flash')
GROUP BY r.name, r.location_city
HAVING COUNT(*) > 500;

Melakukan gabungan pada kueri yang menggunakan operator if

Untuk melakukan operasi gabungan, gunakan operator ai.if/google_ml.if dengan gabungan. Contoh kueri berikut menemukan jumlah ulasan yang menyebutkan setiap item menu dari menu restoran.

    SELECT item_name, COUNT(*)
    FROM menu_items JOIN user_reviews
      ON ai.if(
        prompt => 'Does the following user review talk about the menu item mentioned ? review: ' || user_reviews.review_text || ' menu item: ' || item_name)
    GROUP BY item_name;

Melakukan pemfilteran menggunakan fungsi berbasis array

Contoh berikut mengidentifikasi restoran dengan lebih dari 10 ulasan positif menggunakan model AI (gemini-2.0-flash) untuk menganalisis sentimen ulasan dan memfilter hasilnya. ARRAY_AGG digunakan untuk mengubah setiap baris data menjadi array terstruktur sehingga dapat diproses oleh model AI secara massal, bukan satu baris dalam satu waktu.

WITH initial_arrays AS (WITH initial_arrays AS (
  SELECT
    ARRAY_AGG(r.id ORDER BY r.id) AS review_ids,
    -- Assuming ai.if takes an array of prompts and returns a boolean array
    ai.if(
      prompts => ARRAY_AGG('Is the review positive: ' || r.review ORDER BY r.id)
      model_id => 'gemini-2.5-flash',
      batch_size => 20
    ) AS truth_values
  FROM restaurant_reviews r
),
reviews AS (
SELECT
  initial_arrays.review_ids[i] AS review_id,
  initial_arrays.truth_values[i] AS truth_value
FROM
  initial_arrays,
  generate_series(1, array_length(initial_arrays.review_ids, 1)) AS i
)
SELECT rest_review.city, rest_review.name
FROM restaurant_reviews rest_review JOIN reviews review ON rest_review.id=review.review_id
WHERE review.truth_value = 't'
GROUP BY rest_review.city, rest_review.name
HAVING COUNT(*) > 10;

Melakukan pemfilteran menggunakan kursor

Contoh berikut menunjukkan cara memfilter kumpulan besar ulasan restoran dengan melakukan streaming melalui kursor.

CREATE TABLE filtered_results(input text, result bool);

DO $$
DECLARE
    prompt_cursor REFCURSOR;
    result_cursor REFCURSOR;
    rec RECORD;
BEGIN
    -- 1. Open a cursor for the input data
    OPEN prompt_cursor FOR
        SELECT r.location_city || ' has a population of > 100,000 and is a positive review; Review: ' || r.review
        FROM restaurant_reviews r;

    -- 2. Call the array-based function using the input cursor
    result_cursor := ai.if(
        'Is the given statement true? ',
        prompt_cursor,
        model_id => 'gemini-2.5-flash'
    );

    -- 3. Fetch results from the output cursor and store them
    LOOP
        FETCH result_cursor INTO rec;
        EXIT WHEN NOT FOUND;
        INSERT INTO filtered_results VALUES(rec.input, rec.output);
    END LOOP;

    CLOSE result_cursor;
END $$;

Pembuatan dan peringkasan teks

AlloyDB AI menawarkan operator pembuatan teks seperti ai.generate berbasis skalar, berbasis array, dan berbasis kursor.ai.generate

Melakukan pembuatan teks menggunakan fungsi skalar

Fungsi ai.generate menghasilkan teks dengan menggabungkan data yang diberikan dengan perintah pengguna.

-- Function Signature
FUNCTION ai.generate(prompt TEXT, model_id VARCHAR(100) DEFAULT NULL) RETURNS TEXT

Misalnya, Anda dapat menggunakan kueri berikut untuk membuat ringkasan singkat dari setiap ulasan pengguna.

SELECT
  ai.generate(
    prompt => 'Summarize the review in 20 words or less. Review: ' || review) AS review_summary
FROM user_reviews;

Melakukan pembuatan teks menggunakan fungsi berbasis array

Kueri berikut menggunakan UNNEST dan ai.generate untuk meringkas beberapa ulasan secara efisien.

SELECT
  UNNEST(
    ai.generate(
      prompts => ARRAY_AGG('Summarize the review in 20 words or less. Review: ' || review),
      model_id => 'gemini-2.5-flash',
    )
  ) AS review_summary
FROM user_reviews;

Melakukan pembuatan teks menggunakan kursor

Untuk membuat ringkasan atau terjemahan untuk jutaan baris tanpa mengalami hambatan memori, gunakan pembuatan batch dengan kursor.

CREATE TABLE summary_results(summary text);

DO $$
DECLARE
    prompt_cursor REFCURSOR;
    summary_cursor REFCURSOR;
    rec RECORD;
BEGIN
    OPEN prompt_cursor FOR SELECT review_text FROM user_reviews ORDER BY id;

    summary_cursor := ai.generate(
        'Summarize the review in 20 words or less. Review:',
        prompt_cursor,
    );

    LOOP
        FETCH summary_cursor INTO rec;
        EXIT WHEN NOT FOUND;
        INSERT INTO summary_results VALUES(rec.output);
    END LOOP;

    CLOSE summary_cursor;
END $$;

Memberi skor pada hasil kueri Anda

Jika Anda perlu mengurutkan hasil kueri menggunakan petunjuk bahasa alami kustom, gunakan operator ai.rank.

Melakukan penskoran menggunakan fungsi skalar

Fungsi berikut memungkinkan Anda memberikan perintah yang mendeskripsikan kriteria peringkat dan menampilkan skor untuk setiap item.

-- Function signature
FUNCTION ai.rank(prompt TEXT, model_id VARCHAR(100) DEFAULT NULL) RETURNS real

Misalnya, kueri berikut mendapatkan 20 ulasan restoran paling positif teratas, menggunakan skor dari LLM.

SELECT review AS top20
FROM user_reviews
ORDER BY ai.rank(
  'Score the following review according to these rules:
  (1) Score OF 8 to 10 IF the review says the food IS excellent.
  (2) 4 to 7 IF the review says the food is ok.
  (3) 1 to 3 IF the review says the food is not good. Here is the review:' || review) DESC
LIMIT 20;

Melakukan pemberian skor menggunakan fungsi berbasis array

Fungsi ai.rank ini memungkinkan Anda memberi skor dan memberi peringkat hasil kueri berdasarkan petunjuk bahasa alami kustom.

FUNCTION ai.rank(prompts TEXT[], model_id VARCHAR(100) DEFAULT NULL) RETURNS real[]

Kueri berikut menggunakan UNNEST dan ai.rank untuk memberi skor pada beberapa ulasan secara efisien.

SELECT
  UNNEST(
    ai.rank(
      ARRAY_AGG('Score the following review according to these rules:
  (1) Score OF 8 to 10 IF the review says the food IS excellent.
  (2) 4 to 7 IF the review says the food is ok.
  (3) 1 to 3 IF the review says the food is not good. Here is the review:' || review),
    )
  ) as review_scores
FROM user_reviews;

Melakukan pemberian skor menggunakan kursor

Fungsi ini digunakan untuk memberi skor pada set data besar tanpa mencapai batas memori.

FUNCTION ai.rank(context TEXT, input_cursor REFCURSOR, model_id VARCHAR(100) DEFAULT NULL) RETURNS REFCURSOR

Contoh berikut menunjukkan cara memberi skor pada teks dalam jumlah besar sesuai dengan kriteria bahasa alami tertentu.

CREATE TABLE scored_results(input text, score real);

DO $$
DECLARE
    prompt_cursor REFCURSOR;
    score_cursor REFCURSOR;
    rec RECORD;
BEGIN
    OPEN prompt_cursor FOR SELECT review FROM user_reviews ORDER BY id;

    score_cursor := ai.rank(
        'Score the following review: (1) 8-10 if excellent, (2) 4-7 if ok, (3) 1-3 if not good. Review:',
        prompt_cursor,
    );

    LOOP
        FETCH score_cursor INTO rec;
        EXIT WHEN NOT FOUND;
        INSERT INTO scored_results VALUES(rec.input, rec.output);
    END LOOP;

    CLOSE score_cursor;
END $$;