调用QueryCollectionData API召回向量数据-云原生数据仓库AnalyticDB-阿里云-云原生数据仓库AnalyticDB(AnalyticDB)-阿里云帮助中心

召回向量数据。

调试

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

调试

授权信息

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

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

操作

访问级别

资源类型

条件关键字

关联操作

gpdb:QueryCollectionData

create

*Collection

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

无

请求参数

名称	类型	必填	描述	示例值
DBInstanceId	string	否	实例 ID。说明您可以调用 DescribeDBInstances 接口查看目标地域下所有的 AnalyticDB PostgreSQL 实例的详情，包括实例 ID。	gp-xxxxxxxxx
Collection	string	是	集合名。说明您可以通过 ListCollections 接口查看列表。	document
Namespace	string	否	命名空间。说明您可以通过 ListNamespaces 查看列表。	mynamespace
NamespacePassword	string	是	命名空间对应的密码。	testpassword
Content	string	否	用于全文检索的内容。即此值为空时，仅使用向量检索；不为空时，使用向量和全文双路检索。说明和 Vector 参数不能同时为空。	hello_world
Filter	string	否	要查询的数据的过滤条件，格式为 SQL 的 WHERE 格式。是一个返回布尔值（真或假）的表达式，条件可以是简单的比较运算符，如等于(=)、不等于(<>或!=)、大于(>), 小于(<)、大于等于(>=)、小于等于(<=)，也可以是逻辑运算符（AND, OR, NOT）组合的更复杂的表达式，以及使用 IN、BETWEEN、LIKE 等关键字的条件。说明详细语法可参考：https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-where/	pipeline_id='1yhpmo0rbn' AND (spu='10025667796135' AND dept_id='226')
TopK	integer	是	设置返回 top 结果数量。	10
Vector	array	否	向量数据，长度和 CreateCollection 接口的维度一致。说明当 SparseVector 为空时，只返回稠密向量检索结果。当 Vector 和 SparseVector 均为空时，只返回全文检索结果。
	number	否	向量数据。	1.234
SparseVector	object	否	稀疏向量数据列表。
Indices	array	否	下标数组。说明列表大小不能超过 4000。
	integer	否	下标值。	1
Values	array	否	稀疏向量数组。
	number	否	稀疏向量数据。	1.2345
RegionId	string	是	实例所在地域 ID。	cn-hangzhou
Metrics	string	否	检索时的相似度算法。取值说明： l2：欧氏距离。 ip：点积（内积）距离。 cosine：余弦相似度。说明此值为空时，则使用构建索引时指定的算法。	cosine
IncludeValues	boolean	否	是否返回稠密向量数据。取值说明： true：返回稠密向量数据。 false：不返回稠密向量数据。	true
HybridSearch	string	否	双路召回算法，默认为空(即直接将向量和全文的分数比较并排序)。可选值： RRF：倒数排序融合(Reciprocal rank fusion)，有一个参数 k 控制融合效果，详见 HybridSearchArgs 配置； Weight：比重排序，采用一个参数 alpha 控制向量和全文的分数比重，然后再排序，参数详见 HybridSearchArgs 配置； Cascaded：先全文检索再在其基础上进行向量检索；	RRF
HybridSearchArgs	object	否	双路召回的算法参数。目前支持 RRF 和 Weight 两种： RRF：指定计算分数的算法的`1/(k+rank_i)`中的 k 常数，范围大于 1 的正整数，格式为： `{ "RRF": { "k": 60 } }` Weight: 计算公式`alpha * vector_score + (1-alpha) * text_score`，参数 alpha 表示向量和全文的检索分数比重，范围为 0～1，其中 0 表示只全文，1 表示只向量： `{ "Weight": { "alpha": 0.5 } }`
	object	否	召回算法。
	any	否	召回算法配置。	{ "RRF": { "k": 60 } }
OrderBy	string	否	默认为空，表示排序的依据字段。不支持双路召回场景。字段必须属于 metadata 或表里的默认字段比如 id，格式支持：单个字段，如 chunk_id；多个字段，用逗号连接，如 block_id, chunk_id；支持反序，如: block_id DESC, chunk_id DESC；	chunk_id
Offset	integer	否	默认为空，表示分页查询时的检索起点。不支持双路召回场景。范围必须>=0。当此值不为空时，会返回 Total 表示总的命中数。此参数配合 TopK 使用，比如要分页 20 检索 chunk_id 0~44 的 chunks，则要请求 3 次： Offset=0,TopK=20 返回 chunk_id 0~19 Offset=20,TopK=20 返回 chunk_id 20~39 Offset=30,TopK=20 返回 chunk_id 40~44	0
IncludeMetadataFields	string	否	默认为空，表示要返回的 metadata 字段，多个字段用逗号分隔。	title,content
WorkspaceId	string	否	多数据库实例组成的 Workspace 的 Id。此参数和 DBInstanceId 参数不能同时为空，当和 DBInstanceId 同时指定时以此参数为准。	gp-ws-*****
RelationalTableFilter	object	否	使用另外一张关系表实现向量数据过滤（类似 Join 的功能）。说明关系表的数据可以通过设置 IncludeMetadataFields 参数返回。比如 rds_table_name.id 表示返回关系表的 id 字段。
CollectionMetadataField	string	否	向量集的 Metadata 字段，用来和向量表的字段关联。	doc_id
TableField	string	否	关系表的字段，用来和向量集的 Metadata 的字段做关联。	id
TableName	string	否	关系表的名称。	my_rds_table
Condition	string	否	关系表的过滤条件。	tags @> ARRAY['art']
IncludeSparseValues	boolean	否	是否返回稀疏向量数据。取值说明： true：返回稀疏向量数据。 false：不返稀疏回向量数据。	false

返回参数

名称

类型

描述

示例值

object

召回结果。

Matches

object

match

array<object>

数据列表。

array<object>

单条记录。

string

向量数据的唯一 ID。

doca-1234

Metadata

object

元数据。

string

元数据内容。

{"title":"test title", "content": "test content"}

Values

object

value

array

向量数据列表。

number

向量数据。

1.234

Score

number

此条数据的相似度分数，其分数算法和创建索引时指定的算法(l2/ip/cosine)相关。

0.12345

SparseValues

object

稀疏向量返回体

Indices

object

Indice

array

稀疏向量索引数组

integer

稀疏向量索引值

Values

object

Value

array

稀疏向量值数组

number

稀疏向量值

0.222

MetadataV2

object

元数据。值与 Metadata 一致，元素类型区别于 Metadata，用于在 SDK 端透出任意类型。

any

该字段可容纳多种数据类型，由 SDK 按以下规则进行反序列化。

说明

反序列化规则

ADBPG 数据类型	Java SDK 反序列化类型	Python SDK 反序列化类型
整数(integer, bigint)	Long	int
浮点数(real, double precision)	Double	float
布尔值(boolean)	Boolean	bool
字符串(text, character varying)	String	str
数组(如 int[], text[])	ArrayList<T>(T 类型按本表规则映射)	list
json	String	String

{'array_field': [15.5, 25.5, 35.5], 'float_field': 128.45, 'long_field': 123456789017, 'bool_field': False, 'json_field': '{"key1":"value1","num":999.0}', 'char_array_field': '[c, h, a, r, s, 5]', 'int_field': 128, 'source': 0, 'double_field': 12350.6789, 'string_field': 'test_string_5'}

RequestId

string

请求 ID。

ABB39CC3-4488-4857-905D-2E4A051D0521

Status

string

状态，取值说明：

success：成功。
fail：失败。

success

Message

string

请求失败时的详细信息。

0.1234

Total

integer

当请求 Offset 不为 0 时才返回，返回值为该检索条件的命中总数。

100

示例

正常返回示例

JSON格式

{
  "Matches": {
    "match": [
      {
        "Id": "doca-1234",
        "Metadata": {
          "key": "{\"title\":\"test title\", \"content\":  \"test content\"}"
        },
        "Values": {
          "value": [
            1.234
          ]
        },
        "Score": 0.12345,
        "SparseValues": {
          "Indices": {
            "Indice": [
              20
            ]
          },
          "Values": {
            "Value": [
              0.222
            ]
          }
        },
        "MetadataV2": {
          "key": "{'array_field': [15.5, 25.5, 35.5], 'float_field': 128.45, 'long_field': 123456789017, 'bool_field': False, 'json_field': '{\"key1\":\"value1\",\"num\":999.0}', 'char_array_field': '[c, h, a, r, s, 5]', 'int_field': 128, 'source': 0, 'double_field': 12350.6789, 'string_field': 'test_string_5'}"
        }
      }
    ]
  },
  "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
  "Status": "success",
  "Message": "0.1234",
  "Total": 100
}

错误码

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

变更历史

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