Tipo de datos JSON

Se aplica a: SQL Server 2025 (17.x) Base de datos SQL de Azure SQL Database deAzure SQL Managed Instanceen Microsoft Fabric

El tipo de dato json almacena documentos JSON en formato binario.

El tipo json proporciona almacenamiento de alta fidelidad de documentos JSON optimizado para consultas y manipulaciones. Ofrece los siguientes beneficios respecto a almacenar datos JSON como varchar o nvarchar:

• Lecturas más eficientes, ya que el documento ya está analizado.
• Escrituras más eficientes, ya que la consulta puede actualizar valores individuales sin acceder a todo el documento.
• Almacenamiento más eficiente, optimizado para la compresión.
• No hay cambios en la compatibilidad con el código existente.

El tipo json almacena internamente cadenas usando codificación UTF-8 (Latin1_General_100_BIN2_UTF8). Otros tipos de datos se almacenan como tipos nativos. Este comportamiento coincide con la especificación JSON.

Para obtener más información sobre cómo consultar datos JSON, consulte Datos JSON en SQL Server.

Sintaxis de ejemplo

La sintaxis de uso del tipo json es similar a todos los demás tipos de datos de SQL Server de una tabla.

column_name JSON [ NOT NULL | NULL ] [CHECK ( constraint_expression ) ] [ DEFAULT ( default_expression ) ]

Utiliza el tipo de dato json en una definición de columna contenida en una CREATE TABLE sentencia. Por ejemplo:

CREATE TABLE Orders
(
    order_id INT,
    order_details JSON NOT NULL
);

Especifica restricciones como parte de la definición de columna. Por ejemplo:

CREATE TABLE Orders
(
    order_id INT,
    order_details JSON NOT NULL
        CHECK (JSON_PATH_EXISTS(order_details, '$.basket') = 1)
);

Disponibilidad de funcionalidades

El soporte para funciones JSON se introdujo en SQL Server 2016 (13.x). El tipo de dato json integrado está disponible en Azure SQL Database, Azure SQL Managed Instance y SQL Server 2025 (17.x).

Para más información sobre el soporte JSON en SQL Server 2025 (17.x), consulte Capacidades clave de JSON en SQL Server 2025.

El tipo de datos json está disponible en todos los niveles de compatibilidad de la base de datos.

Método modify

El tipo de datos json admite el modify método . Úsalo modify para cambiar documentos JSON almacenados en una columna. El modify método incluye optimizaciones que realizan modificaciones in situ a los datos cuando es posible. Es la forma preferida de modificar un documento JSON en una columna json .

Para cadenas JSON, si el nuevo valor tiene la misma longitud o es más corto que el existente, el método puede modificar los datos en su lugar.

Para números JSON, si el nuevo valor es del mismo tipo o encaja dentro del rango del valor existente, el método puede modificar los datos en su lugar.

DROP TABLE IF EXISTS JsonTable;

CREATE TABLE JsonTable
(
    id INT PRIMARY KEY,
    d JSON
);

INSERT INTO JsonTable
(
    id,
    d
)
VALUES (1, '{"a":1, "b":"abc", "c":true}');

UPDATE JsonTable
SET d.modify('$.a', 14859)
WHERE id = 1;

UPDATE JsonTable
SET d.modify('$.b', 'def')
WHERE id = 1;

Datos válidos

La entrada al tipo de datos json debe ser un objeto JSON o una matriz JSON. No se soportan escalares, booleanos y NULL valores. El tipo de datos JSON se ajusta a IETF RFC 4627 que solo permite un objeto o matriz JSON.

Utiliza la función ISJSON para comprobar si una cadena contiene JSON válido. Sin restricción de tipo, ISJSON acepta solo un objeto o array JSON en el nivel superior, igual que el tipo de dato json . La VALUE restricción de tipo acepta cualquier valor JSON en el nivel superior, incluyendo un escalar, tal y como permite IETF RFC 8259. Las ARRAYrestricciones , OBJECT, y SCALAR de tipo aceptan solo ese tipo.

Por ejemplo:

DECLARE @true AS JSON = 'true'; -- invalid
DECLARE @false AS JSON = 'false'; -- invalid
DECLARE @number AS JSON = '1234.56'; -- invalid
DECLARE @string AS JSON = '"contoso"'; -- invalid
DECLARE @null AS JSON = 'null'; -- invalid

DECLARE @null AS JSON = NULL; -- valid
DECLARE @object AS JSON = '{}'; -- valid
DECLARE @array AS JSON = '[]'; -- valid

Compatibilidad con funciones

Todas las funciones JSON soportan el tipo de dato json sin requerir cambios en el código.

Para obtener una lista completa de las funciones JSON, consulte Funciones JSON.

Indexes

Una columna json puede ser una columna incluida en una definición de índice, o aparecer en la WHERE cláusula de un índice filtrado. Una columna json no puede usarse como columna clave en un índice estándar.

Para obtener más información, consulte CREATE INDEX.

En Azure SQL Database, Azure SQL Managed Instance, SQL Server 2025 (17.x) y SQL database en Microsoft Fabric, puedes crear un índice JSON para optimizar consultas que acceden a valores dentro de documentos JSON.

Para obtener más información, consulte CREATE JSON INDEX.

Conversion

La conversión de json a char, nchar, varchar y nvarchar debe ser explícita. Utilice CAST o CONVERT.

La conversión de char, nchar, varchar, nvarchar y vector a json puede ser implícita o explícita. La conversión de json a vector también puede ser implícita o explícita.

No se permite la conversión entre json y todos los demás tipos de datos.

Un valor que conviertas en json debe ser un objeto JSON o un array JSON. Un escalar JSON, como 1, "abc", true, o null, causa el error 13609. Una cadena vacía también causa el error 13609. Si un objeto tiene claves duplicadas, json se queda con el primer valor y descarta los otros valores. No se produce ningún error.

La conversión de json a tipo cadena devuelve el texto JSON sin espacios en blanco insignificantes. Si la longitud objetivo es demasiado corta para el texto JSON, aparece el error 13639. El valor no está truncado.

El tipo de datos json no se puede usar con el tipo sql_variant ni asignarse a una variable o columna de sql_variant . Esta restricción es similar a los tipos de datos basados en varchar(max),varbinary(max), nvarchar(max), xml y CLR.

Puede convertir columnas existentes como varchar(max) en json mediante ALTER TABLE. De forma similar al tipo de datos xml , no se puede convertir una columna json en ninguno de los tipos binarios o de cadena mediante ALTER TABLE.

Para obtener más información, consulte Conversión de tipos de datos (motor de base de datos).

Precisión numérica

Cuando conviertes a json desde char, nchar, varchar o nvarchar, el texto JSON que contiene un número JSON puede redondearse según el formato numérico.

Si necesitas mantener la precisión, especifica el número JSON como valor decimal. De manera similar, si necesitas preservar la representación textual del documento JSON, almacena el documento JSON como un tipo de dato de cadena de caracteres.

Compatibility

Puedes usar el tipo de dato json como parámetro o tipo de retorno en una función definida por el usuario, o como parámetro de un procedimiento almacenado. El tipo json es compatible con desencadenadores y vistas.

Actualmente, el formato nativo de la herramienta bcp representa los datos json como varchar o nvarchar. Debe especificar un archivo de formato para designar una columna json .

No puedes crear un tipo de alias para el tipo de datos json con CREATE TYPE. Este comportamiento es el mismo que el tipo de datos xml .

El uso SELECT ... INTO con el tipo de datos json crea una tabla con el tipo json .

Limitations

CAST y CONVERT devuelve el tipo de dato json como se espera.

Limitaciones del controlador

El procedimiento almacenado del sistema sp_describe_first_result_set devuelve correctamente el tipo de dato json si el controlador soporta la JSONSUPPORT extensión de característica TDS. Los controladores que no soportan esta extensión ven varchar o nvarchar en su lugar.

SqlClient (>= 6.0) y JDBC (>= 13.2.0) soportan JSONSUPPORT. Por ejemplo, la última versión de SQL Server Management Studio (SSMS) utiliza el controlador más reciente de SqlClient y reporta correctamente el tipo json en los metadatos del conjunto de resultados.

• Sin JSONSUPPORT, TDS >= 7,4 (con UTF-8) informa varchar(max) con Latin1_General_100_BIN2_UTF8.
• Sin JSONSUPPORT, TDS < 7.4 informa de nvarchar(max) con la recopilación de bases de datos.

Limitaciones de tamaño

Límites de tamaño de los datos JSON en el almacenamiento:

Contenido relacionado

• Almacenamiento de documentos JSON
• Datos JSON en SQL Server