基于湖库一体架构,统一管理结构化、半结构化与非结构化等多模态数据,一个系统承载事务处理、实时分析与 AI 工作负载。
数据操作
更新时间:2026-11-16 20:22:57
本文档介绍闪应用场景中如何建表、改表,以及用标准 SQL 读写数据。示例中的 Collection 名称 my_flash_app、App 名称 app001 与 快速上手 保持一致。
说明
本功能从 V4.6.2.1 版本开始支持。
完成客户端连接并创建 Collection 后,即可按普通表的方式操作数据:先定义表结构,再执行 INSERT / UPDATE / DELETE / SELECT。SQL 里直接写业务表名(如 users),由 json-table-sdk 定位到当前 App 下的数据,无需关心底层 JSON 存储。
指定 App
每次建表或读写都要传入 RequestContext,用来说明在哪个 App 下操作,并可附带审计、追踪等信息。
from antob_json_table import RequestContext
ctx = RequestContext(
coll,
app_prefix="app001",
created_by="admin",
)
带可选参数的示例:
ctx = RequestContext(
coll,
app_prefix="app001",
version="v1.0",
created_by="admin",
trace_id="trace-123",
extra={"key": "value"},
)
| 参数 | 是否必选 | 说明 |
|---|---|---|
coll |
是 | Collection 对象。由 create_collection / get_collection / get_or_create_collection 返回。 |
app_prefix |
是 | 应用标识,映射为 Namespace 名。同一 Collection 下不同 app_prefix 的数据相互隔离,详见 Collection 与 App 管理。 |
created_by |
否 | 操作人,默认 admin,用于审计。 |
version |
否 | 用户自定义版本号。 |
trace_id |
否 | 追踪 ID,用于日志关联。 |
extra |
否 | 扩展字段,类型为字典,供用户按需传递附加信息。 |
SQL 中直接使用业务表名(如 users),SDK 结合当前 app_prefix 对应的 Namespace 与表名定位数据。
建表与改表
常用方法如下:
| 方法 | 说明 |
|---|---|
create_table(ctx, sql) |
创建表(虚拟表)。只登记表结构,不会为每张表单独建物理表。 |
alter_table_add_column(ctx, sql) |
为已有表添加列。新列须指定 DEFAULT,已有行按该默认值回填。 |
get_table_schema(ctx, table_name) |
查看表结构。 |
list_tables(ctx) |
列出当前 App 下的表名。 |
table_exists(ctx, table_name) |
判断表是否存在。 |
drop_table(ctx, table_name) |
删表,同时删除表中数据。 |
创建表
client.create_table(ctx, """
CREATE TABLE users (
id BIGINT NOT NULL,
name VARCHAR(64) NOT NULL,
age INT DEFAULT 0,
created_at TIMESTAMP
)
""")
首次调用 create_table 时,若当前 app_prefix 对应的 Namespace 不存在,系统会自动创建。
使用注意:
- 每个 App 下用户表最多 10 万张;建表语法边界见 限制与约束。
- 单表最多 100 列;单行序列化为 JSON 后不超过 64KB;
VARCHAR最长 65,535 字符。 - 常用列类型:
TINYINT/SMALLINT/INT/BIGINT、DECIMAL/FLOAT/DOUBLE、VARCHAR(n)、DATE/TIME/TIMESTAMP。
添加列
新列必须指定 DEFAULT:
# 正确
client.alter_table_add_column(
ctx,
"ALTER TABLE users ADD COLUMN email VARCHAR(128) DEFAULT ''",
)
# 错误:缺少 DEFAULT,会抛出 ValidationError
# client.alter_table_add_column(ctx, "ALTER TABLE users ADD COLUMN email VARCHAR(128) NOT NULL")
查看与删除表
tables = client.list_tables(ctx)
exists = client.table_exists(ctx, "users")
schema = client.get_table_schema(ctx, "users")
client.drop_table(ctx, "users")
写入、更新与删除
| 方法 | 说明 |
|---|---|
insert(ctx, sql) |
插入一行或多行。 |
update(ctx, sql) |
按条件更新。 |
delete(ctx, sql) |
按条件删除。 |
json-table-sdk 会自动把操作限制在当前 App 与当前表范围内,避免误改其他 App 的数据。
# 须指定列名
client.insert(ctx, "INSERT INTO users (id, name, age) VALUES (1, '张三', 25)")
client.insert(ctx, """
INSERT INTO users (id, name, age) VALUES
(1, '张三', 25),
(2, '李四', 30)
""")
client.update(ctx, "UPDATE users SET age = 26 WHERE id = 1 LIMIT 10")
client.delete(ctx, "DELETE FROM users WHERE id = 2 LIMIT 10")
写入数据时请注意:
- 单次
INSERT最多 1,000 行,须指定列名;更大批量请分批(建议每批 100~200 行)。 UPDATE/DELETE建议带LIMIT。- 不支持的
INSERT语法见 限制与约束。
查询
| 方法 | 说明 |
|---|---|
select(ctx, sql) |
执行查询,返回结构化结果。 |
translate(ctx, sql) |
只翻译 SQL、不真正执行,便于调试。 |
示例如下:
# 查询所有数据
rows = client.select(ctx, "SELECT * FROM users")
# 条件查询
rows = client.select(
ctx,
"SELECT * FROM users WHERE age > 25 ORDER BY age DESC LIMIT 100",
)
# 同表自连接示例
rows = client.select(ctx, """
SELECT a.id AS emp_id, b.id AS mgr_id
FROM users a INNER JOIN users b ON a.manager_id = b.id
LIMIT 100
""")
查询时请注意:
- 单次
LIMIT最大 5,000 行;ORDER BY最多 3 列;GROUP BY最多 5 列。 - 支持的写法与不支持语法见 限制与约束。