基于湖库一体架构,统一管理结构化、半结构化与非结构化等多模态数据,一个系统承载事务处理、实时分析与 AI 工作负载。
通过 json-table-sdk 连接数据库
更新时间:2026-11-16 20:22:57
说明
本功能从 V4.6.2.1 版本开始支持。
闪应用场景使用 json-table-sdk 的 VirtualTableClient 连接 OceanBase AI 数据库。本场景须设置 use_namespace=True,再创建或获取 Collection 后执行业务读写。
前提条件
安装 json-table-sdk
本场景依赖 json-table-sdk 1.5.0 及以上(需支持 Namespace 模式),Python 导入包名为 antob_json_table。
pip install antob-json-table==1.5.0 --index=https://artifacts.antgroup-inc.cn/artifact/repositories/simple-dev/
确认 from antob_json_table import VirtualTableClient 可成功导入。
初始化客户端
下列示例只演示如何建立与关闭连接。创建 Collection、建表以及改表、查询等操作见相关文档。
from antob_json_table import VirtualTableClient
client = VirtualTableClient(
host="127.0.0.1",
port=2881,
user="root@mysql",
password="",
database="test",
use_namespace=True,
)
# 在此调用 create_collection、建表与 SQL 读写等
# 使用完毕后关闭连接;长驻进程可在进程退出前再关闭
client.close()
也支持使用上下文管理器,退出时自动关闭连接,无需再调用 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)
# 在此执行建表与 SQL 读写等(见数据操作)
参数说明
连接与模式
| 参数 | 是否必选 | 说明 |
|---|---|---|
host |
是 | 要连接的数据库主机地址。 |
port |
是 | 数据库端口,OceanBase AI 数据库常见为 2881。 |
user |
是 | 有权限访问目标库的用户名。 |
password |
是 | 对应用户密码;无密码时传空字符串即可。 |
database |
是 | 要操作的目标数据库名。 |
use_namespace |
是(本场景) | 是否启用 Namespace(逻辑表)模式。本场景必须设为 True,否则无法按闪应用方式使用。 |
charset |
否 | 连接字符集,一般保持默认 utf8mb4 即可。 |
index_columns |
否 | 本场景不要设置。该参数与 use_namespace=True 互斥,同时配置会在构造客户端时抛出 ValueError。 |
连接池与缓存(可选)
| 参数 | 是否必选 | 说明 |
|---|---|---|
pool_size |
否 | 连接池初始大小,默认 5。一般无需改动。 |
max_connections |
否 | 单个客户端最多可使用的连接数;默认值以所用 SDK 为准(常见为 20)。并发较高时可按需调大。 |
enable_cache |
否 | 是否启用 Schema 缓存以减少重复拉表结构,默认 False。 |
cache_ttl |
否 | Schema 缓存过期时间(秒),默认 300。仅在开启 enable_cache 时生效。 |
max_connections 决定单个客户端能同时执行多少条 SQL。业务场景并发较高时,可适当调大该值,并确认租户连接数上限足够;也可部署多个客户端实例做水平扩展。
日志(可选)
| 参数 | 说明 |
|---|---|
log_level |
日志级别,例如 WARNING。 |
log_output |
日志输出目标,例如 stdout。 |
log_format |
日志格式字符串。 |
log_date_format |
日志时间格式。 |
log_enable_rotation |
是否启用日志轮转。 |
log_rotation_type |
轮转类型,例如按大小 size。 |
log_max_bytes |
按大小轮转时的单文件上限(字节)。 |
log_backup_count |
保留的备份文件数量。 |
log_when / log_interval |
按时间轮转时的周期配置。 |
初始化行为说明
- 构造
VirtualTableClient时仅初始化连接池,不会自动创建 Collection 及其物理表族。 - 启用
use_namespace=True后,须先通过create_collection、get_collection或get_or_create_collection绑定 Collection,再执行业务读写;否则会抛出ValueError。 VirtualTableClient本身线程安全;连接池中的单个连接请勿跨线程共享。