上下文集是一组指导信息,可帮助 QueryData 等工具为 Spanner 数据库中的属性图生成准确的 Graph Query Language (GQL) 查询。QueryData 会直接从数据库中读取属性图表架构。上下文集可添加架构无法捕获的内容:业务术语的含义、针对用户经常提出的问题的已验证查询,以及用户如何引用存储在图中的值。您无需在上下文集中重新定义图表架构。
QueryData 支持以下数据库:
- AlloyDB for PostgreSQL
- Cloud SQL for MySQL
- Cloud SQL for PostgreSQL
- Spanner(包括 Spanner Graph)
- 与 MongoDB 兼容的 Firestore
如需将上下文集与关系型 Spanner 表(而非 Spanner Graph)搭配使用,请参阅 Spanner 上下文集概览。
您可以在 JSON 文件中定义上下文,该文件包含三种类型的对象:查询模板、查询切面和值搜索。您可以借助上下文工程智能体编写此文件,然后将其上传到您在 Spanner Studio 中创建的上下文集。当 QueryData 请求在 agent_context_reference.context_set_id 字段中引用上下文集时,QueryData 会使用该上下文集。
您可以在 us-central1、us-east1、europe-west4 和 asia-southeast1 区域中创建上下文集。上下文集的区域无需与您在 QueryData 请求中使用的位置(例如 locations/global)一致。
本文档中的示例使用 FinGraph 属性图表架构(Person 和 Account 节点通过 Owns 和 Transfers 边缘连接)。如需在 Spanner 数据库中设置 FinGraph 属性图并插入示例数据,请参阅设置和查询 Spanner Graph。
QueryData 如何使用上下文集
一个情境集可以包含三种类型的情境。每种类型解决不同的问题,QueryData 可以单独使用它们,也可以结合使用:
| 上下文类型 | 您提供的内容 | 何时使用 | QueryData 如何使用这些数据 | FinGraph 示例 |
|---|---|---|---|---|
| 查询模板 | 针对一种问题类型的完整、经过验证的 GQL 查询,其中包含 ? 个占位符,用于表示会发生变化的值。 |
用户会使用不同的参数值重复提出相同的问题,尤其是在查询难以生成时(例如多跃点路径模式)。 | 直接重复使用 sql 查询以实现完全匹配,或者在问题与模板匹配时将参数替换为 parameterized_sql。 |
“从账号 7 汇出的任何款项是否在 60 天内退回该账号?” |
| 查询分面 | 可重复使用的 GQL 子句,例如 MATCH 模式或 WHERE 条件,用于定义业务术语或条件。 |
一个可重复使用的条件或模式出现在许多不同的问题中。 | 在生成新的 GQL 查询时,纳入定义的 GQL 子句。 | 高风险转移是指向被屏蔽账号转移 200或更多资金。 |
| 值搜索 | 用于查找与用户问题中的值短语匹配的存储属性值的查询。 | 用户提及值时使用的名称或拼写与这些值在图谱中的存储方式不同。 | 在生成 GQL 查询之前,使用值短语运行查找查询,然后根据解析后的存储值和属性进行过滤。 | “rainy day”是指Account.nick_name中的Rainy Day Fund。 |
下图展示了 QueryData 如何使用上下文集处理问题:

如图所示,当 QueryData 收到问题时,它会按以下顺序使用您的上下文集:
- 检索相关上下文。QueryData 会检索与问题最相似的模板、分面和值搜索。
- 运行值搜索。对于问题中的每个值短语(例如名称或昵称),QueryData 都会运行值搜索,以查找匹配的存储值。值搜索不适用于数字、日期、时间或货币金额。
- 与查询模板进行匹配。如果问题与某个模板匹配,QueryData 会使用该模板的已验证 GQL 查询。对于与
nl_query完全匹配的情况,QueryData 会直接运行sql查询。对于与参数化模板匹配的情况,QueryData 会将parameterized_sql中的?占位符替换为问题中的值,并运行生成的查询。 - 生成新的 GQL 查询。否则,QueryData 会根据您的图表架构生成新的 GQL 查询。它会将相关分面作为业务规则应用,将相关模板作为示例,并使用值搜索找到的存储值。
上下文集文件格式
上下文集文件是一个 JSON 对象,其中包含三个数组字段(templates、facets 和 value_searches),用于存放下文所述的上下文项。空上下文集文件具有以下结构:
{
"templates": [],
"facets": [],
"value_searches": []
}
您可以任意组合使用这些字段,并忽略不使用的字段。对于 Spanner Graph,一个很好的起点是:为每个需要特定查询结构的多跃点或有时间限制的问题创建一个模板,为出现在多个问题中的每个业务术语创建一个 facet,并为用户按名称引用的每个文本属性(例如名称、昵称或国家/地区)创建一个值搜索。
修改上下文集文件时,请注意以下规则:
- 单行查询字符串。
sql、parameterized_sql、sql_snippet、parameterized_sql_snippet、query和nl_query的值是 JSON 字符串,因此每个查询都写在一行中。在查询中,请使用英文单引号 (') 表示字符串字面量,或将英文双引号转义为\"。 sql字段中的 GQL。某些字段名称包含sql,因为该格式由 QueryData 支持的所有数据库共享。对于 Spanner Graph,请在sql、parameterized_sql、sql_snippet和parameterized_sql_snippet中提供 GQL 查询或子句。- 确切的字段名称。字段名称必须与本文档中的名称完全一致。名称无法识别的字段会被忽略,且不会报错。
查询模板
模板会将用户提出的问题与回答该问题的经过验证的 GQL 查询配对。对于用户反复提出的问题,请使用模板,尤其是当查询生成过程较为复杂时(例如,包含时间条件的多跃点路径模式)。
模板示例
如果您的上下文集文件中包含以下模板,QueryData 就可以回答具有相同结构的问题,例如“从账号 7 发送的任何款项是否在 60 天内退回?”或“从账号 16 发送的任何款项是否在 30 天内退回?”:
{
"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"
}
}
]
}
当用户询问“是否有从账号 7 汇出的款项在 60 天内退回该账号?”时,QueryData 会将问题与模板进行匹配(或者,对于具有不同参数值的问题,例如账号 16 和 30 天,会将 parameterized_sql 中的两个 ? 占位符替换为相应的值),并运行以下 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
使用 FinGraph 抽样数据,此查询会返回类似于以下内容的结果:
+-------------+-----------------+----------------+
| amount_sent | amount_returned | days_to_return |
+-------------+-----------------+----------------+
| 300 | 500 | 36 |
+-------------+-----------------+----------------+
模板字段
模板对象包含以下字段:
| 字段 | 要求 | 说明 |
|---|---|---|
nl_query |
必填 | 一个示例问题,其措辞方式与用户提问的方式相同(例如,“从账号 7 发送的任何资金是否在 60 天内退回?”)。 |
sql |
必填 | 回答 nl_query 的完整 GQL 查询。查询以 GRAPH 开头,后跟您在 QueryData 请求的 graph_ids 字段中指定的属性图名称,例如 GRAPH FinGraph。 |
intent |
必填 | 对 sql 返回的结果的精确描述。用户的问题通常不会说明条件,而 intent 会说明这些条件(例如,指定资金“返回”意味着“在账号 7 开始和结束的 2 到 4 次转账的转账循环,其中最后一次转账发生在第一次转账后的 60 天内”)。 |
manifest |
必填 | intent 的通用版本,用于描述模板回答的问题类型,不包含具体值(例如,“账号 7”变为“给定账号”,“60 天”变为“给定天数”)。QueryData 通过将问题与清单进行比较来检索模板。 |
parameterized.parameterized_intent |
可选 | intent,其中每个特定值都替换为 ? 占位符。 |
parameterized.parameterized_sql |
可选 | sql 查询,其中每个特定值都替换为 ? 占位符,顺序与 parameterized_intent 相同。当问题与模板匹配时,QueryData 会将占位符替换为问题中的值,并运行此查询。 |
如果您手动编写上下文集文件,请填写所有四个必填字段;如果其中任何一个字段为空,上传将失败并显示 INVALID_ARGUMENT 错误。上下文工程智能体会根据您的 nl_query 和 sql 对生成 intent、manifest 和 parameterized。查看生成的值,如果应保持固定的值被替换为占位符,或者应变化的值未被替换,请进行修改。
查询分面
Facet 是可重复使用的 GQL 子句,例如 MATCH 模式或 WHERE 条件,用于定义业务术语或条件。与模板不同,分面是部分查询,而不是完整查询,因此它不以 GRAPH 子句开头,也不与一个问题相关联。当 QueryData 生成新查询时,它会应用与问题相关的分面。
商品详情示例
在以下 facets 配置中,第一个方面捕获涉及已冻结账号的转账模式,第二个方面将高风险转账定义为向已冻结账号转账 200 或更多:
{
"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 >= ?"
}
}
]
}
当用户询问“Alex 进行了多少次高风险转账?”时,没有模板与该问题匹配。QueryData 会生成一个新的 GQL 查询,并纳入第二个方面,以统计向被屏蔽账号转账 200 或更多金额的次数:
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
此查询使用 FinGraph 抽样数据,统计从账号 7 到被屏蔽账号 16 的 300 转账次数,并返回类似以下内容的结果:
+--------------------------+
| high_risk_transfer_count |
+--------------------------+
| 1 |
+--------------------------+
分面字段
Facet 对象使用与查询模板相同的结构,但存在以下差异:
- 没有
nl_query字段。Facet 没有nl_query字段,因为 Facet 描述的是出现在许多问题(而非单个问题)中的条件。 sql_snippet,而不是sql(必需)。GQL 子句,例如MATCH模式或WHERE条件。为避免歧义,请使用明确的节点和边缘标签以及变量名称(例如(account:Account)),以便 QueryData 可以将 GQL 子句与查询的其余部分组合在一起。intent(必需)、manifest(可选)和parameterized(可选)。以与模板字段相同的方式定义业务术语或条件,但 QueryData 会根据intent匹配问题(因此请使其具有描述性,manifest是可选的),并且parameterized包含parameterized_intent和parameterized_sql_snippet。
值搜索查询
值搜索是一项查询,而不是对照表。在 QueryData 生成 GQL 查询之前,它会针对问题中的每个值短语(文本值,例如名称、昵称或国家/地区)运行一次值搜索,并将该短语替换为 $value。然后,它会在编写 GQL 查询时使用查询返回的最接近的存储值以及这些值所属的属性。值搜索不适用于数字、日期、时间或货币金额。
值搜索示例
例如,在 FinGraph 中,账号 20 的昵称为 Rainy Day Fund,Person.country 属性存储 Czech_Republic(带下划线)。以下值搜索会将值短语(例如“rainy day”)映射到 Account.nick_name 中的 Rainy Day Fund,并将“Czech Republic”映射到 Person.country 中的 Czech_Republic:
{
"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"
}
]
}
Account nickname 查询(为便于阅读而设置了格式)如下所示:
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
)
当用户询问“谁拥有应急账户?”时,QueryData 在运行值搜索时,会将 $value 设置为 'rainy day'。Account nickname 搜索会根据短语长度相对于存储的昵称长度计算 distance(而更宽泛的短语(如“fund”)与 Vacation Fund 的距离约为 0.69,与 Rainy Day Fund 的距离约为 0.71,完全匹配(如“rainy day fund”)的距离为 0),并返回类似于以下内容的结果:
+----------------+----------------------------+------------------+--------------------+---------+
| value | columns | concept_type | distance | context |
+----------------+----------------------------+------------------+--------------------+---------+
| Rainy Day Fund | FinGraph.Account.nick_name | Account nickname | 0.3571428571428571 | {} |
+----------------+----------------------------+------------------+--------------------+---------+
然后,QueryData 会生成一个 GQL 查询,该查询会过滤 {nick_name: 'Rainy Day Fund'} 而不是 {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
使用 FinGraph 抽样数据,此查询会以 JSON 格式返回 Dana 的 Person 节点,类似于以下内容:
{
"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"
}
}
值搜索字段和必需的 SELECT 列
值搜索对象包含以下字段:
| 字段 | 要求 | 说明 |
|---|---|---|
query |
必填 | 一个 GoogleSQL 查询,用于查找与值短语匹配的存储值。在短语所在的位置使用 $value。QueryData 会将 $value 替换为带引号的字符串字面量形式的短语,因此请勿将 $value 括在引号中。您可以多次使用 $value。将查询编写为 SELECT 语句,该语句使用 GRAPH_TABLE 运算符匹配节点或边缘标签,将属性与 $value 进行比较,并返回下表中的五列。 |
concept_type |
必填 | 搜索结果中值的类型标签,例如 Account nickname 或 Person country。 |
description |
可选 | 关于搜索如何匹配值的说明。 |
每个值搜索 query 都必须按以下顺序返回以下五列:
| 输出列 | 说明 | FinGraph 示例 |
|---|---|---|
value |
匹配的属性值,存储在数据库中。 | a.nick_name AS value ('Rainy Day Fund') |
columns |
房源的位置,格式为 GRAPH_NAME.LABEL.PROPERTY。QueryData 会将此值作为值的位置传递给模型,因此请使用一致的形式。 |
'FinGraph.Account.nick_name' AS columns |
concept_type |
值类型的标签。使用与值搜索的 concept_type 字段相同的字符串:该字段用于标记搜索,而该列用于标记每个匹配项。 |
'Account nickname' AS concept_type |
distance |
存储的值与短语之间的距离,采用您定义的比例,其中 0 表示完全匹配。按照惯例,请使用 0 到 1 之间的值。QueryData 会按 distance 对所有值搜索中的候选值进行排序,并保留最接近的 10 个。它不会应用阈值,因此请在查询本身中排除弱匹配,例如通过向外部 SELECT 语句添加 WHERE distance < 1.0。 |
1 - LENGTH($value) / LENGTH(a.nick_name) AS distance |
context |
JSON 值。QueryData 不会使用此列,但该列必须在每次值搜索中都存在,且类型相同。返回 JSON '{}'。 |
JSON '{}' AS context |
QueryData 如何运行值搜索
QueryData 不会逐个运行值搜索。对于问题中的每个值短语,它会在每次值搜索中将该短语替换为 $value,在每个查询中附加 ORDER BY distance LIMIT 10,使用 UNION ALL 组合查询,并将结果作为单个 GoogleSQL 语句运行,该语句会保留 10 个最接近的匹配项。由于组合查询的存在,值搜索被编写为基于 GRAPH_TABLE 的 SELECT 语句,而不是独立的 GQL 语句:GRAPH_TABLE 将 GQL MATCH 模式作为表运行,而 UNION ALL 和共享的 ORDER BY distance 是 SQL 构造。
此执行模型对您编写的查询有以下影响:
- 没有外部
ORDER BY或LIMIT。请勿向外部SELECT语句添加ORDER BY或LIMIT。QueryData 会附加这些子句,而重复的子句会导致语句失败。 - 兼容的列类型。文件中的每个值搜索都必须返回相同的五列,且顺序相同、类型兼容。例如,在所有这些情况下,都应针对
context返回JSON '{}',而不是在某些情况下返回'{}'。 - 必需的
$value占位符。查询必须至少包含$value一次,否则上传会失败。 - 仅限文本值。值搜索仅针对文本值运行。QueryData 不会针对数字、日期、时间或货币金额运行这些检查。
限制
Spanner Graph 的上下文集存在以下限制:
- 数据库的上下文集仅支持查询模板、查询分面和值搜索。
- 数据库的上下文集仅由 Conversational Analytics API 中的
QueryData端点使用。
后续步骤
- 了解如何在 Spanner Studio 中创建或删除上下文集。
- 了解如何使用上下文工程智能体构建上下文集。