seekdb-sql-kit

给 AI Agent 用的「本地 SQL 数据工作台」：不需要装数据库服务、不需要写 ETL，直接对一个 seekdb（OceanBase 单机版，MySQL 协议）实例跑 SQL，把 CSV / JSON 文件当表查。

什么时候用它

用户给你一个 CSV/JSON，问「这里面有什么、帮我统计一下、按 X 分组」
需要跑多表 JOIN 但数据还在文件里
想验证一段 SQL 但不想连生产库
想试 OceanBase 的 AI 函数（AI_COMPLETE / AI_EMBED）但不想申请云实例

30 秒上手

# 1) 确认实例在跑（默认 127.0.0.1:2881，root 空密码）
python3 scripts/seekdb.py ping

# 2) 把 CSV 当表建好（自动推断列名与类型）
python3 scripts/seekdb.py load-csv sales.csv --db demo --table sales

# 3) 直接查
python3 scripts/seekdb.py sql "select region, count(*), round(sum(amount),2) from demo.sales group by region order by 2 desc"

没有实例？先起一个：

bash scripts/start_seekdb.sh          # 默认 ~/seekdb-run，端口 2881

核心用法

1. 把文件当表

# CSV：首行是表头，自动推断 int/double/varchar/date
python3 scripts/seekdb.py load-csv data.csv --db demo --table data

# JSON（数组对象）或 JSONL：每行一个对象
python3 scripts/seekdb.py load-json data.jsonl --db demo --table events

推断规则：全是整数 → bigint；含小数 → double；ISO 日期 → datetime；其余 → varchar(512)；空字符串与 NULL 都存成 NULL。

2. 查询

python3 scripts/seekdb.py sql "select * from demo.sales limit 5"
python3 scripts/seekdb.py sql --format csv "select * from demo.sales" > out.csv
python3 scripts/seekdb.py sql --format json "select count(*) as n from demo.sales"

输出默认是对齐的表格，方便直接贴给用户；--format json|csv 便于下游处理。

3. 多表 JOIN

python3 scripts/seekdb.py load-csv orders.csv   --db demo --table orders
python3 scripts/seekdb.py load-csv customers.csv --db demo --table customers
python3 scripts/seekdb.py sql "select c.name, count(*) n, sum(o.amount) total
                                 from demo.orders o join demo.customers c on c.id = o.customer_id
                                group by c.name order by total desc limit 10"

4. AI 函数（需要 seekdb 开启 AI 服务）

-- 文本生成
select AI_COMPLETE('qwen-plus', concat('用一句话总结：', content)) from demo.docs limit 1;

-- 向量（用于相似检索）
select id, AI_EMBED('text-embedding-v3', content) from demo.docs limit 3;

配置见 references/ai-functions.md。

工作约定

先探查再分析：拿到文件先 load-* 后跑 select * ... limit 5 看真实数据，不要凭列名猜。
大文件先抽样：load-csv 支持 --limit N，超过 100 万行建议先抽样理解结构。
写操作要确认：sql 子命令默认拒绝 drop/truncate/delete（除非加 --allow-write）。
结果要可复现：把实际执行的 SQL 一起给用户，而不是只给结论。

排错

| 现象 | 原因 | 处理 | |---|---|---| | Can't connect to MySQL server | 实例没起 | bash scripts/start_seekdb.sh | | Unknown database | 库没建 | load-csv 会自动建库；手动建用 sql "create database x" | | 中文乱码 | 连接字符集 | 脚本已固定 utf8mb4，检查文件本身编码 | | 列全是 varchar | 推断保守 | 用 SQL cast(col as bigint) 显式转换 |

文件

scripts/start_seekdb.sh — 一键起停 seekdb
scripts/seekdb.py — 连接 / 建表 / 导入 / 查询（单文件，无第三方依赖，用 mysql 客户端协议）
references/sql-cheatsheet.md — 常用分析 SQL 模板
references/ai-functions.md — AI 函数速查