请求方法

POST

客户端对向量数据库服务器请求的操作类型

请求头

Content-Type: application/json

请求消息类型

Authorization: HMAC-SHA256 ***

鉴权

collection_name/collection_alias

string

是

指定检索的 Index 所属的 Collection 名称/别名。

• 只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。
• 长度要求：[1, 128]。
• Collection 名称/别名不能重复。

index_name

string

是

指定检索的 Index 名称。

• 只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。
• 长度要求：[1, 128]。
• 索引名称不能重复。

search

order_by_vector

map

是

根据向量距离做检索，可选值如下，vectors 和 primary_keys 二选一：

• vectors：用于检索的向量列表，最大10个。
• primary_keys: 用于检索的数据主键列表，最大10个。会先根据主键查到对应的向量，再对向量做近似检索。支持int类型/string类型。

filter

map

是

过滤条件，详见 filter 表达式说明。

• 默认为空，不做过滤。
• 过滤条件包含 must、must_not、range、range_out四类查询算子，包含 and 和 or 两种对查询算子的组合。

limit

int

否

10

检索结果数量，最大5000个。

dense_weight

float

否

0.5

混合检索中稠密向量的权重，1 表示纯稠密检索 ，0表示纯字面检索。
只有索引是混合索引时有效。范围 [0.2, 1]

partition

string/int

否

"default"

子索引名称，类型与 partition_by 的 field_type 一致，字段值对应 partition_by 的 field_value。

• field_type 为 int64，list<int64> 时，partition 输入类型为 int64。
• field_type 为 string，list<string> 时，partition 输入类型为 string，格式要求 "^[a-zA-Z0-9._]+$"。

output_fields

list<string>

否

过滤字段，指定要返回的标量或向量字段列表。

• output_fields 不传时，返回所有的标量字段，不返回向量字段。
• output_fields 为空列表时，不返回 fields 字段。
• output_fields 格式错误或者过滤字段不是 collection 里的字段时, 接口返回错误。

如果索引的距离方式为cosine，向量字段返回的向量是归一化后的向量。

primary_key_in

list<int64>或list<string>

否

设定此参数，会限定仅在主键列表范围内进行检索。
传入空列表和不传此参数效果相同。

primary_key_not_in

list<int64>或list<string>

否

设定此参数，将把主键列表范围内的数据从检索结果中排除 。

must

针对指定字段名生效，语义为必须在 [...] 之中，即 "must in"。

{
  "op": "must",
  "field": "region",
  "conds": ["cn", "sg"]
}

must_not

针对指定字段名生效，语义为必须不在 [...] 之中，即 "must not in"。

{
  "op": "must_not",
  "field": "data_type",
  "conds": [1,2,3]
}

range

针对指定字段名生效，语义为必须在指定范围内。
配置使用gte（大于等于）, gt（大于）, lte（小于等于）, lt（小于），用以圈定一维范围。
另外，支持用 center 和 radius 表示二维圆内范围。

// price 在 [100.0, 500.0)
{
  "op": "range",
  "field": "price",
  "gte": 100.0,
  "lt": 500.0
}

//price >= 100.0
{
  "op": "range",
  "field": "price",
  "gte": 100.0
}

// 以 center 为中心，半径为50的圆内
{
  "op": "range",
  "field": ["pos_x", "pos_y"],
  "center": [100.0, 123.4],
  "radius": 50.0
}

range_out

针对指定字段名生效，语义为必须在指定范围外。配置使用gte（大于等于）, gt（大于）, lte（小于等于）, lt（小于），用以圈定一维范围。

// 筛选价格低于100或高于500的商品
{
  "op": "range_out",
  "field": "price",
  "gt": 500.0,
  "lt": 100.0
}

and

逻辑算子，针对逻辑查询需求，对多个条件取交集。

{
  "op": "and",   // 算子名
  "conds": [     // 条件列表，支持嵌套逻辑算子和 must/must_not 算子
    {
      "op": "must",
      "field": "type",
      "conds": [1]
    },
    {
        ...         // 支持>=1的任意数量的条件进行组合
    }
  ]
}

or

逻辑算子，针对逻辑查询需求，对多个条件取并集。

{
  "op": "or",   // 算子名
  "conds": [    // 条件列表，支持嵌套逻辑算子和 must/must_not 算子
    {
      "op": "must",
      "field": "type",
      "conds": [1]
    },
    {
        ...      // 支持>=1的任意数量的条件进行组合
    }
  ]
}

code

状态码

message

返回信息

request_id

标识每个请求的唯一标识符

data

检索结果，标量过滤检索会返回检索到的主键、score、fields。

0

200

drop index success

Index 检索成功。

1000008

400

index not exist

指定的 Index 不存在。

1000003

400

invalid request：%s

非法参数：

• 缺失必选参数。
• 缺乏检索输入。
• 不满足约束条件。

1000001

401

unauthorized

请求头中缺乏鉴权信息。

1000002

403

no permission

权限不足。

1000016

400

invalid vectors for index_recall

输入的向量格式不合法。

1000029

429

请求已达上限, 请调整CPU核数

需要调大 cpu_quota