CREAR ÍNDICE JSON (Transact-SQL)

Se aplica a: VERSIÓN PRELIMINAR de SQL Server 2025 (17.x)

Crea un índice JSON en una tabla y columna especificadas en la versión preliminar de SQL Server 2025 (17.x).

Índices JSON:

• Se puede crear antes de que haya datos en la tabla.
• Se puede crear en tablas de otra base de datos especificando un nombre de base de datos calificado.
• Requerir que la tabla tenga una clave principal en clúster.
• No se puede especificar en vistas indexadas.

Convenciones de sintaxis de Transact-SQL

Sintaxis

CREATE JSON INDEX name ON table_name (json_column_name)
  [ FOR ( sql_json_path [ , ...n ] ) ]
  [ WITH ( <json_index_option> [ , ...n ] ) ]
  [ ON { filegroup_name | "default" } ]
[ ; ]

<object> ::=
    { database_name.schema_name.table_name | schema_name.table_name | table_name }

<sql_json_path> ::=
    { character_string_literal }

<json_index_option> ::=
{
    FILLFACTOR = fillfactor
  | DROP_EXISTING = { ON | OFF }
  | ONLINE = OFF
  | ALLOW_ROW_LOCKS = { ON | OFF }
  | ALLOW_PAGE_LOCKS = { ON | OFF }
  | MAXDOP = max_degree_of_parallelism
  | DATA_COMPRESSION = { NONE | ROW | PAGE }
}

Argumentos

nombre_del_indice

El nombre del índice. Los nombres de índice deben ser únicos dentro de una tabla, pero no tienen que ser únicos dentro de una base de datos. Los nombres de índice deben seguir las reglas de identificadores.

• EN <objeto> (json_column_name)

  Especifica el objeto (base de datos, esquema o tabla) en el que se va a crear el índice y el nombre de la columna json .

• json_column_name

  Nombre de la columna del tipo de datos json en table_name que contiene cero o más de las rutas de acceso SQL/JSON especificadas.

• sql_json_path

  Ruta de acceso SQL/JSON que debe extraerse e indexarse de json_column_name. El valor predeterminado para sql_json_path es $.

  • Indexa de forma recursiva todas las claves y valores desde la ruta especificada en adelante.
  • Admite hasta 128 niveles en la ruta de acceso al documento JSON.
  • No permite la superposición.

  Por ejemplo, $.a y $.a.b genera un error, ya que la ruta de acceso $.a incluye de forma recursiva todas las rutas de acceso y la intención del usuario no está clara.

ON filegroup_name

Crea el índice especificado en el grupo de archivos especificado. Si no se especifica ninguna ubicación y la tabla no tiene particiones, el índice usa el mismo grupo de archivos que la tabla subyacente. El grupo de archivos ya debe existir.

ACTIVADO "predeterminado"

Crea el índice especificado en el grupo de archivos predeterminado.

El término predeterminado, en este contexto, no es una palabra clave. Es un identificador para el grupo de archivos predeterminado y debe delimitarse, como en ON "default" o ON [default]. Si "default" se especifica , la QUOTED_IDENTIFIER opción debe ser ON para la sesión actual. Esta es la configuración predeterminada. Para más información, consulte SET QUOTED_IDENTIFIER.

<objeto>:: =

Objeto totalmente calificado o no calificado que se va a indexar.

• database_name

  El nombre de la base de datos.

• schema_name

  El nombre del esquema al que pertenece la tabla.

• table_name

  Nombre de la tabla que se va a indexar.

FILLFACTOR = fillfactor

Especifica un porcentaje que indica cuánto debe llenar el Motor de base de datos el nivel hoja de cada página de índice durante la creación o nueva generación de los índices. fillfactor debe ser un valor entero de 1 a 100. El valor predeterminado es 0. Si fillfactor es 100 o 0, el Motor de Base de Datos crea índices con páginas hoja completamente llenas.

La configuración de FILLFACTOR solo se aplica cuando se crea o se vuelve a generar el índice. El motor de base de datos no mantiene dinámicamente el porcentaje especificado de espacio disponible de las páginas. Para ver la configuración del factor de relleno, use la vista de catálogo sys.indexes .

Crear un índice agrupado con menos FILLFACTOR de lo que 100 afecta a la cantidad de espacio de almacenamiento que ocupan los datos, ya que el motor de base de datos redistribuye los datos cuando crea el índice agrupado.

Para obtener más información, vea Especificar el factor de relleno para un índice.

DROP_EXISTING = { ON | OFF }

Especifica que el índice espacial preexistente con nombre se elimina y se reconstruye. El valor predeterminado es OFF.

• Encendido

  El índice existente se elimina y se reconstruye. El nombre de índice especificado debe ser el mismo que un índice existente actualmente; sin embargo, se puede modificar la definición del índice. Por ejemplo, puede especificar diferentes columnas, criterio de ordenación, esquema de partición o opciones de índice.

• APAGADO

  Se muestra un error si el nombre de índice especificado ya existe.

El tipo de índice no se puede cambiar mediante DROP_EXISTING.

ONLINE = APAGADO

Especifica que las tablas subyacentes y los índices asociados no están disponibles para las consultas y la modificación de datos durante la operación de índice. En esta versión de SQL Server, las compilaciones de índices en línea no se admiten para los índices JSON. Si esta opción se establece ON en para un índice JSON, se genera un error. Omita la ONLINE opción o establezca en ONLINEOFF.

Una operación de índice sin conexión que crea, vuelve a generar o quita un índice JSON, adquiere un bloqueo de modificación de esquema (Sch-M) en la tabla. Esto evita que todos los usuarios tengan acceso a la tabla subyacente durante la operación.

Las operaciones de índice en línea no están disponibles en todas las ediciones de SQL Server.

Para obtener una lista de las características admitidas por ediciones de SQL Server en Windows, vea:

• Ediciones y características admitidas de SQL Server 2025 Preview
• Ediciones y características admitidas de SQL Server 2022
• Ediciones y características admitidas de SQL Server 2019
• Ediciones y las características admitidas de SQL Server 2017
• Ediciones y las características admitidas de SQL Server 2016

ALLOW_ROW_LOCKS = { ON | OFF }

Especifica si se permiten bloqueos de fila. El valor predeterminado es ON.

• Encendido

  Los bloqueos de fila se admiten al obtener acceso al índice. El Motor de base de datos determina cuándo se usan los bloqueos de fila.

• APAGADO

  No se usan bloqueos de fila.

ALLOW_PAGE_LOCKS = { ON | OFF }

Especifica si se permiten bloqueos de página. El valor predeterminado es ON.

• Encendido

  Los bloqueos de página se permiten al obtener acceso al índice. Motor de base de datos determina el momento en que se usan los bloqueos de página.

• APAGADO

  No se usan bloqueos de página.

MAXDOP = max_degree_of_parallelism

Invalida la max degree of parallelism opción de configuración durante la operación de índice. Use MAXDOP para limitar el número de procesadores usados en una ejecución de plan paralelo. El máximo es de 64 procesadores.

max_degree_of_parallelism puede ser uno de los siguientes valores.

Para obtener más información, vea Configurar operaciones de índice en paralelo.

Las operaciones de índices en paralelo no están disponibles en todas las ediciones de SQL Server.

Para obtener una lista de las características admitidas por ediciones de SQL Server en Windows, vea:

• Ediciones y características admitidas de SQL Server 2025 Preview
• Ediciones y características admitidas de SQL Server 2022
• Ediciones y características admitidas de SQL Server 2019
• Ediciones y las características admitidas de SQL Server 2017
• Ediciones y las características admitidas de SQL Server 2016

DATA_COMPRESSION = { NONE | ROW | PAGE }

Determina el nivel de compresión de datos utilizado por el índice.

• NINGUNO

  No se utiliza compresión en los datos del índice

• ROW

  Compresión de fila utilizada por el índice en los datos

• PÁGINA

  Compresión de página utilizada en los datos por el índice

Observaciones

Cada opción solo se puede especificar una vez por CREATE JSON INDEX instrucción. Al especificar un duplicado de cualquier opción, se produce un error.

[ ON { filegroup_name | "default" } ]

Si especifica un grupo de archivos para un índice JSON, el índice se coloca en ese grupo de archivos, independientemente del esquema de partición de la tabla.

Para obtener más información sobre cómo crear índices, vea la sección Comentarios de CREATE INDEX.

Predicados compatibles con un índice JSON

Las operaciones de búsqueda en documentos JSON contenidos en una columna json de una tabla se pueden optimizar si existe un índice JSON en la columna json . El índice JSON se usa en consultas con varias expresiones basadas en funciones JSON.

En los ejemplos siguientes se usa la Sales.SalesOrderHeader tabla de la AdventureWorks2022 base de datos con una columna json denominada Info. La Info columna se crea como un tipo json . También se crea un índice JSON en la Info columna con la configuración predeterminada. En el ejemplo de código siguiente se muestra la CREATE JSON INDEX instrucción :

CREATE JSON INDEX sales_info_idx ON Sales.SalesOrderHeader(Info);

Para las expresiones de búsqueda de ejemplo, use los siguientes documentos JSON como datos:

función JSON_PATH_EXISTS

Use la función JSON_PATH_EXISTS para probar si existe una ruta de acceso SQL/JSON especificada en un documento JSON.

Esta consulta demuestra JSON_PATH_EXISTS en una columna json que se puede optimizar mediante un índice JSON.

SELECT COUNT(*)
FROM Sales.SalesOrderHeader
WHERE JSON_PATH_EXISTS(Info, '$.Order.IsProcessed') = 1;

El índice JSON se admite junto al predicado JSON_PATH_EXISTS y los siguientes operadores:

• Operadores de comparación (=)
• IS [NOT] NULL predicado (no admitido actualmente)

función JSON_VALUE

Utilice JSON_VALUE para extraer el valor escalar o texto JSON en una ruta de acceso SQL/JSON especificada en un documento JSON. Las consultas siguientes muestran cómo se puede optimizar una JSON_VALUE expresión en una columna json mediante un índice JSON.

• Búsqueda de igualdad de una cadena JSON en una propiedad de objeto:

  SELECT COUNT(*)
  FROM Sales.SalesOrderHeader
  WHERE JSON_VALUE(Info, '$.Customer.Type') = 'IN';
  

• Búsqueda de igualdad de un número JSON en una propiedad de objeto después de convertir el valor en un tipo de datos int :

  SELECT *
  FROM Sales.SalesOrderHeader
  WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) = 16167;
  

• Busque un número JSON en una propiedad de objeto después de convertir el valor en un tipo de datos int :

  SELECT *
  FROM Sales.SalesOrderHeader
  WHERE JSON_VALUE(Info, '$.Customer.ID' RETURNING INT) IN (16167, 16517);
  

• Busque un número JSON en una propiedad de objeto después de convertir el valor en un tipo de datos decimal :

  SELECT *
  FROM Sales.SalesOrderHeader
  WHERE JSON_VALUE(Info, '$.Order.TotalDue RETURNING decimal(20, 4)) BETWEEN 1000 and 2000;
  

El índice JSON se admite usando un JSON_VALUE predicado y los operadores siguientes:

• Operadores de comparación (=)
• LIKE predicado (no admitido actualmente)
• IS [NOT] NULL predicado (no admitido actualmente)

función JSON_CONTAINS

La función JSON_CONTAINS admite la búsqueda sencilla de valores JSON en un documento JSON que puede usar un índice JSON si está presente en una columna json . Esta función se puede usar para probar si un valor escalar JSON, un objeto o una matriz se encuentra en la ruta de acceso SQL/JSON especificada en un documento JSON. Los valores de búsqueda especificados como tipos escalares de SQL se convierten según las conversiones de tipos SQL/JSON existentes. Estas reglas se definen en la sección de comportamiento.

Requisito

Se requiere una clave de agrupación en clústeres en la tabla que contiene la columna JSON. Se produce un error si la clave de agrupación en clústeres está ausente. La clave de agrupación en clústeres está limitada a 31 columnas y el tamaño máximo de la clave de índice debe ser inferior a 128 bytes.

Permisos

El usuario debe tener permiso ALTER en la tabla, o ser miembro del rol fijo de servidor sysadmin, o de los roles fijos de base de datos db_ddladmin y db_owner.

Limitaciones

Existen las siguientes limitaciones para la instrucción de índice JSON:

• Solo se puede crear un índice JSON en una columna json de una tabla.
• Puede crear hasta 249 índices JSON en una tabla. No se admite la creación de más de un índice JSON en una columna JSON específica.
• No se puede crear un índice JSON en columnas json calculadas.
• No se puede crear un índice JSON en columnas json en una vista, una variable con valores de tabla o una tabla optimizada para memoria.
• Un índice JSON solo se puede crear o modificar de forma sin conexión.
• Las rutas de acceso JSON no se pueden superponer en la definición del índice. Por ejemplo, $a y $a.b se superponen y no se permiten en la declaración CREATE JSON INDEX.
• La modificación de rutas de acceso requiere volver a crear el índice JSON.
• Los índices JSON no se admiten en sugerencias de índice.
• No se admite la opción de compresión de datos.

Ejemplos

Un. Creación de un índice JSON en una columna JSON

En el ejemplo siguiente se crea una tabla denominada docs que contiene una columna de tipo json , content. A continuación, el ejemplo crea un índice JSON, json_content_index, en la content columna . En el ejemplo se crea el índice json en todo el documento JSON o en todas las rutas de acceso SQL/JSON del documento JSON.

DROP TABLE IF EXISTS docs;

CREATE TABLE docs (content JSON, id INT PRIMARY KEY);
CREATE JSON INDEX json_content_index ON docs(content);

Un. Creación de un índice JSON en una columna JSON con rutas de acceso específicas

En el ejemplo siguiente se crea una tabla denominada docs que contiene una columna de tipo json , content. A continuación, el ejemplo crea un índice JSON, json_content_index, en la content columna . En el ejemplo se crea el índice json en rutas de acceso SQL/JSON específicas en el documento JSON.
En el ejemplo también se establece el índice FILLFACTOR en 80.

DROP TABLE IF EXISTS docs;

CREATE TABLE docs (content JSON, id INT PRIMARY KEY);

CREATE JSON INDEX json_content_index
    ON docs(content) FOR ('$.a', '$.b')
    WITH (FILLFACTOR = 80);

Contenido relacionado

• DROP INDEX (Transact-SQL)
• Datos JSON en SQL Server
• EVENTDATA (Transact-SQL)
• sys.index_columns (Transact-SQL)
• sys.indexes (Transact-SQL)