Note
This feature is supported starting with V4.6.2.1.
This topic describes how to create Collections and apps (automatically mapped to Namespaces by the system), as well as their isolation rules and maintenance APIs in flash applications. The example Collection name my_flash_app and app name app001 are consistent with those in Quick start with flash application scenario.
Two-level isolation model
Level |
Note |
|---|---|
| Collection | create_collection(collection_name) determines the physical table family. Data in different Collections is fully isolated. |
| App | Within the same Collection, the app_prefix of RequestContext is mapped to a Namespace. Different app_prefix values are isolated by namespace_id partitioning. |
Additional notes:
- When using a specific
app_prefixfor the first time, the system automatically creates the corresponding Namespace; no manual creation is required. - You can customize the meaning of
app_prefixas needed, for example, to represent an application ID, tenant ID, or environment identifier. - Apps are specified during read and write operations via the
app_prefixinRequestContext. For construction details, see Data operations.
Collection naming rules
The Collection name is specified by the collection_name parameter in create_collection and must meet the following constraints:
Attribute |
Constraints |
|---|---|
| Type | string |
| Length | [1, 512]Character |
| Unique | Unique globally within the same instance |
| Character set | Supported only in[a-zA-Z0-9_](letters, numbers, underscores) |
Valid and invalid examples are as follows:
# Legal
client.create_collection("my_flash_app", partition_count=64)
# Invalid: contains hyphens
# client.create_collection("app-a-data")
# Invalid: contains Chinese characters.
# client.create_collection("Business data")
In the same database, different collection_names correspond to different Collections, with data being completely isolated.
Collection APIs
In this scenario, the lifecycle of collections is managed through VirtualTableClient. You must create or obtain a Collection before performing business read and write operations. The following methods are all attached to the client:
Method |
Note |
|---|---|
create_collection(collection_name, partition_count) |
Creates a Collection and binds it to the current client, then returns the Collection object. partition_count is the number of partitions. Optional. |
get_collection(collection_name) |
Retrieves an existing Collection; returns an error if the collection does not exist. |
get_or_create_collection(collection_name, partition_count) |
If the key already exists, it is returned; if not, it is created. The operation is concurrent-safe. partition_count is the number of partitions, which is optional. |
has_collection(collection_name) |
Determines whether a Collection with the specified name is registered. |
delete_collection(collection_name) |
The Catalog record and all physical tables of the Collection are deleted, and all app data under it is cleared. |
partition_count is described in detail as follows:
- Specified only when creating a Collection (
create_collection). Value range:[1, 8192]. Default value:64. - Determines the number of partitions for the logical data table and its associated tables and statistics tables.
- After a Collection's physical table is created, the number of partitions cannot be changed; subsequent modifications will not take effect.
- In a test environment or when a tenant has limited partition quotas, it is recommended to appropriately reduce the number of partitions to conserve resources.
The sample code is as follows (assuming client initialization has been completed according to Connect to database by using 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")
# Delete the entire collection (including all app data within it).
client.delete_collection("my_flash_app")
You can create multiple Collections in the same database to achieve isolation:
coll1 = client.create_collection("my_flash_app", partition_count=1000)
coll2 = client.create_collection("your_flash_app", partition_count=64)
App O&M APIs
The create_collection, get_collection, and get_or_create_collection methods return a Collection object. When performing operations such as prewarming, listing, or deleting apps under this Collection, call the methods on this object (do not look for these methods on the VirtualTableClient):
Members / Methods |
Note |
|---|---|
name |
The name of the Collection. |
partition_count |
The number of partitions in the KEY partitioning of physical tables by namespace_id. |
has_app(name) |
Specifies whether the app (namespace) exists. |
list_app() |
Lists all applications under the Collection. |
drop_app(name) |
Deletes a single app. |
prewarm(name) |
Prewarms the specified app. You must have performed at least one business operation to register a Namespace before calling this method. |
coll.prewarm("app001")
coll.drop_app("app001")
if coll.has_app("app001"):
apps = coll.list_app()
Deletion semantics:
drop_app(name): Deletes a single app.delete_collection(name): Called on the client; deletes the catalog and all physical tables, and clears all app data under this Collection.
Multi-instance coexistence rules
Scenarios |
Behavior |
|---|---|
| Same database + same Collection name | Share the same Collection and physical table family for data interoperability. |
| Same database + different Collection name | Data is isolated across different Collections. |
Same app_prefix + same Collection |
Share the same namespace for data interconnection. |
Same app_prefix + different Collections |
Different namespace_id, data isolation. |
In the same Collection, different app_prefix values can use the same table name, with data being isolated from each other (See the RequestContext construction in Data operations.)
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, 'User of App1')")
client.insert(ctx_app2, "INSERT INTO users (id, name) VALUES (1, 'User of App2')");