Un ensemble de contextes est une collection de conseils qui aident des outils tels que QueryData à générer des requêtes GQL (Graph Query Language) précises pour le graphique de propriétés de votre base de données Spanner. QueryData lit le schéma de votre graphe de propriétés directement à partir de la base de données. Un ensemble de contexte ajoute ce que le schéma ne capture pas : la signification de vos termes métier, les requêtes validées pour les questions que vos utilisateurs posent souvent et la façon dont les utilisateurs font référence aux valeurs stockées dans votre graphique. Vous n'avez pas besoin de redéfinir le schéma de votre graphe dans un ensemble de contextes.
Les bases de données suivantes sont compatibles avec QueryData :
- AlloyDB pour PostgreSQL
- Cloud SQL pour MySQL
- Cloud SQL pour PostgreSQL
- Spanner (y compris Spanner Graph)
- Firestore compatible avec MongoDB
Pour utiliser des ensembles de contexte avec des tables Spanner relationnelles plutôt qu'avec Spanner Graph, consultez Présentation des ensembles de contexte pour Spanner.
Vous définissez le contexte dans un fichier JSON contenant trois types d'objets : des modèles de requête, des facettes de requête et des recherches de valeurs. Vous pouvez créer ce fichier à l'aide de l'agent d'ingénierie contextuelle, puis l'importer dans un ensemble de contextes que vous créez dans Spanner Studio. QueryData utilise l'ensemble de contextes lorsqu'une requête QueryData le référence dans le champ agent_context_reference.context_set_id.
Vous pouvez créer des ensembles de contexte dans les régions us-central1, us-east1, europe-west4 et asia-southeast1. La région d'un ensemble de contextes ne doit pas nécessairement correspondre à l'emplacement que vous utilisez dans les requêtes QueryData, comme locations/global.
Les exemples de ce document utilisent le schéma de graphe de propriétés FinGraph (nœuds Person et Account connectés par des arêtes Owns et Transfers). Pour configurer le graphe de propriétés FinGraph dans votre base de données Spanner et insérer des exemples de données, consultez Configurer et interroger Spanner Graph.
Comment QueryData utilise un ensemble de contextes
Un ensemble de contextes peut contenir trois types de contextes. Chaque type résout un problème différent, et QueryData peut les utiliser indépendamment ou ensemble :
| Type de contexte | Ce que vous fournissez | Quand utiliser cette fonctionnalité | Comment QueryData l'utilise | Exemple FinGraph |
|---|---|---|---|---|
| Modèle de requête | Une requête GQL complète et validée pour un type de question, avec des espaces réservés ? pour les valeurs qui changent. |
Les utilisateurs posent la même question de manière répétée avec des valeurs de paramètres différentes, en particulier lorsque la requête est complexe à générer (par exemple, un modèle de chemin à plusieurs sauts). | Réutilise directement la requête sql pour une correspondance exacte ou remplace les paramètres dans parameterized_sql lorsque la question correspond au modèle. |
"De l'argent envoyé depuis le compte 7 a-t-il été renvoyé vers ce compte dans un délai de 60 jours ?" |
| Facette de requête | Clause GQL réutilisable, telle qu'un modèle MATCH ou une condition WHERE, qui définit un terme ou une condition métier. |
Une condition ou un modèle réutilisable apparaît dans de nombreuses questions différentes. | Intègre la clause GQL définie lors de la génération d'une nouvelle requête GQL. | Un transfert à haut risque est un transfert d'au moins 200 vers un compte bloqué. |
| Recherche de valeur | Requête qui recherche les valeurs de propriété stockées correspondant à une expression de valeur dans la question de l'utilisateur. | Les utilisateurs font référence aux valeurs par des noms ou des orthographes différents de ceux stockés dans le graphique. | Exécute la requête de recherche avec l'expression de valeur avant de générer la requête GQL, puis filtre sur la valeur et la propriété stockées résolues. | "jour de pluie" fait référence à Rainy Day Fund dans Account.nick_name. |
Le schéma suivant montre comment QueryData traite une question à l'aide d'un ensemble de contexte :

Comme le montre le diagramme, lorsque QueryData reçoit une question, il utilise votre ensemble de contextes dans l'ordre suivant :
- Récupérer le contexte pertinent. QueryData récupère les modèles, les attributs et les recherches de valeurs les plus similaires à la question.
- Exécuter des recherches de valeurs Pour chaque expression de valeur dans la question, comme un nom ou un pseudo, QueryData exécute vos recherches de valeurs pour trouver les valeurs stockées correspondantes. Les recherches de valeurs ne sont pas exécutées pour les nombres, les dates, les heures ou les montants en devise.
- Correspondance avec les modèles de requête. Si la question correspond à un modèle, QueryData utilise la requête GQL validée du modèle. Pour une correspondance exacte avec
nl_query, QueryData exécute directement la requêtesql. Pour une correspondance avec un modèle paramétré, QueryData remplace les espaces réservés?dansparameterized_sqlpar les valeurs de la question et exécute la requête obtenue. - Générer une nouvelle requête GQL. Sinon, QueryData génère une nouvelle requête GQL à partir de votre schéma de graphe. Il applique les facettes pertinentes en tant que règles métier, utilise les modèles pertinents comme exemples et utilise les valeurs stockées trouvées par les recherches de valeurs.
Format de fichier de l'ensemble de contextes
Un fichier d'ensemble de contexte est un objet JSON comportant trois champs de tableau (templates, facets et value_searches) pour les éléments de contexte décrits dans les sections suivantes. Un fichier d'ensemble de contextes vide présente la structure suivante :
{
"templates": [],
"facets": [],
"value_searches": []
}
Utilisez n'importe quelle combinaison de ces champs et omettez ceux que vous n'utilisez pas. Pour commencer à utiliser Spanner Graph, vous pouvez créer un modèle pour chaque question à plusieurs sauts ou limitée dans le temps qui nécessite une structure de requête spécifique, une facette pour chaque terme métier qui apparaît dans plusieurs questions et une recherche de valeur pour chaque propriété de texte à laquelle les utilisateurs font référence par son nom (comme les noms, les surnoms ou les pays).
Lorsque vous modifiez un fichier d'ensemble de contextes, tenez compte des règles suivantes :
- Chaînes de requête sur une seule ligne. Les valeurs de
sql,parameterized_sql,sql_snippet,parameterized_sql_snippet,queryetnl_querysont des chaînes JSON. Chaque requête est donc écrite sur une seule ligne. Dans une requête, utilisez des guillemets simples (') pour les littéraux de chaîne ou échappez les guillemets doubles en tant que\". - GQL dans les champs
sql. Certains noms de champs contiennentsql, car le format est partagé par toutes les bases de données compatibles avec QueryData. Pour Spanner Graph, fournissez des requêtes ou des clauses GQL danssql,parameterized_sql,sql_snippetetparameterized_sql_snippet. - Noms de champs exacts. Les noms des champs doivent correspondre exactement à ceux de ce document. Les champs dont le nom n'est pas reconnu sont ignorés sans erreur.
Modèles de requêtes
Un modèle associe une question posée par vos utilisateurs à la requête GQL validée qui y répond. Utilisez des modèles pour les questions que les utilisateurs posent de manière répétée, en particulier lorsque la requête est complexe à générer (par exemple, un modèle de chemin à plusieurs sauts avec une condition temporelle).
Exemple de modèle
Avec le modèle suivant dans votre fichier d'ensemble de contexte, QueryData peut répondre à des questions qui partagent la même structure, telles que "L'argent envoyé depuis le compte 7 est-il revenu sur ce compte dans les 60 jours ?" ou "L'argent envoyé depuis le compte 16 est-il revenu sur ce compte dans les 30 jours ?" :
{
"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"
}
}
]
}
Lorsqu'un utilisateur demande "L'argent envoyé depuis le compte 7 a-t-il été reversé sur ce compte dans un délai de 60 jours ?", QueryData fait correspondre la question au modèle (ou, pour une question avec des valeurs de paramètres différentes telles que le compte 16 et 30 jours, remplace les deux espaces réservés ? dans parameterized_sql) et exécute la requête GQL suivante :
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
En utilisant les données échantillonnées FinGraph, cette requête renvoie des résultats semblables à ceux-ci :
+-------------+-----------------+----------------+
| amount_sent | amount_returned | days_to_return |
+-------------+-----------------+----------------+
| 300 | 500 | 36 |
+-------------+-----------------+----------------+
Champs du modèle
Un objet de modèle contient les champs suivants :
| Champ | Exigence | Description |
|---|---|---|
nl_query |
Obligatoire | Exemple de question, formulée de la même manière qu'un utilisateur la poserait (par exemple, "L'argent envoyé depuis le compte 7 a-t-il été restitué dans les 60 jours ?"). |
sql |
Obligatoire | La requête GQL complète qui répond à nl_query. Commencez la requête par GRAPH suivi du nom d'un graphe de propriétés que vous spécifiez dans le champ graph_ids de vos requêtes QueryData, par exemple GRAPH FinGraph. |
intent |
Obligatoire | Une description précise des résultats renvoyés par sql. La question d'un utilisateur laisse souvent des conditions non énoncées, et intent les énonce (par exemple, en précisant que l'argent "est revenu" signifie "boucles de transfert de deux à quatre transferts qui commencent et se terminent au compte 7, où le dernier transfert a lieu dans les 60 jours suivant le premier transfert"). |
manifest |
Obligatoire | Version généralisée de intent qui décrit le type de question auquel le modèle répond, sans les valeurs spécifiques (par exemple, "compte 7" devient "un compte donné" et "60 jours" devient "un nombre de jours donné"). QueryData récupère les modèles en comparant la question au fichier manifeste. |
parameterized.parameterized_intent |
Facultatif | intent, chaque valeur spécifique étant remplacée par un espace réservé ?. |
parameterized.parameterized_sql |
Facultatif | Requête sql, chaque valeur spécifique étant remplacée par un espace réservé ? dans le même ordre que parameterized_intent. Lorsqu'une question correspond au modèle, QueryData remplace les espaces réservés par les valeurs de la question et exécute cette requête. |
Si vous écrivez le fichier d'ensemble de contextes manuellement, remplissez les quatre champs obligatoires. L'importation échoue avec une erreur INVALID_ARGUMENT si l'un d'eux est vide. L'agent d'ingénierie contextuelle génère intent, manifest et parameterized à partir de vos paires nl_query et sql. Examinez les valeurs générées et modifiez-les si une valeur qui devrait rester fixe est remplacée par un espace réservé, ou si une valeur qui devrait varier n'est pas remplacée.
Attributs de requête
Une facette est une clause GQL réutilisable, telle qu'un modèle MATCH ou une condition WHERE, qui définit un terme ou une condition métier. Contrairement à un modèle, une facette est une requête partielle plutôt qu'une requête complète. Elle ne commence donc pas par une clause GRAPH et n'est pas liée à une seule question. Lorsque QueryData génère une nouvelle requête, il applique les facettes pertinentes pour la question.
Exemple d'attribut
Dans la configuration facets suivante, la première facette capture le modèle des transferts impliquant un compte bloqué, et la seconde définit un transfert à haut risque comme un transfert de 200 ou plus vers un compte bloqué :
{
"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 >= ?"
}
}
]
}
Lorsqu'un utilisateur demande "Combien de transferts à haut risque Alex a-t-il effectués ?", aucun modèle ne correspond à la question. QueryData génère une nouvelle requête GQL et intègre la deuxième facette pour compter les transferts de 200 ou plus vers un compte bloqué :
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
À l'aide des données échantillonnées FinGraph, cette requête compte le transfert 300 du compte 7 vers le compte bloqué 16 et renvoie des résultats semblables à ceux-ci :
+--------------------------+
| high_risk_transfer_count |
+--------------------------+
| 1 |
+--------------------------+
Champs d'attributs
Un objet de facette utilise la même structure qu'un modèle de requête, avec les différences suivantes :
- Aucun champ
nl_query. Les facettes n'ont pas de champnl_query, car elles décrivent une condition qui apparaît dans plusieurs questions plutôt que dans une seule. sql_snippetau lieu desql(obligatoire). Une clause GQL, telle qu'un modèleMATCHou une conditionWHERE. Pour éviter toute ambiguïté, utilisez des libellés de nœuds et d'arêtes explicites, ainsi que des noms de variables tels que(account:Account), afin que QueryData puisse combiner la clause GQL avec le reste de la requête.intent(obligatoire),manifest(facultatif) etparameterized(facultatif). Définissez le terme ou la condition métier de la même manière que les champs de modèle, sauf que QueryData met en correspondance les questions avecintent(rendez-le donc descriptif, etmanifestest facultatif), etparameterizedcontientparameterized_intentetparameterized_sql_snippet.
Requêtes de recherche de valeur
Une recherche de valeur est une requête, pas un tableau de conversion. Avant que QueryData ne génère une requête GQL, il exécute vos recherches de valeurs une fois pour chaque expression de valeur dans la question (une valeur textuelle telle qu'un nom, un pseudo ou un pays), en remplaçant l'expression par $value. Il utilise ensuite les valeurs stockées les plus proches renvoyées par les requêtes, ainsi que la propriété dont elles proviennent, lorsqu'il écrit la requête GQL. Les recherches de valeurs ne sont pas exécutées pour les nombres, les dates, les heures ou les montants en devise.
Exemple de recherche de valeur
Par exemple, dans FinGraph, le compte 20 a le pseudo Rainy Day Fund, et la propriété Person.country stocke Czech_Republic avec un trait de soulignement. Les recherches de valeurs suivantes mappent des expressions de valeur telles que "jour de pluie" à Rainy Day Fund dans Account.nick_name, et "République tchèque" à Czech_Republic dans 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 requête Account nickname, formatée pour plus de lisibilité, est la suivante :
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
)
Lorsqu'un utilisateur demande "À qui appartient le compte d'épargne ?", QueryData exécute les recherches de valeurs avec $value défini sur 'rainy day'. La recherche Account nickname calcule distance à partir de la longueur de l'expression par rapport à la longueur du pseudo stocké (alors qu'une expression plus large comme "fund" correspond à Vacation Fund à environ 0.69 et à Rainy Day Fund à environ 0.71, et qu'une correspondance exacte comme "rainy day fund" a une distance de 0), et renvoie des résultats semblables aux suivants :
+----------------+----------------------------+------------------+--------------------+---------+
| value | columns | concept_type | distance | context |
+----------------+----------------------------+------------------+--------------------+---------+
| Rainy Day Fund | FinGraph.Account.nick_name | Account nickname | 0.3571428571428571 | {} |
+----------------+----------------------------+------------------+--------------------+---------+
QueryData génère ensuite une requête GQL qui filtre sur {nick_name: 'Rainy Day Fund'} au lieu de {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
En utilisant les données échantillonnées FinGraph, cette requête renvoie le nœud Person pour Dana au format JSON, comme suit :
{
"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"
}
}
Champs de recherche de valeurs et colonnes SELECT obligatoires
Un objet de recherche de valeur contient les champs suivants :
| Champ | Exigence | Description |
|---|---|---|
query |
Obligatoire | Requête GoogleSQL qui recherche les valeurs stockées correspondant à une expression de valeur. Utilisez $value à l'emplacement de l'expression. QueryData remplace $value par l'expression sous forme de littéral de chaîne entre guillemets. Ne placez donc pas $value entre guillemets. Vous pouvez utiliser $value plusieurs fois. Écrivez la requête sous la forme d'une instruction SELECT sur un opérateur GRAPH_TABLE qui correspond à une étiquette de nœud ou d'arête, compare une propriété à $value et renvoie les cinq colonnes du tableau suivant. |
concept_type |
Obligatoire | Libellé du type de valeur trouvé par la recherche, par exemple Account nickname ou Person country. |
description |
Facultatif | Description de la façon dont la recherche met en correspondance les valeurs. |
Chaque recherche de valeur query doit renvoyer les cinq colonnes suivantes dans cet ordre :
| Colonne de sortie | Description | Exemple FinGraph |
|---|---|---|
value |
Valeur de la propriété correspondante, telle qu'elle est stockée dans la base de données. | a.nick_name AS value ('Rainy Day Fund') |
columns |
Emplacement de la propriété, au format GRAPH_NAME.LABEL.PROPERTY. QueryData transmet cette valeur au modèle en tant qu'emplacement de la valeur. Utilisez donc une forme cohérente. |
'FinGraph.Account.nick_name' AS columns |
concept_type |
Libellé du type de valeur. Utilisez la même chaîne que le champ concept_type de la recherche de valeur : le champ étiquette la recherche et la colonne étiquette chaque correspondance. |
'Account nickname' AS concept_type |
distance |
Écart entre la valeur stockée et l'expression, sur une échelle que vous définissez, où 0 correspond à une correspondance exacte. Par convention, utilisez des valeurs comprises entre 0 et 1. QueryData trie les candidats de toutes les recherches de valeurs par distance et conserve les 10 plus proches. Il n'applique pas de seuil. Par conséquent, excluez les correspondances faibles dans la requête elle-même, par exemple en ajoutant WHERE distance < 1.0 à l'instruction SELECT externe. |
1 - LENGTH($value) / LENGTH(a.nick_name) AS distance |
context |
Une valeur JSON. QueryData n'utilise pas cette colonne, mais elle doit être présente avec le même type dans chaque recherche de valeur. Renvoyez JSON '{}'. |
JSON '{}' AS context |
Comment QueryData exécute des recherches de valeurs
QueryData n'exécute pas les recherches de valeurs une par une. Pour chaque expression de valeur d'une question, il remplace l'expression par $value dans chaque recherche de valeur, ajoute ORDER BY distance LIMIT 10 à chaque requête, combine les requêtes avec UNION ALL et exécute le résultat sous la forme d'une seule instruction GoogleSQL qui conserve les 10 correspondances les plus proches. La requête combinée explique pourquoi les recherches de valeurs sont écrites sous forme d'instructions SELECT sur GRAPH_TABLE plutôt que sous forme d'instructions GQL autonomes : GRAPH_TABLE exécute votre modèle GQL MATCH en tant que table, et UNION ALL et le ORDER BY distance partagé sont des constructions SQL.
Ce modèle d'exécution a les conséquences suivantes sur les requêtes que vous écrivez :
- Pas de
ORDER BYni deLIMITexterne. N'ajoutez pasORDER BYniLIMITà l'instructionSELECTexterne. QueryData les ajoute, et une clause en double entraîne l'échec de l'instruction. - Types de colonnes compatibles. Chaque recherche de valeur dans le fichier doit renvoyer les cinq mêmes colonnes, dans le même ordre et avec des types compatibles. Par exemple, renvoyez
JSON '{}'pourcontextdans toutes les réponses, et non'{}'dans certaines. - Espace réservé
$valueobligatoire. La requête doit contenir$valueau moins une fois, sinon l'importation échoue. - Valeurs textuelles uniquement. Les recherches de valeurs ne s'exécutent que pour les valeurs textuelles. QueryData ne les exécute pas pour les nombres, les dates, les heures ni les montants en devise.
Limites
Les ensembles de contexte pour Spanner Graph présentent les limites suivantes :
- Les ensembles de contexte pour les bases de données ne sont compatibles qu'avec les modèles de requête, les facettes de requête et les recherches de valeurs.
- Les ensembles de contexte pour les bases de données ne sont utilisés que par le point de terminaison
QueryDatadans l'API Conversational Analytics.
Étapes suivantes
- Découvrez comment créer ou supprimer un ensemble de contexte dans Spanner Studio.
- Découvrez comment créer des ensembles de contextes à l'aide de l'agent d'ingénierie contextuelle.