JSONField con SQL Server

En este artículo se explica cómo funciona Django JSONField con SQL Server a través del mssql-django back-end, incluidas las búsquedas admitidas y las limitaciones.

Prerequisites

  • SQL Server 2016 o posterior (se requieren funciones JSON)
  • mssql-django 1.2 o posterior

Cómo se corresponde JSONField con SQL Server

El campo JSONField de Django se asigna a nvarchar(max) con una restricción de validación JSON en SQL Server. El back-end usa las funciones JSON integradas de SQL Server (JSON_VALUE, JSON_QUERY, ISJSON) para implementar búsquedas y consultas.

Definición de un modelo con JSONField

Agregue el siguiente modelo a myapp/models.py. Los ejemplos de este artículo usan el modelo Item para que no entren en conflicto con el modelo Product del inicio rápido de Django.

from django.db import models

class Item(models.Model):
    name = models.CharField(max_length=100)
    metadata = models.JSONField(default=dict)
    tags = models.JSONField(null=True, blank=True)

Genere y aplique la migración para que la tabla subyacente exista en SQL Server:

python manage.py makemigrations myapp
python manage.py migrate myapp

Almacenamiento y recuperación de datos JSON

Abra el shell de Django con python manage.py shell. En el indicador >>>, importa el modelo:

from myapp.models import Item

Cree un registro con datos JSON:

item = Item.objects.create(
    name="Widget",
    metadata={"color": "blue", "weight": 1.5, "dimensions": {"height": 10, "width": 5}},
    tags=["sale", "new"],
)

Recuperar el registro y acceder a los valores JSON:

item = Item.objects.get(name="Widget")
print(item.metadata["color"])  # "blue"
print(item.tags)  # ["sale", "new"]

Búsquedas compatibles

El mssql-django back-end admite las siguientes búsquedas JSONField:

Búsquedas de clave/índice

Acceda a los valores JSON anidados mediante la sintaxis de doble subrayado de Django:

# Filter by nested key value
Item.objects.filter(metadata__color="blue").values()

# Access nested objects
Item.objects.filter(metadata__dimensions__height=10).values()

contains

Note

La búsqueda de contains no es compatible con el mssql-django backend. Utiliza has_key con búsquedas mediante rutas de clave como alternativa:

# Instead of: Item.objects.filter(metadata__contains={"color": "blue"})
# Use key-path lookup:
Item.objects.filter(metadata__color="blue").values()

has_key

Compruebe si existe una clave específica:

Item.objects.filter(metadata__has_key="color").values()

tiene_claves

Compruebe si existen todas las claves especificadas:

Item.objects.filter(metadata__has_keys=["color", "weight"]).values()

has_any_keys

Compruebe si existe alguna de las claves especificadas:

Item.objects.filter(metadata__has_any_keys=["color", "size"]).values()

isnull

La isnull búsqueda tiene un comportamiento específico con SQL Server:

# Returns objects where the key doesn't exist AND keys with None value
Item.objects.filter(metadata__color__isnull=True).values()

# Returns objects where the key exists and has a non-null value
Item.objects.filter(metadata__color__isnull=False).values()

Note

En el mssql-django backend, si existe una clave pero tiene un valor JSON null, has_key devuelve un QuerySet vacío. Esto difiere de PostgreSQL, donde has_key devuelve True independientemente del valor. La isnull=True búsqueda devuelve objetos donde la clave no existe y los objetos donde el valor es null.

exactamente con None

La exact búsqueda no admite None valores. La consulta siguiente devuelve un querySet vacío:

# Returns empty QuerySet - use isnull lookup instead
Item.objects.filter(metadata__color=None).values()

Use la isnull búsqueda en su lugar para buscar valores NULL.

Limitations

  • Actualizaciones masivas con JSONField: algunos casos perimetrales existen al usar bulk_update con valores JSONField, especialmente en Django 5.2 y versiones posteriores. Para obtener más información, consulte Limitaciones y características no admitidas en mssql-django.
  • EXPRESIONES CASE WHEN: en Django 5.2 y versiones posteriores, ciertas operaciones JSONField dentro de las expresiones CASE WHEN podrían generar resultados inesperados.
  • exactamente con None: use isnull en lugar de exact para filtrar los valores JSON NULL.
  • has_key con valores nulos: has_key devuelve un QuerySet vacío para las claves que existen, pero tienen el valor null.
  • Caracteres de comillas literales en valores de cadena JSON: es posible que las búsquedas de igualdad en valores de cadena JSON que contengan caracteres " literales (por ejemplo, metadata={"description": '"quoted"'}) no coincidan con la fila almacenada. Los valores que contienen caracteres de comillas se almacenan correctamente, pero no se pueden recuperar de forma confiable a través de búsquedas de campos.

Contenido relacionado

  • Last updated on