向量检索
更新时间：2025-04-18
POST
http://{host}/v{version}/row?search
基于向量相似性进行查询检索
权限说明
鉴权认证机制的详细内容请参见鉴权认证
请求参数
Headers 参数
除公共头域外，无其它特殊头域
URL 参数
version
string
API版本号，当前取1。
必选
host
string
"{实例IP}:{实例Port}"
必选
Body 参数
database
string
指定库的名称。
必选
table
string
指定表的名称。
必选
anns
object {4}
检索请求参数详情。
必选
显示子属性
隐藏子属性
vectorField
string
检索的向量字段。
必选
vector
anyOf {3}
多选一，只需要符合下列任意一组子节点
检索的向量数据。支持稠密型向量(List Float)、稀疏性向量(List Array)、二进制向量(String)
必选
显示子属性
隐藏子属性
vector
array
稠密向量
显示子属性
隐藏子属性
items
float
vector
array
稀疏向量
显示子属性
隐藏子属性
items
array
显示子属性
隐藏子属性
items
float
vector
string
二进制向量
params
object {6}
向量检索参数详情。
可选
显示子属性
隐藏子属性
M
integer
HNSW、HNSWPQ索引算法参数，取值范围为[4, 128]。该参数表示每个节点在索引构图中可以连接多少个邻居节点。
可选
efConstruction
integer
HNSW、HNSWPQ索引算法参数，取值范围为[8, 1024]。该参数表示搜索时指定寻找节点邻居遍历的范围。数值越大构图效果越好，构图时间也越长。
可选
NSQ
integer
HNSWPQ索引参数，取值范围为[1, dim]。该参数表示量化子空间个数，pq量化相关系数，要求NSQ | dim，NSQ越大量化越精细
可选
sampleRate
float
HNSWPQ索引参数，取值范围为[0.0f, 1.0f]。该参数表示kmeans的采样率，pq抽样总数：10000 + (rowCount - 10000)*sampleRate
可选
fineClusterCount
integer
PUCK索引算法参数，取值范围为[1, 5000]。该参数表示每个粗聚类中心下细聚类中心个数。
可选
coarseClusterCount
integer
PUCK索引算法参数，取值范围为[1, 5000]。该参数表示索引中粗聚类中心个数。
可选
filter
string
过滤条件
可选
partitionKey
object {0}
需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
可选
显示子属性
隐藏子属性
projections
array
指定返回的字段列表，不指定则返回全部字段。
可选
显示子属性
隐藏子属性
items
string
readConsistency
string
查询请求的一致性级别，取值为：
可选
请求结构
POST /v{version}/row?search HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
"database": "db_test",
"table": "table_test",
"anns": {
"vectorField": "vector_field",
"vector": [
0.2323234,
0.34534545,
0.9837234
],
"params": {
"ef": 100,
"limit": 10
},
"filter": "id != '00000' AND age < 35"
},
"partitionKey": {
"username": "alice"
},
"projections": ["id", "username"],
"readConsistency": "EVENTUAL"
}示例代码
请求示例
curl --location --request POST 'http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?search' \
--header 'Authorization: Bearer account=root&api_key=eC4bLRy2va******************************' \
--header 'Content-Type: application/json' \
--data '{
"database": "db_test",
"table": "table_test",
"primaryKey": {
"id": "00001"
},
"partitionKey": {
"username": "alice"
},
"projections": ["id", "username", "vector_field"],
"retrieveVector": true,
"readConsistency": "EVENTUAL"
}'返回响应
Headers 参数
除公共头域外，无其它特殊头域
返回参数
msg
string
返回信息
可选
code
integer
返回码
可选
rows
array
检索结果列表
可选
显示子属性
隐藏子属性
items
object {3}
显示子属性
隐藏子属性
row
string
检索结果记录的详情。
可选
distance
float
结果记录与目标向量的距离。说明如下：
可选
score
float
记录得分，得分越高，与搜索向量越相似。
可选
响应示例
{
"code": 0,
"msg": "Success",
"rows": [
{
"row": {
"id": "00001",
"username": "alice",
"vector_field": [
0.20354213,
0.35934591,
0.89238402
]
},
"distance": 0.01,
"score": 1.0
},
{
"row": {
"id": "00002",
"username": "bob",
"vector_field": [
0.21354213,
0.34934591,
0.90238402
]
},
"distance": 0.05,
"score": 0.99
}
]
}