---
title: "通过 json-table-sdk 连接数据库 - OceanBase AI 数据库 V4.6.3 | OceanBase 文档中心"
description: 通过 json-table-sdk 连接数据库 说明 本功能从 V4.6.2.1 版本开始支持。 闪应用场景使用 json-table-sdk 的 VirtualTableClient 连接 OceanBase AI 数据库。本场景须设置 use_namespace=True ，再创建或获取 Collection 后…
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

# 通过 json-table-sdk 连接数据库

更新时间：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/200.flash-app-connect.md)

#### 说明

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

闪应用场景使用 `json-table-sdk` 的 `VirtualTableClient` 连接 OceanBase AI 数据库。本场景须设置 `use_namespace=True`，再创建或获取 Collection 后执行业务读写。

## 前提条件

- 已部署 OceanBase AI 数据库 V4.6.2.1 及以上版本，有关部署方法请参见 [部署概述](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088254)。
 - 已准备可连接的数据库账号与目标库，有关通用连接方式请参见 [连接方式概述](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088233)。

## 安装 json-table-sdk

本场景依赖 **json-table-sdk 1.5.0 及以上**（需支持 Namespace 模式），Python 导入包名为 `antob_json_table`。

```shell
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、建表以及改表、查询等操作见相关文档。

```shell
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()`：

```shell
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` 本身线程安全；连接池中的单个连接请勿跨线程共享。

## 相关文档

- [场景概述](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088584)
 - [限制与约束](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088582)
 - [快速上手](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088583)
 - [Collection 与 App 管理](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088581)
 - [数据操作](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088580)
 - [连接方式概述](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000007088233)

 上一篇 下一篇 ![有帮助](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) 咨询热线
