QueryContent - 查询文档内容 - 云原生数据仓库AnalyticDB

用自然语句从指定文档库检索向量和元数据。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

gpdb:QueryContent

create

*Document

acs:gpdb:{#regionId}:{#accountId}:document/{#DBInstanceId}

无

请求参数

名称	类型	必填	描述	示例值
DBInstanceId	string	是	实例 ID。说明您可以调用 DescribeDBInstances 接口查看目标地域下所有的 AnalyticDB PostgreSQL 实例的详情，包括实例 ID。	gp-xxxxxxxxx
Namespace	string	否	命名空间，默认为 public。说明您可以通过 CreateNamespace 接口创建，通过 ListNamespaces 接口查看列表。	mynamespace
Collection	string	是	文档库名称。说明由 CreateDocumentCollection 接口创建。您可以调用 ListDocumentCollections 接口查看已经创建的文档库。	document
RegionId	string	是	实例所在的地域 ID。	cn-hangzhou
NamespacePassword	string	是	命名空间对应的密码。说明本值为 CreateNamespace 接口指定。	testpassword
Content	string	否	用于检索的文本内容。	ADBPG是什么？
Filter	string	否	要查询的数据的过滤条件，格式为 SQL 的 WHERE 格式。是一个返回布尔值（真或假）的表达式，条件可以是简单的比较运算符，如等于(=)、不等于(<>或!=)、大于(>), 小于(<)、大于等于(>=)、小于等于(<=)，也可以是逻辑运算符（AND, OR, NOT）组合的更复杂的表达式，以及使用 IN、BETWEEN、LIKE 等关键字的条件。说明详细语法可参考：https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-where/	title = 'test' AND name like 'test%'
RecallWindow	array	否	召回窗口。当该值不为空时，增加返回检索结果的上下文。格式为 2 个元素的数组：List<A, B>，其中-10<=A<=0，0<=B<=10。说明推荐当文档切分过碎、检索可能会丢失上下文信息时使用该参数。重排优先窗口化，即先 rerank，再窗口化处理。
	integer	否	召回窗口大小。	[-5, 5]
TopK	integer	否	返回 top 数量的结果。	10
RerankFactor	number	否	重排因子。当该值不为空时，会对向量检索结果再做一次重排。取值范围：1<RerankFactor<=5。说明当文档切分稀疏时，重排效率慢。建议重排个数（TopK*Factor（向上取整））不超过 50。	2
UseFullTextRetrieval	boolean	否	（参数废弃）是否使用全文检索（双路召回）。默认为 false，仅采用向量检索。	true
Metrics	string	否	检索时的相似度算法。此值为空时则采用创建知识库时指定的算法，建议如无特殊需求不需设置。说明取值说明： l2：欧氏距离。 ip：点积（内积）距离。 cosine：余弦相似度。	cosine
FileName	string	否	以图搜图场景中，待搜索的图片源文件名。说明图片文件必须带有文件后缀，当前支持的图片后缀：bmp、jpg、jpeg、png、 tiff。	test.jpg
FileUrl	string	否	以图搜图场景中，公网可访问的图片文件 URL 地址。说明图片文件必须带有文件后缀，当前支持的图片后缀：bmp、jpg、jpeg、png、tiff。	https://xx/myImage.jpg
IncludeVector	boolean	否	是否返回向量。默认为 false。说明 false：不返回向量。 true：返回向量。	true
HybridSearch	string	否	多路召回算法，默认为空(即直接将稠密向量和全文的分数比较并排序)。可选值： RRF：倒数排序融合(Reciprocal rank fusion)，有一个参数 k 控制融合效果，详见 HybridSearchArgs 配置； Weight：比重排序，采用参数控制向量和全文的分数比重，然后再排序，参数详见 HybridSearchArgs 配置； Cascaded：先全文检索再在其基础上进行向量检索；	RRF
HybridSearchArgs	object	否	多路召回的算法参数。目前支持 RRF 和 Weight 两种。HybridPathsSetting 可以指定召回稠密向量（dense）、稀疏向量（sparse）和全文检索（fulltext），如果值为空，默认召回稠密向量（dense）和全文检索（fulltext）。 RRF：指定计算分数的算法的`1/(k+rank_i)`中的 k 常数，范围大于 1 的正整数，格式为： `{ "HybridPathsSetting": { "paths": "dense,fulltext" }, "RRF": { "k": 60 } }` Weight: 双路召回（不指定 HybridPathsSetting，仅指定 alpha）：计算公式：alpha * dense_score + (1-alpha) * fulltext_score，参数 alpha 表示稠密向量和全文的检索分数比重，范围为 0～1，其中 0 表示只全文，1 表示只稠密向量： `{ "Weight": { "alpha": 0.5 } }` 三路召回模式：计算公式：normalized_dense * dense_score + normalized_sparse * sparse_score + normalized_fulltext * fulltext_score。其中 dense、sparse、fulltext 分别代表稠密向量、稀疏向量、全文检索的权重，取值范围大于等于 0。系统会自动将权重归一化到 0～1（即 normalized_x = x / (dense + sparse + fulltext)）。 `{ "HybridPathsSetting": { "paths": "dense,sparse,fulltext" }, "Weight": { "dense": 0.5, "sparse": 0.3, "fulltext": 0.2 } }`
	object	否	多路召回的参数名。
	any	否	参数值。	{ "HybridPathsSetting": { "paths": "dense,fulltext" }, "RRF": { "k": 60 } }
IncludeMetadataFields	string	否	默认为空，表示要返回的 metadata 字段，多个字段用逗号分隔。	title,page
IncludeFileUrl	boolean	否	是否同步返回文档的链接地址，默认不返回。	false
UrlExpiration	string	否	返回图片 URL 的有效期。说明取值说明支持以秒（s）和日（d）为单位。例如 300s 代表链接有效期为 300 秒，60d 代表链接有效期为 60 天。取值范围在 60s ~ 365d 之间。默认值：7200s，即 2 小时	7200s
GraphEnhance	boolean	否	是否开启知识图谱增强。默认值：false。	false
GraphSearchArgs	object	否	知识图谱检索参数。
GraphTopK	integer	否	返回 top 数量的实体和关系边。默认值：60。	60
OrderBy	string	否	默认为空，表示排序的依据字段。字段必须属于 metadata 或表里的默认字段比如 id，格式支持：单个字段，如 chunk_id；多个字段，用逗号连接，如 block_id, chunk_id；支持反序，如: block_id DESC, chunk_id DESC；	created_at
Offset	integer	否	偏移量，用于分页查询	0

返回参数

名称	类型	描述	示例值
	object
RequestId	string	请求 ID。	ABB39CC3-4488-4857-905D-2E4A051D0521
Message	string	返回信息。	success
Status	string	状态，取值如下： success：成功。 fail：失败。	success
Matches	object
MatchList	array<object>	匹配到的列表。
	array<object>	单条记录。
Id	string	向量数据的唯一 Id。	doca-1234
Content	string	文本内容。	云原生数据仓库AnalyticDB PostgreSQL版提供简单、快速、经济高效的PB级云端数据仓库解决方案。
Metadata	object	元数据 Map。
	string	元数据。	{"title":"test"}
Vector	object
VectorList	array	向量数据 List。
	number	向量数据。	[1.2123,-0.12314,...]
FileName	string	文件名。	my_doc.txt
Score	number	此条数据的相似度分数，其分数算法和创建索引时指定的算法(l2/ip/cosine)相关。	0.12345
RetrievalSource	integer	检索结果的来源。1 表示向量检索，2 表示全文检索，3 表示双路召回。	1
LoaderMetadata	string	文档加载器加载时的元信息。	{"page_pos": 1}
FileURL	string	查询结果图片的公网 URL 地址，有效时长默认为 2 小时。可通过入参 UrlExpiration 自行指定有效时长	https://xxx-cn-beijing.aliyuncs.com/image/test.png
RerankScore	number	重排分数。	6.2345
WindowMatches	object
windowMatches	array<object>	窗口化匹配到的列表。
	array<object>
WindowMatch	object
windowMatch	array<object>	单个 top 窗口化匹配到的列表。
	array<object>
Id	string	向量数据的唯一 ID。	doca-2345
Content	string	文本内容。	云原生数据仓库AnalyticDB PostgreSQL版是一种大规模并行处理（MPP）数据仓库服务，可提供海量数据在线分析服务。
Metadata	object	元数据 Map。
	string	元数据。	{"title":"test"}
FileName	string	文件名。	my_doc.txt
LoaderMetadata	string	文档加载器加载时的元信息。	{"page_pos": 2}
EmbeddingTokens	string	向量化时使用的 token 数。说明 token 是指将输入的文本分割成的最小单位；token 可以是一个单词、一个词组、一个标点符号、一个字符等。	100
Usage	object	本次查询的资源使用量
EmbeddingTokens	string	向量化时使用的 token 数。说明 token 是指将输入的文本分割成的最小单位；token 可以是一个单词、一个词组、一个标点符号、一个字符等。	100
EmbeddingEntries	string	向量化时使用的条目数。说明条目是指对文字、图片做向量化处理时的处理数目，如对文字做一次处理，条目数是 1，对图片做一次处理是 2。	10
Entities	object
entities	array<object>	实体列表。
	object	实体详情。
Id	string	实体 Id。	1
Entity	string	实体名称。	Dr. Wang
Type	string	实体类型。	人物
Description	string	实体描述。	A former advisor at DeepMind.
FileName	string	文件名。	my_doc.txt
Relations	object
relations	array<object>	关系边列表。
	object	关系边详情。
Id	string	关系边 Id。	1
SourceEntity	string	源实体。	DeepMind前顾问
TargetEntity	string	目标实体。	Dr. Wang
Description	string	关系边描述。	Dr. Wang previously served as an advisor at DeepMind.
FileName	string	文件名。	my_doc.txt

示例

正常返回示例

JSON格式

{
  "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
  "Message": "success",
  "Status": "success",
  "Matches": {
    "MatchList": [
      {
        "Id": "doca-1234",
        "Content": "云原生数据仓库AnalyticDB PostgreSQL版提供简单、快速、经济高效的PB级云端数据仓库解决方案。",
        "Metadata": {
          "key": "{\"title\":\"test\"}"
        },
        "Vector": {
          "VectorList": [
            0
          ]
        },
        "FileName": "my_doc.txt",
        "Score": 0.12345,
        "RetrievalSource": 1,
        "LoaderMetadata": "{\"page_pos\": 1}",
        "FileURL": "https://xxx-cn-beijing.aliyuncs.com/image/test.png",
        "RerankScore": 6.2345
      }
    ]
  },
  "WindowMatches": {
    "windowMatches": [
      {
        "WindowMatch": {
          "windowMatch": [
            {
              "Id": "doca-2345",
              "Content": "云原生数据仓库AnalyticDB PostgreSQL版是一种大规模并行处理（MPP）数据仓库服务，可提供海量数据在线分析服务。",
              "Metadata": {
                "key": "{\"title\":\"test\"}"
              },
              "FileName": "my_doc.txt",
              "LoaderMetadata": "{\"page_pos\": 2}"
            }
          ]
        }
      }
    ]
  },
  "EmbeddingTokens": "100",
  "Usage": {
    "EmbeddingTokens": "100",
    "EmbeddingEntries": "10"
  },
  "Entities": {
    "entities": [
      {
        "Id": "1",
        "Entity": "Dr. Wang",
        "Type": "人物",
        "Description": "A former advisor at DeepMind.",
        "FileName": "my_doc.txt"
      }
    ]
  },
  "Relations": {
    "relations": [
      {
        "Id": "1",
        "SourceEntity": "DeepMind前顾问",
        "TargetEntity": "Dr. Wang",
        "Description": "Dr. Wang previously served as an advisor at DeepMind.",
        "FileName": "my_doc.txt\n"
      }
    ]
  }
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。