Usar a linguagem natural da IA do AlloyDB para gerar SQL

Criar o esquema e as tabelas nla_demo

Nas etapas a seguir, você vai criar o esquema nla_demo e as tabelas no esquema. Você preenche as tabelas com dados sintéticos. O esquema e os dados fornecidos foram projetados para oferecer suporte às operações fundamentais de uma empresa de varejo on-line, com possíveis aplicações que se estendem ao gerenciamento de clientes, análises, marketing e aspectos operacionais.

Os dados de exemplo mostram como usar a linguagem natural da IA do AlloyDB para desenvolvimento, testes e demonstração, principalmente para recursos como interfaces de linguagem natural.

1. Crie o esquema executando a consulta a seguir:

   CREATE SCHEMA nla_demo;
   

2. Crie tabelas no esquema nla_demo. A tabela addresses armazena as informações de endereço dos clientes e dos pedidos.

   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. Crie a tabela customers executando a consulta a seguir. Essa tabela armazena informações do cliente, incluindo o ID, o nome, os detalhes de contato, a referência de endereço, a data de nascimento e a hora de criação do registro.

   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. Crie a tabela categories, que armazena categorias de produtos.

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

5. Crie a tabela products. Essa tabela armazena informações do produto, como ID, nome, descrição, marca, vinculação de categoria e hora de criação do registro.

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

6. Crie a tabela orders. Essa tabela armazena informações sobre os pedidos do cliente, incluindo o cliente, a data, o valor total, os endereços de frete e de faturamento e o status do pedido.

   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)
   );
   

7. Crie a tabela order_items. Essa tabela registra itens individuais em um pedido, vincula-se ao pedido e à variante do produto e especifica a quantidade e o preço.

   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
   );
   

Preencher tabelas no esquema nla_demo

1. Preencha a tabela addresses executando a consulta a seguir:

   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. Preencha a tabela 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. Preencha a tabela categories.

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

4. Preencha a tabela 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. Preencha a tabela 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');
   

6. Preencha a tabela 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);
   

Criar uma configuração de linguagem natural

Para usar a linguagem natural da IA do AlloyDB, verifique se o endpoint da Vertex AI está configurado. Em seguida, crie uma configuração e registre um esquema. g_alloydb_ai_nl.g_create_configuration cria o modelo.

1. Crie uma configuração de linguagem natural.

   SELECT alloydb_ai_nl.g_create_configuration( 'nla_demo_cfg' );
   

2. Registre tabelas na configuração 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.products, nla_demo.categories, nla_demo.orders, nla_demo.order_items}'
   );
   

Criar e aplicar contexto a tabelas e colunas

Para fornecer respostas precisas a perguntas em linguagem natural, use a API de linguagem natural da AlloyDB para fornecer contexto sobre tabelas, visualizações e colunas. É possível usar o recurso de geração de contexto automatizado da API de linguagem natural da IA do AlloyDB para produzir contexto de tabelas e colunas e aplicar o contexto como COMMENTS anexado a tabelas, visualizações e colunas.

1. Para gerar contextos de esquema para as tabelas e as colunas registradas na configuração nla_demo_cfg, execute o seguinte:

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

   A consulta anterior preenche a visualização alloydb_ai_nl.generated_schema_context_view com contexto. A transmissão de TRUE substitui o contexto nessa visualização de execuções anteriores.

2. Para verificar o contexto gerado para a tabela nla_demo.products, execute a seguinte consulta:

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

   O contexto resultante é semelhante ao seguinte:

   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. Para verificar o contexto produzido para uma coluna, como nla_demo.products.name, execute o seguinte:

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

   A saída da consulta é semelhante a esta:

   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. Analise o contexto gerado na visualização alloydb_ai_nl.generated_schema_context_view e atualize o contexto que precisa de revisão.

   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. Aplique o contexto gerado que será anexado aos objetos correspondentes:

   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
   );
   

   As entradas de contexto resultantes na visualização alloydb_ai_nl.generated_schema_context_view são aplicadas aos objetos de esquema correspondentes, e os comentários são substituídos.

Construir o índice de valor

A API de linguagem natural da IA do AlloyDB produz consultas SQL precisas usando a vinculação de valores. A vinculação de valores associa frases de valor em frases em linguagem natural a tipos de conceito e nomes de colunas pré-registrados, que podem enriquecer a pergunta em linguagem natural.

Por exemplo, a pergunta "Informe o preço de um moletom" pode ser respondida com mais precisão se Hoodie estiver associado a um conceito product_name, que está associado ao nla_demo.products.name. coluna.

1. Para definir o tipo de conceito product_name e associá-lo à coluna nla_demo.products.name, execute as seguintes consultas:

   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'
   );
   

2. Para verificar se o tipo de conceito product_name foi adicionado à lista de tipos de conceito, execute a consulta a seguir para garantir que product_name seja incluído no resultado dessa consulta:

   SELECT alloydb_ai_nl.list_concept_types();
   

3. Para verificar se a coluna nla_demo.products.name está associada ao tipo de conceito product_name, execute a consulta a seguir:

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

4. Depois de definir os tipos de conceito e associar colunas a eles, crie um índice de valor.

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

Definir um modelo de consulta

É possível definir modelos para melhorar a qualidade das respostas produzidas pela API de linguagem natural da AlloyDB AI.

1. Para fornecer modelos de exemplo para perguntas essenciais para os negócios e para fornecer perguntas antecipadas com alta precisão, execute a consulta a seguir para adicionar um modelo:

   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. Para conferir a lista de modelos adicionados, consulte o alloydb_ai_nl.template_store_view:

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

   Você verá a seguinte resposta:

   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.
   

   Nesse modelo, o valor correspondente ao atributo psql é a consulta SQL parametrizada, e o valor da coluna pintent é a instrução de intent parametrizada. O id de um modelo adicionado recentemente pode ser diferente, com base nos modelos adicionados anteriormente. Os modelos são usados para fornecer respostas altamente precisas às perguntas.

Gerar resultados SQL com base em perguntas em linguagem natural

1. Para usar a API de linguagem natural da IA do AlloyDB para produzir consultas SQL e conjuntos de resultados, execute a seguinte consulta:

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

   Você verá a seguinte resposta:

   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';
   

   A saída JSON é uma consulta SQL que usa o modelo adicionado em Definir um modelo de consulta.

2. Para usar a API de linguagem natural da AlloyDB AI para produzir o resultado de uma pergunta, execute a seguinte consulta:

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

   Você verá a seguinte resposta:

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