Table 操作

更新时间：2024-10-16

创建表

接口描述

在指定的库中新建一个表。

请求结构

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	索引类型。当前支持的类型如下： SECONDARY：标量二级索引 HNSW：HNSW向量索引 FLAT：FLAT向量索引（暴力检索） PUCK：PUCK向量索引（百度自研搜索算法） HNSWPQ：HNSWPQ向量索引
metricType	String	向量索引的距离度量类型。支持的类型如下： L2：欧氏距离度量 IP：内积度量 COSINE：余弦距离度量注：当使用COSINE距离时，用户需要自行对相关向量进行归一化操作，未经归一化的向量将导致search结果不准确
params	VectorIndexParams	向量索引的参数详情。
field	String	索引作用于的目标字段名称。
autoBuild	Boolean	是否自动构建索引。
autoBuildPolicy	AutoBuildPolicy	构建索引策略。

AutoBuildPolicy

参数名称	类型	描述
policyType	String	自动构建索引策略类型，大小写不敏感，支持的类型如下： timing：定时构建索引，只构建一次。 periodical：周期性构建索引，每过多少秒会构建一次索引。 row_count_increment：根据tablet增加多少行数构建一次索引。
timing	String	定时构建索引，支持格式为LOCAL(%Y-%m-%d %H:%M:%S)以及UTC(%Y-%m-%dT%H:%M:%Z)，在policyType为timing时生效时只构建一次，不会重复构建。当policyType为periodical时，传入的时间作为周期性策略的开始时间
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
}

Database 操作

Row 操作

向量数据库 VectorDB

Table 操作

创建表

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

删除表

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

列出所有表

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

查询表详情

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

新增表字段

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例

获取表的统计信息

接口描述

请求结构

请求头域

请求参数

响应头域

响应参数

请求示例

响应示例