SQLite在很多本地应用、移动端和嵌入式场景里都是首选的关系型数据库，但早期版本对JSON数据的处理并不友好。JSON对象只能以普通文本形式存储，想要查询某个字段、更新嵌套值或者遍历数组，通常得把整条记录读出来交给应用层解析，既麻烦又容易出错。SQLite官方从3.9.0版本开始引入了JSON1扩展，提供了一组在SQL内部直接处理JSON的函数。这个扩展让SQLite可以像操作表结构一样操作JSON文档，对半结构化数据的存储和查询带来了很大便利。
JSON1并不是一个独立的数据库引擎，它是一组编译进SQLite库的SQL函数。只要你的SQLite版本足够新，并且编译时没有显式禁用JSON1，这些函数默认就是可用的。在实际项目中，使用JSON1之前最好先确认环境支持情况，然后理解各个核心函数的行为边界，才能在存储和查询之间找到平衡。
JSON1扩展的启用与环境确认
JSON1扩展从SQLite 3.9.0开始提供，如果你的SQLite是通过包管理器安装的，或者使用Python、Node.js等语言内置的SQLite模块，大概率已经包含JSON1支持。检查方法很简单，执行一条最基本的JSON函数语句即可：
SELECT json('{"name":"Alice","age":30}');
如果这条语句返回了原始的JSON字符串，并且没有报错，说明JSON1扩展已经可用。需要注意，某些精简编译的SQLite发行版可能会把JSON1作为可选加载项，这时需要确认编译参数中是否包含了SQLITE_ENABLE_JSON1。如果确定没有编译进去，可以通过.load命令加载对应的动态库文件，或者在重新编译时加上该选项。对于大多数桌面和服务器环境，这一步通常不需要额外操作。
还有一个容易忽略的细节：JSON1函数返回的都是文本类型，而不是某种特殊的JSON对象类型。也就是说，无论是json_extract提取出来的标量值，还是json_set修改后的完整JSON，在SQLite内部仍然以文本形式存在。理解这一点对后续的索引优化和类型比较非常重要，因为直接拿提取结果与数字或字符串比较时，SQLite会按文本比较规则处理，可能需要手动做类型转换。
在命令行工具中，可以通过.functions或PRAGMA compile_options查看当前编译启用的特性，但不是所有版本都支持这样检查JSON1。最可靠的办法还是实际执行一个JSON函数，观察是否出现“no such function”错误。如果函数不存在，优先升级SQLite版本，因为新版默认集成JSON1。
核心JSON函数与路径语法详解
JSON1扩展提供了约二十个函数，其中最常用的包括json_extract、json_set、json_insert、json_replace、json_remove、json_each和json_tree。路径语法以美元符号$开头表示整个JSON文档，使用点号访问对象属性，使用方括号访问数组元素，例如$.user.name或$[0].id。这种语法和JavaScript、Python等语言操作JSON的习惯基本一致，上手成本很低。
json_extract用于提取指定路径的值，可以同时提取多个路径。下面的示例从一个嵌套对象中提取姓名和城市：
SELECT json_extract(
'{"user":{"name":"Alice","address":{"city":"Beijing"}}}',
'$.user.name',
'$.user.address.city'
) AS name, city;
不过上面的写法会返回两列，第一列是姓名，第二列是城市。更常见的做法是分别使用多个json_extract调用，或者在一条SELECT中写多个表达式。如果路径不存在，返回值为NULL，而不是报错，这一点在空值处理上比较宽容。
修改JSON内容时，json_set、json_insert和json_replace很容易混淆。json_set会覆盖已存在的路径值，同时如果路径不存在则新增；json_insert只在路径不存在时插入，不会覆盖原有值；json_replace只在路径已存在时替换，不会新增。实际使用中，json_set最常用，因为它的行为最接近“不管有没有，给我设成这个值”。下面是一个综合示例：
SELECT json_set(
'{"name":"Alice","age":30}',
'$.age', 31,
'$.city', 'Shanghai'
);
这段语句会把age改成31，并新增city字段。路径和值需要成对出现，函数会按顺序应用修改。要注意的是，如果原始JSON不是合法的JSON格式，这些函数会抛出错误，所以在写入前最好确保数据经过验证，或者使用json_valid函数做一次检查。
遍历JSON数组是另一个常见需求。json_each是一个表值函数，它把JSON数组展开为一张关系表，每行包含key、value、type等字段。结合SQLite的普通查询能力，可以很方便地对数组元素进行过滤和聚合。例如一个存储了标签数组的字段，想要统计每个标签出现的次数，可以这样写：
SELECT value AS tag, COUNT(*) FROM articles, json_each(articles.tags) GROUP BY value ORDER BY COUNT(*) DESC;
这里json_each(articles.tags)会把每一行的标签数组展开成多行，然后外层查询按照标签值分组统计。这种写法比在应用层循环累加要简洁得多，而且完全运行在数据库内部，减少了数据传输开销。
实战：用JSON列构建灵活的存储结构
很多业务场景里，某些记录的扩展字段是不固定的。比如一个商品表，不同类别的商品拥有不同的属性，用传统关系型设计需要建EAV表或者大量可空列，维护成本很高。借助JSON1，可以建一个attributes列直接存储JSON对象，查询时按需提取。下面创建一个商品表并插入示例数据：
CREATE TABLE products (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
category TEXT NOT NULL,
attributes TEXT
);
INSERT INTO products (name, category, attributes) VALUES
('ThinkPad X1', 'laptop', '{"cpu":"i7","ram":16,"ssd":512}'),
('iPhone 15', 'phone', '{"color":"black","storage":256,"5g":true}');
接下来查询所有内存大于等于16GB的笔记本，并提取处理器型号：
SELECT name,
json_extract(attributes, '$.cpu') AS cpu,
json_extract(attributes, '$.ram') AS ram
FROM products
WHERE category = 'laptop'
AND CAST(json_extract(attributes, '$.ram') AS INTEGER) >= 16;
可以看到，JSON列的灵活性让同一张表可以容纳不同结构的数据，而不需要频繁修改表结构。但灵活性的代价是查询性能。注意上面这条SQL中对json_extract结果进行了CAST操作，因为提取出来的ram值是文本'16'，如果不转成整数，文本比较可能会得到错误结果。这是新手很容易踩的坑。
如果这类过滤条件经常出现，每次都扫描全表并解析JSON会非常低效。SQLite允许创建生成列，把JSON中的常用字段提取出来单独存储，并在生成列上建立索引。例如：
ALTER TABLE products ADD COLUMN ram INTEGER GENERATED ALWAYS AS (CAST(json_extract(attributes, '$.ram') AS INTEGER)) STORED; CREATE INDEX idx_products_ram ON products(ram);
这样查询时就可以直接对ram列进行过滤和索引扫描，不再需要全表解析JSON。生成列的值会随attributes列的更新自动同步，不需要应用层额外维护。对于读多写少的场景，这种方案能在灵活性和性能之间取得不错的平衡。当然，如果JSON结构非常多变，生成列可能会膨胀，需要根据实际业务选择最常用的几个字段做提取。
常见误区与替代方案对比
使用JSON1时最常见的一个误区就是把JSON列当成了关系型字段来随意过滤。SQLite的查询优化器无法识别json_extract内部的路径表达式，即使你在JSON字段上建立了普通索引，实际上也不会被用到。例如下面的写法看起来正常，但会触发全表扫描：
SELECT name FROM products WHERE json_extract(attributes, '$.ram') = '16';
如果数据量只有几百条，问题不大；数据量达到几十万甚至上百万时，这种查询会严重影响性能。解决办法就是前面提到的生成列加索引，或者使用独立的普通列来存储高频查询字段，把JSON只作为低频扩展数据的容器。
另一个需要澄清的概念是JSON1与SQLite后来支持的JSONB之间的关系。从3.45版本开始，SQLite引入了JSONB二进制格式和相关函数，能够更高效地处理JSON数据，减少重复解析开销。但这并不意味着JSON1会被废弃，JSON1的函数仍然广泛存在于各个版本中，而且JSONB在API层面和JSON1高度兼容。对于大多数应用来说，如果SQLite版本支持JSONB，可以考虑在频繁修改JSON的场景下使用，因为JSONB会缓存解析后的结构；如果只是偶尔读取或者版本较旧，JSON1已经足够。
最后值得强调的是，JSON1函数处理的是合法JSON，如果传入的字符串不是合法JSON，修改函数会报错，提取函数可能返回NULL或抛出异常。因此在写入JSON列之前，建议使用json_valid做一次校验，或者在应用层负责保证数据格式正确。不要指望数据库自动清洗非法JSON，这不在JSON1的职责范围内。只要把数据校验、路径设计和索引策略配合好，JSON1就能在SQLite里发挥出非常实用的价值。
