Row 操作

更新时间：2025-10-30

插入记录

接口描述

将一条或者一批记录插入到指定的表中。插入语义为Insert，即，当记录的主键已存在时，则插入报错。当插入一批时，该接口暂不支持批次的原子性。

请求结构

                JSON
                
            

                POST /v{version}/row?insert HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_name",
    "table": "table_name",
    "rows": [
        {
            "id": "00001",
            "username": "alice",
            "vector_field": [
                0.2323234,
                0.34534545,
                0.9837234
            ],
            "sparse_vector_field" : [[1, 0.56465], [100, 0.2366456], [10000, 0.543111]],
            "binary_vector": "AAAAAAAAAAAAAAAAAAAAew=="
        }
    ]
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
rows	List Row	是	RequestBody参数	插入的数据集，单个批次最大支持1000条。

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息
affectedCount	int	写入成功的记录数

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?insert
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_name",
    "table": "table_name",
    "rows": [
        {
            "id": "00001",
            "username": "alice",
            "vector_field": [
                0.2323234,
                0.34534545,
                0.9837234
            ],
            "sparse_vector_field" : [[1, 0.56465], [100, 0.2366456], [10000, 0.543111]],
            "binary_vector": "AAAAAAAAAAAAAAAAAAAAew=="
        }
    ]
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "code": 0,
    "msg": "Success",
    "affectedCount": 1
}
            

插入或更新记录

接口描述

将一条或者一批记录插入到指定的表中。插入语义为Upsert（Insert or Update），即，当记录的主键已存在时，则用新的数据整体覆盖旧的数据。当插入一批时，该接口暂不支持批次的原子性。该接口可用于批量迁移/灌库等场景。

请求结构

                JSON
                
            

                POST /v{version}/row?upsert HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_name",
    "table": "table_name",
    "rows": [
        {
            "id": "00001",
            "username": "alice",
            "vector_field": [
                0.2323234,
                0.34534545,
                0.9837234
            ],
            "sparse_vector_field" : [[1, 0.56465], [100, 0.2366456], [10000, 0.543111]],
            "binary_vector": "AAAAAAAAAAAAAAAAAAAAew=="
        }
    ]
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
rows	List Row	是	RequestBody参数	插入的数据集，单个批次最大支持1000条。

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息
affectedCount	Int	写入成功的记录数

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?upsert
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_name",
    "table": "table_name",
    "rows": [
        {
            "id": "00001",
            "username": "alice",
            "vector_field": [
                0.2323234,
                0.34534545,
                0.9837234
            ],
            "sparse_vector_field" : [[1, 0.56465], [100, 0.2366456], [10000, 0.543111]],
            "binary_vector": "AAAAAAAAAAAAAAAAAAAAew=="
        }
    ]
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "code": 0,
    "msg": "Success",
    "affectedCount": 1
}
            

更新记录

接口描述

更新指定记录的一个或多个标量或向量字段的值。

请求结构

                JSON
                
            

                POST /v{version}/row?update HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_name",
    "table": "table_name",
    "primaryKey": {
         "id": "00001"
     },
     "partitionKey": {
         "username": "alice"
     },
     "update": {
         "age": 35,
         "address": "Shanghai",
         "vector_column": [
            0.23432432,
            0.8923744,
            ...
         ]
     }
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
primaryKey	JSON Object	是	RequestBody参数	待更新记录的主键值。
partitionKey	JSON Object	否	RequestBody参数	待更新记录的分区值。如果该表的分区键和主键是同一个键，则不需要填写分区键值。只有在有主键值的情况下，分区键值才会生效。
update	JSON Object	是	RequestBody参数	待更新的字段列表及其新值。不允许更新主键、分区键。

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?update
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_name",
    "table": "table_name",
    "primaryKey": {
         "id": "00001"
     },
     "partitionKey": {
         "username": "alice"
     },
     "update": {
         "age": 35,
         "address": "Shanghai",
         "vector_column": [
            0.23432432,
            0.8923744,
            ...
         ]
     }
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "code": 0,
    "msg": "Success"
}
            

删除记录

接口描述

删除指定表中的指定记录。支持基于主键的查询删除和基于标量字段进行过滤删除。

请求结构

                JSON
                
            

                POST /v{version}/row?delete HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_test",
    "table": "table_test",
    "primaryKey": {
        "id": "00001"
    },
    "partitionKey": {
        "username": "alice"
    },
    "filter": "id == '00001' AND username == 'alice'"
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
primaryKey	JSON Object	否	RequestBody参数	待删除记录的主键值。
partitionKey	JSON Object	否	RequestBody参数	待删除记录的分区键值。如果该表的分区键和主键是同一个键，则不需要填写分区键值。只有在有主键值的情况下，分区键值才会生效。
filter	String	否	RequestBody参数	过滤条件。当要删除全部记录，可设置为"*"；Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。必须填写主键值或过滤条件，二者有且仅能选其一。

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息

请求示例

基于主键的查询删除示例如下：

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?delete
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_name",
    "table": "table_name",
    "primaryKey": {
        "id": "00001"
    },
    "partitionKey": {
        "username": "alice"
    }
}
            

基于标量字段进行过滤删除示例如下：

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?delete
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_name",
    "table": "table_name",
    "filter": "id == '00001'"
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "code": 0,
    "msg": "Success"
}
            

标量查询

接口描述

基于主键值的点查操作。

请求结构

                JSON
                
            

                POST /v{version}/row?query HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_test",
    "table": "table_test",
    "primaryKey": {
        "id": "00001"
    },
    "partitionKey": {
        "username": "alice"
    },
    "projections": ["id", "username"],
    "retrieveVector": true,
    "readConsistency": "EVENTUAL"
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
primaryKey	JSON	是	RequestBody参数	目标记录的主键值。
partitionKey	JSON	否	RequestBody参数	目标记录的分区键值。
projections	List String	否	RequestBody参数	投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
retrieveVector	Boolean	否	RequestBody参数	是否返回查询结果记录中的向量字段值，默认false。
readConsistency	String	否	RequestBody参数	查询请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本； STRONG：强一致性，查询请求只会发送给分片主副本。

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息
row	JSON Object	结果数据集

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?query
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_test",
    "table": "table_test",
    "primaryKey": {
        "id": "00001"
    },
    "partitionKey": {
        "username": "alice"
    },
    "projections": ["id", "username"],
    "retrieveVector": true,
    "readConsistency": "EVENTUAL"
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "code": 0,
    "msg": "Success",
    "row": {
        "id": "00001",
        "username": "alice",
        "vector_field": [
            0.2323234,
            0.34534545,
            0.9837234
        ]
    }
}
            

标量批量查询

接口描述

基于主键值的批量查询操作。

请求结构

                JSON
                
            

                POST /v{version}/row?batchQuery HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_test",
    "table": "table_test",
    "keys": [
        {
            "primaryKey": {"id": 123}, 
            "partitionKey": {"username": 123}
        },
        {
            "primaryKey": {"id": 456}
        }
    ],
    "projections": ["column1", "column2"],
    "retrieveVector": true,
    "readConsistency": "EVENTUAL"
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
keys	List JSON	是	RequestBody参数	目标记录的主键及分区键。主键必填，分区键可选。
projections	List String	否	RequestBody参数	投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
retrieveVector	bool	否	RequestBody参数	是否返回检索结果记录中的向量字段值，默认为false。
readConsistency	String	否	RequestBody参数	检索请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，检索请求会随机发送给分片的所有副本； STRONG：强一致性，检索请求只会发送给分片主副本。

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息
rows	List Row	检索结果记录列表。

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?batchQuery
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_test",
    "table": "table_test",
    "keys": [
        {
            "primaryKey": {"id": 123},
            "partitionKey": {"username": 123}
        },
        {
            "primaryKey": {"id": 456}
        }
    ],
    "projections": ["column1", "column2"],
    "retrieveVector": true,
    "readConsistency": "EVENTUAL"
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
  "code": 0,
  "msg": "Success",
  "rows": [
    {
      "id": 123,
      "vector": [
        0.23432432,
        0.8923744,
        0.89238432
      ],
      "other_scalar_column": "other_scalar_column"
    },
    {
      "id": 456,
      "vector": [
        0.23432432,
        0.8923744,
        0.89238432
      ],
      "other_scalar_column": "other_scalar_column"
    }
  ]
}
            

向量检索

接口描述

基于向量字段值的ANN检索操作，支持通过标量字段值进行过滤。

请求结构

                JSON
                
            

                POST /v{version}/row?search HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_test",
    "table": "table_test",
    "anns": {
        "vectorField": "vector_field",
        "vectorFloats": [
                0.2323234,
                0.34534545,
                0.9837234
        ],
        "params": {
           "ef": 100,
           "distanceFar": 50.0,
           "distanceNear": 0.0,
           "limit": 10
        },
        "filter": "id != '00000' AND age < 35"
    },
    "partitionKey": {
        "username": "alice"
    },
    "projections": ["id", "username"],
    "retrieveVector": true,
    "readConsistency": "EVENTUAL"
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
anns	AnnsSearchParams	是	RequestBody参数	检索请求参数详情。
partitionKey	JSON	否	RequestBody参数	目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
projections	List String	否	RequestBody参数	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
retrieveVector	bool	否	RequestBody参数	是否返回检索结果记录中的向量字段值，默认为false。
readConsistency	String	否	RequestBody参数	检索请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，检索请求会随机发送给分片的所有副本； STRONG：强一致性，检索请求只会发送给分片主副本。
advancedOptions	AdvancedOptions	否	RequestBody参数	检索的进阶设置。

AnnsSearchParams参数

参数名称	类型	是否必填	描述
vectorField	String	是	检索的向量字段。
vectorFloats(deprecated)	List Float	是	检索的目标向量值。(仅适用于稠密型向量场景)
vector	List Float/List Array/String	否	该字段与vectorFloats二选一，且支持稠密型向量(List Float)、稀疏性向量(List Array)、二进制向量(String)
params	VectorSearchParams	是	检索的参数详情。
filter	String	否	检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。当检索的向量字段上建立的索引类型为基于规则的索引时，filter字段必须是isolatedField对应列的等值过滤条件，比如'FieldA == 'Aa''

VectorSearchParams参数

HNSW / HNSWPQ / HNSWSQ索引

参数名称	参数类型	是否必选	参数含义
ef	Int	是	检索过程的动态候选列表的大小，取值范围为[limit, 10000]。
limit	Int	否	返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为50。
distanceFar	Float	否	范围检索场景中的最远距离，表示仅检索候选集中与目标向量的距离小于该值的向量。取值约束如下：任意距离算法下，distanceFar都必须大于distanceNear，不支持等于和小于；当索引距离为L2时，distanceFar和distanceNear仅支持正数；当索引距离为COSINE时，distanceFar和distanceNear的取值范围为[-1.0, 1.0]； distanceFar与distanceNear需要成对出现。
distanceNear	Float	否	范围检索场景中的最近距离，表示仅检索候选集中与目标向量的距离大于该值的向量。取值约束同上。

SPARSE_OPTIMIZED_FLAT索引

参数名称	参数类型	是否必选	参数含义
limit	Int	否	返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为50。

注：SPARSE_OPTIMIZED_FLAT索引不支持范围检索

PUCK索引

参数名称	参数类型	是否必选	参数含义
searchCoarseCount	Int	是	PUCK算法检索过程的粗聚类中心候选集的大小。
limit	Int	否	返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为50。

注：PUCK索引不支持范围检索

FLAT索引

参数名称	参数类型	是否必选	参数含义
limit	Int	否	返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为50。
distanceFar	Float	否	范围检索场景中的最远距离，表示仅检索候选集中与目标向量的距离小于该值的向量。取值约束如下：任意距离算法下，distanceFar都必须大于distanceNear，不支持等于和小于；当索引距离为L2时，distanceFar和distanceNear仅支持正数；当索引距离为COSINE时，distanceFar和distanceNear的取值范围为[-1.0, 1.0]； distanceFar与distanceNear需要成对出现。
distanceNear	Float	否	范围检索场景中的最近距离，表示仅检索候选集中与目标向量的距离大于该值的向量。取值约束同上。

IVF / IVFSQ索引

参数名称	参数类型	是否必选	参数含义
nprobe	Int	是	检索过程的候选聚类的数量，取值范围为[1, nlist]。
limit	Int	否	返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为50。
distanceFar	Float	否	范围检索场景中的最远距离，表示仅检索候选集中与目标向量的距离小于该值的向量。取值约束如下：任意距离算法下，distanceFar都必须大于distanceNear，不支持等于和小于；当索引距离为L2时，distanceFar和distanceNear仅支持正数；当索引距离为COSINE时，distanceFar和distanceNear的取值范围为[-1.0, 1.0]； distanceFar与distanceNear需要成对出现。
distanceNear	Float	否	范围检索场景中的最近距离，表示仅检索候选集中与目标向量的距离大于该值的向量。取值约束同上。

DISKANN索引

参数名称	参数类型	是否必选	参数含义
w	Int	是	检索过程的候选节点宽度。
searchL	Int	是	检索过程中搜索队的最大候选集合大小，需要满足searchL >= limit。
limit	Int	否	返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为50。

AdvancedOptions参数

参数名称	参数类型	是否必选	参数含义
acceptPartialSuccessOnMPP	Bool	是	向量检索是否接受MPP请求部分成功。
successRateLowerBoundOnMPP	Float	否	最低可以接受的MPP请求成功率。比如MPP同时请求10个分片，其中8个成功返回结果，那么此时的MPP请求成功率为0.8。当acceptPartialSuccessOnMPP=True时需要填写，取值范围为[0.0, 1.0]。

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息
rows	List Row	检索结果记录列表。

Row参数

参数名称	类型	描述
row	Row	一行记录。
distance	Float	该行记录与目标向量的距离。说明如下：在L2距离度量算法下，距离越小，与搜索向量越相似；在IP和COSINE距离度量算法下，距离越大，与搜索向量越相似。
score	Float	记录得分，得分越高，与搜索向量越相似。

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?search
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_test",
    "table": "table_test",
    "anns": {
        "vectorField": "vector_field",
        "vectorFloats": [
                0.2323234,
                0.34534545,
                0.9837234
        ],
        "params": {
           "ef": 100,
           "limit": 2
        },
        "filter": "id != '00000' AND age < 35"
    },
    "partitionKey": {
        "username": "alice"
    },
    "projections": ["id", "username"],
    "retrieveVector": true,
    "readConsistency": "EVENTUAL"
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "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
        }
    ]
}
            

批量向量检索

接口描述

基于向量字段值的ANN检索操作，支持同时指定多个向量进行检索，并通过标量字段值进行过滤。batchSearch接口仅适用于多节点标准版，单节点免费版请使用 Search 接口

请求结构

                JSON
                
            

                POST /v{version}/row?batchSearch HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_test",
    "table": "table_test",
    "anns": {
        "vectorField": "vector_field",
        "vectorFloats": [
            [
                0.2323234,
                0.34534545,
                0.9837234
            ],
            [
                0.3232321,
                0.54354321,
                0.9837234
            ]
        ],
        "params": {
           "ef": 100,
           "distanceFar": 50.0,
           "distanceNear": 0.0,
           "limit": 10
        },
        "filter": "id != '00000' AND age < 35"
    },
    "partitionKey": {
        "username": "alice"
    },
    "projections": ["id", "username"],
    "retrieveVector": true,
    "readConsistency": "EVENTUAL"
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
anns	AnnsSearchParams	是	RequestBody参数	检索请求参数详情。
partitionKey	JSON	否	RequestBody参数	目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
projections	List String	否	RequestBody参数	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
retrieveVector	bool	否	RequestBody参数	是否返回检索结果记录中的向量字段值，默认为false。
readConsistency	String	否	RequestBody参数	检索请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，检索请求会随机发送给分片的所有副本； STRONG：强一致性，检索请求只会发送给分片主副本。

AnnsSearchParams参数

参数名称	类型	是否必填	描述
vectorField	String	是	检索的向量字段。
vectorFloats(deprecated)	List	是	批量检索的目标向量列表。(仅适用于稠密型向量场景)
vector	List <List Float/List Array/String>	是	该字段与vectorFloats二选一，且支持稠密型向量(List Float)、稀疏型向量(List Array)、二进制向量(String)
params	VectorSearchParams	是	检索的参数详情。
filter	String	否	检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。当检索的向量字段上建立的索引类型为基于规则的索引时，filter字段必须是isolatedField对应列的等值过滤条件，比如'FieldA == 'Aa''

VectorSearchParams参数

请参见上文向量检索接口中的VectorSearchParams参数描述。

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息
results	List SearchResult	检索结果记录列表，每一项为单个向量的检索结果。

SearchResult参数

参数名称	类型	描述
searchVectorFloats	List Float	检索结果对应的检索向量（如果检索向量为稠密向量类型）。
searchVectorSparse	List Array	检索向量（如果检索向量为稀疏向量类型）。
searchVectorBinary	String	检索向量（如果检索向量为二进制向量类型）。
rows	List Row	单个向量的检索结果

注：searchVectorFloats、searchVectorSparse和searchVectorBinary三个参数有且仅有一个会出现在SearchResult中。

Row参数

参数名称	类型	描述
row	Row	一行记录。
distance	Float	该行记录与目标向量的距离。说明如下：在L2距离度量算法下，距离越小，与搜索向量越相似；在IP和COSINE距离度量算法下，距离越大，与搜索向量越相似。
score	Float	记录得分，得分越高，与搜索向量越相似。

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?batchSearch
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_test",
    "table": "table_test",
    "anns": {
        "vectorField": "vector_field",
        "vectorFloats": [
            [
                0.2323234,
                0.34534545,
                0.9837234
            ],
            [
                0.3232321,
                0.54354321,
                0.9837234
            ]
        ],
        "params": {
           "ef": 100,
           "limit": 2
        },
        "filter": "id != '00000' AND age < 35"
    },
    "partitionKey": {
        "username": "alice"
    },
    "projections": ["id", "username"],
    "retrieveVector": true,
    "readConsistency": "EVENTUAL"
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "code": 0,
    "msg": "Success",
    "results": [
        {
            "searchVectorFloats": [
                0.2323234,
                0.34534545,
                0.9837234
            ],
            "rows": [
                {
                    "row": {
                        "id": "00001",
                        "username": "alice",
                        "vector_field": [
                            0.20354213,
                            0.35934591,
                            0.89238402
                        ]
                    },
                    "distance": 0.01,
                    "score": 1.0
                }
            ]
        },
        {
            "searchVectorFloats": [
                -0.38593235,
                0.04340436,
                0.29452138
            ],
            "rows": [
                {
                    "row": {
                        "id": "00002",
                        "username": "tommy",
                        "vector_field": [
                            -0.3032433,
                            0.01492144,
                            0.22234959
                        ]
                    },
                    "distance": 0.01,
                    "score": 1.0
                }
            ]
        }
    ]
}
            

标量过滤查询

接口描述

基于标量属性过滤查询记录。

请求结构

                JSON
                
            

                POST /v{version}/row?select HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_test",
    "table": "table_test",
    "filter": "column1 = 'test' and column2 < 20",
    "marker": {
        "id": 10 
    }
    "limit": 50,
    "projections": ["column1", "column2", "vector"],
    "readConsistency": "EVENTUAL"
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
filter	String	否	RequestBody参数	过滤条件。当要查询全部记录，可不填写该字段或者填写为空字符串； Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。必须填写主键值或过滤条件，二者有且仅能选其一。
marker	JSON Object	否	RequestBody参数	查询的分页起始点，用于控制分页查询返回结果的起始位置，方便用户对数据进行分页展示和浏览，用户不填时，默认从第一条符合条件的记录开始返回。
limit	Int	否	RequestBody参数	查询返回的记录条数，在进行分页查询时，即每页的记录条数。默认为10，取值范围[1, 1000]。
projections	List String	否	RequestBody参数	投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
readConsistency	String	否	RequestBody参数	查询请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本； STRONG：强一致性，查询请求只会发送给分片主副本。

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息
isTruncated	bool	结果是否截断，即是否返回所有满足过滤条件记录：， true：存在截断，未返回所有记录，如需要查询更多的数据，需要使用响应结果中的nextMarker作为查询起始点查询； false：不存在截断，已返回全部结果；
rows	List Row	结果数据集
nextMarker	JSON Object	分页查询时的下一次查询起始点，当isTruncated为true时，可以利用该字段当作下一次的查询起始点分页查询。

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?select
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_test",
    "table": "table_test",
    "filter": "column1 = 'test' and column2 < 20",
    "marker": {
        "id": 10
    }
    "limit": 50,
    "projections": ["column1", "column2", "vector"],
    "readConsistency": "EVENTUAL"
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "isTruncated": true,
    "nextMarker": {
        "id": 100
    },
    "rows": [
        {
            "id": 10,
            "column1": "test",
            "column2": 15,
            "vector": [
                0.23432432,
                0.8923744,
                0.89238432
            ]
        }
    ]
    "code": 0,
    "msg": "Success"
}
            

全文检索

接口描述

基于搜索关键字进行全文检索，支持通过标量属性进行过滤。

请求结构

                JSON
                
            

                POST /v{version}/row?search HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_test",
    "table": "table_test",
    "BM25SearchParams" : {
         "indexName" : "content_inverted_index",
         "searchText" : "百度向量数据具备哪些优势" 
    },
    "partitionKey": {
        "userid":"user1"
    },
    "limit" : 100,
    "filter" : "column1 = 'test' and column2 < 20"
    "projections": ["column1", "column2"],
    "readConsistency": "EVENTUAL"
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
BM25SearchParams	BM25SearchParams	是	全文检索的参数详情。
partitionKey	JSON	否	RequestBody参数	目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
limit	Int	否	RequestBody参数	指定返回相关性最高的条目数
projections	List String	否	RequestBody参数	投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
filter	String	否	RequestBody参数	过滤条件。可设置为"*"；Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
readConsistency	String	否	RequestBody参数	查询请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本； STRONG：强一致性，查询请求只会发送给分片主副本。

BM25SearchParams

参数名称	类型	是否必填	描述
index_name	String	是	倒排索引的名字。
searchText	String	是	全文检索的检索表达式（UTF-8编码）。几种常见用法: `content:数据库`：在content这列搜索"数据库"关键字 `content:百度VectorDB数据库`：在content这列匹配"百度VectorDB数据库"中任意关键字 `content:"百度VectorDB数据库"`：搜索短语"百度VectorDB数据库" `content:百度 AND content:VectorDB`：在content列同时匹配"百度"、"VectorDB" 关键字 `content:百度 OR content:VectorDB`：在content列匹配"百度"、"VectorDB"的任意一个更多用法见全文检索表达式

全文检索表达式

检索类型	用法	例子	例子含义	备注
关键词检索	`field_name:keyword` `field_name:(keyword_1, keyword_2)`	`title:数据库` `title:(数据库百度)`	在title这列搜索“数据库”关键字在title这列搜索“数据库”、"百度"关键字，满足任意一个即可
关键词检索	`keyword` `keyword_1 AND keyword_2`	`数据库` `数据库 AND 百度`	在content 这列上搜索"数据库"关键字在content 这列上搜索，要求同时包括"数据库"、"百度" 关键字	只适用于在单列上建立倒排索引的情况。对于多列倒排索引，必须使用上述 `field_name:keyword` 的方式指定检索词。
复合检索: AND/OR	`query_1 AND query_2` `query_1 OR query_2` `(query_1 OR query_2) AND query_3`	`title:数据库 AND title:百度` `title:数据库 OR title:百度` `(title:数据库 OR title:百度) AND content:VectorDB`	在title这列搜索, 要求同时包括"数据库"、"百度" 这2个关键字在title这列搜索, 要求包括"数据库"、"百度" 任意一个在title这列搜索, 要求包括"数据库"、"百度" 任意一个，同时content列包含"VectorDB"关键字
Phrase检索	`field_name:"phrase"`	`title:"百度VectorDB数据库"`	在title这里搜索"百度VectorDB数据库"短语	短语必须使用双引号
Match检索	`field_name:statement`	`content:百度VectorDB的优缺点`	在content这列搜索"百度VectorDB的优缺点"的任意词，匹配词数量越多，相关性得分越高
Prefix检索	`field_name:keyword*`	`title:数据*`	在title这列检索，包含以"数据"为前缀词的文档
更改查询权重	`field_name:keyword^boost`	`title:数据库^2 OR content:百度`	title包括"数据库"关键字，或content包含“百度”关键字，最后计算相关性得分是，title列匹配的文档权重系数为2， content 列匹配的权重系数为1	不设置boost的话，默认权重都是1

全文检索表达式会将一些特殊字符用于专用目的，如想在表达式中匹配一些特殊字符，需要用 \ 符号进行转义。当前被征用特殊字符包括:

+ - && || ! ( ) { } [ ] ^ " ~ * ? : `

以 百度自研的向量数据库:VectorDB 这个表达式为例，表达式解释器会认为在"百度自研的向量数据库" 这列上搜索 VectorDB，这就违背了使用者的初衷，为此需把表达式写成 百度自研的向量数据库\\:VectorDB。

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息
rows	List Row	返回的记录

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?search
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_test",
    "table": "table_test",
    "BM25SearchParams": {
         "indexName" : "content_inverted_index",
         "searchText" : "content:中国GDP的增速"
    },
    "limit" : 10,
    "projections" : ["id", "title"]
    "readConsistency": "EVENTUAL"
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "rows": [
        {"row":{"id":"333212","title":"名山区"},"score":15.382493019104004},
        {"row":{"id":"3417777","title":"魏建国 (1947年)"},"score":15.32309341430664},
        {"row":{"id":"8131711","title":"习近平在福州"},"score":14.099751472473145},
        {"row":{"id":"7931209","title":"萬億俱樂部"},"score":13.53740406036377},
        {"row":{"id":"659935","title":"尼日利亚经济"},"score":13.401798248291016},
        {"row":{"id":"1659825","title":"江苏省经济"},"score":12.93088436126709},
        {"row":{"id":"3463067","title":"克强指数"},"score":12.81386947631836},
        {"row":{"id":"7537348","title":"内蒙古自治区经济"},"score":12.1427640914917},
        {"row":{"id":"6162361","title":"新常态 (中华人民共和国)"},"score":11.916200637817383},
        {"row":{"id":"5603021","title":"云南省经济"},"score":11.906570434570312}
    ],
    "code": 0,
    "msg": "Success"
}
            

混合检索

接口描述

同时进行关键字全文检索和向量检索，检索结果融合排序后返回，也支持通过标量属性进行过滤。

请求结构

                JSON
                
            

                POST /v{version}/row?search HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_test",
    "table": "table_test",
    "BM25SearchParams" : {
         "indexName" : "content_inverted_index",
         "searchText" : "百度向量数据具备哪些优势",
         "weight" : 0.5 
    },
    "anns" : {
        "vectorField": "vector_field_1",
        "vectorFloats": [
                0.2323234,
                0.34534545,
                0.9837234
        ],
        "params": {
           "ef": 100,
           "distanceFar": 50.0,
           "distanceNear": 0.0
        }
        "weight" : 0.5
    },
    "partitionKey": {
        "userid":"user1"
    },
    "limit" : 100,
    "filter" : "column1 = 'test' and column2 < 20"
    "projections": ["column1", "column2"],
    "readConsistency": "EVENTUAL"
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
BM25SearchParams	BM25SearchParams	否	RequestBody参数	全文检索的参数详情
anns	AnnsSearchParams	否	RequestBody参数	检索请求参数详情。
partitionKey	JSON	否	RequestBody参数	目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
limit	Int	否	RequestBody参数	指定返回相关性最高的条目数
projections	List String	否	RequestBody参数	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
filter	String	否	RequestBody参数	过滤条件。可设置为"*"；Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。当检索的向量字段上建立的索引类型为基于规则的索引时，filter字段必须是isolatedField对应列的等值过滤条件，比如'FieldA == 'Aa''
readConsistency	String	否	RequestBody参数	检索请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，检索请求会随机发送给分片的所有副本； STRONG：强一致性，检索请求只会发送给分片主副本。

BM25SearchParams

参数名称	类型	是否必填	描述
indexName	String	是	倒排索引的名字
searchText	String	是	全文检索的检索表达式（UTF-8编码）。几种常见用法: `content:数据库`：在content这列搜索"数据库"关键字 `content:百度VectorDB数据库`：在content这列匹配"百度VectorDB数据库"中任意关键字 `content:"百度VectorDB数据库"`：搜索短语"百度VectorDB数据库" `content:百度 AND content:VectorDB`：在content列同时匹配"百度"、"VectorDB" 关键字 `content:百度 OR content:VectorDB`：在content列匹配"百度"、"VectorDB"的任意一个更多用法见全文检索表达式
weight	Float	否	全文检索在最终结果的权重，默认是1.0

全文检索表达式

检索类型	用法	例子	例子含义	备注
关键词检索	`field_name:keyword` `field_name:(keyword_1, keyword_2)`	`title:数据库` `title:(数据库百度)`	在title这列搜索“数据库”关键字在title这列搜索“数据库”、"百度"关键字，满足任意一个即可
关键词检索	`keyword` `keyword_1 AND keyword_2`	`数据库` `数据库 AND 百度`	在content 这列上搜索"数据库"关键字在content 这列上搜索，要求同时包括"数据库"、"百度" 关键字	只适用于在单列上建立倒排索引的情况。对于多列倒排索引，必须使用上述 `field_name:keyword` 的方式指定检索词。
复合检索: AND/OR	`query_1 AND query_2` `query_1 OR query_2` `(query_1 OR query_2) AND query_3`	`title:数据库 AND title:百度` `title:数据库 OR title:百度` `(title:数据库 OR title:百度) AND content:VectorDB`	在title这列搜索, 要求同时包括"数据库"、"百度" 这2个关键字在title这列搜索, 要求包括"数据库"、"百度" 任意一个在title这列搜索, 要求包括"数据库"、"百度" 任意一个，同时content列包含"VectorDB"关键字
Phrase检索	`field_name:"phrase"`	`title:"百度VectorDB数据库"`	在title这里搜索"百度VectorDB数据库"短语	短语必须使用双引号
Match检索	`field_name:statement`	`content:百度VectorDB的优缺点`	在content这列搜索"百度VectorDB的优缺点"的任意词，匹配词数量越多，相关性得分越高
Prefix检索	`field_name:keyword*`	`title:数据*`	在title这列检索，包含以"数据"为前缀词的文档
更改查询权重	`field_name:keyword^boost`	`title:数据库^2 OR content:百度`	title包括"数据库"关键字，或content包含“百度”关键字，最后计算相关性得分是，title列匹配的文档权重系数为2， content 列匹配的权重系数为1	不设置boost的话，默认权重都是1

全文检索表达式会将一些特殊字符用于专用目的，如想在表达式中匹配一些特殊字符，需要用 \ 符号进行转义。当前被征用特殊字符包括: + - && || ! ( ) { } [ ] ^ " ~ * ? : `

AnnsSearchParams参数

参数名称	类型	是否必填	描述
vectorField	String	是	检索的向量字段。
vectorFloats(deprecated)	List Float	是	检索的向量数据。(只支持稠密型向量)
vector	List Float/List Array/String	是	该字段与vectorFloats二选一，且支持稠密型向量(List Float)、稀疏型向量(List Array)、二进制向量(String)
params	VectorSearchParams	是	向量检索参数详情。
weight	Float	否	向量检索结果在最终结果的权重

VectorSearchParams参数

请参见上文向量检索接口中的VectorSearchParams参数描述。

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息
rows	List Row	检索结果记录列表。

Row参数

参数名称	类型	描述
row	Row	一行记录。
distance	Float	该行记录与目标向量的距离。说明如下：在L2距离度量算法下，距离越小，与搜索向量越相似；在IP和COSINE距离度量算法下，距离越大，与搜索向量越相似。
score	Float	记录得分，得分越高，与搜索向量越相似。

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?search
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_test",
    "table": "table_test",
    "BM25SearchParams": {
         "indexName" : "content_inverted_index",
         "searchText" : "content:中国GDP的增速",
         "weight" : 0.5
    },
    "anns" : {
        "vectorField": "vector_field_1",
        "vectorFloats": [
                0.2323234,
                0.34534545,
                0.9837234
        ],
        "params": {
           "ef": 100,
           "distanceFar": 50.0,
           "distanceNear": 0.0
        },
        "weight" : 0.5
    },
    "limit" : 10,
    "projections" : ["id", "title"],
    "filter" : "column1 > 10 and column2 < 20",
    "readConsistency": "EVENTUAL"
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "rows": [
          {"row":{"id":"333212","title":"名山区"},"score":1.0},
          {"row":{"id":"3417777","title":"魏建国 (1947年)"},"score":0.5},
          .........
    ],
    "code": 0,
    "msg": "Success"
}
            

多向量检索

接口描述

对多个向量列分别进行相似性检索，对多路结果进行融合排序后返回最终结果。

请求结构

                JSON
                
            

                POST /v{version}/row?multiVectorSearch HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
    "database": "db_test",
    "table": "table_test",
    "search": [
        {
            "vectorField": "title",
            "vector": [0.2323234, 0.34534545, 0.9837234],
            "params": {
                "limit": 20,
                "ef": 100
            }
        },
        {
            "vectorField": "content",
            "vector": [0.0753841, 0.9971545],
            "params": {
                "limit": 30,
                "ef": 100,
                "distanceNear": 0.0,
                "distanceFar": 50.0
            }
        }
    ],
    "ranking": {
        "strategy": "rrf",
        "params": {
            "k": 60
        }
    },

    "limit": 10,
    "filter": "id != '00000' AND age < 35",
    "partitionKey": {
        "username": "alice"
    },
    "projections": ["id", "username"],
    "readConsistency": "EVENTUAL"
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必填	参数位置	描述
version	String	是	URL参数	API版本号，当前取1。
database	String	是	RequestBody参数	指定库的名称。
table	String	是	RequestBody参数	指定表的名称。
search	List SearchParam	是	RequestBody参数	向量检索列表。每个元素代表一路向量检索，包含检索的向量及每个向量的检索参数。
ranking	Ranking	否	RequestBody参数	融合排序算法及参数。
filter	String	否	RequestBody参数	过滤条件。可设置为"*"；Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。当检索的向量字段上建立的索引类型为基于规则的索引时，filter字段必须是isolatedField对应列的等值过滤条件，比如'FieldA == 'Aa''
limit	Int	否	RequestBody参数	指定返回相关性最高的条目数
partitionKey	JSON	否	RequestBody参数	目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
projections	List String	否	RequestBody参数	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
readConsistency	String	否	RequestBody参数	检索请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，检索请求会随机发送给分片的所有副本； STRONG：强一致性，检索请求只会发送给分片主副本。

SearchParams

参数名称	类型	是否必填	描述
vectorField	String	是	检索的向量字段。
vector	List Float/List Array/String	是	检索的向量数据。支持稠密型向量(List Float)、稀疏性向量(List Array)、二进制向量(String)
params	VectorSearchParams	是	向量检索参数详情。

VectorSearchParams参数

请参见上文向量检索接口中的VectorSearchParams参数描述。

Ranking

参数名称	参数类型	是否必选	参数含义
strategy	String	是	融合排序算法，当前支持rrf和ws两种算法。其中rrf代表RRF算法，ws代表WeightedRank算法。
params	RankingParams	否	融合排序算法的参数。对于不同的融合排序算法，其结构不同。当融合排序算法为rrf时，params默认为k=60 当融合排序算法为ws时，params默认为每个向量权重1/n

RankingParams(RRF)

参数名称	参数类型	是否必选	参数含义
k	Int	是	融合排序算法的参数。score 计算公式：

RankingParams(WeightedRank)

参数名称	参数类型	是否必选	参数含义
weights	List Int	是	WeightedRank算法中每个向量的权重，其长度需要与向量个数相同。 score计算公式：

响应头域

除公共头域外，无其它特殊头域。

响应参数

参数名称	类型	描述
code	Int	返回码
msg	String	返回信息
rows	List Row	检索结果记录列表。

Row参数

参数名称	类型	描述
row	Row	一行记录。
score	Float	记录得分，得分越高，与搜索向量越相似。

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?multiVectorSearch
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_test",
    "table": "table_test",
    "search": [
        {
            "vectorField": "title",
            "vector": [0.2323234, 0.34534545, 0.9837234],
            "params": {
                "limit": 20,
                "ef": 100
            }
        },
        {
            "vectorField": "content",
            "vector": [0.0753841, 0.9971545],
            "params": {
                "limit": 30,
                "ef": 100,
                "distanceNear": 0.0,
                "distanceFar": 50.0
            }
        }
    ],
    "ranking": {
        "strategy": "rrf",
        "params": {
            "k": 60
        }
    },

    "limit": 10,
    "filter": "id != '00000' AND age < 35",
    "partitionKey": {
        "username": "alice"
    },
    "projections": ["id", "username"],
    "readConsistency": "EVENTUAL"
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "rows": [
        {
            "row": {
                "id": "00001",
                "username": "alice"
            },
            "score": 1.0
        }
    ],
    "code": 0,
    "msg": "Success"
}
            

SearchIterator

接口描述

SearchIterator 提供了一种分页获取搜索结果的机制。在 SearchIterator 请求中，limit参数用于指定当前分页的返回结果数量。通过多次调用迭代器，可以突破单次检索的 topK 数量限制，逐步获取完整的结果集。对于 topK 值较大的搜索请求，推荐使用 SearchIterator 来实现结果的分批次获取。

限制

仅支持 HNSW、HNSWPQ 索引类型
仅支持向量TopK检索（TopKVectorSearch）、多向量检索（MultiVectorSearch），不支持向量范围检索（RangeVectorSearch）、批量向量检索（BatchVectorSearch）、全文检索（BM25Search）、混合检索（HybridSearch）
对于 MultiVectorSearch，仅支持 ws融合排序算法

请求结构

SearchIterator 接口的 request 和 response 参数与向量检索类似。以下是与向量检索有差异的地方：

request 中需要包含 iteratedIds字段。该字段表示当前 search iterator 已经遍历过的数据。
- 首次请求中，需要将iteratedIds设置为空字符串。
- 后续请求中，将 iteratedIds设置为上次请求 response 中返回的 iteratedIds字段值。
response 中会包含 iteratedIds字段，代表更新后的 iteratedIds值。

请求头域

除公共头域外，无其它特殊头域。

请求参数

以下仅列举与向量检索的请求参数有差异的参数：

参数名称	类型	是否必填	参数位置	描述
iteratedIds	String	是	RequestBody参数	当前 search iterator 已经遍历过的数据

响应头域

除公共头域外，无其它特殊头域。

响应参数

以下仅列举与向量检索的响应有差异的参数：

参数名称	类型	描述
iteratedIds	String	当前 search iterator 已经遍历过的数据

请求示例

                JSON
                
            

                POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/row?search
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
    "database": "db_test",
    "table": "table_test",
    "anns": {
        "vectorField": "vector_field_1",
        "vectorFloats": [
                0.2323234,
                0.34534545,
                0.9837234
        ],
        "params": {
           "ef": 100,
           "distanceFar": 50.0,
           "distanceNear": 0.0,
           "limit": 50
        },
        "filter": "column1 > 10 and column2 < 20"
    },
    "partitionKey": {
        "userid":"user1"
    },
    "projections": ["column1", "column2"],
    "retrieveVector": false,
    "readConsistency": "EVENTUAL",
    "iteratedIds": "Q1p8Y0lDUEpSMkVsU0xITw=="
}
            

响应示例

                JSON
                
            

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Wed, 08 Jul 2015 03:28:11 GMT
Request-ID: d8752367-38e8-45e4-b4c7-e53be3137ce5
{
    "rows": [
        {
            "row": {
                "id": "00001",
                "vector": [
                    0.23432432,
                    0.8923744,
                    0.89238432
                ],
                "other_scalar_column": "other_scalar_column"
            },
            "distance": 0.01
        }
    ],
    "code": 0,
    "msg": "Success",
    "iteratedIds": "Ym5GZ2NZb1hmY0JwQ0FQV2ZKbUZGVWhZQm1KN3V1c3JhU1dHWmNQZ0VJTA=="
}
            

Alias 操作

Index 操作

向量数据库 VectorDB

Row 操作

插入记录

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

插入或更新记录

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

更新记录

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

删除记录

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

标量查询

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

标量批量查询

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

向量检索

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

批量向量检索

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

标量过滤查询

接口描述

请求结构

请求头域

请求参数

响应头域