Panoramica dei set di contesti

Un set di contesti è una raccolta di indicazioni che aiutano strumenti come QueryData a generare query GQL (Graph Query Language) accurate per il grafo delle proprietà nel database Spanner. QueryData legge lo schema del grafico delle proprietà direttamente dal database. Un set di contesto aggiunge ciò che lo schema non acquisisce: il significato dei termini della tua attività, le query verificate per le domande che gli utenti pongono spesso e il modo in cui gli utenti fanno riferimento ai valori archiviati nel tuo grafo. Non è necessario ridefinire lo schema del grafo in un set di contesti.

I seguenti database sono supportati da QueryData:

  • AlloyDB per PostgreSQL
  • Cloud SQL per MySQL
  • Cloud SQL per PostgreSQL
  • Spanner (incluso Spanner Graph)
  • Firestore con compatibilità MongoDB

Per utilizzare i set di contesto con le tabelle Spanner relazionali anziché con Spanner Graph, consulta la panoramica dei set di contesto per Spanner.

Il contesto viene definito in un file JSON che contiene tre tipi di oggetti: modelli di query, aspetti delle query e ricerche di valori. Puoi creare questo file con l'aiuto dell'agente di progettazione del contesto e poi caricarlo in un set di contesti che crei in Spanner Studio. QueryData utilizza il set di contesti quando una richiesta QueryData vi fa riferimento nel campo agent_context_reference.context_set_id.

Puoi creare set di contesti nelle regioni us-central1, us-east1, europe-west4 e asia-southeast1. La regione di un set di contesto non deve necessariamente corrispondere alla località che utilizzi nelle richieste QueryData, ad esempio locations/global.

Gli esempi in questo documento utilizzano lo schema del grafo delle proprietà FinGraph (nodi Person e Account collegati da archi Owns e Transfers). Per configurare il grafico delle proprietà FinGraph nel database Spanner e inserire dati di esempio, consulta Configura ed esegui query su Spanner Graph.

Come QueryData utilizza un set di contesti

Un set di contesti può contenere tre tipi di contesto. Ogni tipo risolve un problema diverso e QueryData può utilizzarli in modo indipendente o congiunto:

Tipo di contesto Cosa fornisci Quando utilizzarla Come viene utilizzato da QueryData Esempio di FinGraph
Modello di query Una query GQL completa e verificata per un tipo di domanda, con segnaposto ? per i valori che cambiano. Gli utenti pongono la stessa domanda ripetutamente con valori parametro diversi, soprattutto quando la query è complessa da generare (ad esempio un pattern di percorso multi-hop). Riutilizza direttamente la query sql per una corrispondenza esatta o sostituisce i parametri in parameterized_sql quando la domanda corrisponde al modello. "Il denaro inviato dal conto 7 è stato restituito entro 60 giorni?"
Query facet Una clausola GQL riutilizzabile, come un pattern MATCH o una condizione WHERE, che definisce un termine o una condizione aziendale. Una condizione o un pattern riutilizzabile viene visualizzato in molte domande diverse. Incorpora la clausola GQL definita durante la generazione di una nuova query GQL. Un trasferimento ad alto rischio è un trasferimento di almeno 200 a un account bloccato.
Ricerca di valore Una query che trova i valori delle proprietà archiviati che corrispondono a una frase di valore nella domanda dell'utente. Gli utenti fanno riferimento ai valori utilizzando nomi o ortografie diversi da quelli memorizzati nel grafico. Esegue la query di ricerca con la frase del valore prima di generare la query GQL, quindi filtra in base al valore e alla proprietà archiviati risolti. "giorno di pioggia" si riferisce a Rainy Day Fund in Account.nick_name.

Il seguente diagramma mostra come QueryData elabora una domanda utilizzando un set di contesti:

Diagramma che mostra come QueryData esegue prima le ricerche dei valori per risolvere le frasi dei valori in valori archiviati, quindi riutilizza un modello con corrispondenza esatta, adatta il modello più vicino o genera una nuova query GQL, utilizzando i modelli di query e i facet di query come guida.

Come mostrato nel diagramma, quando QueryData riceve una domanda, utilizza il set di contesti nel seguente ordine:

  1. Recuperare il contesto pertinente. QueryData recupera i modelli, i facet e le ricerche di valori più simili alla domanda.
  2. Esegui ricerche di valore. Per ogni frase di valore nella domanda, ad esempio un nome o un nickname, QueryData esegue le ricerche dei valori per trovare i valori memorizzati corrispondenti. Le ricerche di valori non vengono eseguite per numeri, date, ore o importi in valuta.
  3. Corrispondenza con i modelli di query. Se la domanda corrisponde a un modello, QueryData utilizza la query GQL verificata del modello. Per una corrispondenza esatta con nl_query, QueryData esegue direttamente la query sql. Per una corrispondenza con un modello con parametri, QueryData sostituisce i segnaposto ? in parameterized_sql con i valori della domanda ed esegue la query risultante.
  4. Genera una nuova query GQL. In caso contrario, QueryData genera una nuova query GQL dallo schema del grafico. Applica gli aspetti pertinenti come regole aziendali, utilizza i modelli pertinenti come esempi e utilizza i valori archiviati trovati dalle ricerche di valori.

Formato file del set di contesti

Un file di set di contesto è un oggetto JSON con tre campi di array (templates, facets e value_searches) per gli elementi di contesto descritti nelle sezioni seguenti. Un file di set di contesti vuoto ha la seguente struttura:

{
  "templates": [],
  "facets": [],
  "value_searches": []
}

Utilizza qualsiasi combinazione di questi campi e ometti quelli che non utilizzi. Un buon punto di partenza per Spanner Graph è creare un modello per ogni domanda multi-hop o con limiti di tempo che richiede una struttura di query specifica, un facet per ogni termine aziendale che appare in più domande e una ricerca di valori per ogni proprietà di testo a cui gli utenti fanno riferimento per nome (ad esempio nomi, nickname o paesi).

Quando modifichi un file di set di contesto, tieni presente le seguenti regole:

  • Stringhe di query su una sola riga. I valori di sql, parameterized_sql, sql_snippet, parameterized_sql_snippet, query e nl_query sono stringhe JSON, quindi ogni query viene scritta su una riga. All'interno di una query, utilizza le virgolette singole (') per i valori letterali stringa o l'interpretazione letterale delle virgolette doppie come \".
  • GQL nei campi sql. Alcuni nomi di campo contengono sql perché il formato è condiviso da tutti i database supportati da QueryData. Per Spanner Graph, fornisci query o clausole GQL in sql, parameterized_sql, sql_snippet e parameterized_sql_snippet.
  • Nomi dei campi esatti. I nomi dei campi devono corrispondere esattamente ai nomi riportati in questo documento. I campi con nomi non riconosciuti vengono ignorati senza errori.

Modelli di query

Un modello associa una domanda posta dagli utenti alla query GQL verificata che risponde alla domanda. Utilizza i modelli per le domande che gli utenti pongono ripetutamente, soprattutto quando la query è complessa da generare (ad esempio un pattern di percorso multi-hop con una condizione temporale).

Esempio di modello

Con il seguente modello nel file del set di contesto, QueryData può rispondere a domande che condividono la stessa struttura, ad esempio "Il denaro inviato dal conto 7 è stato restituito entro 60 giorni?" o "Il denaro inviato dal conto 16 è stato restituito entro 30 giorni?":

{
  "templates": [
    {
      "nl_query": "Did any money sent from account 7 come back to it within 60 days?",
      "sql": "GRAPH FinGraph MATCH TRAIL (src:Account {id: 7})-[sent:Transfers]->(:Account)-[:Transfers]->{0,2}(:Account)-[returned:Transfers]->(src) WHERE returned.create_time > sent.create_time AND TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) <= 60 RETURN sent.amount AS amount_sent, returned.amount AS amount_returned, TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) AS days_to_return",
      "intent": "Find transfer loops of two to four transfers that start and end at account 7, where the last transfer happens within 60 days after the first transfer.",
      "manifest": "Find transfer loops of two to four transfers that start and end at a given account, where the last transfer happens within a given number of days after the first transfer.",
      "parameterized": {
        "parameterized_intent": "Find transfer loops of two to four transfers that start and end at account ?, where the last transfer happens within ? days after the first transfer.",
        "parameterized_sql": "GRAPH FinGraph MATCH TRAIL (src:Account {id: ?})-[sent:Transfers]->(:Account)-[:Transfers]->{0,2}(:Account)-[returned:Transfers]->(src) WHERE returned.create_time > sent.create_time AND TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) <= ? RETURN sent.amount AS amount_sent, returned.amount AS amount_returned, TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) AS days_to_return"
      }
    }
  ]
}

Quando un utente chiede: "È stato restituito del denaro inviato dal conto 7 entro 60 giorni?", QueryData associa la domanda al modello (o, per una domanda con valori parametro diversi, ad esempio l'account 16 e 30 giorni, sostituisce i due segnaposto ? in parameterized_sql) ed esegue la seguente query GQL:

GRAPH FinGraph
MATCH TRAIL
  (src:Account {id: 7})-[sent:Transfers]->(:Account)
    -[:Transfers]->{0,2}(:Account)-[returned:Transfers]->(src)
WHERE returned.create_time > sent.create_time
  AND TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) <= 60
RETURN
  sent.amount AS amount_sent,
  returned.amount AS amount_returned,
  TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) AS days_to_return

Utilizzando i dati campionati FinGraph, questa query restituisce risultati simili ai seguenti:

+-------------+-----------------+----------------+
| amount_sent | amount_returned | days_to_return |
+-------------+-----------------+----------------+
| 300         | 500             | 36             |
+-------------+-----------------+----------------+

Campi del modello

Un oggetto template contiene i seguenti campi:

Campo Requisito Descrizione
nl_query Obbligatorio Una domanda di esempio, formulata nel modo in cui la pone un utente (ad esempio, "Il denaro inviato dall'account 7 è stato restituito entro 60 giorni?").
sql Obbligatorio La query GQL completa che risponde a nl_query. Inizia la query con GRAPH seguito dal nome di un grafico delle proprietà specificato nel campo graph_ids delle richieste QueryData, ad esempio GRAPH FinGraph.
intent Obbligatorio Una descrizione precisa dei risultati restituiti da sql. La domanda di un utente spesso lascia le condizioni non dichiarate e intent le dichiara (ad esempio, specificando che il denaro "è tornato" significa "loop di trasferimento da due a quattro trasferimenti che iniziano e terminano nell'account 7, dove l'ultimo trasferimento avviene entro 60 giorni dal primo trasferimento").
manifest Obbligatorio Una versione generalizzata di intent che descrive il tipo di domanda a cui risponde il template, senza i valori specifici (ad esempio, "account 7" diventa "un determinato account" e "60 giorni" diventa "un determinato numero di giorni"). QueryData recupera i modelli confrontando la domanda con il manifest.
parameterized.parameterized_intent Facoltativo intent, con ogni valore specifico sostituito da un segnaposto ?.
parameterized.parameterized_sql Facoltativo La query sql, con ogni valore specifico sostituito da un segnaposto ? nello stesso ordine di parameterized_intent. Quando una domanda corrisponde al modello, QueryData sostituisce i segnaposto con i valori della domanda ed esegue la query.

Se scrivi il file del set di contesto manualmente, compila tutti e quattro i campi obbligatori. Il caricamento non va a buon fine e viene visualizzato un errore INVALID_ARGUMENT se uno di questi campi è vuoto. L'agente di progettazione del contesto genera intent, manifest e parameterized dalle coppie nl_query e sql. Esamina i valori generati e modificali se un valore che dovrebbe rimanere fisso viene sostituito da un segnaposto o se un valore che dovrebbe variare non viene sostituito.

Facet di query

Un facet è una clausola GQL riutilizzabile, ad esempio un pattern MATCH o una condizione WHERE, che definisce un termine o una condizione aziendale. A differenza di un template, un facet è una query parziale anziché una query completa, quindi non inizia con una clausola GRAPH e non è legato a una domanda. Quando QueryData genera una nuova query, applica i facet pertinenti alla domanda.

Esempio di facet

Nella seguente configurazione di facets, il primo facet acquisisce il pattern per i trasferimenti che coinvolgono un account bloccato, mentre il secondo definisce un trasferimento ad alto rischio come un trasferimento di 200 o più a un account bloccato:

{
  "facets": [
    {
      "sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})",
      "intent": "transfers involving a blocked account, in either direction"
    },
    {
      "sql_snippet": "MATCH (account:Account)-[transfer:Transfers]->(blocked_account:Account {is_blocked: true}) WHERE transfer.amount >= 200",
      "intent": "high-risk transfers, which are transfers of 200 or more to a blocked account",
      "manifest": "high-risk transfers, which are transfers of a given amount or more to a blocked account",
      "parameterized": {
        "parameterized_intent": "high-risk transfers, which are transfers of ? or more to a blocked account",
        "parameterized_sql_snippet": "MATCH (account:Account)-[transfer:Transfers]->(blocked_account:Account {is_blocked: true}) WHERE transfer.amount >= ?"
      }
    }
  ]
}

Quando un utente chiede "Quanti trasferimenti ad alto rischio ha effettuato Alex?", nessun template corrisponde alla domanda. QueryData genera una nuova query GQL e incorpora la seconda dimensione per conteggiare i trasferimenti di 200 o più a un account bloccato:

GRAPH `FinGraph`
MATCH (p:`Person` {`name`: "Alex"})-[:`Owns`]->(src:`Account`)
      -[t:`Transfers`]->(dst:`Account` {`is_blocked`: true})
FILTER t.`amount` >= 200.0
RETURN COUNT(*) AS high_risk_transfer_count

Utilizzando i dati campionati di FinGraph, questa query conteggia il trasferimento di 300 dall'account 7 all'account bloccato 16 e restituisce risultati simili ai seguenti:

+--------------------------+
| high_risk_transfer_count |
+--------------------------+
| 1                        |
+--------------------------+

Campi facet

Un oggetto facet utilizza la stessa struttura di un template di query, con le seguenti differenze:

  • Nessun campo nl_query. I facet non hanno un campo nl_query, perché descrivono una condizione che appare in molte domande anziché in una singola domanda.
  • sql_snippet invece di sql (obbligatorio). Una clausola GQL, ad esempio un pattern MATCH o una condizione WHERE. Per evitare ambiguità, utilizza etichette di nodi e archi e nomi di variabili espliciti, come (account:Account), in modo che QueryData possa combinare la clausola GQL con il resto della query.
  • intent (obbligatorio), manifest (facoltativo) e parameterized (facoltativo). Definisci il termine o la condizione commerciale nello stesso modo dei campi del modello, con la differenza che QueryData associa le domande a intent (quindi rendilo descrittivo e manifest è facoltativo) e parameterized contiene parameterized_intent e parameterized_sql_snippet.

Query di ricerca di valore

Una ricerca di valori è una query, non una tabella di ricerca. Prima che QueryData generi una query GQL, esegue le ricerche dei valori una volta per ogni frase di valore nella domanda (un valore di testo come un nome, un nickname o un paese), sostituendo la frase con $value. Poi, utilizza i valori archiviati più vicini restituiti dalle query, insieme alla proprietà da cui provengono, quando scrive la query GQL. Le ricerche di valori non vengono eseguite per numeri, date, ore o importi di valuta.

Esempio di ricerca di valori

Ad esempio, in FinGraph, l'account 20 ha il nickname Rainy Day Fund e la proprietà Person.country memorizza Czech_Republic con un trattino basso. Le seguenti ricerche di valori mappano frasi di valore come "giorno di pioggia" a Rainy Day Fund in Account.nick_name e "Repubblica Ceca" a Czech_Republic in Person.country:

{
  "value_searches": [
    {
      "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (a:Account) WHERE STRPOS(LOWER(a.nick_name), LOWER($value)) > 0 RETURN DISTINCT a.nick_name AS value, 'FinGraph.Account.nick_name' AS columns, 'Account nickname' AS concept_type, 1 - LENGTH($value) / LENGTH(a.nick_name) AS distance, JSON '{}' AS context)",
      "concept_type": "Account nickname",
      "description": "Case-insensitive partial match on account nicknames. Distance is 0 for an exact match and grows as the phrase covers less of the nickname."
    },
    {
      "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (p:Person) WHERE LOWER(REPLACE(p.country, '_', ' ')) = LOWER(REPLACE($value, '_', ' ')) RETURN DISTINCT p.country AS value, 'FinGraph.Person.country' AS columns, 'Person country' AS concept_type, 0 AS distance, JSON '{}' AS context)",
      "concept_type": "Person country",
      "description": "Match for country names on Person nodes that ignores case and treats underscores as spaces"
    }
  ]
}

La query Account nickname, formattata per la leggibilità, è la seguente:

SELECT value, columns, concept_type, distance, context
FROM GRAPH_TABLE(
  FinGraph
  MATCH (a:Account)
  WHERE STRPOS(LOWER(a.nick_name), LOWER($value)) > 0
  RETURN DISTINCT
    a.nick_name AS value,
    'FinGraph.Account.nick_name' AS columns,
    'Account nickname' AS concept_type,
    1 - LENGTH($value) / LENGTH(a.nick_name) AS distance,
    JSON '{}' AS context
)

Quando un utente chiede "Chi è il proprietario dell'account per le emergenze?", QueryData esegue le ricerche dei valori con $value impostato su 'rainy day'. La ricerca di Account nickname calcola distance dalla lunghezza della frase rispetto alla lunghezza del nickname memorizzato (mentre una frase più ampia come "fondo" corrisponde a Vacation Fund a circa 0.69 e Rainy Day Fund a circa 0.71, e una corrispondenza esatta come "fondo per le emergenze" ha una distanza di 0) e restituisce risultati simili ai seguenti:

+----------------+----------------------------+------------------+--------------------+---------+
| value          | columns                    | concept_type     | distance           | context |
+----------------+----------------------------+------------------+--------------------+---------+
| Rainy Day Fund | FinGraph.Account.nick_name | Account nickname | 0.3571428571428571 | {}      |
+----------------+----------------------------+------------------+--------------------+---------+

QueryData genera quindi una query GQL che filtra in base a {nick_name: 'Rainy Day Fund'} anziché a {nick_name: 'rainy day'}:

GRAPH `FinGraph`
MATCH (p:`Person`)-[:`Owns`]->(a:`Account` {`nick_name`: 'Rainy Day Fund'})
RETURN DISTINCT SAFE_TO_JSON(p) AS person

Utilizzando i dati campionati FinGraph, questa query restituisce il nodo Person per Dana in formato JSON, simile al seguente:

{
  "element_definition_name": "Person",
  "identifier": "kQKRBA==",
  "kind": "node",
  "labels": ["Person"],
  "properties": {
    "birthday": "1980-10-31T08:00:00Z",
    "city": "Moravia",
    "country": "Czech_Republic",
    "id": 2,
    "name": "Dana"
  }
}

Campi di ricerca dei valori e colonne SELECT obbligatorie

Un oggetto di ricerca dei valori contiene i seguenti campi:

Campo Requisito Descrizione
query Obbligatorio Una query GoogleSQL che trova i valori archiviati che corrispondono a una frase di valore. Utilizza $value dove va la frase. QueryData sostituisce $value con la frase come stringa letterale tra virgolette, quindi non racchiudere $value tra virgolette. Puoi utilizzare $value più di una volta. Scrivi la query come istruzione SELECT su un operatore GRAPH_TABLE che corrisponde a un'etichetta di nodo o arco, confronta una proprietà con $value e restituisce le cinque colonne della tabella seguente.
concept_type Obbligatorio Un'etichetta per il tipo di valore trovato dalla ricerca, ad esempio Account nickname o Person country.
description Facoltativo Una descrizione di come la ricerca corrisponde ai valori.

Ogni ricerca di valori query deve restituire le seguenti cinque colonne in questo ordine:

Colonna di output Descrizione Esempio di FinGraph
value Il valore della proprietà corrispondente, così come è archiviato nel database. a.nick_name AS value ('Rainy Day Fund')
columns La località della proprietà, nel formato GRAPH_NAME.LABEL.PROPERTY. QueryData passa questo valore al modello come posizione del valore, quindi utilizza un formato coerente. 'FinGraph.Account.nick_name' AS columns
concept_type Un'etichetta per il tipo di valore. Utilizza la stessa stringa del campo concept_type della ricerca di valori: il campo etichetta la ricerca e la colonna etichetta ogni corrispondenza. 'Account nickname' AS concept_type
distance La distanza del valore memorizzato dalla frase, su una scala definita da te, dove 0 è una corrispondenza esatta. Per convenzione, utilizza valori compresi tra 0 e 1. QueryData ordina i candidati di tutte le ricerche di valori in base a distance e mantiene i 10 più vicini. Non applica una soglia, quindi escludi le corrispondenze deboli nella query stessa, ad esempio aggiungendo WHERE distance < 1.0 all'istruzione SELECT esterna. 1 - LENGTH($value) / LENGTH(a.nick_name) AS distance
context Un valore JSON. QueryData non utilizza questa colonna, ma la colonna deve essere presente con lo stesso tipo in ogni ricerca di valori. Restituisci JSON '{}'. JSON '{}' AS context

In che modo QueryData esegue le ricerche di valori

QueryData non esegue ricerche di valori una alla volta. Per ogni frase di valore in una domanda, sostituisce la frase con $value in ogni ricerca di valore, aggiunge ORDER BY distance LIMIT 10 a ogni query, combina le query con UNION ALL ed esegue il risultato come una singola istruzione GoogleSQL che mantiene le 10 corrispondenze più vicine. La query combinata è il motivo per cui le ricerche di valori vengono scritte come istruzioni SELECT su GRAPH_TABLE anziché come istruzioni GQL autonome: GRAPH_TABLE esegue il pattern GQL MATCH come tabella, mentre UNION ALL e ORDER BY distance condiviso sono costrutti SQL.

Questo modello di esecuzione ha le seguenti conseguenze per le query che scrivi:

  • Nessun ORDER BY o LIMIT esterno. Non aggiungere ORDER BY o LIMIT all'istruzione SELECT esterna. QueryData li aggiunge e una clausola duplicata causa l'errore dell'istruzione.
  • Tipi di colonna compatibili. Ogni ricerca di valori nel file deve restituire le stesse cinque colonne, nello stesso ordine e con tipi compatibili. Ad esempio, restituisci JSON '{}' per context in tutti i casi, non '{}' in alcuni.
  • Segnaposto $value obbligatorio. La query deve contenere $value almeno una volta, altrimenti il caricamento non va a buon fine.
  • Solo valori di testo. Le ricerche di valori vengono eseguite solo per i valori di testo. QueryData non li esegue per numeri, date, ore o importi in valuta.

Limitazioni

I set di contesto per Spanner Graph presentano le seguenti limitazioni:

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

Passaggi successivi