JSONField 查询慢主因是默认无索引、Python反序列化开销大、嵌套路径SQL生成易错；需建GIN索引（jsonb_path_ops或函数索引），避免全表扫描和Python解析，用jsonb_set原地更新而非全量替换。
JSONField 查询为什么慢？先看底层存储结构
Django 的 JSONField 在 PostgreSQL 中映射为 jsonb 类型，本身支持索引和路径查询，但默认不建索引，且 Python 层反序列化开销大。直接用 .filter(data__key=value) 看似简洁，实际可能触发全表扫描或逐行 Python 解析。
- 如果字段嵌套深（如
data<strong>meta</strong>tags<strong>0</strong>name），Django 生成的 SQL 路径表达式易出错，PostgreSQL 也难优化 -
<strong>contains</strong>、icontains在jsonb上无法走 B-tree 索引，只能依赖GIN索引，且仅对键存在、对象包含等场景有效 - 字符串值带空格或特殊字符时，
__exact可能因 JSON 序列化格式差异（如空格、换行）匹配失败
给 JSONField 建 GIN 索引的两种可靠方式
PostgreSQL 的 jsonb 必须配 GIN 索引才支持高效路径查询。Django 不自动创建，需手动加：
- 在模型 Meta 中声明：
class MyModel(models.Model): data = models.JSONField() class Meta: indexes = [ models.Index(fields=['data'], opclasses=['jsonb_path_ops']) ]jsonb_path_ops是最常用选项，支持__contains、__has_key、__has_keys等，但不支持__gt或路径提取比较 - 若需按某个固定路径查（如
data->'user'->>'id'），用函数索引更高效：# migrations/xxx.py from django.db import migrations </li></ul><p>class Migration(migrations.Migration): operations = [ migrations.RunSQL( "CREATE INDEX idx_data_user_id ON myapp_mymodel USING GIN ((data -> 'user' ->> 'id'));", reverse_sql="DROP INDEX idx_data_user_id;" ) ]</p>
注意：函数索引字段名必须用括号包裹，且->>返回 text，适合字符串等值查询；若查数字，用->+ 铸造（如(data -> 'score')::int），但需确保数据类型一致避免 Python 层解析：用 raw SQL 或 extra() 提取路径值
当需要按 JSON 内某个数值字段排序或范围查询（如“找 score > 85 的记录”），用纯 ORM 易触发全表解析：
- 错误写法：
MyModel.objects.filter(data<strong>score</strong>gt=85)→ Django 会尝试把整个data字段取出来再 Python 里解析，极慢 - 正确做法：用
extra()直接下推到数据库：MyModel.objects.extra( where=["(data ->> 'score')::numeric > %s"], params=[85] )
或更现代的annotate()+Func：from django.db.models import Func, F </li></ul><p>class JSONBExtract(Func): function = 'jsonb_extract_path_text' template = "%(function)s(%(expressions)s, '%(key)s')" def <strong>init</strong>(self, expression, key, <strong>kwargs): super().<strong>init</strong>(expression, key=key, </strong>kwargs)</p><p>qs = MyModel.objects.annotate( score_val=JSONBExtract('data', 'score') ).filter(score_val__gt='85')</p>注意：jsonb_extract_path_text返回 text，数值比较需确保字段内容可转为数字，否则结果不可靠；生产环境建议在数据库层用COALESCE或NULLIF处理脏数据更新 JSONField 单个键值别用 full replace，要用 jsonb_set
用
obj.data['key'] = new_val; obj.save()会导致整字段重写，锁表时间长、WAL 日志暴涨。PostgreSQL 提供jsonb_set原地更新：立即学习“Python免费学习笔记（深入）”；
- Django 没有内置封装，需用
update()+Func：from django.db.models import Func </li></ul><p>MyModel.objects.filter(id=123).update( data=Func( 'data', Func( Func('data', function='jsonb_build_array', template="'key'"), function='jsonb_build_array', template="'new_value'" ), function='jsonb_set', template="%(function)s(%(expressions)s, %(template)s, true)" ) )</p>更稳妥的做法是写原生 SQL：MyModel.objects.filter(id=123).update( data=Func( 'data', function='jsonb_set', template="%(function)s(%(expressions)s, '{key}', %s::jsonb, true)", args=['"new_value"'] ) )关键点：true表示插入不存在的键；args中的值必须是合法 JSON 字符串（如数字不加引号，字符串要双引号转义）；批量更新时务必加 where 条件，否则全表被改JSON 查询真正卡点不在语法，而在索引策略与操作粒度——建错索引比写错查询更难排查，原地更新漏掉
true参数会导致静默失败。
- Django 没有内置封装，需用
- 错误写法：
