不再为 JSON 纠结：MySQL HeatWave Document Store 的混合之道

预计阅读时间：9 分钟

用户画像、IoT 遥测、AI 提示词日志、商品目录——现代应用每天都在吞吐大量半结构化数据。这些数据天生带着 JSON 的灵活基因，字段随时增减，嵌套层级深浅不一，硬塞进严苛的关系型表结构里，往往意味着无休止的 ALTER TABLE 和痛苦的 ORM 映射。

但另一方面，企业又很难彻底拥抱纯文档数据库。事务一致性、细粒度权限控制、成熟的运维生态，以及最关键的——对海量数据做实时分析的能力，这些恰恰是传统关系型数据库的看家本领。

MySQL HeatWave Document Store 的出现，本质上是在这两个极端之间架起了一座桥：既不用放弃 MySQL 的企业级底气，又能获得 NoSQL 级别的开发灵活性。

关系与文档的边界正在消融

过去，处理半结构化数据通常面临两条路线的拉扯：

纯关系型路线：把 JSON 展平为多张表，或者塞进 TEXT/JSON 字段。前者运维成本极高，后者查询性能堪忧，且无法利用数据库的分析引擎。
纯文档数据库路线：用 MongoDB 等 NoSQL 存储开发极其丝滑，但一旦涉及跨文档的复杂聚合分析，或者需要强事务保证的场景，往往需要引入额外的数据管道（ETL）同步到分析型数据库中。

HeatWave Document Store 的思路是：何必折腾？ 它在 MySQL 原生的 JSON 数据类型之上，封装了一套符合 NoSQL 习惯的 CRUD API（X DevAPI），让开发者可以用 JavaScript/Python 等语言的直觉操作文档。同时，底层依然是 InnoDB 引擎在保障事务与持久性。

更关键的是，当这些文档需要做统计分析时，数据无需移动。HeatWave 的内存列存引擎会自动识别 JSON 字段并将其加载为可分析的列，直接在数据库内部完成 OLAP 级别的聚合查询。

从开发到分析的丝滑切换

Document Store 的核心体验在于“双模操作”。在日常开发中，你可以完全无视 SQL，把 MySQL 当作一个文档数据库来用；而在业务分析时，你又可以直接打开 SQL 接口，对同一批 JSON 数据做复杂的聚合与过滤。

这种能力对于 AI 应用尤其契合。比如存储大模型的交互日志，每次请求的参数、Token 消耗、响应延迟天然是结构多变的 JSON。存入 Document Store 后，既能通过 NoSQL API 快速检索某次对话，又能通过 SQL + HeatWave 实时统计不同模型的平均 Token 成本。

实战：用 MySQL Shell 管理 AI 提示词日志

下面通过一个具体的场景——存储和查询 AI 模型的提示词执行日志，来演示 Document Store 的日常操作。

确保你已经安装了 MySQL Shell（mysqlsh），并且连接到启用了 HeatWave 的 MySQL 实例。默认情况下，X Protocol 监听在 33060 端口。

1. 建立连接与创建集合

进入 MySQL Shell，切换到 JavaScript 模式，通过 X DevAPI 连接并创建一个专门存文档的 Schema 和 Collection：

// 连接到 MySQL 实例 (X Protocol)
// 请将 <user>, <password>, <host> 替换为你的实际配置
var session = mysqlx.getSession('mysqlx://<user>:<password>@<host>:33060');

// 创建 Schema 和 Collection（相当于 NoSQL 里的 Database 和 Collection）
var schema = session.createSchema('ai_app_logs');
var promptLogs = schema.createCollection('prompt_logs');

print("Collection created successfully.");

2. 插入半结构化文档

AI 交互日志的字段可能随模型版本迭代而变化。使用 add() 方法插入文档，无需预先定义表结构：

// 插入两条不同结构的 AI 提示词日志
promptLogs.add({
    model: "gpt-4-turbo",
    prompt_tokens: 150,
    completion_tokens: 320,
    latency_ms: 1200,
    metadata: {
        region: "us-east-1",
        user_tier: "premium"
    }
}).execute();

promptLogs.add({
    model: "claude-3-opus",
    prompt_tokens: 80,
    completion_tokens: 410,
    latency_ms: 950,
    // 字段随时可以增减，比如新增 cost_usd
    cost_usd: 0.025,
    metadata: {
        region: "eu-west-1",
        user_tier: "standard"
    }
}).execute();

print("Documents inserted.");

3. NoSQL 风格的条件查询

日常排查问题时，直接用链式调用查找特定条件的文档，无需拼凑 SQL 字符串：

// 查找延迟超过 1 秒且属于 premium 用户的记录
var result = promptLogs.find("latency_ms > 1000 AND metadata.user_tier = 'premium'")
                      .fields("model", "latency_ms", "metadata.region")
                      .sort("latency_ms DESC")
                      .execute();

var doc = result.fetchOne();
while (doc) {
    print(doc);
    doc = result.fetchOne();
}

4. 切换 SQL 视角做统计分析

当运营团队需要统计各模型的平均 Token 消耗和成本时，NoSQL 的聚合管道可能显得笨拙。此时，直接在同一个 MySQL 实例上开启 SQL 会话，利用 HeatWave 对 JSON 字段进行高性能分析：

-- 切换到 SQL 模式 (\sql)
-- 确保 HeatWave 引擎已加载该表的数据

SELECT 
    JSON_UNQUOTE(JSON_EXTRACT(doc, '$.model')) AS model_name,
    AVG(JSON_EXTRACT(doc, '$.prompt_tokens')) AS avg_prompt_tokens,
    AVG(JSON_EXTRACT(doc, '$.latency_ms')) AS avg_latency_ms,
    COUNT(*) AS total_calls
FROM 
    ai_app_logs.prompt_logs 
GROUP BY 
    model_name
ORDER BY 
    avg_latency_ms ASC;

注意：在 HeatWave 中，针对 JSON 字段的提取与聚合会被自动优化为列存计算，速度远比在单机 MySQL 上做全表扫描快得多。

落地建议与边界考量

引入 HeatWave Document Store 并不是要替代所有的 NoSQL 数据库，它最适合的是那些既需要灵活的半结构化存储，又离不开强一致性事务和实时分析的混合场景。在决定落地前，有几条边界需要明确：

文档大小限制：底层依然受 MySQL max_allowed_packet 和 InnoDB 行大小限制的约束。如果你的单条 JSON 文档动辄几 MB（比如存储完整的网页快照或长视频元数据），这并非最佳选择，大文档的更新性能会显著下降。
嵌套深度与查询复杂度：虽然 MySQL 提供了丰富的 JSON 函数（如 JSON_EXTRACT, JSON_TABLE），但极其深层的嵌套路径查询（例如 $.level1.level2...level5.attr）在 SQL 里的书写体验不如 MongoDB 的点号查询直观。建议在写入时，将高频过滤字段适当提升到 JSON 的顶层结构。
更新模式：如果应用对 JSON 文档的局部字段有极高频率的细粒度更新（如秒级更新 IoT 设备状态），InnoDB 的行锁机制可能引发热点竞争。此时，将高频变更字段拆分到独立的关系型列中与文档并存，是更稳妥的做法。

采纳检查清单： 1. 数据是否天生为半结构化，且模式迭代频繁？ 2. 是否有跨文档、跨表做实时聚合分析的需求？ 3. 是否要求事务 ACID 特性（如金融、订单关联场景）？ 4. 单条文档体积是否控制在合理范围（建议 1MB 以内）？ 5. 团队是否已有 MySQL 运维经验且不想引入新数据库栈？

如果以上多数答案是肯定的，那么把 JSON 留在 MySQL 里，让 HeatWave 赋予它 NoSQL 的灵活与 OLAP 的性能，会是一个减少架构复杂度、提升交付效率的务实选择。