---
title: "Collection 与 App 管理 - OceanBase AI 数据库 V4.6.3 | OceanBase 文档中心"
description: Collection 与 App 管理 说明 本功能从 V4.6.2.1 版本开始支持。 本文档介绍闪应用场景中 Collection 与 App（系统自动映射为 Namespace）的创建、隔离规则与运维接口。示例中的 Collection 名称 my_flash_app 、App 名称 app001 与 快速上手…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*M1BcQZvbrRMAAAAAQGAAAAgAeiGDAQ/original) OceanBase AI 数据库V 4.6.3

# Collection 与 App 管理

更新时间：2026-11-16 20:22:57

[编辑](https://github.com/oceanbase/oceanbase-database-ai/edit/V4.6.3/zh-CN/250.database-schema-design/600.logical-table/200.flash-app-scene/400.flash-app-collection-and-app.md)

#### 说明

本功能从 V4.6.2.1 版本开始支持。

本文档介绍闪应用场景中 Collection 与 App（系统自动映射为 Namespace）的创建、隔离规则与运维接口。示例中的 Collection 名称 `my_flash_app`、App 名称 `app001` 与 [快速上手](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088583) 保持一致。

## 两级隔离模型

| **层级** | **说明** |
| --- | --- |
| 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_]`（字母、数字、下划线） |

合法与非法示例如下：

```shell
# 合法
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 连接数据库](#相关文档) 完成客户端初始化）：

```shell
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 以实现隔离：

```shell
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 后再调用。 |

```shell
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` 构造见 [数据操作](#相关文档)）：

```shell
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用户')")

```

## 相关文档

- [场景概述](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088584)
 - [限制与约束](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088582)
 - [通过 json-table-sdk 连接数据库](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088585)
 - [快速上手](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088583)
 - [数据操作](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088580)

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线
