Django中JSONField使用icontains过滤JSON数据失效问题

问题概述 #

使用Django的JSONField存储嵌套JSON数据时，尝试通过__icontains过滤嵌套字段（如template_message__header__content），无报错但结果不符合预期——原因是部分数据库将JSON存储为字符串，__icontains会匹配整个JSON字符串而非解析后的字段值。

模型与数据结构 #

模型定义 #

from django.db import models

class ChatMessage(models.Model):
    template_message = models.JSONField(null=True)

存储的JSON示例 #

{
    "header": {
        "type": "text",
        "content": "Hello"
    },
    "body": "Hi there",
    "footer": "Hello there"
}

失效的过滤代码 #

ChatMessage.objects.filter(
    Q(template_message__header__content__icontains=search_key) |
    Q(template_message__body__icontains=search_key) |
    Q(template_message__footer__icontains=search_key)
)

解决方案 #

1. PostgreSQL 原生JSONB操作（推荐） #

PostgreSQL支持jsonb类型（Django JSONField默认使用），可以利用数据库原生函数实现准确的不区分大小写匹配：

方式A：使用Django内置字段查找

from django.db.models import Q

# 统一转为小写后匹配，避免大小写问题
search_key_lower = search_key.lower()
ChatMessage.objects.filter(
    Q(template_message__header__content__lower__contains=search_key_lower) |
    Q(template_message__body__lower__contains=search_key_lower) |
    Q(template_message__footer__lower__contains=search_key_lower)
)

方式B：使用extra调用原生SQL

from django.db.models import Q

search_pattern = f'%{search_key.lower()}%'
ChatMessage.objects.filter(
    Q(template_message__header__content__isnull=False) |
    Q(template_message__body__isnull=False) |
    Q(template_message__footer__isnull=False)
).extra(
    where=[
        "LOWER(template_message->'header'->>'content') LIKE %s",
        "LOWER(template_message->>'body') LIKE %s",
        "LOWER(template_message->>'footer') LIKE %s"
    ],
    params=[search_pattern]*3,
    connective='OR'
)

2. SQLite 兼容方案 #

SQLite需先启用JSON1扩展，再通过json_extract提取字段后匹配：

from django.db.models import Func, Value, Q

class JsonExtract(Func):
    function = 'json_extract'
    template = "%(function)s(%(expressions)s, %(path)s)"
    def __init__(self, expression, path, **kwargs):
        super().__init__(expression, path=Value(path), **kwargs)

search_key_lower = search_key.lower()
ChatMessage.objects.filter(
    Q(
        Func(JsonExtract('template_message', '$.header.content'), function='LOWER')__contains=search_key_lower
    ) |
    Q(
        Func(JsonExtract('template_message', '$.body'), function='LOWER')__contains=search_key_lower
    ) |
    Q(
        Func(JsonExtract('template_message', '$.footer'), function='LOWER')__contains=search_key_lower
    )
)

3. 内存过滤（小数据量适用） #

如果数据量不大，可先查询所有记录，再在Python层面过滤：

search_key_lower = search_key.lower()
filtered = []
for msg in ChatMessage.objects.all():
    tm = msg.template_message
    if not tm:
        continue
    content = tm.get('header', {}).get('content', '').lower()
    body = tm.get('body', '').lower()
    footer = tm.get('footer', '').lower()
    if search_key_lower in content or search_key_lower in body or search_key_lower in footer:
        filtered.append(msg)

关键注意事项 #

• PostgreSQL下优先用jsonb类型，性能和功能更完善。
• SQLite必须启用JSON1扩展才能支持JSON字段的解析操作。
• 大数据量场景避免使用内存过滤，会导致性能瓶颈。
• 统一转为小写后匹配，能确保不区分大小写的搜索准确性。

内容的提问来源于stack exchange，提问作者mahmudsajib