query

最近更新时间：2024-01-18 17:43:01

我的收藏

本页目录：

功能介绍
/document/query 接口用于精确查找与查询条件完全匹配的向量，具体支持如下功能。
支持根据主键 id（Document ID），搭配自定义的标量字段的 Filter 表达式一并检索。
支持指定查询起始位置 offset 和返回数量 limit，实现数据 SCAN 能力。
请求示例
注意：
如下示例可直接复制，在 CVM 运行之前，您需在文本编辑器将 api_key=A5VOgsMpGWJhUI0WmUbY******************** 与 10.0.X.X 依据实际情况进行替换。 
使用 /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 名称。
-
是
使用 /database/list 获取集群中的数据库列表，复制需查询数据的集合所属的数据库名。
collection
指定要查询的Collection 名称。
-
是
使用/collection/list 获取指定数据库名下的 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 参数均可以配置是否输出向量值，二者任意一个配置需输出向量字段，则将输出向量字段。
?
响应消息
HTTP 响应消息体是服务器返回给客户端的数据，通常包含了请求的结果或者所请求的资源。/document/query 接口返回的状态码以及相关信息，如下所示。
状态码
状态码
含义
响应信息
200
查询数据成功
?
返回所查询的 Document，具体信息，请参见返回消息。
400
查询数据失败
{
  "code": 400,
  "msg": "operation failed, reason...."
}
返回消息
查询结果，如下所示，返回了 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 的文本字段。
?
?

上一篇: upsert 下一篇: search

参数名称	参数含义	子参数	是否必选	配置方法及要求
database	指定要查询的Database 名称。	-	是	使用 /database/list 获取集群中的数据库列表，复制需查询数据的集合所属的数据库名。
collection	指定要查询的Collection 名称。	-	是	使用/collection/list 获取指定数据库名下的 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 参数均可以配置是否输出向量值，二者任意一个配置需输出向量字段，则将输出向量字段。 ?

参数名	子参数	参数含义
count	-	统计返回的 Document 数量。
documents	id	Document 的 ID 信息。
	?	vector	Document 的向量值。
	?	other_scalar_field	Document 其他自定义的标量字段。例如：author、page、bookName。说明：自定义输出字段为在请求参数 outputFields 中配置的字段。如果创建 Collection 时配置 Embedding 参数，写入原始文本，则可通过 outputFields 参数配置输出 Embedding 的文本字段。 ?

状态码	含义	响应信息
200	查询数据成功	? 返回所查询的 Document，具体信息，请参见返回消息。
400	查询数据失败	{ "code": 400, "msg": "operation failed, reason...." }