You need to enable JavaScript to run this app.
导航

混合检索

最近更新时间2023.11.09 18:59:54

首次发布时间2023.11.03 15:00:09

概述

/index/search 接口用于实现检索,本页面主要介绍如何实现混合检索。
混合检索是指在向量数据库中,同时使用向量检索和标量检索两种方法进行检索。在混合检索中,使用向量检索来匹配向量的相似度,同时可以使用标量检索来匹配数据的标量值进行过滤。

说明

Collection 数据写入/删除后,Index 数据更新时间最长滞后 20s,不能立即在 Index 检索到。

请求接口

说明

请求向量数据库 VikingDB 的 OpenAPI 接口时,需要构造签名进行鉴权,详细的 OpenAPI 签名调用方法请参见 API签名调用指南

URI

/api/index/search

统一资源标识符

请求方法

POST

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

请求头

Content-Type: application/json

请求消息类型

Authorization: HMAC-SHA256 ***

鉴权

请求参数

参数

子参数

类型

是否必选

默认值

参数说明

collection_name

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、georange 五类查询算子,包含 and 和 or 两种对查询算子的组合。

limit

int

10

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

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 里的字段时, 接口返回错误。

filter 表达式

算子

算子说明

示例

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(小于),用以圈定一维范围。
另外,支持用 centerradius 表示二维圆内范围。

// 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
}

georange

支持地理距离范围筛选 。
指定经纬度字段,以center为中心,筛选出地表距离在radius范围内的数据。

// 距离center地表距离 radius 内
{
  "op": "georange",
  "field": ["longitude", "latitude"],
  "center": [100.12312, 22.4324],
  "radius": 50.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。

状态码说明

状态码

http状态码

返回信息

状态码说明

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

输入的向量格式不合法。

完整示例

请求消息

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  http://***/api/index/search \
  -d '{
    "collection_name": "test_name",
    "index_name": "index_test",
    "search": {
        "order_by_vector": {
            "vectors": [
                [0.1, 0.2, 0.3......0.9], 
                [0.01, 0.02, 0.03......0.09],
            ],         
        }, 
        "limit": 2,     
        "filter": {
          "op": "must",    
          "field": "region", 
          "conds": ["cn", "sg"]
        }
        "partition": "china"     //子索引名称,对应 field 的值。
    }
}'

响应消息

执行成功返回:

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{
    "code":0,
    "msg":"search success",
    "request_id":"021695029757920fd001de6666600000000000000000002569b8f",
    "data": [
        [
            {
                "id": 1,
                "score": 0.99,
                "fields": {
                    "time": 1690529704,
                    "author": "zhangsan"
                } 
            },
            {
                "id": 2,
                "score": 0.98,
                "fields": {
                    "time": 1690529701,
                    "author": "lisi"
                } 
            }
        ],
        [
            {
                "id": 9,
                "score": 0.95,
                "fields": {
                    "time": 1690529708,
                    "author": "wangwu"
                } 
            },
            {
                "id": 8,
                "score": 0.84,
                "fields": {
                    "time": 1690529710,
                    "author": "zhaoliu"
                } 
            }            
        ]
    ]
}

执行失败返回:

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000008, "msg":"index not exist", "request_id":"021695029757920fd001de6666600000000000000000002569b8f"}