JSON: leer, transformar y producir documentos desde SQL Server

Una API o integración puede entregar un documento JSON que necesitamos validar y convertir en filas. SQL Server incluye funciones para consultar valores, abrir arreglos, modificar propiedades y generar una salida estructurada.

Las funciones trabajan con rutas que comienzan en $, la raíz del documento. Conviene validar la entrada antes de depender de su contenido.

Consultar valores y fragmentos

DECLARE @Documento NVARCHAR(MAX) = N'
{
  "cliente": { "id": 101, "nombre": "Ana" },
  "productos": [
    { "id": 1, "cantidad": 2 },
    { "id": 5, "cantidad": 1 }
  ]
}';

SELECT
    JSON_VALUE(@Documento, '$.cliente.id') AS IdCliente,
    JSON_VALUE(@Documento, '$.cliente.nombre') AS Nombre,
    JSON_QUERY(@Documento, '$.productos') AS Productos;

JSON_VALUE devuelve un valor escalar. JSON_QUERY devuelve un objeto o arreglo conservando su estructura JSON.

ISJSON(@Documento) permite comprobar si la expresión contiene JSON válido. La validación sintáctica no confirma que existan todas las propiedades ni que respeten nuestras reglas de negocio.

Convertir un arreglo en filas

SELECT
    j.IdProducto,
    j.Cantidad
FROM OPENJSON(@Documento, '$.productos')
WITH
(
    IdProducto INT '$.id',
    Cantidad INT '$.cantidad'
) AS j;

La cláusula WITH define el contrato esperado y convierte cada propiedad al tipo indicado. Si la forma del documento es variable, OPENJSON también puede devolver columnas genéricas de clave, valor y tipo.

Modificar una propiedad

SET @Documento = JSON_MODIFY(
    @Documento,
    '$.cliente.nombre',
    N'Ana Torres'
);

SELECT @Documento AS DocumentoActualizado;

JSON_MODIFY devuelve una nueva expresión con el cambio; por eso asignamos el resultado. Para varias modificaciones anidamos llamadas o las aplicamos por pasos.

Generar JSON desde filas

SELECT
    p.IdProducto AS id,
    p.Nombre AS nombre,
    p.Precio AS precio
FROM dbo.Producto AS p
WHERE p.Activo = 1
ORDER BY p.IdProducto
FOR JSON PATH, ROOT('productos');

FOR JSON PATH utiliza los alias para construir las propiedades. ROOT envuelve el arreglo en un objeto raíz. El consumidor debe acordar nombres, tipos, nulabilidad y forma del documento.

Tipos y versiones

Las funciones JSON existen desde SQL Server 2016. En versiones tradicionales el documento suele almacenarse en NVARCHAR; SQL Server 2025 ofrece además un tipo nativo JSON en versión preliminar. Diseñamos la ficha para que los ejemplos de texto sigan siendo aplicables en un rango amplio de instalaciones.

OPENJSON requiere un nivel de compatibilidad de base de datos 130 o superior. Otras capacidades nuevas pueden depender de la versión, por lo que verificamos el destino antes de publicar o desplegar scripts.

Qué conviene comprobar

Validamos tamaño, codificación, rutas, tipos y propiedades ausentes. Los modos lax y strict permiten decidir si una ruta faltante produce NULL o un error; elegimos el comportamiento de manera consciente.

Si filtramos con frecuencia por una propiedad, una columna calculada e indexada puede evitar analizar todo el documento en cada consulta. No obstante, datos que requieren relaciones, restricciones o actualizaciones frecuentes suelen pertenecer a columnas y tablas normales.

Relacionado con

• OPENJSON: transforma objetos o arreglos en filas.
• JSON_VALUE y JSON_QUERY: extraen escalares y fragmentos.
• JSON_MODIFY: devuelve el documento con una propiedad modificada.
• FOR JSON PATH: genera una representación JSON desde una consulta.