Questa pagina documenta la versione 18.3.0 di AlloyDB Omni che utilizza l'opzione di deployment RPM. Scegli un'altra opzione di deployment.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Generare query SQL dal linguaggio naturale

Seleziona una versione della documentazione:

Puoi configurare, impostare e generare istruzioni SQL utilizzando il linguaggio naturale di AlloyDB AI, che ti consente di creare applicazioni di AI generativa rivolte agli utenti utilizzando il linguaggio naturale per eseguire query sui database.

Per abilitare l'estensione alloydb_ai_nl, ovvero l'API di supporto del linguaggio naturale di AlloyDB Omni, segui questi passaggi di alto livello:

Installa l'estensione alloydb_ai_nl.
Definisci una configurazione in linguaggio naturale per la tua applicazione.
Registra uno schema.
Aggiungi contesto.
Aggiungi modelli di query.
Definisci i tipi di concetti e crea un indice dei valori.
Genera istruzioni SQL utilizzando un'interfaccia in linguaggio naturale.

Prima di iniziare

Scopri come installare e connetterti al database AlloyDB Omni ed eseguire i comandi PostgreSQL. Per saperne di più, consulta Installare AlloyDB Omni ed Eseguire la connessione ad AlloyDB Omni.
Popola il database con i dati e lo schema a cui l'utente finale vuole accedere.

Attiva l'estensione richiesta

Prima di installare e utilizzare il linguaggio naturale di AlloyDB AI, attiva l'estensione eseguendo il seguente comando PostgreSQL nel file postgresql.conf:

ALTER SYSTEM SET alloydb_ai_nl.enabled=on;
SELECT pg_reload_conf();

Installa AlloyDB Omni e AlloyDB AI

Installa AlloyDB Omni. Utilizzi l'istanza AlloyDB per PostgreSQL per creare il database dell'applicazione e lo schema.
Installa AlloyDB AI in AlloyDB Omni.

Ruoli obbligatori

Per installare l'estensione alloydb_ai_nl e concedere l'accesso ad altri utenti, devi disporre di un ruolo di superuser. L'utente postgres predefinito ha un ruolo di super utente. Per saperne di più, consulta la panoramica dei ruoli utente di AlloyDB Omni.

prepara l'ambiente

Per prepararti a generare query in linguaggio naturale, devi installare l'estensione richiesta, creare una configurazione e registrare uno schema.

Installa l'estensione alloydb_ai_nl

L'estensione alloydb_ai_nl utilizza l'estensione google_ml_integration, che interagisce con modelli linguistici di grandi dimensioni (LLM), inclusi i modelli Gemini su Vertex AI.

Per installare l'estensione alloydb_ai_nl:

Abilita AlloyDB AI su AlloyDB Omni.
Connettiti al database AlloyDB Omni ed esegui il seguente comando:

CREATE EXTENSION alloydb_ai_nl cascade;

Esegui l'upgrade dell'estensione alloydb_ai_nl

Assicurati di avere l'ultima versione dell'estensione alloydb_ai_nl. Se hai già installato l'estensione, controlla se è disponibile una nuova versione ed esegui l'upgrade se non utilizzi l'ultima versione.

Determina se devi eseguire l'upgrade dell'estensione. Se la default_version è successiva alla installed_version, esegui l'upgrade dell'estensione.
```
SELECT * FROM pg_available_extensions where name = 'alloydb_ai_nl';
```
Esegui l'upgrade dell'estensione.
```
ALTER EXTENSION alloydb_ai_nl UPDATE;
```

Crea una configurazione in linguaggio naturale e registra uno schema

Il linguaggio naturale di AlloyDB AI utilizza nl_config per associare le applicazioni a determinati schemi, modelli di query ed endpoint del modello. nl_config è una configurazione che associa un'applicazione a uno schema, a modelli e ad altri contesti.

Un'applicazione di grandi dimensioni può anche utilizzare configurazioni diverse per parti diverse dell'applicazione, a condizione che tu specifichi la configurazione corretta quando viene inviata una domanda da quella parte dell'applicazione. Puoi registrare un intero schema o oggetti di schema specifici, come tabelle, viste e colonne.

Crea una configurazione in linguaggio naturale utilizzando il seguente esempio:
```
SELECT
  alloydb_ai_nl.g_create_configuration(
    'my_app_config'        -- configuration_id
  );
```
gemini-2.0-flash:generateContent è l'endpoint del modello.

Registra uno schema per una configurazione specificata utilizzando il seguente esempio.

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

Aggiungi contesto

Contesto include qualsiasi tipo di informazione che puoi utilizzare per rispondere a una domanda dell'utente finale, ad esempio:

Struttura e relazioni dello schema
Riepiloghi e descrizioni delle colonne
Valori delle colonne e relativa semantica
Regole o istruzioni di logica di business specifiche per l'applicazione o il dominio

Aggiungi un contesto generale per le regole specifiche dell'applicazione

Gli elementi di contesto generali includono regole specifiche dell'applicazione, istruzioni di logica di business o qualsiasi terminologia specifica dell'applicazione e del dominio che non è collegata a un oggetto schema specifico.
Per aggiungere un contesto generale per le regole specifiche dell'applicazione e la terminologia specifica dell'applicazione o del dominio, segui questi passaggi:

Aggiungi un elemento di contesto generale per la configurazione specificata utilizzando la seguente query di esempio:
```
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."}'
  );
```
L'istruzione precedente aiuta il linguaggio naturale di AlloyDB AI a fornire risposte di qualità superiore alle domande in linguaggio naturale degli utenti.
Visualizza i contesti generali per la configurazione specificata.
```
SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);
```

Generare e rivedere il contesto dello schema

Il contesto dello schema descrive gli oggetti dello schema, tra cui tabelle, viste, viste materializzate e colonne. Questo contesto viene archiviato come COMMENT di ogni oggetto schema.

Per generare contesti per gli oggetti schema, chiama le seguenti API. Per ottenere risultati ottimali, assicurati che le tabelle del database contengano dati rappresentativi.

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

Esamina i contesti dello schema generati.
```
SELECT schema_object, object_context
FROM alloydb_ai_nl.generated_schema_context_view;
```
I contesti dello schema generati vengono archiviati nella visualizzazione precedente.

(Facoltativo) Aggiorna i contesti dello schema generati.

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

Applica il contesto. Quando applichi il contesto, questo ha effetto immediato e viene eliminato dalla visualizzazione 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
  );

(Facoltativo) Verifica il contesto generato. La seguente API consente di controllare i contesti dello schema, che vengono utilizzati durante la generazione delle istruzioni 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'
  );

Applica il contesto dello schema generato.
```
SELECT alloydb_ai_nl.apply_generated_schema_context(
  'nla_demo_cfg',
  TRUE);
```
Il passaggio di TRUE sovrascrive il contesto esistente per gli oggetti registrati in "nla_demo_cfg".

(Facoltativo) Imposta manualmente il contesto dello schema.


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

Crea modelli di query

Per migliorare la qualità delle applicazioni di AI generativa create con gli LLM, puoi aggiungere modelli. Un modello di query è un insieme curato di domande rappresentative o comuni in linguaggio naturale, con le query SQL corrispondenti, nonché spiegazioni per fornire una motivazione dichiarativa per la generazione di linguaggio naturale in SQL (NL2SQL).

I modelli sono destinati principalmente a essere specificati dall'applicazione, ma possono anche essere generati automaticamente dall'estensione alloydb_ai_nl in base alle query SQL utilizzate di frequente. Ogni modello deve essere associato a un nl_config.

L'estensione alloydb_ai_nl utilizza un template_store per incorporare dinamicamente modelli SQL pertinenti nel processo di generazione di un'istruzione SQL per rispondere alla domanda dell'utente finale. template_store esegue le seguenti operazioni:

Identifica i modelli con intenzioni simili alla domanda in linguaggio naturale posta dall'utente finale.
Identifica l'istruzione SQL parametrizzata corrispondente.
Sintetizza un'istruzione SQL istanziando i parametri con i valori della domanda in linguaggio naturale.

Se non esiste un modello con lo stesso intento della domanda posta dall'utente finale, alloydb_ai_nl utilizza ogni modello e contesto pertinente per comporre un'istruzione SQL.

Aggiungi un modello allo Store dei modelli

Aggiungi i modelli specificando la domanda, utilizzando un parametro denominato intent, e la query SQL.

Per aggiungere un template all'archivio dei template, esegui questa query:

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

Quando check_intent è TRUE, alloydb_ai_nl esegue un controllo semantico per confermare che l'intent fornito corrisponda all'istruzione SQL passata. Se l'intent non corrisponde all'istruzione SQL, il modello non viene aggiunto.

L'SQL e l'intent sono parametrizzati da alloydb_ai_nl. La vista alloydb_ai_nl.template_store_view espone le istruzioni SQL parametrizzate e i relativi intenti.

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

Questa istruzione restituisce quanto segue:

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
  ```

### Provide a customized parameterization {:#custom-parameterization}

To provide a customized parameterization for a SQL statement using the manual
interface of the `add_template` function, run the statement in the following
example:

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

Nella definizione precedente viene fornita la parametrizzazione dell'istruzione SQL. I parametri sono $1 e $2, rispettivamente, per Slokolov e 1950. Un manifest viene fornito come versione generalizzata dell'intent, in cui i valori dei valori letterali vengono sostituiti con descrizioni generiche dei valori.

In questo esempio, il valore di 1950 nell'intent viene sostituito con a given date e il valore di Slokolov viene sostituito nel manifest con a given city. Quando viene fornito un valore TRUE per l'argomento facoltativo check_intent, viene eseguita una verifica dell'intent basata su LLM durante add_template. Durante questo controllo, quando l'istruzione SQL fornita non acquisisce lo scopo e l'obiettivo dell'istruzione di intent fornita, add_template non riesce e il motivo viene fornito come output.

Nell'esempio seguente, lo scopo del template, come indicato nell'intent, è recuperare l'ID account degli account associati al carico e che si trovano in una regione. L'istruzione SQL fornita restituisce il numero di account, anziché l'elenco di ID account, come mostrato nell'esempio seguente.

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

Quando check_intent è impostato su TRUE, non puoi aggiungere il modello precedente allo store dei modelli. Se esegui l'istruzione precedente, viene restituito un errore simile al seguente:

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.

Gestisci modelli

Puoi gestire i modelli nello Store dei modelli utilizzando le seguenti API:

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

Quando crei un modello, questo viene attivato per impostazione predefinita. Un template disabilitato rimane nello store dei template, ma non viene utilizzato da alloydb_ai_nl per la sintesi delle query. Puoi attivare un modello disattivato utilizzando alloydb_ai_nl.enable_template. L'esecuzione di alloydb_ai_nl.drop_template rimuove definitivamente il modello dal negozio di modelli.

Puoi utilizzare alloydb_ai_nl.template_store_view per estrarre il template_id di un template, in base ai suoi contenuti. Ad esempio, per trovare l'identificatore dei template con l'intent accounts that associated with loans, esegui la seguente query, che restituisce un identificatore del template e indica se il template è abilitato da alloydb_ai_nl.template_store_view:

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

Aggiorna un template

Quando utilizzi i modelli in alloydb_ai_nl.template_store_view, assicurati che l'intent di ogni modello sia coerente con quanto segue:

L'istruzione SQL
L'istruzione SQL con parametri
L'intent parametrizzato
Il manifest del modello

alloydb_ai_nl può recuperare i modelli pertinenti se l'incorporamento mantenuto per i modelli corrisponde ai contenuti dei modelli.

Per aggiornare un modello:

Identifica il template_id utilizzando alloydb_ai_nl.template_store_view.
Rimuovi il modello.
Ridefinisci il nuovo template con la modifica richiesta utilizzando la funzione alloydb_ai_nl.add_template.

Creare frammenti di query

Puoi specializzare i template al momento della query utilizzando i frammenti, che aiutano i template di query a eseguire ricerche con faccette come le domande in linguaggio naturale. Un frammento è un insieme selezionato di condizioni rappresentative o comuni in linguaggio naturale con i corrispondenti predicati SQL. I frammenti devono essere specificati dall'applicazione.

Ogni frammento deve essere associato a un nl_config_id e a un array di tabelle e viste con alias a cui si applica il predicato del frammento. Puoi verificare lo scopo di un frammento quando l'argomento check_intent è impostato su TRUE. L'estensione alloydb_ai_nl può utilizzare un modello con una combinazione di frammenti per sintetizzare la risposta a una query in linguaggio naturale.

L'estensione alloydb_ai_nl utilizza fragment_store per incorporare dinamicamente le condizioni in frammenti pertinenti nel processo di generazione di un'istruzione SQL per rispondere alla domanda dell'utente finale. Innanzitutto, template_store identifica i template con intenti simili alla domanda in linguaggio naturale posta dall'utente finale. Successivamente, vengono recuperati i frammenti che possono fornire specializzazione ai modelli identificati. La sostituzione dei parametri viene applicata sia ai template che ai frammenti per sintetizzare un'istruzione SQL.

I valori dei parametri vengono estratti dalla domanda in linguaggio naturale e vengono sostituiti dall'LLM utilizzando i pattern impliciti dei modelli e dei frammenti pertinenti. Tuttavia, se la combinazione di template e frammenti non ha lo stesso scopo della domanda posta dall'utente finale, alloydb_ai_nl utilizza ogni template e contesto pertinente per comporre un'istruzione SQL.

Aggiungere un frammento

Per aggiungere un frammento, esegui le seguenti query di esempio utilizzando la funzione alloydb_ai_nl.add_fragment. Ogni frammento deve essere associato a un identificatore nl_config_id dell'applicazione.

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

Quando viene eseguito alloydb_ai_nl.add_fragment, l'estensione alloydb_ai_nl estrae un manifest dall'intent fornito e parametrizza l'intent e la condizione per il frammento, se possibile. I frammenti disponibili vengono esposti da visualizzazioni come alloydb_ai_nl.fragment_store_view, come mostrato nell'esempio seguente:

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

La query restituisce un set di risultati simile al seguente:

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

Un manifest in un fragment viene generato automaticamente dall'intent e rappresenta una versione generalizzata dell'intent. Ad esempio, i numeri 6000 e 10000 nell'intent vengono sostituiti da a given number nel manifest. I numeri vengono sostituiti rispettivamente con $2 e $1 nelle colonne pfragment e pintent. Le colonne pfragment e pintent in alloydb_ai_nl.fragment_store_view sono, rispettivamente, la rappresentazione parametrizzata di fragment e intent.

Per fornire una parametrizzazione personalizzata di un frammento, utilizza la versione manuale di alloydb_ai_nl.add_fragment, come mostrato nell'esempio seguente:

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

Gestisci i frammenti

Per gestire i frammenti, utilizza le seguenti API:

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

Puoi utilizzare la vista alloydb_ai_nl.fragment_store_view per estrarre il fragment_id di un frammento, in base ai suoi contenuti. Ad esempio, per trovare l'identificatore di un frammento con l'intent Average salary between 6000 and 10000, esegui la seguente query di esempio:

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

Aggiorna un frammento

Quando aggiorni un fragment, assicurati che l'intent del fragment sia coerente con quanto segue:

Il manifest del frammento e l'istruzione SQL
L'istruzione SQL con parametri
L'intent con parametri

Per garantire la coerenza quando aggiorni un frammento, segui questi passaggi:

Rimuovi il frammento che vuoi modificare utilizzando la funzione alloydb_ai_nl.drop_fragment.
Inserisci il frammento aggiornato utilizzando la funzione alloydb_ai_nl.add_fragment.

Genera automaticamente i modelli

Una volta ottenuto un set di dati rappresentativo nelle tabelle, ti consigliamo di eseguire query SQL corrispondenti alle domande comuni che gli utenti finali potrebbero porre. Assicurati che le query abbiano piani di query completi e che le prestazioni siano buone.

Dopo aver eseguito le query, il linguaggio naturale di AlloyDB AI può generare automaticamente modelli in base alla cronologia delle query. Puoi chiamare le seguenti API per generare modelli. Devi esaminare e applicare i modelli generati prima che diventino effettivi.

La generazione automatica dei modelli si basa sulle query più utilizzate nel log delle query, google_db_advisor_workload_statements. Le query vengono filtrate in base ai seguenti criteri:

SELECT istruzioni
Eseguibili: la query può essere elaborata correttamente dal comando EXPLAIN.
Nessuna duplicazione: la query non è stata utilizzata in precedenza per generare modelli.
Tutte le tabelle e le viste a cui viene fatto riferimento rientrano nell'ambito di nl_config.

Per generare automaticamente, esaminare e applicare i modelli, segui questi passaggi:

Richiedi ad AlloyDB per PostgreSQL di generare modelli in base alla cronologia delle query:
```
SELECT
  alloydb_ai_nl.generate_templates(
    'my_app_config',
);
```
Utilizza la visualizzazione fornita, alloydb_ai_nl.generated_templates_view, per esaminare il generated_templates. L'output seguente mostra il numero di template generati:
```
-[ RECORD 1 ]------+--
generate_templates | 1
```

Esamina i modelli generati utilizzando la visualizzazione generated_templates_view.

SELECT *
FROM alloydb_ai_nl.generated_templates_view;

Di seguito è riportato un esempio dell'output restituito:

-[ 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 nell'output restituito è un modello generale o una descrizione generale del tipo di domanda o dell'operazione che può essere eseguita. pintent è una versione parametrizzata di intent e generalizza intent sostituendo il valore specifico (1997) con un segnaposto ($1).

Per aggiornare un modello generato, esegui la seguente istruzione di esempio:

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

);

Applica i modelli. I modelli che applichi vengono aggiunti immediatamente allo store di modelli e vengono eliminati dalla visualizzazione di revisione.
```
-- For all templates generated under the nl config.
SELECT
  alloydb_ai_nl.apply_generated_templates('my_app_config');
```

Configura la sicurezza per il linguaggio naturale

Per configurare la sicurezza per il linguaggio naturale di AlloyDB AI, consulta Gestisci la sicurezza delle applicazioni di dati utilizzando viste sicure parametrizzate

Definisci i tipi di concetti e gli indici di valore

Definisci i tipi di concetti e gli indici di valori per fornire una comprensione più approfondita delle domande poste. Un tipo di concetto è una categoria o una classe di entità che identifica il significato semantico di parole e frasi, anziché solo la loro forma letterale.

Ad esempio, due nomi di paesi potrebbero essere uguali anche se uno è in maiuscolo, ad esempio USA, e l'altro è in minuscolo, ad esempio usa. In questo caso, il nome del paese è il tipo di concetto. Altri esempi di tipi di concetti includono nome della persona, nome della città e data.

Un indice di valori è un indice dei valori nelle colonne che fanno parte della configurazione in linguaggio naturale nl_config, basato sui tipi di concetti associati a ogni colonna. Un indice di valori consente di trovare in modo efficiente le corrispondenze tra le frasi di valore per la domanda posta e i valori nel database.

Per definire i tipi di concetti e un indice dei valori, segui questi passaggi utilizzando gli esempi forniti. Gli esempi associano una colonna a un tipo di concetto, creano e aggiornano un indice di valori e utilizzano un insieme di sinonimi per eseguire una ricerca di valori.

Associa una colonna a un tipo di concetto.

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

Crea un indice di valori basato su tutte le colonne che fanno parte di una configurazione in linguaggio naturale e che sono associate a un tipo di concetto.
```
SELECT
  alloydb_ai_nl.create_value_index(
    nl_config_id_in => 'my_app_config'
  );
  ```
```

Quando associ i tipi di concetti a nuove colonne, aggiorna l'indice di valori per riflettere le modifiche.

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

Abilita il linguaggio naturale di AlloyDB AI per trovare i sinonimi di un valore.
```
SELECT
  alloydb_ai_nl.insert_synonym_set(
    ARRAY [
      'USA',
      'US',
      'United States',
      'United States of America'
    ]
  );
```
Anche se i dati nelle tabelle potrebbero utilizzare un valore specifico, ad esempio se United States viene utilizzato per identificare un paese, puoi definire un insieme di sinonimi che contiene tutti i sinonimi di United States. Se uno dei sinonimi viene visualizzato nella domanda in linguaggio naturale, il linguaggio naturale di AlloyDB AI associa i sinonimi ai valori nelle tabelle.
Esegui una ricerca di valori per trovare i valori corretti del database, dato un array di frasi di valore.
```
SELECT
  alloydb_ai_nl.get_concept_and_value(
    value_phrases_in => ARRAY['United States'],
    nl_config_id_in  => 'my_app_config'
  );
```
Ad esempio, se un utente pone una domanda come "Qual è la popolazione degli Stati Uniti?" che utilizza la seguente query get_sql, l'AI di AlloyDB in linguaggio naturale utilizza la funzione get_concept_and_value con la frase di valore United States per eseguire una ricerca fuzzy negli indici dei valori. Una ricerca approssimativa è una tecnica di ricerca che trova corrispondenze anche quando la query di ricerca non corrisponde esattamente ai dati corrispondenti.

Il linguaggio naturale trova un risultato, il valore USA, che è vicino alla query di ricerca e lo utilizza per generare la query 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';
```

Tipi di concetti integrati definiti dal linguaggio naturale di AlloyDB AI

I tipi di concetti integrati definiti dal linguaggio naturale di AlloyDB AI sono elencati nella tabella seguente.

Nome del concetto	Descrizione
`generic_entity_name`	È possibile utilizzare una singola colonna di tipo stringa per un nome di entità generico. Ad esempio: SELECT alloydb_ai_nl.associate_concept_type('public.item.item_name', 'generic_entity_name')
`country_name, city_name, region_name`	Nomi di paesi, città e regioni. L'utilizzo è esattamente lo stesso del tipo di concetto `generic_entity_name`.
`full_person_name`	Il nome della persona, composto da nome, cognome e secondo nome. Per il nome completo di una persona è possibile utilizzare fino a tre colonne di tipo stringa. È possibile saltare una qualsiasi delle colonne durante l'associazione delle colonne dei nomi al `full_person_name`. Ad esempio: SELECT alloydb_ai_nl.associate_concept_type('public.person.last_name,public.person.first_name,public.person.middle_name','full_person_name')
`ssn`	Una singola colonna di stringhe contenente un codice fiscale. Ad esempio: SELECT alloydb_ai_nl.associate_concept_type('public.person.ssn','ssn')
`date`	Una data o un timestamp. Ad esempio: SELECT alloydb_ai_nl.associate_concept_type('public.person.date_col','date')

Genera automaticamente le associazioni dei tipi di concetto

Per associare automaticamente le colonne ai tipi di concetti, utilizza la funzionalità di associazione automatica dei tipi di concetti dell'API di linguaggio naturale di AlloyDB AI. Un'associazione di tipi di concetti definisce la relazione tra un tipo di concetto e una o più colonne del database, che è un prerequisito per la creazione di indici di valori.

Per generare automaticamente le associazioni di tipi di concetti:

Per generare le associazioni, chiama le seguenti API.

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

Rivedi le associazioni generate.

SELECT * FROM alloydb_ai_nl.generated_value_index_columns_view;

(Facoltativo) Aggiorna le associazioni generate.

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

(Facoltativo) Rimuovi un'associazione generata.

SELECT alloydb_ai_nl.drop_generated_concept_type_association(id => 1);

Applica le associazioni generate.

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

Aggiorna l'indice di valori per riflettere le modifiche.

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

Generare istruzioni SQL da input in linguaggio naturale

Puoi utilizzare il linguaggio naturale di AlloyDB AI per generare istruzioni SQL dagli input in linguaggio naturale. Quando esegui l'istruzione SQL generata, vengono forniti i dati del database necessari per rispondere alla domanda in linguaggio naturale.

Per utilizzare il linguaggio naturale per ottenere risultati dal database utilizzando la funzione alloydb_ai_nl.get_sql, utilizza l'esempio seguente:

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

  The following JSON output is returned:

  ```Json
  {
  "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?"
  }
  ```

(Facoltativo) Per estrarre la query SQL generata come stringa di testo, aggiungi ->>'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';
```
L'operatore ->> viene utilizzato per estrarre un valore JSON come testo. La funzione alloydb_ai_nl.get_sql restituisce un oggetto JSON, ovvero la parte dell'istruzione che recupera il valore associato alla chiave sql. Questo valore è la query SQL generata.

Genera riepiloghi dei risultati da input in linguaggio naturale

Puoi utilizzare il linguaggio naturale di AlloyDB AI per generare riepiloghi dei risultati da input in linguaggio naturale. La funzione alloydb_ai_nl.get_sql_summary esegue in modo sicuro la domanda in linguaggio naturale sulla tabella sottostante, riassume un campione del set di risultati e restituisce il riepilogo in linguaggio naturale.

Per generare un riepilogo dei risultati per una domanda in linguaggio naturale nel tuo database, utilizza la funzione alloydb_ai_nl.get_sql_summary come mostrato nell'esempio seguente:

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

La chiamata all'istruzione precedente produce il seguente oggetto JSON di esempio:

{
  "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."
}

Puoi proteggere le tabelle e le viste a cui accede una query in alloydb_ai_nl.get_sql_summary utilizzando una o più viste sicure parametrizzate. I nomi dei parametri e i relativi valori sono disponibili per un'applicazione e sono richiesti da alloydb_ai_nl.get_sql_summary.

Ad esempio, l'applicazione potrebbe voler fornire il parametro user_id per un utente autenticato con un ID utente 123. A questo scopo, fornisci gli input param_names e param_values, come mostrato nell'esempio seguente:

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

Fornendo gli argomenti param_names e param_values, ti assicuri che, quando la nl_question può essere risolta da un'istruzione SQL applicata da viste sicure con parametri, i filtri di sicurezza designati vengano applicati quando viene prodotto il set di risultati e viene generato il riepilogo.

Testa e perfeziona

Per ottenere query generate automaticamente migliori, modifica o aggiungi un contesto migliore, modelli di query e indici di valori, quindi ripeti l'operazione fino a ottenere i risultati desiderati.