Note
This feature is supported starting with V4.6.2.1.
In this scenario, you use the VirtualTableClient of json-table-sdk to connect to OceanBase AI Database. You must set use_namespace=True and then create or obtain a Collection before performing business read and write operations.
Prerequisites
- OceanBase AI Database V4.6.2.1 or later has been deployed. For more information about deployment, see Choose an appropriate deployment plan.
- A database account that can be used to connect to the target database has been prepared. For more information about connection methods, see Overview of connection methods.
Install json-table-sdk
This scenario requires json-table-sdk 1.5.0 or later (which must support Namespace mode). In Python, import the package named antob_json_table.
pip install antob-json-table==1.5.0 --index=https://artifacts.antgroup-inc.cn/artifact/repositories/simple-dev/
Verify that from antob_json_table import VirtualTableClient can be imported successfully.
Initialize the client
The following example only demonstrates how to establish and close a connection. For operations such as creating a Collection, creating a table, modifying a table, and querying, refer to the relevant documentation.
from antob_json_table import VirtualTableClient
client = VirtualTableClient(
host="127.0.0.1",
port=2881,
user="root@mysql",
password="",
database="test",
use_namespace=True,
)
# In this case, you can call create_collection, create tables, and perform SQL read and write operations.
# Close the connection after use; a persistent process can close it before exiting.
client.close()
You can also use a context manager to automatically close the connection when you exit, eliminating the need to call close():
with VirtualTableClient(
host="127.0.0.1",
port=2881,
user="root@mysql",
password="",
database="test",
use_namespace=True,
) as client:
coll = client.create_collection("my_flash_app", partition_count=64)
# Perform table creation and SQL read/write operations here (see Data Operations).
Parameters
Connection and mode
Parameters |
Required |
Note |
|---|---|---|
host |
Yes | The host address of the database to be connected. |
port |
Yes | Database port. For OceanBase AI Database, it is typically 2881. |
user |
Yes | The username that has permission to access the target database. |
password |
Yes | The corresponding user password. If no password is provided, pass an empty string. |
database |
Yes | The name of the target database. |
use_namespace |
Yes (for this scenario) | Whether to enable namespace (logical table) mode. In this scenario, it must be set to True. Otherwise, it cannot be used in flash mode. |
charset |
No | Connection character set, which is generally left as the default. utf8mb4 is sufficient. |
index_columns |
No | This parameter is not required in this scenario. It is mutually exclusive with use_namespace=True. Configuring both at the same time will throw a ValueError when constructing the client. |
Connection pool and cache (Optional)
Parameters |
Required |
Note |
|---|---|---|
pool_size |
No | Initial size of the connection pool. Default: 5. Generally, no changes are required. |
max_connections |
No | The maximum number of connections a single client can use. The default value depends on the SDK used (commonly 20). You can increase it as needed when concurrency is high. |
enable_cache |
No | Whether to enable schema caching to reduce repeated table schema pulls. Default: False. |
cache_ttl |
No | Schema cache expiration time (in seconds). Default value: 300. It takes effect only when enable_cache is enabled. |
max_connections determines how many SQL statements a single client can execute simultaneously. When your business scenarios have high concurrency, you can appropriately increase this value and ensure that the maximum number of tenant connections is sufficient. Alternatively, you can deploy multiple client instances for horizontal scaling.
Log (Optional)
Parameters |
Note |
|---|---|
log_level |
Log level, for example,WARNING. |
log_output |
Log output target, for example,stdout. |
log_format |
Log format string. |
log_date_format |
Log time format. |
log_enable_rotation |
Whether to enable log rotation. |
log_rotation_type |
Rotation type, for example, by size.size. |
log_max_bytes |
The maximum size of a single file during round-robin scheduling. |
log_backup_count |
Number of retained backup files. |
log_when / log_interval |
The period configured for time-based rotation. |
Initialization behavior
- When constructing a
VirtualTableClient, only the connection pool is initialized; Collections and their physical table families are not automatically created. - After enabling
use_namespace=True, you must first bind a Collection usingcreate_collection,get_collection, orget_or_create_collectionbefore performing business read/write operations. Otherwise, aValueErrorwill be thrown. - The
VirtualTableClientitself is thread-safe; individual connections in the connection pool must not be shared across threads.