向量数据库 query

本接口（/document/query）用于精确查找与查询条件完全匹配的文档。
支持根据主键 id（Document ID），搭配自定义的标量字段的 Filter 表达式一并检索。
支持指定查询起始位置 offset 和返回数量 limit，实现数据 SCAN 能力。
Method 与 URL
POST https://{实例访问 IP 地址}:{实例网络端口}/document/query
使用示例
使用 /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 必须使用英文双引号括起来。
uint64：大于（>）、大于等于（>=）、等于（=）、小于（<）、小于等于（<=）、不等于（!=）。例如，exipred_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>：表示要匹配的值。
﻿
﻿
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条记录开始返回数据。
﻿
﻿
sort
否
指定查询结果按照特定字段升序（或降序）排序，数据类型为数组。
"sort": [{
    "fieldName": "scalar1",
    "direction": "desc"
}]
fieldName：指定特定字段，查询结果将依据该字段确定输出顺序。当前排序字段仅支持 uint64 的类型，且该字段为标量字段索引，可通过接口 describe 确认该字段是否为索引字段。
说明：
当满足条件的数据量小于或等于1000时，orderby 操作将正常生效，否则会引发错误。
目前仅支持对单个字段进行排序，暂时不支持多字段排序功能。
direction：指定排序的方向。
desc：降序排序。
asc：升序排序，默认为 asc。
﻿
﻿
outputFields
否
以数组形式配置需返回的字段。
说明：
outputFields 与 retrieveVector 参数均可以配置是否输出向量值，二者任意一个配置需输出向量字段，则将输出向量字段。
输出 Json 字段时，outputFields 仅支持指定 Json 字段的名称，而不支持直接指定 Json 字段内部的键（key）。例如，写入"a": {"b": "test", "c": 12}，outputFields 只能指定返回整个 "a" 字段，而无法单独指定返回 "a.b" 。
响应消息
查询结果，如下所示，返回了 id（Document ID）为2的文档数据。
{
  "code": 0,
  "msg": "Operation success",
  "count": 2,
  "documents": [
    {
      "id": "0002",
      "vector": [
        0.21230000257492066,
        0.2199999988079071,
        0.21299999952316285
      ],
      "sparse_vector": [
        [2, 0.9700000286102295],
        [5, 0.5400000214576721],
        [100, 0.4449999928474426]
      ],
      "bookName": "西游记",
      "page": 22,
      "author": "吴承恩"
    },
    {
      "id": "0001",
      "vector": [
        0.21230000257492066,
        0.23000000417232514,
        0.21299999952316285
      ],
      "sparse_vector": [
        [2, 0.9599999785423279],
        [5, 0.5299999713897705],
        [100, 0.4429999887943268]
      ],
      "page": 21,
      "author": "罗贯中",
      "bookName": "三国演义"
    }
  ]
}
参数名
子参数
参数含义
count
-
统计返回的 Document 数量。
documents
id
Document 的 ID 信息。
﻿
vector
Document 的向量值。
﻿
other_scalar_field
Document 其他自定义的标量字段。例如：author、page、bookName。
说明：
自定义输出字段为在请求参数 outputFields 中配置的字段。
如果创建 Collection 时配置 Embedding 参数，写入原始文本，则可通过 outputFields 参数配置输出 Embedding 的文本字段。

参数名称	参数含义	子参数	是否必选	配置方法及要求
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 必须使用英文双引号括起来。 uint64：大于（>）、大于等于（>=）、等于（=）、小于（<）、小于等于（<=）、不等于（!=）。例如，exipred_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>：表示要匹配的值。
				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条记录开始返回数据。
				sort	否	指定查询结果按照特定字段升序（或降序）排序，数据类型为数组。 "sort": [{ "fieldName": "scalar1", "direction": "desc" }] fieldName：指定特定字段，查询结果将依据该字段确定输出顺序。当前排序字段仅支持 uint64 的类型，且该字段为标量字段索引，可通过接口 describe 确认该字段是否为索引字段。说明：当满足条件的数据量小于或等于1000时，orderby 操作将正常生效，否则会引发错误。目前仅支持对单个字段进行排序，暂时不支持多字段排序功能。 direction：指定排序的方向。 desc：降序排序。 asc：升序排序，默认为 asc。
				outputFields	否	以数组形式配置需返回的字段。说明： outputFields 与 retrieveVector 参数均可以配置是否输出向量值，二者任意一个配置需输出向量字段，则将输出向量字段。输出 Json 字段时，outputFields 仅支持指定 Json 字段的名称，而不支持直接指定 Json 字段内部的键（key）。例如，写入`"a": {"b": "test", "c": 12}`，outputFields 只能指定返回整个 "a" 字段，而无法单独指定返回 "a.b" 。

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

query

本页目录：

Method 与 URL

使用示例

请求参数

响应消息