Row 操作
更新时间:2024-06-18
插入记录
接口描述
将一条或者一批记录插入到指定的表中。插入语义为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
]
}
]
}
请求头域
除公共头域外,无其它特殊头域。
请求参数
参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
---|---|---|---|---|
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
]
}
]
}
响应示例
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
]
}
]
}
请求头域
除公共头域外,无其它特殊头域。
请求参数
参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
---|---|---|---|---|
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
]
}
]
}
响应示例
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?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参数 | 查询请求的一致性级别,取值为: |
响应头域
除公共头域外,无其它特殊头域。
响应参数
参数名称 | 类型 | 描述 |
---|---|---|
code | Int | 返回码 |
msg | String | 返回信息 |
tables | List 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
]
}
}
向量检索与混合检索
接口描述
基于向量字段值的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参数 | 检索请求的一致性级别,取值为: |
AnnsSearchParams参数
参数名称 | 类型 | 是否必填 | 描述 |
---|---|---|---|
vectorField | String | 是 | 检索的向量字段。 |
vectorFloats | String | 是 | 检索的目标向量值。 |
params | VectorSearchParams | 是 | 检索的参数详情。 |
filter | String | 否 | 检索的标量过滤条件,表示仅在符合过滤条件的候选集中进行检索,默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计,其详细描述和使用示例请参见Filter条件表达式。 |
VectorSearchParams参数
HNSW索引
参数名称 | 参数类型 | 是否必选 | 参数含义 |
---|---|---|---|
ef | Int | 是 | HNSW算法检索过程的动态候选列表的大小。 |
limit | Int | 否 | 返回最接近目标向量的向量记录数量,相当于TopK的K值,默认为50。 |
distanceFar | Float | 否 | 范围检索场景中的最远距离,表示仅检索候选集中与目标向量的距离小于该值的向量。取值约束如下: |
distanceNear | Float | 否 | 范围检索场景中的最近距离,表示仅检索候选集中与目标向量的距离大于该值的向量。取值约束同上。 |
PUCK索引
参数名称 | 参数类型 | 是否必选 | 参数含义 |
---|---|---|---|
searchCoarseCount | Int | 是 | PUCK算法检索过程的粗聚类中心候选集的大小。 |
limit | Int | 否 | 返回最接近目标向量的向量记录数量,相当于TopK的K值,默认为50。 |
distanceFar | Float | 否 | mochow.1.2 puck索引暂不支持range search |
distanceNear | Float | 否 | mochow.1.2 puck索引暂不支持range search |
响应头域
除公共头域外,无其它特殊头域。
响应参数
参数名称 | 类型 | 描述 |
---|---|---|
code | Int | 返回码 |
msg | String | 返回信息 |
rows | List Row | 检索结果记录列表。 |
Row参数
参数名称 | 类型 | 描述 |
---|---|---|
row | Row | 一行记录。 |
distance | Float | 该行记录与目标向量的距离。说明如下: |
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
}
]
}