Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat kueri SQL menggunakan pertanyaan bahasa alami

Halaman ini menjelaskan cara menyiapkan, mengonfigurasi, dan membuat pernyataan SQL menggunakan bahasa alami AlloyDB AI. Natural language memungkinkan Anda membuat aplikasi AI generatif yang menghadap pengguna menggunakan natural language untuk membuat kueri database.

Untuk mengaktifkan ekstensi alloydb_ai_nl, yang merupakan API dukungan bahasa alami AlloyDB untuk PostgreSQL, Anda harus melakukan langkah-langkah tingkat tinggi berikut:

Instal ekstensi alloydb_ai_nl.
Tentukan konfigurasi bahasa alami untuk aplikasi Anda.
Mendaftarkan skema.
Tambahkan konteks.
Tambahkan template kueri.
Tentukan jenis konsep dan buat indeks nilai.
Buat pernyataan SQL menggunakan antarmuka bahasa alami.

Sebelum memulai

Pahami cara terhubung ke database AlloyDB dan menjalankan perintah PostgreSQL. Untuk mengetahui informasi selengkapnya, lihat Ringkasan koneksi.
Isi database dengan data dan skema yang ingin diakses pengguna akhir.

Aktifkan ekstensi yang diperlukan

Sebelum dapat menginstal dan menggunakan natural language AlloyDB AI, Anda harus mengaktifkan ekstensi dengan menambahkan tanda alloydb_ai_nl.enabled. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi flag database instance.

Membuat cluster dan mengaktifkan integrasi Vertex AI

Buat cluster dan instance AlloyDB. Anda menggunakan instance AlloyDB untuk membuat database dan skema aplikasi.
Aktifkan integrasi Vertex AI. Untuk mengetahui informasi selengkapnya, lihat Mengintegrasikan dengan Vertex AI.

Peran yang diperlukan

Untuk menginstal ekstensi alloydb_ai_nl dan memberikan akses kepada pengguna lain, Anda harus memiliki peran Identity and Access Management (IAM) berikut dalam project Google Cloud yang Anda gunakan:

roles/alloydb.admin (peran IAM bawaan Admin AlloyDB)

Untuk mengetahui informasi selengkapnya, lihat Mengelola pengguna PostgreSQL dengan autentikasi standar.

Menyiapkan lingkungan Anda

Untuk bersiap membuat kueri bahasa alami, Anda harus menginstal ekstensi yang diperlukan, membuat konfigurasi, dan mendaftarkan skema.

Instal ekstensi alloydb_nl_ai

Ekstensi alloydb_ai_nl menggunakan ekstensi google_ml_integration, yang berinteraksi dengan model bahasa besar (LLM), termasuk model Gemini di Vertex AI.

Untuk menginstal ekstensi alloydb_ai_nl, hubungkan ke database dan jalankan perintah berikut:

CREATE EXTENSION alloydb_ai_nl cascade;

Mengupgrade ekstensi alloydb_ai_nl

Pastikan Anda memiliki ekstensi alloydb_ai_nl versi terbaru. Jika Anda sudah menginstal ekstensi, periksa apakah ada versi ekstensi baru yang tersedia, dan upgrade ekstensi jika Anda tidak menggunakan versi terbaru. Untuk mengetahui informasi selengkapnya tentang ekstensi alloydb_ai_nl, lihat Ringkasan bahasa alami AI AlloyDB.

Tentukan apakah Anda perlu mengupgrade ekstensi. Jika default_version lebih baru daripada installed_version, upgrade ekstensi.
```
SELECT * FROM pg_available_extensions where name = 'alloydb_ai_nl';
```
Upgrade ekstensi.
```
ALTER EXTENSION alloydb_ai_nl UPDATE;
```

Membuat konfigurasi bahasa alami dan mendaftarkan skema

Bahasa alami AI AlloyDB menggunakan nl_config untuk mengaitkan aplikasi dengan skema, template kueri, dan endpoint model tertentu. nl_config adalah konfigurasi yang mengaitkan aplikasi dengan skema, template, dan konteks lainnya. Aplikasi besar juga dapat menggunakan konfigurasi yang berbeda untuk berbagai bagian aplikasi, selama Anda menentukan konfigurasi yang tepat saat pertanyaan dikirim dari bagian aplikasi tersebut. Anda dapat mendaftarkan seluruh skema, atau Anda dapat mendaftarkan objek skema tertentu, seperti tabel, tampilan, dan kolom.

Untuk membuat konfigurasi bahasa alami, gunakan contoh berikut:

SELECT
  alloydb_ai_nl.g_create_configuration(
    'my_app_config'        -- configuration_id
  );

gemini-2.0-flash:generateContent adalah endpoint model.

Daftarkan skema untuk konfigurasi tertentu menggunakan contoh berikut:

SELECT
  alloydb_ai_nl.g_manage_configuration(
    operation => 'register_schema',
    configuration_id_in => 'my_app_config',
    schema_names_in => '{my_schema}'
  );

Tambahkan konteks

Konteks mencakup semua jenis informasi yang dapat Anda gunakan untuk menjawab pertanyaan pengguna akhir, seperti berikut:

Struktur dan hubungan skema
Ringkasan dan deskripsi kolom
Nilai kolom dan semantiknya
Aturan atau pernyataan logika bisnis khusus untuk aplikasi atau domain

Menambahkan konteks umum untuk aturan spesifik per aplikasi

Item konteks umum mencakup aturan khusus aplikasi, pernyataan logika bisnis, atau terminologi khusus aplikasi dan domain yang tidak ditautkan ke objek skema tertentu.

Untuk menambahkan konteks umum untuk aturan khusus aplikasi dan terminologi khusus aplikasi atau domain, ikuti langkah-langkah berikut:

Untuk menambahkan item konteks umum untuk konfigurasi yang ditentukan, jalankan kueri berikut:

SELECT
  alloydb_ai_nl.g_manage_configuration(
    'add_general_context',
    'my_app_config',
    general_context_in => '{"If the user asks for a good seat, assume that means a window or aisle seat."}'
  );

Pernyataan sebelumnya membantu bahasa alami AlloyDB AI memberikan respons berkualitas lebih tinggi atas pertanyaan bahasa alami pengguna.

Untuk melihat konteks umum untuk konfigurasi yang ditentukan, jalankan kueri berikut:
```
SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);
```

Membuat dan meninjau konteks skema

Konteks skema menjelaskan objek skema termasuk tabel, tampilan, tampilan terwujud, dan kolom. Konteks ini disimpan sebagai COMMENT setiap objek skema.

Untuk membuat konteks untuk objek skema, panggil API berikut. Untuk mendapatkan hasil terbaik, pastikan tabel database berisi data yang representatif.

-- For all schema objects (tables, views, materialized views and columns)
-- within the scope of a provided nl_config.
SELECT
  alloydb_ai_nl.generate_schema_context(
    'my_app_config' -- nl_config
  );

Tinjau konteks skema yang dihasilkan dengan menjalankan kueri berikut:
```
SELECT schema_object, object_context
FROM alloydb_ai_nl.generated_schema_context_view;
```
Konteks skema yang dihasilkan disimpan dalam tampilan sebelumnya.

Opsional: Perbarui konteks skema yang dihasilkan.

SELECT
  alloydb_ai_nl.update_generated_relation_context(
    'my_schema.my_table',
    'This table contains archival records, if you need latest records use records_new table.'
  );

SELECT
  alloydb_ai_nl.update_generated_column_context(
    'my_schema.my_table.column1',
    'The seat_class column takes single letters like "E" for economy, "P" for premium economy, "B" for business and "F" for First.'
  );

Terapkan konteks. Saat Anda menerapkan konteks, konteks akan langsung berlaku dan dihapus dari tampilan generated_schema_context_view.

-- For all schema objects (tables, views, materialized views and columns)
-- within the scope of nl_config.
SELECT
  alloydb_ai_nl.apply_generated_schema_context(
    'my_app_config' --nl_config
  );

Opsional: Verifikasi konteks yang dihasilkan. API berikut memungkinkan Anda memeriksa konteks skema, yang digunakan saat Anda membuat pernyataan SQL.

-- For table, view or materialized view.
SELECT
  alloydb_ai_nl.get_relation_context(
    'my_schema.my_table'
  );

-- For column.
SELECT
  alloydb_ai_nl.get_column_context(
    'my_schema.my_table.column1'
  );

Opsional: Tetapkan konteks skema secara manual.

-- For table, view or materialized view.
SELECT
  alloydb_ai_nl.set_relation_context(
    'my_schema.my_table',
    'One-to-many mapping from product to categories'
  );

-- For column.
SELECT
  alloydb_ai_nl.set_column_context(
    'my_schema.my_table.column1',
    'This column provides additional tagged info for the product in  Json format, e.g., additional color or size information of the product - tags: { "color": "red", "size": "XL"}'
  );

Membuat template kueri

Untuk meningkatkan kualitas aplikasi AI generatif yang dibangun dengan LLM, Anda dapat menambahkan template. Template kueri adalah kumpulan terkurasi dari pertanyaan bahasa alami yang representatif atau umum, dengan kueri SQL yang sesuai, serta penjelasan untuk memberikan alasan deklaratif bagi pembuatan natural language-to-SQL (NL2SQL). Template terutama ditujukan untuk ditentukan oleh aplikasi, tetapi template juga dapat dibuat secara otomatis oleh ekstensi alloydb_ai_nl berdasarkan kueri SQL yang sering digunakan. Setiap template harus dikaitkan dengan nl_config.

Ekstensi alloydb_ai_nl menggunakan template_store untuk menggabungkan template SQL yang relevan secara dinamis dalam proses pembuatan pernyataan SQL untuk menjawab pertanyaan pengguna akhir. template_store melakukan hal berikut:

Mengidentifikasi template dengan maksud yang serupa dengan pertanyaan bahasa alami yang diajukan pengguna akhir.
Mengidentifikasi pernyataan SQL berparameter yang sesuai.
Mensintesis pernyataan SQL dengan membuat parameter menggunakan nilai dari pertanyaan bahasa alami.

Jika tidak ada template dengan maksud yang sama dengan pertanyaan yang diajukan pengguna akhir, alloydb_ai_nl menggunakan setiap template dan konteks yang relevan untuk menyusun pernyataan SQL.

Menambahkan template ke toko template

Anda menambahkan template dengan menentukan pertanyaan—menggunakan parameter bernama intent—dan kueri SQL.

Untuk menambahkan template ke toko template, jalankan kueri berikut:

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => 'my_app_config',
    intent => 'How many accounts associated with loans are located in the Prague region?',
    sql => 'SELECT COUNT(T1.account_id)
            FROM bird_dev_financial.account AS T1
            INNER JOIN bird_dev_financial.loan AS T2
              ON T1.account_id = T2.account_id
            INNER JOIN bird_dev_financial.district AS T3
              ON T1.district_id = T3.district_id
            WHERE T3."A3" = ''Prague''',
    check_intent => TRUE
  );

Jika check_intent adalah TRUE, alloydb_ai_nl akan melakukan pemeriksaan semantik untuk mengonfirmasi bahwa intent yang diberikan cocok dengan pernyataan SQL yang diteruskan. Jika intent tidak cocok dengan pernyataan SQL, template tidak ditambahkan.

SQL dan maksud diparameterkan oleh alloydb_ai_nl. Tampilan alloydb_ai_nl.template_store_view menampilkan pernyataan SQL yang diberi parameter dan maksudnya.

SELECT psql
FROM alloydb_ai_nl.template_store_view
WHERE intent = 'How many accounts associated with loans are located in the Prague region?';

Pernyataan ini menampilkan hal berikut:

SELECT COUNT(T1.account_id)
FROM account AS T1 INNER JOIN loan AS T2
  ON T1.account_id = T2.account_id
INNER JOIN district AS T3
  ON T1.district_id = T3.district_id WHERE T3."A3" = $1

Menyediakan parameterisasi yang disesuaikan

Untuk memberikan parameterisasi yang disesuaikan untuk pernyataan SQL menggunakan antarmuka manual fungsi add_template, jalankan pernyataan dalam contoh berikut:

SELECT
  alloydb_ai_nl.add_template(
     nl_config_id => 'my_app_config',
     intent => 'Among the accounts opened, how many customers born before 1950 resided in Slokolov at the time of account opening?',
     sql => $$SELECT COUNT(DISTINCT T2.client_id)
              FROM district AS T1 INNER JOIN client AS T2
                ON T1.district_id = T2.district_id
             INNER JOIN account AS T3 ON T2.client_id IN (
                   SELECT client_id FROM disp WHERE account_id = T3.account_id)
             WHERE to_char(T2.birth_date::timestamp, 'YYYY') < '1950'
               AND T1."A2" = 'Slokolov'$$,
  parameterized_sql => $$SELECT COUNT(DISTINCT T2.client_id)
                         FROM district AS T1 INNER JOIN client AS T2
                           ON T1.district_id = T2.district_id
                   INNER JOIN account AS T3 ON T2.client_id IN (
                         SELECT client_id FROM disp WHERE account_id = T3.account_id)
                   WHERE to_char(T2.birth_date::timestamp, 'YYYY') < $2
                     AND T1."A2" = $1$$,
  parameterized_intent => $$Among the accounts opened, how many customers born before $2 resided in $1 at the time of account opening?$$,
  manifest => $$Among the accounts opened, how many customers born before a given date resided in a given city at the time of account opening?$$,
  check_intent => TRUE);

Dalam definisi sebelumnya, parameterisasi pernyataan SQL diberikan. Parameternya adalah $1 dan $2, masing-masing untuk Slokolov dan 1950. Manifes disediakan sebagai versi umum dari maksud, dengan nilai literal diganti dengan deskripsi umum dari nilai tersebut.

Dalam contoh ini, nilai 1950 dalam intent diganti dengan a given date, dan nilai Slokolov diganti dalam manifes dengan a given city. Jika nilai TRUE diberikan untuk argumen opsional check_intent , verifikasi niat berbasis LLM dilakukan selama add_template. Selama pemeriksaan ini, jika pernyataan SQL yang diberikan tidak mencakup tujuan dan sasaran pernyataan maksud yang diberikan, add_template akan gagal dan alasannya diberikan sebagai output.

Dalam contoh berikut, tujuan template—seperti yang ditunjukkan dalam maksud—adalah untuk mengambil ID akun dari akun yang terkait dengan beban dan yang berada di suatu region. Pernyataan SQL yang diberikan menampilkan jumlah akun, bukan daftar ID akun, seperti yang ditunjukkan dalam contoh berikut.

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => 'my_app_config',
    intent => 'List the account id for all accounts that associated with loans and are located in the Prague region.',
    sql => 'SELECT COUNT(T1.account_id)
            FROM account AS T1 INNER JOIN loan AS T2
              ON T1.account_id = T2.account_id
            INNER JOIN district AS T3
              ON T1.district_id = T3.district_id
            WHERE T3."A3" = ''Prague''',
    check_intent => TRUE
  );

Jika check_intent disetel ke TRUE, Anda tidak dapat menambahkan template sebelumnya ke toko template. Jika Anda menjalankan pernyataan sebelumnya, error yang mirip dengan berikut akan ditampilkan:

ERROR:  Checking intent failed, for nl_question:List the account id for all accounts that associated with loans and are located in the Prague region...reason:The SQL query only counts the number of account IDs, but the question asks for a list of the account IDs.

Kelola template

Anda dapat mengelola template di toko template menggunakan API berikut:

-- To disable a template:
SELECT alloydb_ai_nl.disable_template(INPUT template_id);

-- To enable a template which has been disabled:
SELECT alloydb_ai_nl.enable_template(INPUT template_id);

-- To permanently remove a template:
SELECT alloydb_ai_nl.drop_template(INPUT template_id);

Saat Anda membuat template, template tersebut diaktifkan secara default. Template yang dinonaktifkan tetap ada di penyimpanan template, tetapi tidak digunakan oleh alloydb_ai_nl untuk sintesis kueri. Anda dapat mengaktifkan template yang dinonaktifkan menggunakan alloydb_ai_nl.enable_template. Menjalankan alloydb_ai_nl.drop_template akan menghapus template secara permanen dari template store.

Anda dapat menggunakan alloydb_ai_nl.template_store_view untuk mengekstrak template_id dari template, berdasarkan kontennya. Misalnya, untuk menemukan ID template yang memiliki maksud accounts that associated with loans, jalankan kueri berikut, yang menampilkan ID template dan mengidentifikasi apakah template diaktifkan dari alloydb_ai_nl.template_store_view:

SELECT id, enabled
FROM alloydb_ai_nl.template_store_view
WHERE intent ILIKE '%accounts that associated with loans%';

Memperbarui template

Saat Anda menggunakan template di alloydb_ai_nl.template_store_view, pastikan bahwa maksud setiap template konsisten dengan hal berikut:

Pernyataan SQL
Pernyataan SQL berparameter
Intent berparameter
Manifes template

alloydb_ai_nl dapat mengambil template yang relevan jika sematan yang dipertahankan untuk template sesuai dengan konten template.

Untuk memperbarui template, ikuti langkah-langkah berikut:

Identifikasi template_id menggunakan alloydb_ai_nl.template_store_view.
Hapus template.
Tentukan ulang template baru dengan modifikasi yang diperlukan menggunakan fungsi alloydb_ai_nl.add_template.

Membuat fragmen kueri

Anda dapat mengkhususkan template pada waktu kueri menggunakan fragmen, yang membantu template kueri melakukan penelusuran berfaset seperti pertanyaan bahasa alami. Fragmen adalah kumpulan kondisi bahasa alami yang umum atau representatif dengan predikat SQL yang sesuai. Fragmen dimaksudkan untuk ditentukan oleh aplikasi.

Setiap fragmen harus dikaitkan dengan nl_config_id dan dengan array tabel dan tampilan dengan alias yang diterapkan predikat fragmennya. Anda dapat memverifikasi tujuan fragmen saat argumen check_intent disetel ke TRUE. Ekstensi alloydb_ai_nl dapat menggunakan template dengan kombinasi fragmen untuk menyintesis jawaban atas kueri bahasa alami.

Ekstensi alloydb_ai_nl menggunakan fragment_store untuk menggabungkan kondisi secara dinamis dalam fragmen yang relevan dalam proses pembuatan pernyataan SQL untuk menjawab pertanyaan pengguna akhir. Pertama, template_store mengidentifikasi template dengan maksud yang serupa dengan pertanyaan bahasa alami yang diajukan pengguna akhir. Selanjutnya, fragmen yang dapat memberikan spesialisasi pada template yang diidentifikasi akan diambil. Penggantian parameter diterapkan ke template dan fragmen untuk menyintesis pernyataan SQL.

Nilai parameter diekstrak dari pertanyaan bahasa alami dan diganti oleh LLM menggunakan pola yang tersirat dari template dan fragmen yang relevan. Namun, jika kombinasi template dan fragmen tidak memiliki tujuan yang sama untuk pertanyaan yang diajukan pengguna akhir, alloydb_ai_nl akan menggunakan setiap template dan konteks yang relevan untuk menyusun pernyataan SQL.

Menambahkan fragmen

Untuk menambahkan fragmen, jalankan contoh kueri berikut menggunakan fungsi alloydb_ai_nl.add_fragment. Setiap fragmen harus dikaitkan dengan ID nl_config_id dari aplikasi.

-- A fragment that cannot be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['account AS T'],
  intent => 'Accounts with issuance after transaction',
  fragment => 'T.frequency = ''POPLATEK PO OBRATU''',
  check_intent => True);

-- A fragment that can be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['district AS T'],
  intent => 'Average salary between 6000 and 10000',
  fragment => 'T."A11" BETWEEN 6000 AND 10000',
  check_intent => True);

Saat alloydb_ai_nl.add_fragment berjalan, ekstensi alloydb_ai_nl mengekstraksi manifes dari intent yang diberikan, dan ekstensi memparameterkan intent dan kondisi untuk fragmen, jika memungkinkan. Fragmen yang tersedia diekspos oleh tampilan seperti alloydb_ai_nl.fragment_store_view, seperti yang ditunjukkan dalam contoh berikut:

SELECT manifest, scope, fragment, intent, pfragment, pintent
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = 'Average salary between 6000 and 10000';

Kueri menampilkan kumpulan hasil yang mirip dengan berikut ini:

manifest  | Average salary between a given number and a given number
scope     | district AS T
fragment  | T."A11" BETWEEN 6000 AND 10000
intent    | Average salary between 6000 and 10000
pfragment | T."A11" BETWEEN $2 AND $1
pintent   | Average salary between $2 and $1

Manifes dalam fragmen dibuat secara otomatis dari intent, dan manifes tersebut merepresentasikan versi umum dari intent. Misalnya, angka 6000 dan 10000 dalam intent masing-masing diganti dengan a given number dalam manifest. Angka tersebut masing-masing diganti dengan $2 dan $1 di kolom pfragment dan pintent. Kolom pfragment dan pintent di alloydb_ai_nl.fragment_store_view masing-masing adalah representasi berparameter untuk fragment dan intent.

Untuk memberikan parameterisasi fragmen yang disesuaikan, gunakan versi manual alloydb_ai_nl.add_fragment, seperti yang ditunjukkan dalam contoh berikut:

SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['bird_dev_financial.district AS T'],
  intent => $$districts in 'Prague'$$,
  parameterized_intent => $$districts in $1$$,
  fragment => $$T."A3" = 'Prague'$$,
  parameterized_fragment => $$T."A3" = $1$$,
  manifest => $$districts in a given city$$,
  check_intent => TRUE);

Mengelola fragmen

Untuk mengelola fragmen, gunakan API berikut:

-- To disable a fragment:
SELECT alloydb_ai_nl.disable_fragment(INPUT fragment_id);

-- To enable a fragment which has been disabled:
SELECT alloydb_ai_nl.enable_fragment(INPUT fragment_id);

-- To permanently remove a fragment:
SELECT alloydb_ai_nl.drop_fragment(INPUT fragment_id);

Anda dapat menggunakan tampilan alloydb_ai_nl.fragment_store_view untuk mengekstrak fragment_id fragmen, mengingat isinya. Misalnya, untuk menemukan ID fragmen yang memiliki intent Average salary between 6000 and 10000, jalankan contoh kueri berikut:

SELECT id
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = "Average salary between 6000 and 10000";

Memperbarui fragmen

Saat Anda memperbarui fragmen, pastikan intent fragmen konsisten dengan hal berikut:

Pernyataan SQL dan manifes fragmen
Pernyataan SQL berparameter
Intent berparameter

Untuk memastikan konsistensi saat Anda memperbarui fragmen, ikuti langkah-langkah berikut:

Hapus fragmen yang ingin Anda ubah menggunakan fungsi alloydb_ai_nl.drop_fragment.
Masukkan fragmen yang diperbarui menggunakan fungsi alloydb_ai_nl.add_fragment.

Membuat template secara otomatis

Setelah Anda memiliki set data representatif di tabel, sebaiknya Anda menjalankan kueri SQL yang sesuai dengan pertanyaan umum yang kemungkinan akan diajukan oleh pengguna akhir Anda. Pastikan kueri memiliki paket kueri yang lengkap dan berperforma baik.

Setelah Anda menjalankan kueri, bahasa alami AlloyDB AI dapat membuat template secara otomatis berdasarkan histori kueri. Anda dapat memanggil API berikut untuk membuat template. Anda harus meninjau dan menerapkan template yang dibuat sebelum template tersebut berlaku.

Pembuatan otomatis template didasarkan pada kueri yang paling sering digunakan dalam log kueri, google_db_advisor_workload_statements. Kueri difilter berdasarkan kriteria berikut:

Pernyataan SELECT
Dapat dieksekusi: kueri dapat berhasil diproses oleh perintah EXPLAIN.
Tidak ada duplikasi: kueri belum pernah digunakan sebelumnya untuk membuat template.
Semua tabel dan tampilan yang dirujuk berada dalam cakupan nl_config.

Untuk membuat, meninjau, dan menerapkan template secara otomatis, ikuti langkah-langkah berikut:

Minta AlloyDB untuk membuat template berdasarkan histori kueri Anda:
```
SELECT
  alloydb_ai_nl.generate_templates(
    'my_app_config',
);
```
Gunakan tampilan yang disediakan, alloydb_ai_nl.generated_templates_view, untuk meninjau generated_templates.

Output berikut menunjukkan jumlah template yang dihasilkan:
```
-[ RECORD 1 ]------+--
generate_templates | 1
```

Tinjau template yang dibuat menggunakan tampilan generated_templates_view.

SELECT *
FROM alloydb_ai_nl.generated_templates_view;

Berikut adalah contoh output yang ditampilkan:

-[ RECORD 1 ]----------------------------------------------------------------
id          | 1
config      | my_app_config
type        | Template
manifest    | How many clients have a birth year of a given number?
nl          | How many clients have a birth year of 1997?
sql         | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = '1997';
intent      | How many clients have a birth year of 1997?
psql        | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = $1;
pintent     | How many clients have a birth year of $1?
comment     |
explanation |
weight      | 1

manifest dalam output yang ditampilkan adalah template umum atau deskripsi luas tentang jenis pertanyaan atau operasi yang dapat dilakukan. pintent adalah versi berparameter dari intent, dan menggeneralisasi intent dengan mengganti nilai tertentu (1997) dengan placeholder ($1).

Untuk memperbarui template yang dibuat, jalankan contoh pernyataan berikut:

SELECT alloydb_ai_nl.update_generated_template(
  id => 1,
  manifest => 'How many clients are born in a given year?',
  nl => 'How many clients are born in 1997?',
  intent => 'How many clients are born in 1997?',
  pintent => 'How many clients are born in $1?'

);

Terapkan template. Template yang Anda terapkan akan langsung ditambahkan ke toko template, dan dihapus dari tampilan ulasan.

-- For all templates generated under the nl config.
SELECT
  alloydb_ai_nl.apply_generated_templates('my_app_config');

Mengonfigurasi keamanan untuk bahasa alami

Untuk mengonfigurasi keamanan untuk natural language AlloyDB AI, lihat Mengelola keamanan aplikasi data menggunakan tampilan aman berparameter.

Menentukan jenis konsep dan indeks nilai

Anda menentukan jenis konsep dan indeks nilai untuk memberikan pemahaman yang lebih mendalam tentang pertanyaan yang diajukan. Jenis konsep adalah kategori atau class entitas yang mengidentifikasi makna semantik kata dan frasa, bukan hanya bentuk literalnya.

Misalnya, dua nama negara mungkin sama meskipun salah satu nama negara menggunakan huruf kapital, misalnya, USA, dan nama negara lainnya menggunakan huruf kecil, misalnya, usa. Dalam hal ini, nama negara adalah jenis konsep. Contoh jenis konsep lainnya mencakup nama orang, nama kota, dan tanggal.

Indeks nilai adalah indeks di atas nilai dalam kolom yang merupakan bagian dari konfigurasi bahasa alami nl_config, berdasarkan jenis konsep yang terkait dengan setiap kolom. Indeks nilai memungkinkan pencocokan frasa nilai yang efisien untuk pertanyaan yang diajukan dan nilai dalam database.

Untuk menentukan jenis konsep dan indeks nilai, ikuti langkah-langkah berikut menggunakan contoh yang diberikan. Contoh ini mengaitkan kolom dengan jenis konsep, membuat dan memperbarui indeks nilai, serta menggunakan set sinonim untuk melakukan penelusuran nilai.

Untuk mengaitkan kolom dengan jenis konsep, jalankan kueri berikut:

SELECT
  alloydb_ai_nl.associate_concept_type(
    column_names_in => 'my_schema.country.country_name',
    concept_type_in => 'country_name',
    nl_config_id_in => 'my_app_config'
  );

Untuk membuat indeks nilai berdasarkan semua kolom yang merupakan bagian dari konfigurasi bahasa alami dan terkait dengan jenis konsep, jalankan pernyataan berikut:
```
SELECT
  alloydb_ai_nl.create_value_index(
    nl_config_id_in => 'my_app_config'
  );
```

Saat Anda mengaitkan jenis konsep ke kolom baru, muat ulang indeks nilai untuk mencerminkan perubahan.

SELECT
  alloydb_ai_nl.refresh_value_index(
    nl_config_id_in => 'my_app_config'
  );

Untuk mengaktifkan bahasa alami AI AlloyDB agar cocok dengan sinonim nilai, jalankan contoh pernyataan berikut:
```
SELECT
  alloydb_ai_nl.insert_synonym_set(
    ARRAY [
      'USA',
      'US',
      'United States',
      'United States of America'
    ]
  );
```
Meskipun data dalam tabel Anda mungkin menggunakan nilai tertentu—misalnya, jika United States digunakan untuk mengidentifikasi negara—Anda dapat menentukan kumpulan sinonim yang berisi semua sinonim untuk United States. Jika ada sinonim yang muncul dalam pertanyaan natural language, AlloyDB AI akan mencocokkan sinonim tersebut dengan nilai dalam tabel Anda.

Lakukan penelusuran nilai untuk menemukan nilai database yang benar, dengan mempertimbangkan array frasa nilai.

SELECT
  alloydb_ai_nl.get_concept_and_value(
    value_phrases_in => ARRAY['United States'],
    nl_config_id_in  => 'my_app_config'
  );

Misalnya, jika pengguna mengajukan pertanyaan seperti "Berapa populasi Amerika Serikat?" yang menggunakan kueri get_sql berikut, bahasa alami AlloyDB AI menggunakan fungsi get_concept_and_value dengan frasa nilai United States untuk melakukan penelusuran fuzzy terhadap indeks nilai. Penelusuran fuzzy adalah teknik penelusuran yang menemukan kecocokan meskipun kueri penelusuran tidak cocok dengan data terkait.

Bahasa alami menemukan hasil—nilai USA— yang mirip dengan kueri penelusuran, dan menggunakan hasil tersebut untuk membuat kueri SQL.

SELECT
  alloydb_ai_nl.get_sql(
    nl_config_id    => 'my_app_config',
    nl_question     => 'What is the population of the United States?',
    additional_info => json_build_object('enrich_nl_question', TRUE)
  ) ->> 'sql';

Jenis konsep bawaan yang ditentukan oleh bahasa alami AlloyDB AI tercantum dalam tabel berikut.

Nama konsep	Deskripsi
`generic_entity_name`	Satu kolom jenis string dapat digunakan untuk nama entity generik. Misalnya: SELECT alloydb_ai_nl.associate_concept_type('public.item.item_name', 'generic_entity_name')
`country_name`, `city_name`, `region_name`	Nama negara, kota, dan wilayah. Penggunaannya sama persis dengan jenis konsep `generic_entity_name`.
`full_person_name`	Nama orang, yang terdiri dari nama depan, nama belakang, dan nama tengah. Hingga tiga kolom jenis string dapat digunakan untuk nama lengkap seseorang. Kolom mana pun dapat dilewati saat mengaitkan kolom nama ke `full_person_name`. Contoh: SELECT alloydb_ai_nl.associate_concept_type('public.person.last_name,public.person.first_name,public.person.middle_name','full_person_name')
`ssn`	Kolom string tunggal yang berisi nomor jaminan sosial. Misalnya: SELECT alloydb_ai_nl.associate_concept_type('public.person.ssn','ssn')
`date`	Tanggal atau stempel waktu. Misalnya: SELECT alloydb_ai_nl.associate_concept_type('public.person.date_col','date')

Membuat asosiasi jenis konsep secara otomatis

Untuk mengaitkan kolom dengan jenis konsep secara otomatis, gunakan fitur pengaitan jenis konsep otomatis dari API bahasa alami AlloyDB AI. Asosiasi jenis konsep menentukan hubungan antara jenis konsep dan satu atau beberapa kolom database, yang merupakan prasyarat untuk membuat indeks nilai.

Untuk membuat asosiasi jenis konsep secara otomatis, ikuti langkah-langkah berikut:

Untuk membuat asosiasi, panggil API berikut.

-- To cover all relations within the scope of a provided nl_config.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To cover a specific relation.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config',
  relation_name => 'my_app_table'
);

Tinjau asosiasi yang dihasilkan dengan menjalankan kueri berikut.

SELECT * FROM alloydb_ai_nl.generated_value_index_columns_view;

Opsional: Perbarui pengaitan yang dibuat.

-- NULL means keeping the original value.
SELECT alloydb_ai_nl.update_generated_concept_type_associations(
  id => 1,
  column_names => NULL,
  concept_type => 'generic_entity_name',
  additional_info => NULL
);

Opsional: Hapus atribusi yang dibuat.

SELECT alloydb_ai_nl.drop_generated_concept_type_association(id => 1);

Terapkan asosiasi yang dihasilkan.

-- To apply all associations under a nl config.
SELECT alloydb_ai_nl.apply_generated_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To apply a specific association by id.
SELECT alloydb_ai_nl.apply_generated_concept_type_association(
  id => 1
);

Muat ulang indeks nilai untuk mencerminkan perubahan.

SELECT alloydb_ai_nl.refresh_value_index(
  nl_config_id_in => 'my_app_config'
);

Membuat pernyataan SQL dari input bahasa alami

Anda dapat menggunakan natural language AlloyDB AI untuk membuat pernyataan SQL dari input natural language. Saat Anda menjalankan pernyataan SQL yang dihasilkan, pernyataan tersebut akan memberikan data dari database yang Anda butuhkan untuk menjawab pertanyaan bahasa alami.

Untuk menggunakan bahasa alami guna mendapatkan hasil dari database menggunakan fungsi alloydb_ai_nl.get_sql, gunakan contoh berikut:

SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  );

Output JSON berikut akan ditampilkan:

{
  "sql": "SELECT T3.balance FROM public.client AS T1 INNER JOIN public.account AS T2 ON T1.district_id = T2.district_id INNER JOIN public.trans AS T3 ON T2.account_id = T3.account_id WHERE T1.client_id = 4 AND T3.trans_id = 851",
  "prompt": "",
  "retries": 0,
  "error_msg": "",
  "nl_question": "What is the sum that client number 4's account has following transaction 851?"
}

Opsional: Untuk mengekstrak kueri SQL yang dibuat sebagai string teks, tambahkan ->>'sql':
```
SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  ) ->> 'sql';
```
Operator ->> digunakan untuk mengekstrak nilai JSON sebagai teks. Fungsi alloydb_ai_nl.get_sql menampilkan objek JSON, yang merupakan bagian dari pernyataan yang mengambil nilai yang terkait dengan kunci sql. Nilai ini adalah kueri SQL yang dihasilkan.

Membuat ringkasan hasil dari input bahasa alami

Anda dapat menggunakan natural language AlloyDB AI untuk membuat ringkasan hasil dari input natural language. Fungsi alloydb_ai_nl.get_sql_summary mengeksekusi pertanyaan bahasa alami dengan aman pada tabel pokok, meringkas sampel set hasil, dan menampilkan ringkasan dalam bahasa alami.

Untuk membuat ringkasan hasil untuk pertanyaan bahasa alami di database Anda, gunakan fungsi alloydb_ai_nl.get_sql_summary seperti yang ditunjukkan dalam contoh berikut:

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?');

Memanggil pernyataan sebelumnya akan menghasilkan contoh objek JSON berikut:

{
  "answer": "The result set indicates that there are 13 accounts that chose issuance after a transaction and are located in the East Bohemia region. The earliest opening date among these accounts is August 21, 1993. Other information about these accounts is not provided in the result set."
}

Anda dapat mengamankan tabel dan tampilan yang diakses oleh kueri di alloydb_ai_nl.get_sql_summary menggunakan satu atau beberapa tampilan aman berparameter. Nama parameter dan nilainya tersedia untuk aplikasi, dan diperlukan oleh alloydb_ai_nl.get_sql_summary.

Misalnya, aplikasi mungkin ingin memberikan parameter user_id untuk pengguna yang diautentikasi dengan ID pengguna 123. Anda dapat melakukannya dengan memberikan input param_names dan param_values, seperti yang ditunjukkan dalam contoh berikut:

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?',
    param_names => ARRAY ['user_id'],
    param_values => ARRAY ['123']
);

Dengan memberikan argumen param_names dan param_values, Anda memastikan bahwa, saat nl_question dapat dijawab oleh pernyataan SQL yang diterapkan oleh tampilan aman berparameter, filter keamanan yang ditetapkan diterapkan saat set hasil dibuat dan ringkasan dibuat.

Menguji dan menyempurnakan

Untuk mendapatkan kueri yang dibuat secara otomatis yang lebih baik, ubah atau tambahkan konteks yang lebih baik, template kueri, dan indeks nilai, lalu lakukan iterasi hingga Anda mendapatkan hasil yang diinginkan.