Menggunakan bahasa alami AlloyDB AI untuk membuat SQL

Tutorial ini menjelaskan cara menyiapkan dan menggunakan API bahasa alami AlloyDB AI menggunakan konsol Google Cloud . Anda akan mempelajari cara mengonfigurasi API natural language AlloyDB AI sehingga Anda dapat mengajukan pertanyaan dalam natural language dan menerima kueri serta hasil SQL.

Tujuan

  • Buat dan isi tabel, lalu gunakan pembuatan otomatis untuk membuat konteks.
  • Buat indeks nilai untuk kolom dalam database.
  • Buat dan konfigurasi objek konfigurasi bahasa alami (nl_config).
  • Buat template untuk contoh kueri di aplikasi.
  • Gunakan fungsi get_sql() untuk menghasilkan kueri SQL yang menjawab pertanyaan.
  • Gunakan fungsi execute_nl_query() untuk menjawab pertanyaan bahasa alami menggunakan database.

Biaya

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih berikut:

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Setelah menyelesaikan tugas yang dijelaskan dalam dokumen ini, Anda dapat menghindari penagihan berkelanjutan dengan menghapus resource yang Anda buat. Untuk mengetahui informasi selengkapnya, lihat Pembersihan.

Sebelum memulai

Minta akses

Sebelum dapat menggunakan natural language AlloyDB AI untuk membuat SQL, Anda harus meminta akses ke natural language AlloyDB AI dan menunggu hingga Anda menerima konfirmasi pengaktifan sebelum mengikuti petunjuk dalam tutorial ini.

Mengaktifkan penagihan dan API yang diperlukan

  1. Di konsol Google Cloud , pilih project.

    Buka pemilih project

  2. Pastikan penagihan diaktifkan untuk Google Cloud project Anda.

  3. Aktifkan Cloud API yang diperlukan untuk membuat dan menghubungkan ke AlloyDB untuk PostgreSQL.

    Mengaktifkan API

    1. Pada langkah Confirm project, klik Next untuk mengonfirmasi nama project yang akan Anda ubah.

    2. Pada langkah Enable APIs, klik Enable untuk mengaktifkan berikut ini:

      • AlloyDB API

Membuat dan menghubungkan ke database

  1. Buat cluster dan instance utamanya.
  2. Hubungkan ke instance dan buat database.
  3. Aktifkan integrasi Vertex AI. Untuk mengetahui informasi selengkapnya, lihat Mengintegrasikan dengan Vertex AI.

Menginstal ekstensi yang diperlukan

Untuk menginstal ekstensi alloydb_ai_nl, yaitu API dukungan bahasa alami AlloyDB AI, jalankan kueri berikut:

CREATE EXTENSION alloydb_ai_nl cascade;

Membuat skema dan tabel nla_demo

Pada langkah-langkah berikut, Anda akan membuat skema dan tabel nla_demo dalam skema. Anda mengisi tabel dengan data sintetis. Skema dan data yang disediakan dirancang untuk mendukung operasi mendasar bisnis retail online, dengan potensi aplikasi yang mencakup pengelolaan pelanggan, analisis, pemasaran, dan aspek operasional.

Data sampel menunjukkan cara Anda dapat menggunakan natural language AlloyDB AI untuk tujuan pengembangan, pengujian, dan demonstrasi, terutama untuk fitur seperti antarmuka natural language.

  1. Buat skema dengan menjalankan kueri berikut:

    CREATE SCHEMA nla_demo;

  2. Buat tabel dalam skema nla_demo. Tabel addresses menyimpan informasi alamat untuk pelanggan dan pesanan.

    CREATE TABLE nla_demo.addresses (
    address_id      SERIAL         PRIMARY KEY,
    street_address  VARCHAR(255)   NOT NULL,
    city            VARCHAR(255)   NOT NULL,
    country         VARCHAR(255)
);

  3. Buat tabel customers dengan menjalankan kueri berikut. Tabel ini menyimpan informasi pelanggan, termasuk ID pelanggan, nama, detail kontak, referensi alamat, tanggal lahir, dan waktu pembuatan data.

    CREATE TABLE nla_demo.customers (
    customer_id     SERIAL         PRIMARY KEY,
    first_name      VARCHAR(255)   NOT NULL,
    last_name       VARCHAR(255)   NOT NULL,
    email           VARCHAR(255)   UNIQUE NOT NULL,
    address_id      INTEGER        REFERENCES nla_demo.addresses(address_id),
    date_of_birth   DATE,
    created_at      TIMESTAMP      DEFAULT CURRENT_TIMESTAMP
);

  4. Buat tabel categories, yang menyimpan kategori produk.

    CREATE TABLE nla_demo.categories (
    category_id     INTEGER        PRIMARY KEY,
    category_name   VARCHAR(255)   UNIQUE NOT NULL
);

  5. Buat tabel brands, yang menyimpan nama merek.

    CREATE TABLE nla_demo.brands (
    brand_id      INTEGER        PRIMARY KEY,
    brand_name    VARCHAR(255)   NOT NULL
);

  6. Buat tabel products, yang menyimpan informasi produk seperti ID produk, nama, deskripsi, merek, keterkaitan kategori, dan waktu pembuatan data.

    CREATE TABLE nla_demo.products (
    product_id    INTEGER        PRIMARY KEY,
    name          VARCHAR(255)   NOT NULL,
    description   TEXT           DEFAULT 'Not available',
    brand_id      INTEGER        REFERENCES nla_demo.brands(brand_id),
    category_id   INTEGER        REFERENCES nla_demo.categories(category_id),
    created_at    TIMESTAMP      DEFAULT CURRENT_TIMESTAMP
);

  7. Buat tabel orders. Tabel ini menyimpan informasi tentang pesanan pelanggan, termasuk pelanggan, tanggal, jumlah total, alamat pengiriman dan penagihan, serta status pesanan.

    CREATE TABLE nla_demo.orders (
    order_id            INTEGER        PRIMARY KEY,
    customer_id         INTEGER        REFERENCES nla_demo.customers(customer_id),
    order_date          TIMESTAMP      DEFAULT CURRENT_TIMESTAMP,
    total_amount        DECIMAL(10, 2) NOT NULL,
    shipping_address_id INTEGER        REFERENCES nla_demo.addresses(address_id),
    billing_address_id  INTEGER        REFERENCES nla_demo.addresses(address_id),
    order_status        VARCHAR(50)
);

  8. Buat tabel order_items. Tabel ini mencatat setiap item dalam pesanan, menautkan ke pesanan dan varian produk, serta menentukan jumlah dan harga.

    CREATE TABLE nla_demo.order_items (
    order_item_id   SERIAL         PRIMARY KEY,
    order_id        INTEGER        REFERENCES nla_demo.orders(order_id),
    product_id      INTEGER        REFERENCES nla_demo.products(product_id),
    quantity        INTEGER        NOT NULL,
    price           DECIMAL(10, 2) NOT NULL
);

Mengisi tabel dalam skema nla_demo

  1. Isi tabel addresses dengan menjalankan kueri berikut:

    INSERT INTO nla_demo.addresses (street_address, city, country)
VALUES
    ('1800 Amphibious Blvd', 'Mountain View', 'USA'),
    ('Avenida da Pastelaria, 1903', 'Lisbon', 'Portugal'),
    ('8 Rue du Nom Fictif 341', 'Paris', 'France');

  2. Isi tabel customers.

    INSERT INTO nla_demo.customers (first_name, last_name, email, address_id, date_of_birth)
VALUES
    ('Alex', 'B.', 'alex.b@example.com', 1, '2003-02-20'),
    ('Amal', 'M.', 'amal.m@example.com', 2, '1998-11-08'),
    ('Dani', 'G.', 'dani.g@example.com', 3, '2002-07-25');

  3. Isi tabel categories.

    INSERT INTO nla_demo.categories (category_id, category_name)
VALUES
    (1, 'Accessories'),
    (2, 'Apparel'),
    (3, 'Footwear'),
    (4, 'Swimwear');

  4. Isi tabel brands.

    INSERT INTO nla_demo.brands (brand_id, brand_name)
VALUES
    (1, 'CymbalPrime'),
    (2, 'CymbalPro'),
    (3, 'CymbalSports');

  5. Isi tabel products.

    INSERT INTO nla_demo.products (product_id, brand_id, category_id, name)
VALUES
    (1, 1, 2, 'Hoodie'),
    (2, 1, 3, 'Running Shoes'),
    (3, 2, 4, 'Swimsuit'),
    (4, 3, 1, 'Tote Bag'),
    (5, 3, 3, 'CymbalShoe');

  6. Isi tabel orders.

    INSERT INTO nla_demo.orders (order_id, customer_id, total_amount, shipping_address_id, billing_address_id, order_status)
VALUES
    (1, 1, 99.99, 1, 1, 'Shipped'),
    (2, 1, 69.99, 1, 1, 'Delivered'),
    (3, 2, 20.99, 2, 2, 'Processing'),
    (4, 3, 79.99, 3, 3, 'Shipped');

  7. Isi tabel order_items.

    INSERT INTO nla_demo.order_items (order_id, product_id, quantity, price)
VALUES
    (1, 1, 1, 79.99),
    (1, 3, 1, 20.00),
    (2, 4, 1, 69.99),
    (3, 3, 1, 20.00),
    (4, 2, 1, 79.99);

Membuat konfigurasi natural language

Untuk menggunakan bahasa alami AlloyDB AI, pastikan endpoint Vertex AI telah dikonfigurasi. Kemudian, Anda membuat konfigurasi dan mendaftarkan skema. g_alloydb_ai_nl.g_create_configuration membuat model.

  1. Buat konfigurasi bahasa alami.

    SELECT alloydb_ai_nl.g_create_configuration( 'nla_demo_cfg' );

  2. Daftarkan tabel ke konfigurasi nla_demo_cfg.

    SELECT alloydb_ai_nl.g_manage_configuration(
    operation => 'register_table_view',
    configuration_id_in => 'nla_demo_cfg',
    table_views_in=>'{nla_demo.customers, nla_demo.addresses, nla_demo.brands, nla_demo.products, nla_demo.categories, nla_demo.orders, nla_demo.order_items}'
);

Membuat dan menerapkan konteks untuk tabel dan kolom

Untuk memberikan jawaban yang akurat atas pertanyaan natural language, Anda menggunakan AlloyDB AI Natural Language API untuk memberikan konteks tentang tabel, tampilan, dan kolom. Anda dapat menggunakan fitur pembuatan konteks otomatis dari AlloyDB AI Natural Language API untuk menghasilkan konteks dari tabel dan kolom, serta menerapkan konteks sebagai COMMENTS yang dilampirkan ke tabel, tampilan, dan kolom.

  1. Untuk membuat konteks skema bagi tabel dan kolomnya yang terdaftar dalam konfigurasi nla_demo_cfg, jalankan perintah berikut:

    SELECT alloydb_ai_nl.generate_schema_context(
  'nla_demo_cfg',
  TRUE
);

    Kueri sebelumnya mengisi tampilan alloydb_ai_nl.generated_schema_context_view dengan konteks. Penerusan TRUE akan menimpa konteks dalam tampilan ini dari proses sebelumnya.

  2. Untuk memverifikasi konteks yang dihasilkan untuk tabel nla_demo.products, jalankan kueri berikut:

    SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'nla_demo.products';

    Konteks yang dihasilkan mirip dengan berikut ini:

    The products table stores information about products, including their name,
a brief description, the brand they belong to (referenced by brand_id),
and the category they fall under (referenced by category_id). Each product
has a unique identifier (product_id) and a timestamp indicating its creation
time (created_at).

  3. Untuk memverifikasi konteks yang dihasilkan untuk kolom, seperti nla_demo.products.name, jalankan perintah berikut:

    SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'nla_demo.products.name';

    Output kuerinya mirip dengan berikut ini:

    The name column in the nla_demo.products table contains the specific
name or title of each product. This is a short, descriptive text string
that clearly identifies the product, like "Hoodie," "Tote Bag,"
"Running Shoes," or "Swimsuit." It helps distinguish individual products
within the broader context of their brand and category. The name column
specifies the exact product. This column is essential for users and
systems to identify and refer to specific products within the database.

  4. Tinjau konteks yang dihasilkan dalam tampilan alloydb_ai_nl.generated_schema_context_view, dan perbarui konteks yang perlu direvisi.

    SELECT alloydb_ai_nl.update_generated_relation_context(
  'nla_demo.products',
  'The "nla_demo.products" table stores product details such as ID, name, description, brand, category linkage, and record creation time.'
);

SELECT alloydb_ai_nl.update_generated_column_context(
  'nla_demo.products.name',
  'The "name" column in the "nla_demo.products" table contains the specific name or title of each product.'
);

  5. Terapkan konteks yang dihasilkan yang akan dilampirkan ke objek yang sesuai:

    SELECT alloydb_ai_nl.apply_generated_relation_context(
  'nla_demo.products', true
);

SELECT alloydb_ai_nl.apply_generated_column_context(
  'nla_demo.products.name',
  true
);

    Entri konteks yang dihasilkan dalam tampilan alloydb_ai_nl.generated_schema_context_view diterapkan ke objek skema yang sesuai, dan komentar akan ditimpa.

Membangun indeks nilai

API natural language AlloyDB AI menghasilkan kueri SQL yang akurat dengan menggunakan penautan nilai. Penautan nilai mengaitkan frasa nilai dalam pernyataan bahasa alami dengan jenis konsep dan nama kolom yang telah terdaftar sebelumnya yang dapat memperkaya pertanyaan bahasa alami.

Misalnya, pertanyaan "Beri tahu harga Hoodie" dapat dijawab dengan lebih akurat jika Hoodie dikaitkan dengan konsep product_name, yang dikaitkan dengan nla_demo.products.name. kolom.

  1. Untuk menentukan jenis konsep product_name dan mengaitkannya dengan kolom nla_demo.products.name, jalankan kueri berikut:

    SELECT alloydb_ai_nl.add_concept_type(
    concept_type_in => 'product_name',
    match_function_in => 'alloydb_ai_nl.get_concept_and_value_generic_entity_name',
    additional_info_in => '{
      "description": "Concept type for product name.",
      "examples": "SELECT alloydb_ai_nl.get_concept_and_value_generic_entity_name(''Camera'')" }'::jsonb
);
SELECT alloydb_ai_nl.associate_concept_type(
    'nla_demo.products.name',
    'product_name',
    'nla_demo_cfg'
);

  2. Untuk memverifikasi bahwa jenis konsep product_name telah ditambahkan ke daftar jenis konsep, jalankan kueri berikut untuk memastikan bahwa product_name disertakan dalam hasil kueri ini:

    SELECT alloydb_ai_nl.list_concept_types();

  3. Untuk memverifikasi bahwa kolom nla_demo.products.name dikaitkan dengan jenis konsep product_name, jalankan kueri berikut:

    SELECT *
FROM alloydb_ai_nl.value_index_columns
WHERE column_names = 'nla_demo.products.name';

  4. Untuk menentukan jenis konsep brand_name dan mengaitkannya dengan kolom nla_demo.brands.brand_name, jalankan kueri berikut:

    SELECT alloydb_ai_nl.add_concept_type(
    concept_type_in => 'brand_name',
    match_function_in => 'alloydb_ai_nl.get_concept_and_value_generic_entity_name',
    additional_info_in => '{
      "description": "Concept type for brand name.",
      "examples": "SELECT alloydb_ai_nl.get_concept_and_value_generic_entity_name(''CymbalPrime'')" }'::jsonb
);
SELECT alloydb_ai_nl.associate_concept_type(
    'nla_demo.brands.brand_name',
    'brand_name',
    'nla_demo_cfg'
);

  5. Setelah menentukan jenis konsep dan mengaitkan kolom dengannya, buat indeks nilai.

    SELECT alloydb_ai_nl.create_value_index('nla_demo_cfg');
SELECT alloydb_ai_nl.refresh_value_index('nla_demo_cfg');

Menentukan template kueri

Anda dapat menentukan template untuk meningkatkan kualitas jawaban yang dihasilkan oleh API bahasa alami AlloyDB AI.

  1. Untuk memberikan contoh template untuk pertanyaan penting bisnis, dan untuk memberikan perkiraan pertanyaan yang diharapkan memiliki akurasi tinggi, jalankan kueri berikut untuk menambahkan template:

    SELECT alloydb_ai_nl.add_template(
    nl_config_id => 'nla_demo_cfg',
    intent => 'List the first names and the last names of all customers who ordered Swimsuit.',
    sql => 'SELECT c.first_name, c.last_name FROM nla_demo.Customers c JOIN nla_demo.orders o ON c.customer_id = o.customer_id JOIN nla_demo.order_items oi ON o.order_id = oi.order_id JOIN nla_demo.products p ON oi.product_id = p.product_id  AND p.name = ''Swimsuit''',
    sql_explanation => 'To answer this question, JOIN `nla_demo.Customers` with `nla_demo.orders` on having the same `customer_id`, and JOIN the result with nla_demo.order_items on having the same `order_id`. Then JOIN the result with `nla_demo.products` on having the same `product_id`, and filter rwos that with p.name = ''Swimsuit''. Return the `first_name` and the `last_name` of the customers with matching records.',
    check_intent => TRUE
);

  2. Untuk melihat daftar template yang ditambahkan, buat kueri alloydb_ai_nl.template_store_view:

    SELECT nl, sql, intent, psql, pintent
FROM alloydb_ai_nl.template_store_view
WHERE config = 'nla_demo_cfg';

    Output berikut akan ditampilkan:

    nl      | List the first names and the last names of all customers who ordered Swimsuit.
sql     | SELECT c.first_name, c.last_name
        | FROM nla_demo.Customers c
        | JOIN nla_demo.orders o ON c.customer_id = o.customer_id
        | JOIN nla_demo.order_items oi ON o.order_id = oi.order_id
        | JOIN nla_demo.products p ON oi.product_id = p.product_id
        | AND p.name = 'Swimsuit'
intent  | List the first names and the last names of all customers who ordered
        | Swimsuit.
psql    | SELECT c.first_name, c.last_name
        | FROM nla_demo.Customers c JOIN nla_demo.orders o
        | ON c.customer_id = o.customer_id 
        | JOIN nla_demo.order_items oi ON o.order_id = oi.order_id
        | JOIN nla_demo.products p ON oi.product_id = p.product_id
        | AND p.name = $1
pintent | List the first names and the last names of all customers who ordered
        | $1.

    Dalam template ini, nilai yang sesuai dengan atribut psql adalah kueri SQL yang diparameterkan, dan nilai untuk kolom pintent adalah pernyataan intent yang diparameterkan. id template yang baru ditambahkan dapat berbeda, berdasarkan template yang ditambahkan sebelumnya. Template digunakan untuk memberikan jawaban yang sangat akurat atas pertanyaan.

Membuat hasil SQL dari pertanyaan bahasa alami

  1. Untuk menggunakan API natural language AlloyDB AI guna menghasilkan kueri SQL dan set hasil, jalankan kueri berikut:

    SELECT
    alloydb_ai_nl.get_sql(
        'nla_demo_cfg',
        'Find the customers who purchased Tote Bag.'
    ) ->> 'sql';

    Output berikut akan ditampilkan:

    SELECT DISTINCT "c"."first_name", "c"."last_name"
FROM "nla_demo"."customers" AS "c"
JOIN "nla_demo"."orders" AS "o" ON "c"."customer_id" = "o"."customer_id"
JOIN "nla_demo"."order_items" AS "oi" ON "o"."order_id" = "oi"."order_id"
JOIN "nla_demo"."products" AS "p" ON "oi"."product_id" = "p"."product_id"
WHERE "p"."name" = 'Tote Bag';

    Output JSON adalah kueri SQL menggunakan template yang Anda tambahkan di Menentukan template kueri.

  2. Untuk menggunakan API natural language AlloyDB AI guna menghasilkan kueri SQL, jalankan kueri berikut:

    SELECT
    alloydb_ai_nl.get_sql(
        'nla_demo_cfg',
        'List the maximum price of any CymbalShoe.'
    ) ->> 'sql';

    Output berikut akan ditampilkan:

    SELECT max("price")
FROM "nla_demo"."order_items" AS t1
JOIN "nla_demo"."products" AS t2 ON t1."product_id" = t2."product_id"
WHERE t2."name" = 'CymbalShoe';

    AlloyDB AI natural language API mengenali bahwa CymbalShoe adalah nama produk, dengan menggunakan indeks nilai. Mengganti CymbalShoe dengan nama merek (CymbalPrime) dalam kueri berikut:

    SELECT
    alloydb_ai_nl.get_sql(
        'nla_demo_cfg',
        'List the maximum price of any CymbalPrime.'
    ) ->> 'sql';

    menghasilkan output berikut:

    SELECT max("price")
FROM "nla_demo"."order_items" AS "oi"
JOIN "nla_demo"."products" AS "p" ON "oi"."product_id" = "p"."product_id"
JOIN "nla_demo"."brands" AS "b" ON "p"."brand_id" = "b"."brand_id"
WHERE "b"."brand_name" = 'CymbalPrime';

    AlloyDB AI menggunakan indeks nilai yang dibuat di Membuat indeks nilai untuk menyelesaikan CymbalPrime ke dalam jenis konsep brand_name, dan menggunakan kolom nla_demo.brands.brand_name yang terkait dengan brand_name.

  3. Untuk menggunakan API natural language AlloyDB AI guna menghasilkan hasil pertanyaan, jalankan kueri berikut:

    SELECT
alloydb_ai_nl.execute_nl_query(
    'Find the last name of the customers who live in Lisbon.',
    'nla_demo_cfg'
);

    Output berikut akan ditampilkan:

    execute_nl_query     
--------------------------
{"last_name":"M."}

Pembersihan

Agar tidak perlu membayar biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus project yang berisi resource tersebut, atau simpan project dan hapus setiap resource.

Bagian berikut menjelaskan cara menghapus resource dan objek ini.

Menghapus cluster

Saat Anda menghapus cluster yang Anda buat di Sebelum memulai, semua objek yang Anda buat juga akan dihapus.

  1. Di konsol Google Cloud , buka halaman Clusters.

    Buka Cluster

  2. Klik nama cluster Anda, my-cluster, di kolom Nama resource.

  3. Klik Hapus cluster.

  4. Di Delete cluster my-cluster, masukkan my-cluster untuk mengonfirmasi bahwa Anda ingin menghapus cluster.

  5. Klik Hapus.

  6. Jika Anda membuat koneksi pribadi saat membuat cluster, buka Google Cloud halaman jaringan VPC konsol dan klik Hapus jaringan VPC.

Menghapus objek

Anda dapat memilih untuk menyimpan resource yang Anda siapkan di bagian Sebelum Anda memulai, dan Anda dapat menghapus hanya objek yang Anda buat di project Google Cloud .

  1. Untuk menghapus template yang Anda tentukan di Tentukan template kueri, jalankan kueri berikut:

    SELECT alloydb_ai_nl.drop_template(id)
FROM alloydb_ai_nl.template_store_view
WHERE config = 'nla_demo_cfg';

  2. Untuk menghapus jenis konsep product_name yang Anda tentukan di Buat indeks nilai, jalankan kueri berikut:

    SELECT alloydb_ai_nl.drop_concept_type('product_name');

  3. Untuk memperbarui indeks nilai setelah Anda menghapus jenis konsep product_name, jalankan kueri berikut:

    SELECT alloydb_ai_nl.refresh_value_index();

  4. Untuk menghapus konfigurasi nla_demo_cfg yang Anda buat di Membuat konfigurasi bahasa alami, jalankan kueri berikut:

    SELECT
alloydb_ai_nl.g_manage_configuration(
    'drop_configuration',
    'nla_demo_cfg'
);

  5. Untuk menghapus skema dan tabel nla_demo yang Anda buat dan isi di Membuat skema dan tabel nla_demo dan Mengisi tabel dalam skema nla_demo, jalankan kueri berikut:

    DROP SCHEMA nla_demo CASCADE;

Langkah berikutnya