·支持根据指定 id 或向量数值进行相似度检索，返回指定的 Top K 个最相似的 Document。
·支持根据主键 id（Document ID）或向量数值，搭配自定义的标量字段的 Filter 表达式一并进行相似度检索。
·配置 Embedding 参数，支持输入原始文本检索与输入文本相似的文档，同时，支持搭配标量字段的 Filter 表达式一并检索。
一、Method 与 URL
POST https://{实例访问 IP 地址}:{实例网络端口}/document/search。
注意：说明：
注意：search 接口支持根据主键 id（Document ID）、向量 vector 以及文本进行检索。id、vector、文本仅需指定其中一个即可。
二、使用示例
根据文本进行向量检索根据 id（Document ID）进行向量检索根据 Vector 进行向量检索二进制向量检索json 类型检索
如果使用腾讯云向量数据库（Tencent Cloud VectorDB）的 Embedding 功能，基于 /document/upsert 写入的原始文本，在集合 book-emb 中，使用 /document/search 接口查询与输入文本'天下大势，分久必合，合久必分'最相似，且满足过滤条件的 Top3 数据。因写入文本数据为高维数据，不便于显示，则设置 retrieveVector 参数为 false，检索信息不显示向量数据。
curl -i -X POST \\ -H 'Content-Type: application/json' \\ -H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\ http://10.0.X.X:80/document/search \\ -d '{ "database": "db-test", "collection": "book-emb", "search": { "embeddingItems": [ "天下大势，分久必合，合久必分" ], "limit": 3, "params": { "ef": 200 }, "retrieveVector": false, "filter": "bookName in (\\"三国演义\\",\\"西游记\\")", "outputFields": [ "id", "author", "text", "bookName" ] }}'
检索信息如下所示。具体返回参数含义，请参见 输出参数。
注意：说明：
{ "code": 0, "msg": "operation success", "embeddingExtraInfo":{"tokenUsed":14}, "documents": [ [ { "id": "0001", "score": 0.9792741537094116, "bookName": "三国演义", "author": "罗贯中", "text": "话说天下大势，分久必合，合久必分。" }, { "id": "0002", "score": 0.7909858226776123, "bookName": "西游记", "author": "吴承恩", "text": "混沌未分天地乱，茫茫渺渺无人间。" } ] ]
基于 /document/upsert 写入的向量数据，使用 /document/search 接口在集合 book-vector 中，查询与 id（Document ID）为0001、 0002、0003最相似，且满足过滤条件的 Top3 数据。
curl -i -X POST \\ -H 'Content-Type: application/json' \\ -H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\ http://10.0.X.X:80/document/search \\ -d '{ "database": "db-test", "collection": "book-vector", "search": { "documentIds": [ "0001", "0002", "0003" ], "params": { "ef": 200 }, "retrieveVector": true, "filter": "bookName in (\\"三国演义\\",\\"西游记\\")", "limit": 3 }}'
检索信息，如下所示。
注意：说明：
{ "code": 0, "msg": "operation success", "documents": [ [ { "id": "0001", "vector": [ 0.21230000257492066, 0.23000000417232514, 0.21299999952316285 ], "score": 1.0000001192092896, "author": "罗贯中", "bookName": "三国演义", "page": 21 }, { "id": "0002", "vector": [ 0.21230000257492066, 0.2199999988079071, 0.21299999952316285 ], "score": 0.9997729659080505, "bookName": "西游记", "author": "吴承恩", "page": 22 } ], [ { "id": "0002", "vector": [ 0.21230000257492066, 0.2199999988079071, 0.21299999952316285 ], "score": 1.000000238418579, "author": "吴承恩", "page": 22, "bookName": "西游记" }, { "id": "0001", "vector": [ 0.21230000257492066, 0.23000000417232514, 0.21299999952316285 ], "score": 0.9997729659080505, "bookName": "三国演义", "author": "罗贯中", "page": 21 } ], [ { "id": "0002", "vector": [ 0.21230000257492066, 0.2199999988079071, 0.21299999952316285 ], "score": 0.9997580051422119, "author": "吴承恩", "bookName": "西游记", "page": 22 }, { "id": "0001", "vector": [ 0.21230000257492066, 0.23000000417232514, 0.21299999952316285 ], "score": 0.9990617632865906, "page": 21, "bookName": "三国演义", "author": "罗贯中" } ] ]}
基于 /document/upsert 写入的向量数据，则可使用 /document/search 接口，在集合 book-vector 中，根据指定向量以及过滤条件，查找 Top 3 个相似性结果。
curl -i -X POST \\ -H 'Content-Type: application/json' \\ -H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\ http://10.0.X.X:80/document/search \\ -d '{ "database": "db-test", "collection": "book-vector", "search": { "vectors": [ [ 0.3123, 0.43, 0.213 ] ], "params": { "ef": 200 }, "filter": "bookName in (\\"三国演义\\",\\"西游记\\")", "retrieveVector": true, "limit": 3 }}'
检索信息如下所示。具体返回参数含义，请参见 输出参数。
注意：说明：
{ "code": 0, "msg": "operation success", "documents": [ [ { "id": "0001", "vector": [ 0.21230000257492066, 0.23000000417232514, 0.21299999952316285 ], "score": 0.9714228510856628, "page": 21, "author": "罗贯中", "bookName": "三国演义" }, { "id": "0002", "vector": [ 0.21230000257492066, 0.2199999988079071, 0.21299999952316285 ], "score": 0.9668837785720825, "bookName": "西游记", "author": "吴承恩", "page": 22 } ] ]}
curl -i -X POST \\ -H 'Content-Type: application/json' \\ -H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\ http://10.0.X.X:80/document/search \\ -d '{ "database": "db-test", "collection": "bin-vector", "search": { "vectors": [ [ 20, 18 ] ], "retrieveVector": true, "limit": 2 }}'响应信息，如下所示。{"code":0,"msg":"Operation success","documents":[[{"id":"0001","vector":[21.0,13.0],"score":6.0,"page":21}]]}
如下示例，使用 json 类型的字段 bookInfo 的 Filter 表达式检索数据。curl -i -X POST \\ -H 'Content-Type: application/json' \\ -H 'Authorization: Bearer account=root&api_key=9M6AucQGql5FlMyuBNnUuzrd10W7MTmZ0L2ZFDx7' \\ http://gz-vdb-jggokqoy.sql.tencentcdb.com:8100/document/search \\ -d '{ "database": "db-test-1", "collection": "coll-json-test", "search": { "vectors": [ [ 0.3123, 0.43, 0.213 ] ], "params": { "ef": 200 }, "filter": "bookInfo.bookName in (\\"三国演义\\",\\"西游记\\")", "retrieveVector": true, "limit": 3 }}'
三、请求参数
| 参数名称 | 参数含义 | 子参数 | 是否必选 | 配置方法及要求 |
| database | 指定要查询的Database 名称。 | – | 是 | 使用 /database/list 获取集群中的数据库列表，复制需查询数据的集合所属的数据库名。 |
| collection | 指定要查询的Collection 名称。 | – | 是 | 使用 /collection/list 获取指定数据库名下的 Collection 列表，复制需查询数据的集合名。 |
| readConsistency | 设置检索数据的一致性要求。 | – | 否 | 取值如下所示：strongConsistency：强一致性。eventualConsistency：最终一致性。 |
| search | 表示查询条件。 | vectors | 否 | 指定要查询的向量列表。数组元素数量最大为20。vectors 与 documentIds 两个字段，只需配置其中一个即可。集合为二进制索引时，支持使用十进制写入。原始二进制每8bit（即1字节）被视为向量的一个维度的值。以十进制写入数据的长度=创建集合时指定的维度/8。例如：创建集合时，指定的维度为128，那么写入数据时元素的长度只能为16。 |
| | | documentIds | 否 | 指定待查询的文档 ID 列表。数组元素数量最大为20。注意：vectors、documentIds、embeddingItems 三个字段，只需配置其中一个即可。这三个字段任何一个可以结合 filter 字段进行混合检索。 |
| | | embeddingItems | 否 | 输入文本信息，用于检索与该文本信息相似的数据。类型：字符串数组。范围：数组元素最大批量为20。 |
| | | params | 否 | 创建集合时，向量索引类型不同，检索时，所需配置的参数不同。FLAT ：无需指定参数。HNSW 类型：需配置参数 ef，指定需要访问向量的数目。取值范围[1,32768]，默认为10。IVF_RABITQ/IVF 系列：需设置参数 nprobe ，指定所需查询的单位数量。取值范围[1,nlist]，其中 nlist 在创建 Collection 时已设置，可通过 /collection/list 查看。 |
| | | filter | 否 | 使用创建 Collection 指定的 Filter 索引的字段设置查询过滤表达式。Filter 表达式格式为 <field_name><operator><value>，多个表达式之间支持 and（与）、or（或）、not（非）关系。具体信息，请参见 Filter 表达式。其中： <field_name>：表示要过滤的字段名。<operator>：表示要使用的运算符。string ：匹配单个字符串值（=）、排除单个字符串值（!=）、匹配任意一个字符串值（in）、排除所有字符串值（not in）。其对应的 Value 必须使用英文双引号括起来。uint64/int64/double：大于（>）、大于等于（>=）、等于（=）、小于（<）、小于等于（<=）、不等于（!=）。例如：expired_time > 1623388524。array：数组类型，包含数组元素之一（include）、排除数组元素之一（exclude）、全包含数组元素（include all）。例如，name include (\\"Bob\\", \\"Jack\\")。json：json 类型的 Filter 表达式语法和 json 字段的键值类型保持一致。若访问 Json 对象中的键，使用点（.）符号连接。例如：Json 类型的字段 bookInfo ，其键 bookName 的 Filter 表达式如下所示。更多信息，请参见 Json 类型表达式。"filter": "bookInfo.bookName in (\\"三国演义\\",\\"西游记\\")"<value>：表示要匹配的值。 |
| | | retrieveVector | 否 | 标识是否需要返回检索结果的向量值。true：需要。false：不需要。默认为 false。 |
| | | limit | 是 | 指定返回最相似的 Top K 条数据的 K 的值。K 为大于0的正整数。 |
| | | radius | 否 | 指定相似性检索的半径范围。每一种相似性计算方法的检索半径范围如下所示。IP：检索结果返回满足 score >= radius 的数据，此时，radius 取值范围为 (-∞, +∞)。COSINE：检索结果返回满足 score >= radius 的数据。此时，radius 取值范围为 [-1, 1]L2：检索结果返回满足 score <= radius 的数据。此时，radius 取值范围为 [0, +∞)说明：支持的索引类型为：FLAT、IVF 系列。检索结果将限定在指定的检索半径内，并根据你设置的 'limit' 参数值来确定返回结果的数量。 |
| | | outputFields | 否 | 指定需要输出的字段。若不设置，将返回所有字段。说明：retrieveVector 和 outputFields 只要有其中一个配置输出向量字段即可输出 vector。输出 Json 字段时，outputFields 仅支持指定 Json 字段的名称，而不支持直接指定 Json 字段内部的键（key）。例如，写入"a": {"b": "test", "c": 12}，outputFields 只能指定返回整个 "a" 字段，而无法单独指定返回 "a.b" 。 |
四、输出参数
| 参数名 | 参数名 | 参数含义 |
| embeddingExtraInfo | tokenUsed | 使用 Embedding 功能已经消耗的 Token 数量。 |
| documents | id | Document 的 ID 信息。 |
| | vector | Document 的向量值。 |
| | score | 表示查询向量与检索结果向量之间的相似性计算分数。欧式距离（L2）与汉明距离（Hamming Distance）计算所得的分数越小与搜索值越相似；而余弦相似度（COSINE）与内积（IP） 计算所得的分数越大与搜索值越相似。 |
| | text | 如果该 Collection 开启 Embedding 功能，在建表时，指定文本信息的字段名，则显示该字段。 |
| | other_scalar_field | Document 其他自定义的标量字段。例如：author、bookName、page 等。 |