Table 操作
更新时间:2024-09-29
创建表
接口描述
在指定的库中新建一个表。
请求结构
POST /v{version}/table?create HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
"database": "db_name",
"table": "table_name",
"description": "table description",
"replication": 3,
"partition": {
"partitionType": "HASH",
"partitionNum": 10
},
"enableDynamicField": false,
"schema": {
"fields": [
{
"fieldName": "id",
"fieldType": "UINT64",
"primaryKey": true,
"partitionKey": true,
"autoIncrement": true
},
...
],
"indexes": [
{
"field": "vector1",
"indexName": "vector1_idx",
"indexType": "HNSW",
"metricType": "L2",
"params": {
"M": 32,
"efConstruction": 200
},
"autoBuild": true,
"autoBuildPolicy": {
"policyType": "timing",
"timing": "2024-01-01 12:00:00"
}
},
...
]
}
}
请求头域
除公共头域外,无其它特殊头域。
请求参数
参数名称 | 类型 | 是否必填 | 传递位置 | 描述 |
---|---|---|---|---|
version | String | 是 | URL参数 | API版本号,当前仅v1。 |
database | String | 是 | URL参数 | 库的名称。 |
table | String | 是 | RequestBody参数 | 表的名称。表命名要求如下: 1. 仅支持大小写字母、数字以及下划线(_),必须以字母开头; 2. 长度限制为1-255。 |
description | String | 否 | RequestBody参数 | 表的描述信息。 |
replication | Int | 是 | RequestBody参数 | 复制数,即单个表分区的副本数量(含主副本),取值范围为[1,10]。 若需要完整的高可用性特性,副本数需>=3。 注意:副本数需要小于等于数据节点(DataNode)的数量,否则无法正常建表。 |
partition | Partition | 是 | RequestBody参数 | 表的分区数量,取值范围为[1, 1000]。 建议根据预期的记录总数来评估分区数量,建议将单个分区的记录数量控制在100万到1000万之间。 |
enableDynamicField | Bool | 否 | RequestBody参数 | 是否支持动态字段,默认为false。 |
schema | Schema | 是 | RequestBody参数 | 表的Schema信息。 |
Partition参数
参数名称 | 参数类型 | 描述 |
---|---|---|
partitionType | String | 分区类型枚举,当前仅支持"HASH"。 |
partitionNum | Int | 分区的数量,取值范围为[1,1000]。 |
Schema参数
参数名称 | 参数类型 | 描述 |
---|---|---|
fields | List Field | 字段列表。 |
indexes | List Index | 索引列表。 |
Field参数
参数名称 | 类型 | 描述 |
---|---|---|
fieldName | String | 字段名称。字段命名要求如下: 1. 仅支持大小写字母、数字以及下划线(_),必须以字母开头; 2. 长度限制为1-255。 |
fieldType | String | 字段类型。当前支持如下类型:BOOL、INT8、UINT8、INT16、UINT16、INT32、UINT32、INT64、UINT64、FLOAT、DOUBLE、DATE、DATETIME、TIMESTAMP、UUID、STRING、BINARY、TEXT、TEXT_GBK、TEXT_GB18030、FLOAT_VECTOR。 各数据类型的详细定义和约束请参见“产品介绍”目录的“数据类型”页面。 |
primaryKey | Boolean | 是否为主键,默认取值为False。 当前已支持多主键,详情参见多主键。 主键字段不支持如下类型:BOOL、FLOAT、DOUBLE和FLOAT_VECTOR。 |
partitionKey | Boolean | 是否为分区键,默认取值为False。 当前仅支持单一字段作为分区键,分区键可以是主键,也可以不是主键,但一张表只能有一个分区键,每行记录都会根据分区键的取值哈希映射到不同的分区。 分区键字段不支持如下类型:BOOL、FLOAT、DOUBLE和FLOAT_VECTOR。 |
autoIncrement | Boolean | 是否为自增主键,默认取值为False。 仅适用于类型为UINT64的主键字段,其它字段不适用该属性。 |
notNull | Boolean | 是否非空,默认取值为False。 如下字段类型不可为空:主键字段、分区键字段、二级索引键字段、向量字段。 |
dimension | Int | 向量维度。只有数据类型为FLOAT_VECTOR时,才需要指定该参数。 |
Index参数
参数名称 | 类型 | 描述 |
---|---|---|
indexName | String | 索引名字。索引命名要求如下: 1. 仅支持大小写字母、数字以及下划线(_),必须以字母开头; 2. 长度限制为1-255。 |
indexType | String | 索引类型。当前支持的类型如下: |
metricType | String | 向量索引的距离度量类型。支持的类型如下: |
params | VectorIndexParams | 向量索引的参数详情。 |
field | String | 索引作用于的目标字段名称。 |
autoBuild | Boolean | 是否自动构建索引。 |
autoBuildPolicy | AutoBuildPolicy | 构建索引策略。 |
AutoBuildPolicy
参数名称 | 类型 | 描述 |
---|---|---|
policyType | String | 自动构建索引策略类型,大小写不敏感,支持的类型如下: |
timing | String | |
periodInSecond | Uint64 | 周期性构建索引的参数,每过periodInSecond构建一次索引,只在policyType为periodical时生效。可以指定从某个时间点开始,通过上面的timing参数传入。周期不能低于3600 |
rowCountIncrement | Uint64 | 当tablet(不是table)增加或者减少行数大于rowCountIncrement时构建一次索引,只在policyType为row_count_increment时生效。不能低于10000 |
rowCountIncrementRatio | double | 当tablet增加或者减少行数百分比大于rowCountIncrementRatio时构建一次索引,只在policyType为row_count_increment时生效。不能小于等于0 |
VectorIndexParams参数
HNSW索引
参数名称 | 类型 | 描述 |
---|---|---|
M | Int | HNSW索引参数,取值范围为[4, 128]。 该参数表示在HNSW索引图中每个节点连接多少个邻居节点。 |
efConstruction | Int | HNSW索引参数,取值范围为[8, 1024]。 该参数表示在构建时使用临时邻居节点的数量,数值较大时搜索质量更好,构建时间也较长。 |
PUCK索引
参数名称 | 类型 | 描述 |
---|---|---|
coarseClusterCount | Int | PUCK索引参数,取值范围为[1, 5000]。 该参数表示索引中粗聚类中心个数。 |
fineClusterCount | Int | PUCK索引参数,取值范围为[1, 5000]。 该参数表示每个粗聚类中心下细聚类中心个数。 |
HNSWPQ索引
参数名称 | 类型 | 描述 |
---|---|---|
M | Int | HNSWPQ索引参数,取值范围为[4, 128]。 该参数表示在HNSWPQ索引图中每个节点连接多少个邻居节点。 |
efConstruction | Int | HNSWPQ索引参数,取值范围为[8, 1024]。 该参数表示在构建时使用临时邻居节点的数量,数值较大时搜索质量更好,构建时间也较长。 |
NSQ | Int | HNSWPQ索引参数,取值范围为[1, dim]。 该参数表示量化子空间个数,pq量化相关系数,要求NSQ | dim,NSQ越大量化越精细 |
sampleRate | float | HNSWPQ索引参数,取值范围为[0.0f, 1.0f]。 该参数表示kmeans的采样率,pq抽样总数:10000 + (rowCount - 10000)*sampleRate |
响应头域
除公共头域外,无其它特殊头域。
响应参数
参数名称 | 类型 | 描述 |
---|---|---|
code | Int | 返回码 |
msg | String | 返回信息 |
请求示例
POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/table?create
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
"database": "db_test",
"table": "table_test",
"description": "table description",
"replication": 3,
"partition": {
"partitionType": "HASH",
"partitionNum": 10
},
"enableDynamicField": false,
"schema": {
"fields": [
{
"fieldName": "id",
"fieldType": "UINT64",
"primaryKey": true,
"partitionKey": true,
"autoIncrement": true
},
{
"fieldName": "scalar1",
"fieldType": "UINT64",
"notNull": true
},
{
"fieldName": "scalar2",
"fieldType": "STRING"
},
{
"fieldName": "vector1",
"fieldType": "FLOAT_VECTOR",
"dimension": 768
},
{
"fieldName": "vector2",
"fieldType": "FLOAT_VECTOR",
"dimension": 1536
},
{
"fieldName": "vector3",
"fieldType": "FLOAT_VECTOR",
"dimension": 1024
},
{
"fieldName": "vector4",
"fieldType": "FLOAT_VECTOR",
"dimension": 128
},
],
"indexes": [
{
"field": "vector1",
"indexName": "vector1_idx",
"indexType": "HNSW",
"metricType": "L2",
"params": {
"M": 32,
"efConstruction": 200
}
},
{
"field": "vector2",
"indexName": "vector2_idx",
"indexType": "FLAT",
"metricType": "L2"
},
{
"field": "vector3",
"indexName": "vector3_idx",
"indexType": "PUCK",
"metricType": "L2"
"params": {
"coarseClusterCount": 50,
"fineClusterCount": 50
}
},
{
"field": "vector4",
"indexName": "vector4_idx",
"indexType": "HNSWPQ",
"metricType": "L2"
"params": {
"M": 50,
"efConstruction": 160,
"NSQ": 128,
"sampleRate": 1.0
}
},
{
"field": "scalar1",
"indexName": "scalar1_idx",
"indexType": "SECONDARY"
}
]
}
}
响应示例
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"
}
删除表
接口描述
删除指定的表。
请求结构
DELETE /v{version}/table HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
"database": "db_name",
"table": "table_name"
}
请求头域
除公共头域外,无其它特殊头域。
请求参数
参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
---|---|---|---|---|
version | String | 是 | URL参数 | API版本号,当前取1。 |
database | String | 是 | Query参数 | 指定库的名称。 |
table | String | 是 | Query参数 | 指定表的名称。 |
响应头域
除公共头域外,无其它特殊头域。
响应参数
参数名称 | 类型 | 描述 |
---|---|---|
code | Int | 返回码 |
msg | String | 返回信息 |
请求示例
DELETE http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/table
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
"database": "db_test",
"table": "table_test",
}
响应示例
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}/table?list HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
"database": "db_name"
}
请求头域
除公共头域外,无其它特殊头域。
请求参数
参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
---|---|---|---|---|
version | String | 是 | URL参数 | API版本号,当前取1。 |
database | String | 是 | RequestBody参数 | 指定库的名称。 |
响应头域
除公共头域外,无其它特殊头域。
响应参数
参数名称 | 类型 | 描述 |
---|---|---|
code | Int | 返回码 |
msg | String | 返回信息 |
tables | List String | 数据表列表 |
请求示例
POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/table?list
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
"database": "db_test"
}
响应示例
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",
"tables": ["table_test1","table_test2"]
}
查询表详情
接口描述
查询指定表的详情。
请求结构
POST /v{version}/table?desc HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
"database": "db_name",
"table": "table_name"
}
请求头域
除公共头域外,无其它特殊头域。
请求参数
参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
---|---|---|---|---|
version | String | 是 | URL参数 | API版本号,当前取1。 |
database | String | 是 | RequestBody参数 | 指定库的名称。 |
table | String | 是 | RequestBody参数 | 指定表的名称。 |
响应头域
除公共头域外,无其它特殊头域。
响应参数
参数名称 | 类型 | 描述 |
---|---|---|
code | Int | 返回码 |
msg | String | 返回信息 |
table | String | 数据表名称 |
请求示例
POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/table?desc
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
"database": "db_test",
"table": "table_test"
}
响应示例
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",
"table": {
"database": "db_test",
"table":" table_test",
"createTime": "2024-02-02T12:02:08Z",
"description": "This is a testing table",
"replication": 3,
"partition": {
"partitionType": "HASH",
"partitionNum": 10
},
"enableDynamicField": false,
"state": "NORMAL",
"aliases": ["table_alias_1", "table_alias_2"],
"schema": {
"fields": [
{
"fieldName": "id",
"fieldType": "UINT64",
"primaryKey": true,
"partitionKey": true,
"autoIncrement": true,
"notNull": true
},
{
"fieldName": "vector1",
"fieldType": "FLOAT_VECTOR",
"dimension": 768,
"notNull": true
},
{
"fieldName": "scalar1",
"fieldType": "UINT64",
"notNull": false
},
{
"fieldName": "scalar2",
"fieldType": "STRING",
"notNull": false
}
],
"indexes": [
{
"field": "vector1",
"indexName": "vector1_idx",
"indexType": "HNSW",
"metricType": "L2",
"params": {
"M": 32,
"efConstruction": 200
},
"state": "NORMAL"
},
{
"indexName": "scalar1_idx",
"indexType": "SECONDARY",
"field": "scalar1",
"state": "NORMAL"
}
]
}
}
}
新增表字段
接口描述
在指定表中新增一个字段,当前仅支持新增标量字段。
请求结构
POST /v{version}/table?addField HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
"database": "db_name",
"table": "table_name",
"schema": {
"fields": [
{
"fieldName": "scalar1",
"fieldType": "UINT64"
},
{
"fieldName": "scalar2",
"fieldType": "STRING"
}
]
}
}
请求头域
除公共头域外,无其它特殊头域。
请求参数
参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
---|---|---|---|---|
version | String | 是 | URL参数 | API版本号,当前取1。 |
database | String | 是 | RequestBody参数 | 指定库的名称。 |
table | String | 是 | RequestBody参数 | 指定表的名称。 |
schema | Schema | 是 | RequestBody参数 | 待新增字段的Schema定义。 |
响应头域
除公共头域外,无其它特殊头域。
响应参数
参数名称 | 类型 | 描述 |
---|---|---|
code | Int | 返回码 |
msg | String | 返回信息 |
请求示例
POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/table?addField
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
"database": "db_test",
"table": "table_test"
"schema": {
"fields": [
{
"fieldName": "age",
"fieldType": "UINT64"
},
{
"fieldName": "name",
"fieldType": "STRING"
}
]
}
}
响应示例
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}/table?stats HTTP/1.1
HOST: {Endpoint}
Authorization: {Authorization}
{
"database": "db_name",
"table": "table_name"
}
请求头域
除公共头域外,无其它特殊头域。
请求参数
参数名称 | 类型 | 是否必填 | 参数位置 | 描述 |
---|---|---|---|---|
version | String | 是 | URL参数 | API版本号,当前取1。 |
database | String | 是 | RequestBody参数 | 数据库的名称。 |
table | String | 是 | RequestBody参数 | 数据表的名称。 |
响应头域
除公共头域外,无其它特殊头域。
响应参数
参数名称 | 类型 | 描述 |
---|---|---|
code | Int | 返回码 |
msg | String | 返回信息 |
请求示例
POST http://vdb.nXWNyPCOSLci.vdb.bj.baidubce.com/v1/table?stats
Host: vdb.nXWNyPCOSLci.vdb.bj.baidubce.com
Authorization: Bearer account=root&api_key=eC4bLRy2va******************************
{
"database": "db_test",
"table": "table_test"
}
响应示例
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",
"rowCount": 123456,
"memorySizeInByte": 12345678,
"diskSizeInByte": 22345678
}