基于湖库一体架构,统一管理结构化、半结构化与非结构化等多模态数据,一个系统承载事务处理、实时分析与 AI 工作负载。
Collection 与 App 管理
更新时间:2026-11-16 20:22:57
说明
本功能从 V4.6.2.1 版本开始支持。
本文档介绍闪应用场景中 Collection 与 App(系统自动映射为 Namespace)的创建、隔离规则与运维接口。示例中的 Collection 名称 my_flash_app、App 名称 app001 与 快速上手 保持一致。
两级隔离模型
| 层级 | 说明 |
|---|---|
| Collection | create_collection(collection_name) 决定物理表族。不同 collection_name 数据完全隔离。 |
| App | 同一 Collection 内,RequestContext 的 app_prefix 映射为 Namespace。不同 app_prefix 通过 namespace_id 分区隔离。 |
补充说明如下:
- 首次使用某个
app_prefix时,系统会自动创建对应 Namespace,无需手动创建。 app_prefix可按需自定义含义,例如应用 ID、租户 ID、环境标识等。- 读写时通过
RequestContext的app_prefix指定 App,构造方式见 数据操作。
Collection 命名规则
Collection 名称由 create_collection 的 collection_name 参数指定,须满足以下约束:
| 属性 | 约束 |
|---|---|
| 类型 | 字符串 |
| 长度 | [1, 512] 字符 |
| 唯一性 | 同一实例内全局唯一,不可重名 |
| 字符集 | 仅支持 [a-zA-Z0-9_](字母、数字、下划线) |
合法与非法示例如下:
# 合法
client.create_collection("my_flash_app", partition_count=64)
# 非法:含连字符
# client.create_collection("app-a-data")
# 非法:含中文
# client.create_collection("业务数据")
同一数据库下,不同 collection_name 对应不同 Collection,数据完全隔离。
Collection 接口
本场景通过 VirtualTableClient 管理 Collection 的生命周期。须先创建或获取 Collection,再执行业务读写。下列方法均挂在 Client 上:
| 方法 | 说明 |
|---|---|
create_collection(collection_name, partition_count) |
创建 Collection,并绑定到当前 Client;返回 Collection 对象。partition_count 为分区数,可选。 |
get_collection(collection_name) |
获取已存在的 Collection;不存在时返回报错。 |
get_or_create_collection(collection_name, partition_count) |
已存在则返回,不存在则创建;并发下安全。partition_count 为分区数,可选。 |
has_collection(collection_name) |
判断指定名称的 Collection 是否已注册。 |
delete_collection(collection_name) |
删除该 Collection 的 Catalog 记录与全部物理表;其下所有 App 数据一并清除。 |
partition_count 详细说明如下:
- 仅在
create_collection时指定,取值范围[1, 8192],默认值为64。 - 决定逻辑数据表及其附属表、统计表的分区数量。
- Collection 物理表创建后,分区数不可变更,后续修改不会生效。
- 测试环境或租户分区配额有限时,建议适当调低分区数以节约资源。
示例代码如下(假定已按 通过 json-table-sdk 连接数据库 完成客户端初始化):
coll = client.create_collection("my_flash_app", partition_count=64)
coll = client.get_or_create_collection("my_flash_app", partition_count=64)
if client.has_collection("my_flash_app"):
coll = client.get_collection("my_flash_app")
# 删除整个 Collection(其下所有 App 数据一并清除)
client.delete_collection("my_flash_app")
同一数据库可创建多个 Collection 以实现隔离:
coll1 = client.create_collection("my_flash_app", partition_count=1000)
coll2 = client.create_collection("your_flash_app", partition_count=64)
App 运维接口
create_collection、get_collection、get_or_create_collection 会返回 Collection 对象。对该 Collection 下的 App 做预热、列举、删除等操作时,调用该对象上的方法(不要在 VirtualTableClient 上找这些方法):
| 成员 / 方法 | 说明 |
|---|---|
name |
Collection 名称。 |
partition_count |
物理表按 namespace_id KEY 分区的分区数。 |
has_app(name) |
指定 App(Namespace)是否存在。 |
list_app() |
列出该 Collection 下所有 App。 |
drop_app(name) |
删除单个 App。 |
prewarm(name) |
预热指定 App。须至少执行过一次业务操作以注册 Namespace 后再调用。 |
coll.prewarm("app001")
coll.drop_app("app001")
if coll.has_app("app001"):
apps = coll.list_app()
删除语义:
drop_app(name):删除单个 App。delete_collection(name):在 Client 上调用;删除 Catalog 与全部物理表,该 Collection 下所有 App 数据一并清除。
多实例共存规则
| 场景 | 行为 |
|---|---|
| 相同 database + 相同 collection name | 共享同一 Collection 与物理表族,数据互通。 |
| 相同 database + 不同 collection name | 不同 Collection,数据隔离。 |
相同 app_prefix + 相同 Collection |
共享同一 Namespace,数据互通。 |
相同 app_prefix + 不同 Collection |
不同 namespace_id,数据隔离。 |
同一 Collection 下,不同 app_prefix 可使用相同表名,数据相互隔离(RequestContext 构造见 数据操作):
ctx_app1 = RequestContext(coll, app_prefix="app001")
ctx_app2 = RequestContext(coll, app_prefix="app002")
client.create_table(ctx_app1, "CREATE TABLE users (id BIGINT, name VARCHAR(64))")
client.create_table(ctx_app2, "CREATE TABLE users (id BIGINT, name VARCHAR(64))")
client.insert(ctx_app1, "INSERT INTO users (id, name) VALUES (1, 'App1用户')")
client.insert(ctx_app2, "INSERT INTO users (id, name) VALUES (1, 'App2用户')")