Panoramica dei set di contesti

Un set di contesti è una raccolta di informazioni specifiche del database che consente a strumenti come QueryData di generare query con un'elevata precisione. I set di contesto possono includere modelli, aspetti e ricerche di valori che aiutano QueryData a comprendere lo schema del database e la logica di business delle tue applicazioni.

Sono supportati i seguenti database:

  • AlloyDB per PostgreSQL
  • Cloud SQL per MySQL
  • Cloud SQL per PostgreSQL
  • Spanner
  • Firestore con compatibilità MongoDB
  • Bigtable

Cosa sono i set di contesti

Per creare applicazioni agentiche efficaci, strumenti come QueryData devono comprendere l'organizzazione dei dati e la logica di business. Fornisci queste informazioni sotto forma di set di contesto.

Il contesto viene definito in file che contengono oggetti JSON per ogni tipo di contesto. Puoi creare questi file di contesto con l'aiuto dell'agente di progettazione del contesto. Poi, carichi il file di contesto in un set di contesti che crei nella console Google Cloud. Questo processo consente a strumenti come QueryData di apprendere lo schema specifico del database e la logica di business dell'applicazione.

Il file di contesto è simile al seguente:

{
  "templates": [
    {
      "nl_query": "Count Prague loan accounts",
      "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'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_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\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

Formato file del set di contesti

Un file del set di contesti è costituito da un insieme selezionato di modelli, facet e ricerche di valori in formato JSON che guidano strumenti come QueryData nella traduzione di domande in linguaggio naturale in query per un database specifico. La definizione del contesto garantisce una generazione SQL ad alta precisione per i pattern di query comuni.

Per massimizzare l'accuratezza, assicurati che il set di contesto sia accurato e completo nella copertura delle query previste per l'applicazione.

I set di contesto possono essere creati nelle regioni us-central1, us-east1, europe-west4 e asia-southeast1. Devi selezionare una regione quando crei il primo set di contesti in un progetto. I set di contesto successivi utilizzano la stessa regione.

Modelli di query

I template di query sono un insieme selezionato di domande rappresentative in linguaggio naturale con query SQL corrispondenti. Includono anche spiegazioni per fornire una logica dichiarativa per la generazione da linguaggio naturale a SQL.

Un oggetto modello di query è simile al seguente:

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "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'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_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\" = $1"
      }
    }
  ],
  ...
}

I componenti principali dell'oggetto JSON del modello di query sono i seguenti:

  • nl_query: un esempio di query in linguaggio naturale gestita da strumenti come QueryData.
  • sql: la query SQL per la query in linguaggio naturale.
  • intent: l'obiettivo o lo scopo della query in linguaggio naturale. Se non viene impostato, questo valore viene impostato per impostazione predefinita sulla query in linguaggio naturale.
  • manifest: una forma generalizzata e generata automaticamente dell'intent.
  • parameterized_intent: una forma basata su modelli e generata automaticamente dell'intent, con i valori delle entità sostituiti dai parametri.
  • parameterized_sql: un modulo basato su modelli e generato automaticamente della query SQL che corrisponde all'intent con parametri.

Facet di query

I facet di query sono un insieme selezionato di condizioni rappresentative in linguaggio naturale con predicati SQL corrispondenti. I facet gestiscono i filtri e le condizioni, consentendo ai modelli di query di eseguire ricerche per facet.

Un oggetto facet di query è simile al seguente:

{
...
"facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

I componenti principali dell'oggetto JSON dei facet sono i seguenti:

  • sql_snippet: uno snippet SQL. Per evitare ambiguità, qualifica i nomi delle colonne con i nomi delle tabelle (ad esempio, table_name.column_name).
  • intent: una spiegazione del predicato SQL.
  • manifest: una forma generalizzata e generata automaticamente dell'intent.
  • parameterized_intent: una forma basata su modelli e generata automaticamente dell'intent, con i valori delle entità sostituiti dai parametri.
  • parameterized_sql_snippet: un modulo basato su modelli e generato automaticamente dello snippet sql_snippet che corrisponde all'intent parametrizzato.

Query di ricerca di valore

Query di ricerca dei valori sono query definite dallo sviluppatore che utilizzano funzioni di corrispondenza per trovare i valori e il relativo contesto all'interno di un database. Il collegamento dei valori utilizza i risultati di queste query per identificare quali tabelle e colonne contengono un valore corrispondente, comprendere il tipo di concetto del valore e correggere gli errori ortografici.

L'API QueryData utilizza il collegamento dei valori per convertire in modo più accurato il linguaggio naturale in SQL. Utilizzando le query di ricerca dei valori, l'API può correggere gli errori ortografici e risolvere i tipi di valori in base ai valori del database, migliorando così l'accuratezza della conversione.

Il collegamento dei valori migliora l'accuratezza della conversione da linguaggio naturale a SQL. Ad esempio, se un utente chiede "Ci sono voli in partenza da Heathrow?", il database potrebbe memorizzare il nome dell'aeroporto come "Londra Heathrow". Senza il collegamento dei valori, l'SQL generato potrebbe filtrare per WHERE name = 'Heathrow' e non restituire risultati. Le query di ricerca dei valori guidano l'agente nella mappatura di "Heathrow" al valore corretto del database "London Heathrow" e alla sua posizione nello schema (airports.name), garantendo l'accuratezza dell'SQL generato.

Un esempio di query di ricerca per valore è:

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    },
    {
      "query": "WITH SemanticMetrics AS ( SELECT T.\"city\" AS original_value, ( (google_ml.embedding('gemini-embedding-001', $value)::vector <=> google_ml.embedding('gemini-embedding-001', T.\"city\")::vector) / 2.0 ) AS normalized_dist FROM \"airports\" T WHERE T.\"city\" IS NOT NULL ) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM SemanticMetrics",
      "concept_type": "Airport City",
      "description": "Semantic search on string values for airport city names"
    }
  ]
}

I componenti principali dell'oggetto JSON di ricerca dei valori sono i seguenti:

  • query: un'istruzione SQL con parametri che definisce la logica per la corrispondenza di una frase di valore con i valori archiviati in un database. Il set di risultati in genere proietta il valore corrispondente, la posizione dello schema, il tipo di concetto e una metrica di distanza normalizzata (tra 0 e 1).
  • concept_type: un'etichetta semantica assegnata al valore, ad esempio district o loan_status. Questa etichetta aiuta a collegare i valori e, in ultima analisi, gli strumenti come l'API QueryData a comprendere il ruolo della frase del valore nello schema. Inoltre, aiuta a produrre un'istruzione SQL che ha come target il concetto del valore, nonché la tabella e la colonna in cui viene visualizzata la frase del valore.
  • description: : una descrizione della logica di ricerca.

Limitazioni

I set di contesto presentano le seguenti limitazioni:

  • I set di contesto per i database supportano solo modelli, facet e ricerche di valori.
  • I set di contesto per i database vengono utilizzati solo dall'endpoint QueryData nell'API Conversational Analytics.

Passaggi successivi