文档中心

向量数据库VikingDB

检索能力

search_by_id

概述

search_by_id 用于主键 id 检索。根据主键 id，搜索与其距离最近的 limit 个向量。

支持使用 hnsw-hybrid 的混合索引进行 search_by_id；可通过 dense_weight 调节稠密向量在混合检索中的权重。
Collection 数据写入/删除后，Index 数据更新时间预计20s，不能立即在 Index 检索到。
当请求参数 filter 配置时，表示混合检索；当请求参数 filter 没有配置时，表示纯向量检索。
异步调用使用async_search_by_id接口，参数不变。

前提条件

通过 create_collection 接口创建数据集时，定义字段 fields 已添加 vector 字段。
通过 upsert_data 接口写入数据时，已写入 vector 类型的字段名称和字段值。
通过 create_index 创建索引时，已创建 vector_index 向量索引。

请求参数

参数	类型	是否必选	默认值	参数说明
id	int64	是		主键 id。
filter	map	否	None	过滤条件，详见标量过滤。默认为空，不做过滤。过滤条件包含 must、must_not、range、range_out四类查询算子，包含 and 和 or 两种对查询算子的组合。
limit	int	否	10	检索结果数量，最大5000个。
offset	int	否	0	偏移量。仅分页场景下使用，不建议设置过大值，否则有深分页影响。默认值为0。设置值至少为0，语义和mysql的offset相同。
dense_weight	float	否	0.5	对于标量过滤检索，dense_weight 用于控制稠密向量在检索中的权重。范围为[0.2，1]。仅在检索的索引为混合索引时有效。
output_fields	list	否		过滤字段，指定要返回的标量或向量字段列表。向量字段返回必须填入到output_fields。 output_fields 不传时，返回所有的标量字段，不返回向量字段。 output_fields 为空列表时，不返回 fields 字段。 output_fields 格式错误或者过滤字段不是 collection 里的字段时, 接口返回错误。如果索引的距离方式为cosine，向量字段返回的向量是归一化后的向量。
partition	string/int	否	"default"	子索引名称，类型与 partition_by 的 field_type 一致，字段值对应 partition_by 的 field_value。 field_type 为 int64，list 时，partition 输入类型为 int64。 field_type 为 string，list 时，partition 输入类型为 string，格式要求 "^[a-zA-Z0-9._]+$"。
scale_k	float64	否	1	检索时的 ef 是索引参数 ef 的 scale_k 倍默认1，取值范围[0.1, 100]，值越大检索结果越精确，但相应地会降低性能。

filter 表达式

算子	算子说明	示例
must	针对指定字段名生效，语义为必须在 [...] 之中，即 "must in"。	`JSON <br> { <br> "op": "must", <br> "field": "region", <br> "conds": ["cn", "sg"] <br> } <br>`
must_not	针对指定字段名生效，语义为必须不在 [...] 之中，即 "must not in"。	`JSON <br> { <br> "op": "must_not", <br> "field": "data_type", <br> "conds": [1,2,3] <br> } <br>`
range	针对指定字段名生效，语义为必须在指定范围内。配置使用`gte`（大于等于）, `gt`（大于）, `lte`（小于等于）, `lt`（小于），用以圈定一维范围。另外，支持用 `center` 和 `radius` 表示二维圆内范围。	`JSON <br> // price 在 [100.0, 500.0) <br> { <br> "op": "range", <br> "field": "price", <br> "gte": 100.0, <br> "lt": 500.0 <br> } <br> <br> //price >= 100.0 <br> { <br> "op": "range", <br> "field": "price", <br> "gte": 100.0 <br> } <br> <br> // 以 center 为中心，半径为50的圆内 <br> { <br> "op": "range", <br> "field": ["pos_x", "pos_y"], <br> "center": [100.0, 123.4], <br> "radius": 50.0 <br> } <br>`
range_out	针对指定字段名生效，语义为必须在指定范围外。配置使用`gte`（大于等于）, `gt`（大于）, `lte`（小于等于）, `lt`（小于），用以圈定一维范围。	`JSON <br> // 筛选价格低于100或高于500的商品 <br> { <br> "op": "range_out", <br> "field": "price", <br> "gt": 500.0, <br> "lt": 100.0 <br> } <br>`
and	逻辑算子，针对逻辑查询需求，对多个条件取交集。	`JSON <br> { <br> "op": "and", // 算子名 <br> "conds": [ // 条件列表，支持嵌套逻辑算子和 must/must_not 算子 <br> { <br> "op": "must", <br> "field": "type", <br> "conds": [1] <br> }, <br> { <br> ... // 支持>=1的任意数量的条件进行组合 <br> } <br> ] <br> } <br>`
or	逻辑算子，针对逻辑查询需求，对多个条件取并集。	`JSON <br> { <br> "op": "or", // 算子名 <br> "conds": [ // 条件列表，支持嵌套逻辑算子和 must/must_not 算子 <br> { <br> "op": "must", <br> "field": "type", <br> "conds": [1] <br> }, <br> { <br> ... // 支持>=1的任意数量的条件进行组合 <br> } <br> ] <br> } <br>`

示例

运行示例前，请完成以下准备：
安装对应版本的 VikingDB Python SDK，将完整代码保存为 example.py 后执行 python3 example.py。
AK/SK 在火山引擎控制台“密钥管理”中创建；Host 和 Region 取自地域和访问域名。请按代码的参数或环境变量读取方式完成配置。
Collection、Index 名称从 VikingDB 控制台对应资源详情获取；Task ID 使用创建或查询任务接口返回的 ID。请将 <YOUR_...> 占位符替换为真实值。
若示例包含 TOS 路径，请从 TOS 控制台确认桶名和对象路径，并替换为真实的 <YOUR_BUCKET_NAME>/<YOUR_TOS_PATH>。

请求参数

请在火山引擎控制台的密钥管理页面获取 AK 和 SK，并将示例中的 <YOUR_AK>、<YOUR_SK> 等占位符替换为真实配置。

# 获取指定索引，程序初始化时调用即可，无需重复调用
from volcengine.viking_db.IndexClient import IndexClient

index_client = IndexClient("<YOUR_COLLECTION_NAME>", "<YOUR_INDEX_NAME>", "api-vikingdb.volces.com", "cn-beijing", "<YOUR_AK>", "<YOUR_SK>", "http")

res = index_client.search_by_id("22", limit=2, output_fields=["doc_id", "like", "text_vector"], partition="default")

# 异步调用
async def search_by_id():
    index_client = IndexClient("<YOUR_COLLECTION_NAME>", "<YOUR_INDEX_NAME>", "api-vikingdb.volces.com", "cn-beijing", "<YOUR_AK>", "<YOUR_SK>", "http")
    res = await index_client.async_search_by_id("222")
asyncio.run(search_by_id())

返回值

Python 调用执行上面的任务，返回 List 。Data 实例包含的属性如下表所示。

属性	说明
id	主键 id。
fields	请求返回中的 fields 字段，是具体的数据，字典类型。
score	表示找到的向量和输入的向量的匹配程度。

使用说明修正

id 支持 int64 或 string，具体类型必须与 Collection 主键字段一致。因此示例中的 "22" 适用于字符串主键；整数主键应传 22。

最近更新时间：2026.09.08 15:30:02

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

filter 表达式 #

请求参数 #

返回值 #

使用说明修正 #

filter 表达式

请求参数

返回值

使用说明修正