Table 操作

更新时间：2026-09-01

创建表

功能介绍

在指定的库中新建一个表。字段和索引通过 Schema 定义；建表时可以同时创建向量索引、标量二级索引、FILTERING 索引、PERSISTENT_BITMAP 索引、PERSISTENT_AGGREGATED_BITMAP 索引和倒排索引。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration
from pymochow.model.enum import (
    FieldType,
    IndexStructureType,
    IndexType,
    InvertedIndexAnalyzer,
    InvertedIndexFieldAttribute,
    InvertedIndexParseMode,
    MetricType,
    StopWordsMode,
)
from pymochow.model.schema import (
    AutoBuildPeriodical,
    Field,
    FilteringIndex,
    HNSWParams,
    InvertedIndex,
    InvertedIndexParams,
    PersistentAggregatedBitmapIndex,
    PersistentBitmapIndex,
    Schema,
    SecondaryIndex,
    StopWordsParams,
    VectorIndex,
)
from pymochow.model.table import Partition

account = "root"
api_key = "您的账户API密钥"
endpoint = "您的实例访问端点"  # 例如："http://127.0.0.1:5287"

config = Configuration(
    credentials=BceCredentials(account, api_key),
    endpoint=endpoint,
)
client = pymochow.MochowClient(config)
db = client.database("db_test")

fields = [
    Field(
        "id",
        FieldType.STRING,
        primary_key=True,
        partition_key=True,
        auto_increment=False,
        not_null=True,
    ),
    Field("bookName", FieldType.STRING, not_null=True),
    Field("status", FieldType.UINT32, not_null=True),
    Field("publishTime", FieldType.TIMESTAMP, not_null=True),
    Field("segment", FieldType.TEXT, not_null=True),
    Field("vector", FieldType.FLOAT_VECTOR, not_null=True, dimension=8),
]

indexes = [
    VectorIndex(
        index_name="vector_idx",
        index_type=IndexType.HNSW,
        field="vector",
        metric_type=MetricType.L2,
        params=HNSWParams(m=32, efconstruction=200),
        auto_build=True,
        auto_build_index_policy=AutoBuildPeriodical(
            5000, "2026-01-01 12:00:00"
        ),
        # 使用原向量下标 [0, 4) 的维度构建索引。
        truncation_dimension=[0, 4],
    ),
    SecondaryIndex(index_name="book_name_idx", field="bookName"),
    FilteringIndex.from_dict_list(
        index_name="filtering_idx",
        fields=[
            {
                "field": "status",
                "indexStructureType": IndexStructureType.BITMAP,
            },
            {
                "field": "publishTime",
                "indexStructureType": IndexStructureType.AGGREGATED_BITMAP,
            },
        ],
    ),
    PersistentBitmapIndex(
        index_name="status_persistent_bitmap_idx",
        field="status",
    ),
    PersistentAggregatedBitmapIndex(
        index_name="publish_time_persistent_aggregated_bitmap_idx",
        field="publishTime",
        fanout_bits=4,
        max_depth=10,
    ),
    InvertedIndex(
        index_name="segment_inverted_idx",
        fields=["segment"],
        params=InvertedIndexParams(
            analyzer=InvertedIndexAnalyzer.DEFAULT_ANALYZER,
            parse_mode=InvertedIndexParseMode.COARSE_MODE,
            case_sensitive=True,
            stop_words=StopWordsParams(
                mode=StopWordsMode.CUSTOM,
                words=["呀", "啊", "哦"],
            ),
        ),
        field_attributes=[InvertedIndexFieldAttribute.ANALYZED],
    ),
]

table = db.create_table(
    table_name="book_vector",
    replication=3,
    partition=Partition(partition_num=3),
    schema=Schema(fields=fields, indexes=indexes),
    enable_dynamic_field=False,
    description="图书信息表",
    datanode_memory_reserved_in_gb=0.5,
    ttl=0,
)

client.close()
            

请求参数

Table 参数

参数	参数类型	是否必选	参数含义
table_name	String	是	指定表的名称。仅支持大小写字母、数字以及下划线（_），且必须以字母开头；长度限制为 1～255。
replication	Int	是	单个分区的总副本数（含主副本），取值范围为 `[1, 10]`。若需要完整的高可用特性，副本总数需不小于 3。总副本数需要小于等于数据节点数量，否则无法正常建表。
partition	Partition	是	表的分区策略。`partition_num` 取值范围为 `[1, 1000]`；若非 FLAT 索引，建议将单个分区的记录总数控制在 100 万到 1000 万之间。当前 `partition_type` 仅支持 `PartitionType.HASH`。
schema	Schema	是	表的 Schema 信息。
enable_dynamic_field	Boolean	否	表是否支持自动增加字段，默认值为 `False`。
description	String	否	表的描述信息。
datanode_memory_reserved_in_gb	Float	否	数据节点预留内存，单位为 GB，默认值为 0；值大于 0 时 SDK 才会发送该参数。
ttl	Int	否	数据生命周期，单位为秒。0 表示永不过期，默认值为 0；值大于 0 时 SDK 才会发送该参数。
config	Configuration	否	本次请求使用的配置。

Schema 参数

参数	参数类型	是否必选	参数含义
fields	List<Field>	是	指定表的字段详情列表。
indexes	List<IndexField>	否	表的索引详情列表。

Field 参数

参数	参数类型	是否必选	参数含义
field_name	String	是	字段名称，表内唯一；命名规则同表名。
field_type	FieldType	是	字段数据类型。支持 BOOL、INT8、UINT8、INT16、UINT16、INT32、UINT32、INT64、UINT64、FLOAT、DOUBLE、DATE、DATETIME、TIMESTAMP、STRING、BINARY、UUID、TEXT、TEXT_GBK、TEXT_GB18030、ARRAY、JSON、MAP、FLOAT_VECTOR、BINARY_VECTOR 和 SPARSE_FLOAT_VECTOR。各数据类型的详细定义和约束请参见数据类型。
primary_key	Boolean	否	是否为主键，默认值为 `False`。支持多主键。主键字段不支持 BOOL、FLOAT、DOUBLE、ARRAY、JSON、MAP、FLOAT_VECTOR、BINARY_VECTOR 和 SPARSE_FLOAT_VECTOR。
partition_key	Boolean	否	是否为分区键，默认值为 `False`。一张表只能有一个分区键；每行记录根据分区键的值哈希映射到不同分区。分区键字段不支持 BOOL、FLOAT、DOUBLE、ARRAY、JSON、MAP、FLOAT_VECTOR、BINARY_VECTOR 和 SPARSE_FLOAT_VECTOR。
auto_increment	Boolean	否	是否为自增主键，默认值为 `False`。仅适用于 UINT64 主键字段。
not_null	Boolean	否	是否非空，默认值为 `False`。主键字段、分区键字段、向量字段和索引键字段不可以为空。
dimension	Int	否	向量维度。字段类型为 FLOAT_VECTOR 或 BINARY_VECTOR 时指定。
element_type	ElementType	否	ARRAY 字段的元素类型。
max_capacity	Int	否	ARRAY 字段的最大容量。
key_type	MapKeyType	否	MAP 字段的 Key 类型。
value_type	MapValueType	否	MAP 字段的 Value 类型。

Index 参数

参数	参数类型	是否必选	参数含义
vector_index	VectorIndex	否	向量索引对象。
secondary_index	SecondaryIndex	否	标量二级索引对象。
filtering_index	FilteringIndex	否	过滤索引对象。为过滤条件中的标量字段添加索引，可提升过滤检索性能。
persistent_bitmap_index	PersistentBitmapIndex	否	PERSISTENT_BITMAP 持久化索引对象。
persistent_aggregated_bitmap_index	PersistentAggregatedBitmapIndex	否	PERSISTENT_AGGREGATED_BITMAP 持久化聚合索引对象。
inverted_index	InvertedIndex	否	倒排索引对象。

VectorIndex 参数

                Python
                
            

                VectorIndex(
    index_name,
    index_type,
    field,
    metric_type,
    params=None,
    auto_build=False,
    auto_build_index_policy=None,
    truncation_dimension=None,
)
            

参数	参数类型	是否必选	参数含义
index_name	String	是	索引名称。命名规则同表名。
index_type	IndexType	是	向量索引类型。当前 SDK 支持 FLAT、HNSW、HNSWPQ、HNSWSQ、HNSWRABITQ、PUCK、IVF、IVFSQ、IVFPQ、IVFRABITQ、DISKANN 和 SPARSE_OPTIMIZED_FLAT。
field	String	是	索引作用于的目标字段名称。
metric_type	MetricType	是	距离度量类型，支持 L2、IP 和 COSINE。使用 COSINE 时，用户需要自行对向量归一化，否则检索结果可能不准确。
params	Params	否	向量索引构建参数；FLAT 和 SPARSE_OPTIMIZED_FLAT 不需要构建参数。
auto_build	Boolean	否	是否自动构建索引，默认值为 `False`。
auto_build_index_policy	AutoBuildPolicy	否	自动构建索引策略。仅当 `auto_build=True` 时发送。
truncation_dimension	List<Int>	否	截断维度范围 `[begin, end)`，与 `params` 同级。

truncation_dimension 必须满足 0 <= begin < end <= dimension，有效维度为 end - begin。该参数仅支持 FLOAT_VECTOR 字段以及 HNSW、HNSWRABITQ、HNSWPQ、HNSWSQ、IVF、IVFPQ、IVFSQ 索引；HNSWPQ、IVFPQ 还要求有效维度能被 NSQ 整除。

索引类型	Python 参数类	构建参数及约束
HNSW	`HNSWParams(m, efconstruction)`	`m` 取值范围为 `[4, 128]`；`efconstruction` 取值范围为 `[8, 1024]`。
HNSWRABITQ	`HNSWRABITQParams(m, efconstruction)`	在 HNSW 图上使用 RaBitQ 量化；`m`、`efconstruction` 范围同 HNSW。
HNSWPQ	`HNSWPQParams(m, efconstruction, NSQ, samplerate)`	`m`、`efconstruction` 范围同 HNSW；`NSQ` 取值为 `[1, dim]` 并整除有效维度；`samplerate` 取值为 `[0.0, 1.0]`。
HNSWSQ	`HNSWSQParams(m, efconstruction, qtBits)`	`m`、`efconstruction` 范围同 HNSW；`qtBits` 取值为 8 或 16。
PUCK	`PUCKParams(coarseClusterCount, fineClusterCount)`	`coarseClusterCount` 为粗聚类中心个数；`fineClusterCount` 为每个粗聚类中心下的细聚类中心个数。
DISKANN	`DISKANNParams(NSQ, R, L)`	`1 <= NSQ <= 512` 且 `NSQ <= dim`；`R` 取值范围为 `[1, 128]`；`L` 取值范围为 `[8, 1024]`。
IVF	`IVFParams(nlist)`	`nlist` 取值范围为 `[1, 65536]`。
IVFSQ	`IVFSQParams(nlist, qtBits)`	`nlist` 取值范围为 `[1, 65536]`；`qtBits` 支持 4、8、16。
IVFPQ	`IVFPQParams(nlist, NSQ)`	`nlist` 取值范围为 `[1, 65536]`；`NSQ` 整除有效维度。
IVFRABITQ	`IVFRABITQParams(nlist)`	`nlist` 取值范围为 `[1, 65536]`。

自动构建策略如下：

AutoBuildTiming(timing)：在指定时间构建一次。
AutoBuildPeriodical(period_s, timing="")：每隔 period_s 秒构建一次，可指定开始时间。
AutoBuildRowCountIncrement(row_count_increment=0, row_count_increment_ratio=0)：Tablet 记录数变化达到指定行数或比例时构建。

SecondaryIndex 参数

参数	参数类型	是否必选	参数含义
index_name	String	是	索引名称。
field	String	是	索引作用于的目标字段名称。

FilteringIndex 参数

可通过 FilteringIndex.from_list(index_name, fields) 使用默认结构，也可通过 FilteringIndex.from_dict_list(index_name, fields) 为各字段指定结构。

参数	参数类型	是否必选	参数含义
index_name	String	是	索引名称。
fields	List<String> / List<Dict>	是	索引作用于的字段列表。字符串列表使用默认结构；字典列表中的每项为一个 FilteringIndexField。

FilteringIndexField 参数

参数	参数类型	是否必选	参数含义
field	String	是	索引作用于的字段名称。支持通配符 `@SCALAR`，表示所有标量列，包括后续通过动态列添加的标量列。
indexStructureType	IndexStructureType	否	内存结构，支持 DEFAULT、BITMAP 和 AGGREGATED_BITMAP，默认值为 DEFAULT。

FILTERING 的 AGGREGATED_BITMAP 是内存结构，除等值过滤外还可加速 >、>=、<、<= 范围过滤。它仅支持 INT8、UINT8、INT16、UINT16、INT32、UINT32、INT64、UINT64、FLOAT、DOUBLE、DATE、DATETIME 和 TIMESTAMP。

PersistentBitmapIndex 参数

参数	参数类型	是否必选	参数含义
index_name	String	是	索引名称。
field	String	是	索引作用于的目标字段名称。

PERSISTENT_BITMAP 是独立的持久化 BITMAP 索引类型，不是 FILTERING 的结构选项，适用于等值过滤。支持 BOOL、各整数、FLOAT、DOUBLE、日期时间、UUID、STRING、BINARY、TEXT 系列和 ARRAY，不支持 JSON。

PersistentAggregatedBitmapIndex 参数

参数	参数类型	是否必选	参数含义
index_name	String	是	索引名称。
field	String	是	索引作用于的目标字段名称。
fanout_bits	Int	是	扇出位数，取值范围为 `[1, 10]`。
max_depth	Int	是	最大深度，取值范围为 `[2, 30]`。

PERSISTENT_AGGREGATED_BITMAP 是独立的持久化聚合 BITMAP 索引类型，支持等值和范围过滤；支持整数、浮点和日期时间字段。参数还需满足 fanout_bits * (max_depth - 1) <= 64。

InvertedIndex 参数

参数	参数类型	是否必选	参数含义
index_name	String	是	索引名称。
fields	List<String>	是	索引作用于的字段名称。协议支持 TEXT、TEXT_GBK、TEXT_GB18030、ARRAY<TEXT> 和 JSON。
params	InvertedIndexParams	是	倒排索引参数。
field_attributes	List<InvertedIndexFieldAttribute>	否	是否对字段分词，顺序与 `fields` 一一对应；支持 `ANALYZED` 和 `NOT_ANALYZED`。

InvertedIndexParams 参数

参数	参数类型	是否必选	参数含义
analyzer	InvertedIndexAnalyzer	否	分词器，支持 ENGLISH_ANALYZER、CHINESE_ANALYZER 和 DEFAULT_ANALYZER。
parse_mode	InvertedIndexParseMode	否	分词模式，支持 COARSE_MODE 和 FINE_MODE。
case_sensitive	Boolean	否	是否大小写敏感，默认值为 `True`。
stop_words	StopWordsParams	否	停用词配置。

StopWordsParams(mode, words=None) 的 mode 支持 DEFAULT、CUSTOM 和 NONE。CUSTOM 必须提供非空 words，每项为单个 term；未配置停用词等价于 DEFAULT。停用词只能在建表或创建索引时设置，不能原地修改，检索时也不能临时覆盖。

倒排索引异步构建：IndexState.BUILDING 时不能用于 BM25/Hybrid 检索，检索返回错误码 95（Index Building），并且索引不可删除；变为 IndexState.NORMAL 后方可检索。

返回参数

参数	参数类型	参数含义
table	Table	创建的表对象。

删除表

功能介绍

删除指定的表。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration

account = "root"
api_key = "您的账户API密钥"
endpoint = "您的实例访问端点"  # 例如："http://127.0.0.1:5287"

config = Configuration(
    credentials=BceCredentials(account, api_key),
    endpoint=endpoint,
)
client = pymochow.MochowClient(config)

db = client.database("db_test")
db.drop_table("book_vector")

client.close()
            

请求参数

参数	参数类型	是否必选	参数含义
table_name	String	是	指定表的名称。
config	Configuration	否	本次请求使用的配置。

查询指定表详情

功能介绍

查询指定表的详情。Database.table() 是 Database.describe_table() 的别名，两者都从服务端查询并返回完整的 Table 对象。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration

account = "root"
api_key = "您的账户API密钥"
endpoint = "您的实例访问端点"  # 例如："http://127.0.0.1:5287"

config = Configuration(
    credentials=BceCredentials(account, api_key),
    endpoint=endpoint,
)
client = pymochow.MochowClient(config)

db = client.database("db_test")
table = db.table("book_vector")
print(table.to_dict())

client.close()
            

请求参数

参数	参数类型	是否必选	参数含义
table_name	String	是	指定表的名称。
config	Configuration	否	本次请求使用的配置。

返回参数

参数	参数类型	参数含义
table	Table	表对象。

Table 参数

参数	参数类型	参数含义
database_name	String	库的名称。
table_name	String	表的名称。
replication	Int	单个分区的总副本数（含主副本）。
partition	Partition	表的分区配置，可通过 `partition.partition_num` 查看分区数。
schema	Schema	表的 Schema 信息，包括完整的 `fields` 和当前 SDK 可解析的 `indexes`。
enable_dynamic_field	Boolean	表是否支持自动增加字段。
description	String	表的描述信息。
ttl	Int	数据生命周期，单位为秒；0 表示永不过期。
create_time	String / Int	表的创建时间，具体表示形式取决于服务端返回。
state	TableState	表的当前状态：CREATING、NORMAL 或 DELETING。
aliases	List<String>	表的别名列表。

Schema 参数

参数	参数类型	参数含义
fields	List<Field>	字段对象列表。每个对象包含 `field_name`、`field_type`、`primary_key`、`partition_key`、`auto_increment`、`not_null`、`dimension`、`element_type`、`key_type` 和 `value_type` 等属性。
indexes	List<IndexField>	索引对象列表。包括当前 SDK 可解析的 VectorIndex、SecondaryIndex、FilteringIndex、PersistentBitmapIndex、PersistentAggregatedBitmapIndex 和 InvertedIndex。

table.schema.indexes 会恢复 PERSISTENT_BITMAP、PERSISTENT_AGGREGATED_BITMAP 以及带 state 的 INVERTED 对象。当前 SDK 的表详情解析不会恢复向量索引的 truncation_dimension，也不会恢复倒排索引的 stop_words、case_sensitive 和 field_attributes，请勿依赖表详情读取这些创建参数。

查询表的列表

功能介绍

查询指定库包含的所有表。list_table() 返回 List[Table]；SDK 会先获取表名列表，再逐个调用表详情接口构造完整的 Table 对象，而不是只返回表名。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration

account = "root"
api_key = "您的账户API密钥"
endpoint = "您的实例访问端点"  # 例如："http://127.0.0.1:5287"

config = Configuration(
    credentials=BceCredentials(account, api_key),
    endpoint=endpoint,
)
client = pymochow.MochowClient(config)

db = client.database("db_test")
tables = db.list_table()
for table in tables:
    print(table.table_name, table.state, table.schema.fields, table.schema.indexes)

client.close()
            

请求参数

参数	参数类型	是否必选	参数含义
database_name	String	是	库的名称，在 `client.database(database_name)` 时指定。
config	Configuration	否	本次请求使用的配置。

返回参数

参数	参数类型	参数含义
tables	List<Table>	完整表对象列表；每个对象的返回结构与“查询指定表详情”的 Table 参数一致。

查询指定表的统计信息

功能介绍

查询指定表的统计信息。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration

account = "root"
api_key = "您的账户API密钥"
endpoint = "您的实例访问端点"  # 例如："http://127.0.0.1:5287"

config = Configuration(
    credentials=BceCredentials(account, api_key),
    endpoint=endpoint,
)
client = pymochow.MochowClient(config)

db = client.database("db_test")
table = db.table("book_vector")
table_stats = table.stats()
print(
    table_stats.row_count,
    table_stats.memory_size_in_byte,
    table_stats.disk_size_in_byte,
)

client.close()
            

请求参数

参数	参数类型	是否必选	参数含义
database_name	String	是	库的名称，在 `client.database(database_name)` 时指定。
table_name	String	是	表的名称，在获取 `Table` 对象时指定。
config	Configuration	否	本次请求使用的配置。

返回参数

参数	协议字段	参数类型	参数含义
row_count	rowCount	Int	记录数。
memory_size_in_byte	memorySizeInByte	Int	内存大小，单位为字节。
disk_size_in_byte	diskSizeInByte	Int	磁盘大小，单位为字节。

评价此篇文章

有帮助没帮助

Database 操作

Alias 操作

百度智能云

向量数据库 VectorDB

向量数据库 VectorDB

Table 操作

创建表

功能介绍

请求示例

请求参数

返回参数

删除表

功能介绍

请求示例

请求参数

查询指定表详情

功能介绍

请求示例

请求参数

返回参数

查询表的列表

功能介绍

请求示例

请求参数

返回参数

查询指定表的统计信息

功能介绍

请求示例

请求参数

返回参数