The SQL Booklet

Buscar en SQL Server

Escribe dos caracteres o más.

English

JSON: leer, transformar y producir documentos desde SQL Server

Una API —una interfaz mediante la que dos sistemas intercambian solicitudes y respuestas— o integración puede entregar un documento JSON que necesitamos validar y convertir en filas. JSON es un formato de texto estructurado con objetos, arreglos, propiedades y valores. SQL Server incluye funciones para consultar valores, abrir arreglos, modificar propiedades y generar una salida estructurada.

Las funciones trabajan con rutas, expresiones que indican qué parte del documento queremos localizar. Comienzan en $, la raíz que representa el documento completo. Conviene validar la entrada antes de depender de su contenido.

Operaciones con JSON

ISJSON: comprobar la sintaxis del documento

ISJSON devuelve 1 cuando una expresión contiene JSON válido y 0 cuando no lo contiene. Comprueba la forma del documento, no que sus propiedades satisfagan las reglas del sistema.

ISJSON(Expresion)

JSON_VALUE: extraer un valor escalar

JSON_VALUE localiza mediante una ruta un solo texto, número o valor lógico. Un valor escalar no contiene dentro otro objeto o arreglo.

JSON_VALUE(Documento, Ruta)

JSON_QUERY: conservar un objeto o arreglo

JSON_QUERY extrae un fragmento que contiene un objeto o arreglo y conserva su estructura JSON.

JSON_QUERY(Documento, Ruta)

OPENJSON: convertir JSON en filas

OPENJSON recorre un objeto o arreglo y devuelve un conjunto tabular. Un conjunto tabular tiene filas y columnas que pueden consultarse como las de una tabla.

OPENJSON(Documento, Ruta)

JSON_MODIFY: cambiar una propiedad

JSON_MODIFY devuelve otra expresión JSON con el valor indicado en la ruta. No modifica por sí sola la variable o columna de origen; debemos asignar o almacenar el resultado.

JSON_MODIFY(Documento, Ruta, ValorNuevo)

FOR JSON PATH: construir JSON desde filas

FOR JSON PATH transforma las filas finales de una consulta en un arreglo JSON. Los nombres o alias de las columnas determinan las propiedades producidas.

SELECT Columna1, Columna2
FROM dbo.Tabla
FOR JSON PATH;

Una ruta como $.cliente.id se lee desde la raíz $, entra al objeto cliente y después localiza la propiedad id.

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, es decir, un solo texto, número o valor lógico. 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 —los nombres y tipos que la consulta admite— 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, una capacidad todavía sujeta a cambios antes de su disponibilidad general. Los ejemplos utilizan texto para conservar compatibilidad con 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. El modo lax tolera una ruta faltante y puede producir NULL; strict la trata como error. Elegimos el comportamiento de manera consciente.

Si filtramos con frecuencia por una propiedad, una columna calculada —cuyo valor deriva de una expresión— e indexada puede evitar analizar todo el documento en cada consulta. El índice organiza esos valores para facilitar el acceso. No obstante, datos que requieren relaciones, restricciones o actualizaciones frecuentes suelen pertenecer a columnas y tablas normales.

Relacionado con