更新时间:2025-07-18 GMT+08:00
分享

标量查询

功能介绍

接口用于精确查找与查询条件完全匹配的向量,此操作使用指定的布尔表达式对标量字段进行筛选。

URI

POST /v1/entities/query

请求参数

表1 请求Body参数

参数

是否必选

参数类型

描述

store_name

String

参数解释:

知识仓实例名称,region内唯一。

约束限制:

长度范围为3到63个字符,支持小写字母、数字、中划线(-),第一个字符只能够是小写字母,中划线(-)不得出现在字符串末尾。

取值范围:

不涉及。

默认取值:

不涉及。

collection_name

String

参数解释:

collection名称,知识仓内唯一。

约束限制:

长度范围为1到255个字符,支持字母、数字、中划线(-)和下划线(),大小写敏感。第一个字符只能够是下划线()和字母,中划线(-)不得出现在字符串末尾。

取值范围:

不涉及。

默认取值:

不涉及。

output_fields

Array of strings

参数解释:

field名称列表,配置需与搜索结果一起返回的字段。

约束限制:

当取值为["count(*)"]时,top_k必须为负数,表示统计符合条件的entity数量。

取值范围:

不涉及。

默认取值:

[ ],不返回任何额外的字段数据。

top_k

Integer

参数解释:

返回的entity个数限制。可以将此参数与offset结合使用以启用分页。当取值为负数时,表示返回所有符合条件的数据。

约束限制:

与offset取值的总和应小于16384。当output_field为["count(*)"]时,top_k必须为负数。

取值范围:

小于等于16384

默认取值:

10

offset

Integer

参数解释:

在搜索结果中跳过的记录数。可以将此参数与 top_k 参数结合使用以启用分页。

约束限制:

与top_k取值的总和应小于16384。

取值范围:

大于等于0

默认取值:

0

filter

String

参数解释:

用于过滤匹配entity的标量过滤条件。

约束限制:

要构建标量过滤条件,请参阅filter表达式规则。

取值范围:

不涉及。

默认取值:

不涉及。

响应参数

状态码:200

表2 响应Body参数

参数

参数类型

描述

code

String

参数解释:

返回码。参见错误码章节。

约束限制:

不涉及。

取值范围:

不涉及。

默认取值:

不涉及。

message

String

参数解释:

描述信息

约束限制:

不涉及。

取值范围:

不涉及。

默认取值:

不涉及。

data

entities_data object

参数解释:

响应数据。

约束限制:

不涉及。

表3 entities_data

参数

参数类型

描述

entities

Array of entity objects

参数解释:

查询到的信息。

约束限制:

不涉及。

表4 entity

参数

参数类型

描述

{自定义key}

Map<String,Object>

参数解释:

collection中的一个基本结构化数据实体,包含向量和标量等字段数据。

约束限制:

必须满足目标collection field schema。

取值范围:

不涉及。

默认取值:

不涉及。

状态码:400

表5 响应Body参数

参数

参数类型

描述

code

String

参数解释:

返回码。参见错误码章节。

约束限制:

不涉及。

取值范围:

不涉及。

默认取值:

不涉及。

message

String

参数解释:

描述信息。

约束限制:

不涉及。

取值范围:

不涉及。

默认取值:

不涉及。

请求示例

/v1/entities/query

{
  "store_name" : "test-storename",
  "collection_name" : "test-collection",
  "output_fields" : [ "pk", "vector", "scalar" ],
  "filter" : "pk > 0",
  "top_k" : 2,
  "offset" : 0
}

响应示例

状态码:200

搜索成功

{
  "code" : "LMS.00000000",
  "data" : {
    "entities" : [ {
      "pk" : 1,
      "scalar" : "文档1",
      "vector" : [ 0.324, 0.21, 0.2456 ]
    }, {
      "pk" : 2,
      "scalar" : "文档4",
      "vector" : [ 0.333, 0.222, 0.1116 ]
    } ]
  },
  "message" : "query entities success"
}

状态码:400

搜索失败

{
  "code" : "LMS.00004002",
  "message" : "ErrInvalidSearchResult:Fail to parse search result"
}

状态码

状态码

描述

200

搜索成功

400

搜索失败

错误码

请参见错误码

相关文档