标量排序检索--向量数据库VikingDB-火山引擎

文档中心

导航

标量排序检索

最近更新时间：2025.06.10 11:47:57首次发布时间：2025.01.10 19:13:06

向量数据库中的标量排序检索指的是基于标量值的检索方法。在向量数据库中，每个向量都有一个或多个标量值，标量排序检索可以基于这些标量值进行检索，找到与查询相关的数据。例如文档检索中的作者特征检索。
本页面主要介绍如何基于/index/search 接口实现标量排序检索。

请求接口

说明

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

URI	/api/index/search	统一资源标识符
请求方法	POST	客户端对向量数据库服务器请求的操作类型
请求头	Content-Type: application/json	请求消息类型
请求头	Authorization: HMAC-SHA256 ***	鉴权

基础标量排序检索

最简洁的标量排序检索可通过配置search接口下的order_by_scalar参数来实现，允许用户根据文档中的某个标量字段（如价格、评分、时间戳等）对检索结果进行排序。请求参数如下：

参数	子参数	类型	是否必选	参数说明
collection_name/collection_alias		string	是	指定检索的 Index 所属的 Collection 名称/别名。只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。长度要求：[1, 128]。 Collection 名称/别名不能重复。
index_name		string	是	指定检索的 Index 名称。只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。长度要求：[1, 128]。索引名称不能重复。
resource_id		string	否	资源ID
search	order_by_scalar	map	是	根据标量字段做排序。 field_name: 字段名。约束：必须为此字段建立 range 索引。 order：asc（ascending，升序）、desc（descending，降序）。注意 order 和 field_name 两个参数必须同时配置，如果两个参数均未配置，则直接返回符合filter条件的limit条数据，且检索结果随机排序。

在下面的示例中，假设 Collection 已经存放了如下 10 条数据。每条数据都有 id, vector, name,city, salary这几个字段。

{"id":"1","vector":[0.12,0.98,0.45,...,0.33,0.77],"name":"Alice","city":"New York","salary":85000}
{"id":"2","vector":[0.55,0.22,0.91,...,0.14,0.68],"name":"Bob","city":"San Francisco","salary":120000}
{"id":"3","vector":[0.31,0.44,0.27,...,0.88,0.15],"name":"Charlie","city":"Chicago","salary":78000}
{"id":"4","vector":[0.66,0.39,0.72,...,0.58,0.23],"name":"Diana","city":"London","salary":95000}
{"id":"5","vector":[0.09,0.81,0.34,...,0.47,0.56],"name":"Ethan","city":"Toronto","salary":91000}
{"id":"6","vector":[0.48,0.29,0.67,...,0.12,0.99],"name":"Fiona","city":"Sydney","salary":104000}
{"id":"7","vector":[0.25,0.73,0.58,...,0.46,0.31],"name":"George","city":"Berlin","salary":83000}
{"id":"8","vector":[0.94,0.16,0.39,...,0.85,0.02],"name":"Hannah","city":"Paris","salary":98000}
{"id":"9","vector":[0.53,0.67,0.41,...,0.29,0.76],"name":"Ian","city":"Tokyo","salary":89000}
{"id":"10","vector":[0.77,0.51,0.24,...,0.63,0.40],"name":"Julia","city":"Singapore","salary":115000}

输入需要排序的字段和排序规则，检索后会对数据进行排序：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
    "collection_name": "test_name",    //用于检索的集合的名称
    "index_name": "index_test",     //用于检索的索引名称
    "search": {
         "order_by_scalar": {    //按标量字段排序的规则
            "field_name": "salary",    //用于排序的字段名称
            "order": "desc",    //排序顺序：降序
        }
        }
}'

执行成功返回：

{
        "code": 0,
        "data": [[{
                "fields": {
                        "city": "San Francisco",
                        "id": 2,
                        "name": "Bob",
                        "salary": 120000
                },
                "id": 2,
                "score": 120000
        },
        {
                "fields": {
                        "city": "New York",
                        "id": 1,
                        "name": "Alice",
                        "salary": 85000
                },
                "id": 1,
                "score": 85000
        }]],
        "message": "success",
        "request_id": "02174798492189800000000000000000000ffff0a006058b62280"
}

在子索引中进行检索

如果在创建索引时划分了子索引 partition，并且查询目标可以具体到其中的一个 partition，可以在检索时指定在特定partiton中进行检索，从而减少扫描的数据量，提高检索速度。
在基础向量检索的基础上，通过配置search接口下的partition参数可以实现对特定子索引的检索：

参数	子参数	类型	是否必选	默认值	参数说明
search	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._]+$"。

参数

子参数

类型

是否必选

默认值

参数说明

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._]+$"。

假设在创建索引时设置了city字段为子索引字段，根据city字段的取值将数据集划分成了不同的子数据集，现在想对名为London的partiton进行检索，可以通过如下方式实现：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
    "collection_name": "test_name",    //用于检索的集合的名称
    "index_name": "index_test",    //用于检索的索引名称
    "search": {
        "order_by_scalar": {    //按标量字段排序的规则
            "field_name": "salary",    //用于排序的字段名称
            "order": "desc",    //排序顺序：降序
        },
        "partiton": "London"
        }
}'

检索过滤（可选）

检索过滤是指在向量相似度检索过程中，结合结构化的元数据（如数值、布尔值、字符串等）对候选数据进行筛选的过程。这种过滤可以提高检索结果的相关性和精度。
检索过滤为可选能力，需要配合基础的向量检索能力使用，可以配置一种或多种检索过滤方式。

标量过滤

标量过滤检索是指在向量数据库中，同时使用向量检索和标量检索两种方法进行检索。在标量过滤检索中，使用向量检索来匹配向量的相似度，同时使用标量检索来匹配向量的标量值。
在基础向量检索的基础上，可以通过配置search接口下的filter参数来实现对检索结果的标量过滤，详细的使用方法参考标量过滤。

主键过滤

主键过滤是指在向量检索时，仅对指定主键值数据执行近邻搜索，从而有效缩小检索范围并提升性能与准确度
在基础向量检索的基础上，可以通过配置search接口下的 primary_key_in/primary_key_not_in 子参数对特定主键值的数据进行检索，详细的使用方法参考主键过滤。

后置过滤

后置过滤是 VikingDB 提供的一种检索后处理能力，用于在向量召回之后，对候选数据进行进一步的过滤和优化，确保最终返回的搜索结果更加精准、高效。VikingDB 提供了以下几种后置过滤能力：

**正则表达式匹配：**利用正则表达式对字符串字段进行模式匹配的过滤方式。适用于需要进行复杂字符串匹配的场景。
**关键词匹配：**一种基于字符串字段内容进行子串匹配的过滤方式。它允许用户查找字段中包含特定关键词或字符的数据记录。
**频控：**用于保证一次召回的结果中, 一个特定取值出现的总数不超过特定值。

在基础向量检索的基础上，可以通过配置search接口下的 post_process_ops和post_process_input_limit配置后置过滤能力，详细的使用方法详见后置处理算子。

检索结果处理（可选）

输出字段选择

通过配置search接口下的 output_fields子参数可以限制检索结果只返回指定的字段:

参数	子参数	类型	是否必选	默认值	参数说明
search	output_fields	list<string>	否		过滤字段，指定要返回的标量或向量字段列表。 output_fields 不传时，返回所有的标量字段，不返回向量字段。 output_fields 为空列表时，不返回 fields 字段。 output_fields 格式错误或者过滤字段不是 collection 里的字段时, 接口返回错误。如果索引的距离方式为cosine，向量字段返回的向量是归一化后的向量。

参数

子参数

类型

是否必选

默认值

参数说明

output_fields

list<string>

否

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

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

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

例如希望在返回结果中只保留“name”字段：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
        "collection_name": "test_name",
        //用于检索的集合的名称
        "index_name": "index_test",
        //用于检索的索引名称
        "search": {
                "order_by_scalar": {    //按标量字段排序的规则
                    "field_name": "salary",    //用于排序的字段名称
                    "order": "desc",    //排序顺序：降序
        },
                "output_fields": ['name']
        }
}'

分页查询

分页能力通过在检索请求中指定 offset 和 limit参数，将结果分批返回，在降低单次响应延迟的同时便于前端交互和资源管理

参数	子参数	类型	是否必选	默认值	参数说明
search	limit	int	否	10	检索结果数量，最大5000个。
search	offset	int	否	0	偏移量。仅分页场景下使用，不建议设置过大值，否则有深分页影响。默认值为0。设置值至少为0，语义和mysql的offset相同。

例如指定返回10个结果：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
        "collection_name": "test_name",
        //用于检索的集合的名称
        "index_name": "index_test",
        //用于检索的索引名称
        "search": {
                "order_by_scalar": {    //按标量字段排序的规则
                    "field_name": "salary",    //用于排序的字段名称
                    "order": "desc",    //排序顺序：降序
        },
                "limit": 2, # 每页返回 2 条结果
                "offset": 4 # 跳过前 4 条结果,获取第三页结果
        }
}'

响应消息

参数	参数说明
code	状态码
message	返回信息
request_id	标识每个请求的唯一标识符
data	检索结果，向量检索会返回检索到的主键、score、fields。

状态码说明

状态码	http状态码	返回信息	状态码说明
0	200	drop index success	向量检索成功。
1000008	400	index not exist	指定的 Index 不存在。
1000003	400	invalid request	非法参数：缺失必选参数。缺乏检索输入。不满足约束条件。
1000001	401	unauthorized	请求头中缺乏鉴权信息。
1000002	403	no permission	权限不足。
1000016	400	invalid vectors for index_recall	输入的向量格式不合法。
1000029	429	请求已达上限, 请调整CPU核数	需要调大 cpu_quota

完整示例

请求消息

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
    "collection_name": "test_name",    //用于检索的集合的名称
    "index_name": "index_test",    //用于检索的索引名称
    "search": {
        "order_by_scalar": {    //按标量字段排序的规则
            "field_name": "salary",    //用于排序的字段名称
            "order": "desc",    //排序顺序：降序
        }, 
        "partiton": "London"，//指定partition，
        "filter": {
                        "op": "range",
                        "field": "salary",
                        "gte": 10000
                }，
         "post_process_ops": {
                        "op": "string_contain",
                        "field": "name",
                        "pattern": "s"
                }，
          "output_fields": ['name']，
          "limit": 2, # 每页返回 2 条结果
          "offset": 4 # 跳过前 4 条结果,获取第三页结果
        }
}
}'

响应消息

执行成功返回：

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{
    "code":0,
    "msg":"search success",
    "request_id":"021695029537650fd001de666660000000000000000000230da93",
    "data": [
        [
            {
                "id": 1,
                "score": 0.99,
                "fields": {
                    "name": "Alice"
                } 
            },
            {
                "id": 2,
                "score": 0.98,
                "fields": {
                    "name": "Fiona"
                } 
            }
        ],
        [
            {
                "id": 9,
                "score": 0.95,
                "fields": {
                    "name": "Charlie"
                } 
            },
            {
                "id": 8,
                "score": 0.84,
                "fields": {
                    "name": "Ethan"
                } 
            }            
        ]
    ]
}

执行失败返回：

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