Method 与 URL
精确查找与查询条件完全匹配的向量:
POST https://{实例访问 IP 地址}:{实例网络端口}/document/query
。支持根据主键 id(Document ID),搭配自定义的标量字段的 Filter 表达式一并检索。
支持指定查询起始位置 offset 和返回数量 limit,实现数据 SCAN 能力。
使用示例
使用 /document/query 接口,查询集合 book-vector 中, Document Id 为 0001、0002、0003中,满足 Filter 表达式
bookName in (\\"三国演义\\",\\"西游记\\")
的文档。curl -i -X POST \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\http://10.0.X.X:80/document/query \\-d '{"database": "db-test","collection": "book-vector","readConsistency": "eventualConsistency","query": {"documentIds": ["0001","0002","0003"],"retrieveVector": true,"filter": "bookName in (\\"三国演义\\",\\"西游记\\")","limit": 3,"offset": 0,"outputFields": ["id","author","bookName","page"]}}'
请求参数
参数名称 | 参数含义 | 子参数 | 是否必选 | 配置方法及要求 |
database | 指定要查询的Database 名称。 | - | 是 | |
collection | 指定要查询的Collection 名称。 | - | 是 | |
readConsistency | 配置读一致性要求。 | - | 否 | 取值如下所示,默认为 eventualConsistency。 strongConsistency:强一致性。 eventualConsistency:最终一致性。 |
query |
设置查询条件。
| documentIds | 否 | 表示要查询的文档的所有 ID,支持批量查询,数组元素范围[1,20]。 |
| | retrieveVector | 否 | 标识是否需要返回检索结果的向量值。 true:需要。 false:不需要。默认为 false。 |
| | filter | 否 | 使用创建 Collection 指定的 Filter 索引的字段设置查询过滤表达式。Filter 的表达式格式为 '<field_name><operator><value>',多个表达式之间支持 and(与)、or(或)、not(非)关系。具体信息,请参见 Filter 条件表达式。其中 <field_name>:表示要过滤的字段名。 <operator>:表示要使用的运算符。 string:匹配单个字符串值(=)、排除单个字符串值(!=)、匹配任意一个字符串值(in)、排除所有字符串值(not in)。其对应的 Value 必须使用英文双引号括起来。 unit64:大于(>)、大于等于(>=)、等于(=)、小于(<)、小于等于(<=)。例如,exipred_time > 1623388524。 array:数组类型,包含数组元素之一(include)、排除数组元素之一(exclude)、全包含数组元素(include all)。例如,name include (\\"Bob\\", \\"Jack\\")。 <value>:表示要匹配的值。 示例: Filter('author="jerry"').And('page>20')。 |
| | limit | 是 | 每页返回的 Document 数量。默认为 1。 数据类型:uint 64。 取值范围:[1,16384] 注意: 若使用 query 检索数据时,不配置 documentIds 和 filter 参数,则必须配置 offeset 和 limit 参数,返回从 offset 开始的 limit 条数据,避免遍历所有数据而浪费不必要的资源。 |
| | offset | 否 | 设置分页偏移量,用于控制分页查询返回结果的起始位置,方便用户对数据进行分页展示和浏览。 取值:为 limit 整数倍。 计算公式:offset = limit * (page-1)。 例如:当 limit = 10,page = 2 时,分页偏移量 offset = 10 * (2 - 1) = 10,表示从查询结果的第 11 条记录开始返回数据。 |
| | outputFields | 否 | 以数组形式配置需返回的字段。 说明: outputFields 与 retrieveVector 参数均可以配置是否输出向量值,二者任意一个配置需输出向量字段,则将输出向量字段。 |
响应消息
查询结果,如下所示,返回了 id(Document ID) 为 2 的文档数据。
{"code": 0,"msg": "operation success","count": 2,"documents": [{"id": "0001","vector": [0.21230000257492066,0.23000000417232514,0.21299999952316285],"page": 21,"author": "罗贯中","bookName": "三国演义"},{"id": "0002","vector": [0.21230000257492066,0.2199999988079071,0.21299999952316285],"page": 22,"bookName": "西游记","author": "吴承恩"}]}
参数名 | 子参数 | 参数含义 |
count | - | 统计返回的 Document 数量。 |
documents | id | Document 的 ID 信息。 |
| vector | Document 的向量值。 |
| other_scalar_field | Document 其他自定义的标量字段。例如:author、page、bookName。 说明: 自定义输出字段为在请求参数 outputFields 中配置的字段。 如果创建 Collection 时配置 Embedding 参数,写入原始文本,则可通过 outputFields 参数配置输出 Embedding 的文本字段。 |