Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

上下文集概览

上下文集包含特定数据库的信息，可帮助 QueryData 等工具生成高精确度的查询。上下文集可以包含模板、分面和值搜索，这些内容有助于 QueryData 了解您的数据库架构和应用的业务逻辑。

支持以下数据库：

AlloyDB for PostgreSQL
Cloud SQL for MySQL
Cloud SQL for PostgreSQL
Spanner
与 MongoDB 兼容的 Firestore

什么是上下文集

如需构建有效的代理应用，QueryData 等工具必须了解您的数据组织和业务逻辑。您以上下文集的形式提供此信息。

您可以在包含每种上下文类型的 JSON 对象的文件中定义上下文。您可以在上下文工程代理的帮助下编写这些上下文文件。然后，您将上下文文件上传到在 Google Cloud 控制台中创建的上下文集。此过程使 QueryData 等工具能够了解数据库的特定架构和应用的业务逻辑。

上下文文件类似于以下内容：

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "db.accounts.countDocuments({ \"district.region\": \"Prague\", \"loans\": { $exists: true, $not: { $size: 0 } }});",
      "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": "db.accounts.countDocuments({ \"district.region\": $1, \"loans\": { $exists: true, $not: { $size: 0 } }});",
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "\"district.average_salary\": { $gt: 6000, $lt: 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": "\"district.average_salary\": { $gt: $1, $lt: $2 }"
      }
    }
  ],
  "value_searches": [
    {
      "query": "db.airports.aggregate([{ '$match': { 'iata': $value } }, { '$project': { 'value': '$iata', 'columns': 'airports.iata', 'concept_type': 'Airport IATA Code', 'distance': 0, 'context': '', '_id': 0 } }, { '$limit': 1 }])",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (standard MQL) for 3-letter airport codes"
    },
    {
      "query": "db.airports.aggregate([{ '$match': { 'name': { '$regex': $value, '$options': 'i' } } }, { '$project': { 'value': '$name', 'columns': 'airports.name', 'concept_type': 'Airport Name', 'distance': 0, 'context': '', '_id': 0 } }, { '$limit': 1 }])",
      "concept_type": "Airport Name",
      "description": "Regex match for partial airport names"
    },
    {
      "query": "db.products.aggregate([{ '$match': { '$text': { '$search': $value } } }, { '$project': { 'value': '$name', 'columns': 'airports.name', 'concept_type': 'Airport Name', 'distance': { '$meta': 'textScore' }, 'context': '', '_id': 0 } }, { '$sort': { 'distance': -1 } }, { '$limit': 1 }])",
      "concept_type": "Airport Name",
      "description": "Full-text search for airport names"
    }
  ]
}

上下文集文件格式

上下文集文件包含一组精选的模板、分面和值搜索，这些内容采用 JSON 格式，可指导 QueryData 等工具将自然语言问题转换为特定数据库的查询。定义上下文可确保针对常见查询句式生成高度准确的 MongoDB 兼容查询语言 (MQL)。

为最大限度地提高准确性，请确保上下文集准确且全面地涵盖预期应用查询。

可以在 us-central1、us-east1、europe-west4 和 asia-southeast1 区域中创建上下文集。

查询模板

查询模板是一组精选的代表性自然语言问题，其中包含相应的 MQL 查询。它们还包含说明，用于为自然语言到 MQL 的生成提供声明性依据。

查询模板对象类似于以下内容：

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "db.accounts.countDocuments({ \"district.region\": \"Prague\", \"loans\": { $exists: true, $not: { $size: 0 } }});",
      "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": "db.accounts.countDocuments({ \"district.region\": $1, \"loans\": { $exists: true, $not: { $size: 0 } }});"
      }
    }
  ],
  ...
}

查询模板 JSON 对象的主要组成部分如下：

nl_query：QueryData 等工具处理的自然语言查询示例。
sql：自然语言查询的 MQL 查询。尽管 sql 键的名称如此，但其中包含的是 MQL。
intent：自然语言查询的目标或用途。如果未设置，此值默认为自然语言查询。
manifest：意图的通用自动生成形式。
parameterized_intent：意图的模板化自动生成形式，实体值替换为参数。
parameterized_sql：与参数化意图对应的 MQL 查询的模板化自动生成形式。尽管 parameterized_sql 键的名称如此，但其中包含的是 MQL。

查询分面是一组精选的代表性自然语言条件，其中包含相应的 MQL 谓词。分面管理过滤条件和条件，使查询模板能够执行分面搜索。

查询分面对象类似于以下内容：

{
  ...
  "facets": [
    {
      "sql_snippet": "\"district.average_salary\": { $gt: 6000, $lt: 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": "\"district.average_salary\": { $gt: $1, $lt: $2 }"
      }
    }
  ]
}

分面 JSON 对象的主要组成部分如下：

sql_snippet：MQL 代码段。尽管 sql_snippet 键的名称如此，但其中包含的是 MQL。为避免歧义，请使用文档名称限定字段名称（例如 doc_name.field_name）。
intent：对 MQL 谓词的说明。
manifest：意图的通用自动生成形式。
parameterized_intent：意图的模板化自动生成形式，实体值替换为参数。
parameterized_sql_snippet：与参数化意图对应的 sql_snippet 的模板化自动生成形式。尽管 parameterized_sql_snippet 键的名称如此，但其中包含的是 MQL。

值搜索查询

值搜索查询 是开发者定义的查询，使用匹配函数在数据库中查找值及其上下文。值关联使用这些查询的结果来识别哪些表和列包含匹配的值，了解值的概念类型，并纠正拼写错误。

QueryData API 使用值关联将自然语言更准确地转换为 MQL。通过使用值搜索查询，API 可以根据数据库值纠正拼写错误并解析值类型，从而提高转换准确性。

值关联可提高自然语言到 MQL 的转换准确性。例如，如果用户问“有没有从希思罗机场起飞的航班？”，数据库可能会将机场名称存储为“London Heathrow”。如果没有值关联，生成的 MQL 可能会按 { "name": "Heathrow" } 进行过滤，并且不会返回任何结果。值搜索查询会引导代理将“Heathrow”映射到正确的数据库值“London Heathrow”及其架构位置 (airports.name)，确保生成的 MQL 准确无误。

值搜索查询示例：

{
  ...
  "value_searches": [
    {
      "query": "db.airports.aggregate([{ '$match': { 'iata': $value } }, { '$project': { 'value': '$iata', 'columns': 'airports.iata', 'concept_type': 'Airport IATA Code', 'distance': 0, 'context': '', '_id': 0 } }, { '$limit': 1 }])",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (standard MQL) for 3-letter airport codes"
    },
    {
      "query": "db.airports.aggregate([{ '$match': { 'name': { '$regex': $value, '$options': 'i' } } }, { '$project': { 'value': '$name', 'columns': 'airports.name', 'concept_type': 'Airport Name', 'distance': 0, 'context': '', '_id': 0 } }, { '$limit': 1 }])",
      "concept_type": "Airport Name",
      "description": "Regex match for partial airport names"
    },
    {
      "query": "db.products.aggregate([{ '$match': { '$text': { '$search': $value } } }, { '$project': { 'value': '$name', 'columns': 'airports.name', 'concept_type': 'Airport Name', 'distance': { '$meta': 'textScore' }, 'context': '', '_id': 0 } }, { '$sort': { 'distance': -1 } }, { '$limit': 1 }])",
      "concept_type": "Airport Name",
      "description": "Full-text search for airport names"

    }
  ]
}

值搜索 JSON 对象的主要组成部分如下：

query：参数化 MQL 语句，用于定义将值短语与数据库中存储的值进行匹配的逻辑。结果集通常会投影匹配的值、架构位置、概念类型和归一化距离指标（介于 0 和 1 之间）。
concept_type：分配给值的语义标签，例如 district 或 loan_status。此标签有助于值关联，并最终帮助 QueryData API 等工具了解值短语在架构中的作用。它还有助于生成针对值的概念的 MQL 语句，以及值短语在其中显示的表和列。
description：对搜索逻辑的说明。

限制

上下文集具有以下限制：

数据库的上下文集仅支持模板、分面和值搜索。
数据库的上下文集仅由 Conversational Analytics API 中的 QueryData 端点使用。

后续步骤

了解如何使用上下文工程代理构建上下文集。