Peewee中JSON字段查询的列名处理问题解析

问题现象

在使用Peewee ORM操作SQLite数据库时，当查询JSON字段中的特定键值时，返回结果的列名会出现异常情况。具体表现为：

1. 查询结果中只包含部分请求的JSON键值
2. 返回的列名显示为奇怪的格式，如json", ?

问题复现

通过以下代码可以复现该问题：

from peewee import *
from playhouse.sqlite_ext import JSONField

db = SqliteDatabase(':memory:')

class Table(Model):
    id = IntegerField(primary_key=True)
    json = JSONField()

    class Meta:
        database = db

db.connect()
db.create_tables([Table])

record = Table.create(
    id=1,
    json={'value': 3, 'other_value': 4}
)

query = Table.select(Table.id, Table.json['value'], Table.json['other_value']).dicts()
print("SQL Query:", query.sql())
results = list(query)
print("Results:", results)

db.close()

执行结果会显示：

SQL Query: ('SELECT "t1"."id", json_extract("t1"."json", ?), json_extract("t1"."json", ?) FROM "table" AS "t1"', ['$.value', '$.other_value'])
Results: [{'id': 1, 'json", ?': 3}]

问题根源

深入分析后发现，这个问题源于SQLite本身对JSON提取函数的列名处理方式。当执行json_extract函数时，SQLite返回的列名实际上是完整的函数表达式字符串，包括参数占位符?。

通过检查SQLite返回的列名描述信息可以确认这一点：

curs = db.execute(query)
print([r[0] for r in curs.description])  # 打印SQLite返回的列名

输出结果为：

['id', 'json_extract("t1"."json", ?)', 'json_extract("t1"."json", ?)']

Peewee尝试对这些原始列名进行清理和简化，但在处理包含参数占位符的复杂表达式时，这种清理逻辑并不总是能完美工作，导致出现奇怪的列名格式。

解决方案

方案一：使用alias显式指定列名

最可靠的解决方案是为每个JSON提取操作指定明确的别名：

query = Table.select(
    Table.id,
    Table.json['value'].alias('value'),
    Table.json['other_value'].alias('other_value')
).dicts()

这样就能确保结果字典中的键名符合预期。

方案二：使用tuples()方法获取元组结果

如果不介意以元组形式获取结果，可以使用.tuples()方法：

query = Table.select(Table.id, Table.json['value'], Table.json['other_value']).tuples()
for row in query:
    id, value, other_value = row
    print(id, value, other_value)

这种方法更加直接，避免了列名处理的问题。

技术背景

SQLite的JSON扩展功能通过json_extract()函数实现，该函数在查询执行时会生成包含完整函数表达式的列名。这种设计在直接使用SQL时没有问题，但在ORM映射到Python对象时，会导致列名难以处理。

Peewee作为ORM工具，需要在SQL抽象和Python对象之间建立桥梁，对于这种特殊情况，显式指定列名是最稳妥的做法。

最佳实践建议

1. 当查询JSON字段中的特定键值时，总是使用.alias()方法为结果列指定明确的名称
2. 对于复杂的JSON查询，考虑使用SQLite的JSON1扩展提供的其他函数，如json_each等
3. 在调试时，可以通过检查query.sql()和数据库返回的原始列名来理解问题所在
4. 对于简单的键值提取，.tuples()方法可以提供更直接的结果访问方式

通过理解这些底层机制，开发者可以更有效地使用Peewee处理SQLite中的JSON数据。