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": "List all luxury hotels",
      "sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = 'Luxury' ORDER BY _key ASC",
      "intent": "hotels in Luxury tier",
      "manifest": "hotels in a given product tier",
      "parameterized": {
        "parameterized_intent": "hotels in ? tier",
        "parameterized_sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = ? ORDER BY _key ASC"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= 4.5",
      "intent": "hotels with rating at least 4.5",
      "manifest": "hotels with rating at least a given number",
      "parameterized": {
        "parameterized_intent": "hotels with rating at least ?",
        "parameterized_sql_snippet": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= ?"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT CAST(T.cf['location'] AS STRING) AS value, 'hotels.location' AS `columns`, 'City' AS concept_type, 0 AS distance, '' AS context FROM `hotels` AS T WHERE CAST(T.cf['location'] AS STRING) = CAST($value AS STRING)",
      "concept_type": "City",
      "description": "Exact match for hotel city in hotels table"
    }
  ]
}

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": "List all luxury hotels",
      "sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = 'Luxury' ORDER BY _key ASC",
      "intent": "hotels in Luxury tier",
      "manifest": "hotels in a given product tier",
      "parameterized": {
        "parameterized_intent": "hotels in ? tier",
        "parameterized_sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = ? ORDER BY _key ASC"
      }
    }
  ],
  ...
}

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": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= 4.5",
      "intent": "hotels with rating at least 4.5",
      "manifest": "hotels with rating at least a given number",
      "parameterized": {
        "parameterized_intent": "hotels with rating at least ?",
        "parameterized_sql_snippet": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= ?"
      }
    }
  ]
}

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 CAST(T.cf['location'] AS STRING) AS value, 'hotels.location' AS `columns`, 'City' AS concept_type, 0 AS distance, '' AS context FROM `hotels` AS T WHERE CAST(T.cf['location'] AS STRING) = CAST($value AS STRING)",
      "concept_type": "City",
      "description": "Exact match for hotel city in hotels table"
    }
  ]
}

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.
  • GoogleSQL per Bigtable non supporta le operazioni sui set (UNION ALL), pertanto il collegamento dei valori tra più query di ricerca dei valori non è supportato. Una richiesta di questo tipo va a buon fine, ma i valori non vengono collegati per i set di contesto con più di una ricerca di valori.
  • I set di contesto per i database vengono utilizzati solo dall'endpoint QueryData nell'API Conversational Analytics.

Passaggi successivi