Row 操作

更新时间：2024-11-29

插入记录

接口描述

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

请求结构

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	写入成功的记录数

请求示例

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=="
        }
    ]
}

响应示例

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），即，当记录的主键已存在时，则用新的数据整体覆盖旧的数据。当插入一批时，该接口暂不支持批次的原子性。该接口可用于批量迁移/灌库等场景。

请求结构

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	写入成功的记录数

请求示例

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=="
        }
    ]
}

响应示例

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
}

更新记录

接口描述

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

请求结构

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	返回信息

请求示例

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,
            ...
         ]
     }
}

响应示例

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

删除记录

接口描述

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

请求结构

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	返回信息

请求示例

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

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

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

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'"
}

响应示例

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

查询单条记录

接口描述

基于主键值的点查操作。

请求结构

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	结果数据集

请求示例

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

响应示例

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

标量批量查询

接口描述

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

请求结构

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	检索结果记录列表。

请求示例

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

响应示例

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检索操作，支持通过标量字段值进行过滤。

请求结构

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：强一致性，检索请求只会发送给分片主副本。

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条件表达式。

VectorSearchParams参数

HNSW索引

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

PUCK索引

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

HNSWPQ索引

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

响应头域

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

响应参数

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

Row参数

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

请求示例

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

响应示例

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 接口

请求结构

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 Float	是	批量检索的目标向量列表。(仅适用于稠密型向量场景)
vector	List Float/List Array/String	是	该字段与vectorFloats二选一，且支持稠密型向量(List Float)、稀疏性向量(List Array)、二进制向量(String)
params	VectorSearchParams	是	检索的参数详情。
filter	String	否	检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。

VectorSearchParams参数

HNSW索引

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

PUCK索引

参数名称	参数类型	是否必选	参数含义
searchCoarseCount	Int	是	PUCK算法检索过程的粗聚类中心候选集的大小。
limit	Int	否	返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为50。
distanceFar	Float	否	mochow.1.3 puck索引暂不支持range search
distanceNear	Float	否	mochow.1.3 puck索引暂不支持range search

HNSWPQ索引

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

响应头域

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

响应参数

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

SearchResult

参数名称	类型	描述
searchVectorFloats	List Float	检索向量。
rows	List Row	单个向量的检索结果

Row参数

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

请求示例

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

响应示例

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

标量过滤查询

接口描述

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

请求结构

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时，可以利用该字段当作下一次的查询起始点分页查询。

请求示例

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

响应示例

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

全文检索

接口描述

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

请求结构

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

参数名称	类型	是否必填	描述
indexName	String	是	倒排索引的名字
searchText	String	是	全文检索的检索表达式，UTF-8编码，几种常见用法: 在content这列搜索"数据库"关键字，例子 content:数据库在content这列匹配"百度VectorDB数据库"中任意关键字, 例子 content: 百度VectorDB数据库搜索短语"百度VectorDB数据库"，例子 content: "百度VectorDB数据库" content这列同时匹配"百度"、"VectorDB" 关键字, 例子 content: 百度 AND content: VectorDB 在content这列匹配"百度"、"VectorDB"的任意一个，例子 content: 百度 OR 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 这列上搜索，要求同时包括"数据库"、"百度" 关键字	只适用于在单列上建立倒排索引的情况，如在content 这列上建立倒排索引
复合检索: 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	返回的记录

请求示例

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

响应示例

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

混合检索

接口描述

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

请求结构

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条件表达式。
readConsistency	String	否	RequestBody参数	检索请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，检索请求会随机发送给分片的所有副本； STRONG：强一致性，检索请求只会发送给分片主副本。

BM25SearchParams

参数名称	类型	是否必填	描述
indexName	String	是	倒排索引的名字
searchText	String	是	全文检索的检索表达式，UTF-8编码，几种常见用法: 在content这列搜索"数据库"关键字，例子 content:数据库在content这列匹配"百度VectorDB数据库"中任意关键字, 例子 content: 百度VectorDB数据库搜索短语"百度VectorDB数据库"，例子 content: "百度VectorDB数据库" content这列同时匹配"百度"、"VectorDB" 关键字, 例子 content: 百度 AND content: VectorDB 在content这列匹配"百度"、"VectorDB"的任意一个，例子 content: 百度 OR 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 这列上搜索，要求同时包括"数据库"、"百度" 关键字	只适用于在单列上建立倒排索引的情况，如在content 这列上建立倒排索引
复合检索: 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参数

HNSW索引

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

PUCK索引

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

HNSWPQ索引

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

响应头域

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

响应参数

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

Row参数

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

请求示例

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

响应示例

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

多向量检索

接口描述

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

请求结构

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条件表达式。
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参数

HNSW索引

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

PUCK索引

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

HNSWPQ索引

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

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	记录得分，得分越高，与搜索向量越相似。

请求示例

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",
    "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"
}

响应示例

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

Alias 操作

Index 操作

向量数据库 VectorDB

Row 操作

插入记录

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

更新插入记录

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

更新记录

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

删除记录

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

查询单条记录

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

标量批量查询

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

向量检索

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

批量向量检索

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

标量过滤查询

接口描述

请求结构

请求头域

请求参数

响应头域