Indexación JSON

Los campos JSON proporcionan una forma flexible de almacenar metadatos estructurados en Milvus. Sin indexación, las consultas en campos JSON requieren escaneos completos de la colección, que se vuelven lentos a medida que crece su conjunto de datos. La indexación JSON permite búsquedas rápidas mediante la creación de índices dentro de sus datos JSON.

La indexación JSON es ideal para:

• esquemas estructurados con claves coherentes y conocidas

• Consultas de igualdad y rango en rutas JSON específicas

• Escenarios en los que se necesita un control preciso sobre qué claves se indexan

• Aceleración eficiente del almacenamiento de consultas específicas

Sintaxis de indexación JSON

Cuando se crea un índice JSON, se especifica

• Ruta JSON: La ubicación exacta de los datos que desea indexar

• Tipo de reparto de datos: Cómo interpretar y almacenar los valores indexados

• Conversión de tipos opcional: Transformar los datos durante la indexación si es necesario

Esta es la sintaxis para indexar un campo JSON:

# Prepare index params
index_params = MilvusClient.prepare_index_params()

index_params.add_index(
    field_name="<json_field_name>",  # Name of the JSON field
    index_type="AUTOINDEX",  # Must be AUTOINDEX or INVERTED
    index_name="<unique_index_name>",  # Index name
    params={
        "json_path": "<path_to_json_key>",  # Specific key to be indexed within JSON data
        "json_cast_type": "<data_type>",  # Data type to use when interpreting and indexing the value
        # "json_cast_function": "<cast_function>"  # Optional: convert key values into a target type at index time
    }
)

Parámetro	Descripción	Valor / Ejemplo
field_name	El nombre de su campo JSON en el esquema de la colección.	"metadata"
index_type	Debe ser "AUTOINDEX" o "INVERTED" para la indexación JSON.	"AUTOINDEX"
index_name	Identificador único para este índice.	"category_index"
json_path	La ruta a la clave que desea indexar dentro de su objeto JSON.	Clave de nivel superior: 'metadata["category"]' Clave anidada: 'metadata["supplier"]["contact"]["email"]' Todo el objeto JSON: "metadata" Subobjeto: 'metadata["supplier"]'
json_cast_type	El tipo de datos que se utilizará al interpretar e indexar el valor. Debe coincidir con el tipo de datos real de la clave. Para obtener una lista de los tipos de conversión disponibles, consulte Tipos de conversión admitidos más abajo.	"VARCHAR"
json_cast_function	(Opcional) Convierte los valores de clave originales a un tipo de destino en el momento de la indexación. Esta configuración sólo es necesaria cuando los valores clave se almacenan en un formato incorrecto y se desea convertir el tipo de datos durante la indexación. Para obtener una lista de las funciones de conversión disponibles, consulte Funciones de conversión admitidas a continuación.	"STRING_TO_DOUBLE"

Tipos de conversión soportados

Milvus admite los siguientes tipos de datos para la conversión en el momento de la indexación. Estos tipos aseguran que sus datos se interpretan correctamente para un filtrado eficiente.

Tipo de conversión	Descripción	Ejemplo Valor JSON
BOOL / bool	Utilizado para indexar valores booleanos, permitiendo consultas que filtran en condiciones verdadero/falso.	true, false
DOUBLE / double	Se utiliza para valores numéricos, tanto enteros como de coma flotante. Permite el filtrado basado en rangos o igualdades (por ejemplo, >, <, ==).	42, 99.99
VARCHAR / varchar	Se utiliza para indexar valores de cadena, lo que es habitual para datos basados en texto como nombres, categorías o ID.	"electronics", "BrandA"
ARRAY_BOOL / array_bool	Se utiliza para indexar una matriz de valores booleanos.	[true, false, true]
ARRAY_DOUBLE / array_double	Se utiliza para indexar una matriz de valores numéricos.	[1.2, 3.14, 42]
ARRAY_VARCHAR / array_varchar	Sirve para indexar una matriz de cadenas, ideal para una lista de etiquetas o palabras clave.	["tag1", "tag2", "tag3"]
JSON / json	Objetos JSON enteros o subobjetos con inferencia automática de tipos y aplanamiento. La indexación de objetos JSON completos aumenta el tamaño del índice. Para escenarios con muchas claves, considere JSON Shredding.	Cualquier objeto JSON

Funciones cast admitidas

Si su clave de campo JSON contiene valores en un formato incorrecto (por ejemplo, números almacenados como cadenas), puede pasar una función de conversión al argumento json_cast_function para convertir estos valores en el momento de la indexación.

Las funciones de conversión no distinguen entre mayúsculas y minúsculas. Se admiten las siguientes funciones:

Función Cast	Convierte De → A	Caso de uso
STRING_TO_DOUBLE / string_to_double	Cadena → Numérico (doble)	Convierte "99.99" a 99.99

Crear índices JSON

Esta sección muestra cómo crear índices en diferentes tipos de datos JSON mediante ejemplos prácticos. Todos los ejemplos utilizan la estructura JSON de muestra que se muestra a continuación y suponen que ya ha establecido una conexión con MilvusClient con un esquema de colección correctamente definido.

Estructura JSON de muestra

{
  "metadata": { 
    "category": "electronics",
    "brand": "BrandA",
    "in_stock": true,
    "price": 99.99,
    "string_price": "99.99",
    "tags": ["clearance", "summer_sale"],
    "supplier": {
      "name": "SupplierX",
      "country": "USA",
      "contact": {
        "email": "support@supplierx.com",
        "phone": "+1-800-555-0199"
      }
    }
  }
}

Configuración básica

Antes de crear cualquier índice JSON, prepare sus parámetros de índice:

# Prepare index params
index_params = MilvusClient.prepare_index_params()

Ejemplo 1: Indexar una clave JSON simple

Cree un índice en el campo category para permitir un filtrado rápido por categoría de producto:

index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", # Must be set to AUTOINDEX or INVERTED for JSON path indexing
    index_name="category_index",  # Unique index name
    params={
        "json_path": 'metadata["category"]', # Path to the JSON key
        "json_cast_type": "varchar" # Data cast type
    }
)

Ejemplo 2: Indexar una clave anidada

Cree un índice en el campo email anidado profundamente para realizar búsquedas de contactos de proveedores:

# Index the nested key
index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", # Must be set to AUTOINDEX or INVERTED for JSON path indexing
    index_name="email_index", # Unique index name
    params={
        "json_path": 'metadata["supplier"]["contact"]["email"]', # Path to the nested JSON key
        "json_cast_type": "varchar" # Data cast type
    }
)

Ejemplo 3: Convertir el tipo de datos en el índice

A veces, los datos numéricos se almacenan erróneamente como cadenas. Utilice la función de conversión STRING_TO_DOUBLE para convertirlos e indexarlos correctamente:

# Convert string numbers to double for indexing
index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", # Must be set to AUTOINDEX or INVERTED for JSON path indexing
    index_name="string_to_double_index", # Unique index name
    params={
        "json_path": 'metadata["string_price"]', # Path to the JSON key to be indexed
        "json_cast_type": "double", # Data cast type
        "json_cast_function": "STRING_TO_DOUBLE" # Cast function; case insensitive
    }
)

Importante: Si la conversión falla para algún documento (por ejemplo, una cadena no numérica como "invalid"), el valor de ese documento se excluirá del índice y no aparecerá en los resultados filtrados.

Ejemplo 4: Indexar objetos completos

Indexe el objeto JSON completo para poder realizar consultas en cualquier campo que contenga. Cuando se utiliza json_cast_type="JSON", el sistema automáticamente

• Aplana la estructura JSON: Los objetos anidados se convierten en rutas planas para una indexación eficaz.

• Infiere los tipos de datos: Cada valor se clasifica automáticamente como numérico, cadena, booleano o fecha en función de su contenido.

• Crea una cobertura completa: Se pueden buscar todas las claves y rutas anidadas del objeto.

Para el ejemplo de estructura JSON anterior, indexe todo el objeto metadata:

# Index the entire JSON object
index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX",
    index_name="metadata_full_index",
    params={
        "json_path": "metadata",
        "json_cast_type": "JSON"
    }
)

También puede indexar sólo una parte de la estructura JSON, por ejemplo, toda la información de supplier:

# Index a sub-object
index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", 
    index_name="supplier_index",
    params={
        "json_path": 'metadata["supplier"]',
        "json_cast_type": "JSON"
    }
)

Aplicar la configuración del índice

Una vez definidos todos los parámetros del índice, aplíquelos a la colección:

# Apply all index configurations to the collection
MilvusClient.create_index(
    collection_name="your_collection_name",
    index_params=index_params
)

Una vez finalizada la indexación, tus consultas de campos JSON utilizarán automáticamente estos índices para obtener un rendimiento más rápido.

PREGUNTAS FRECUENTES

¿Qué ocurre si la expresión de filtro de una consulta utiliza un tipo diferente del tipo de molde indexado?

Si su expresión de filtro utiliza un tipo diferente al del índice json_cast_type, Milvus no utilizará el índice y puede recurrir a un escaneo de fuerza bruta más lento si los datos lo permiten. Para un mejor rendimiento, alinee siempre su expresión de filtro con el tipo de molde del índice. Por ejemplo, si se crea un índice numérico con json_cast_type="double", sólo las condiciones de filtro numéricas aprovecharán el índice.

Al crear un índice JSON, ¿qué ocurre si una clave JSON tiene tipos de datos incoherentes en diferentes entidades?

Los tipos incoherentes pueden dar lugar a una indexación parcial. Por ejemplo, si un campo metadata["price"] se almacena como número (99.99) y como cadena ("99.99") y se crea un índice con json_cast_type="double", sólo se indexarán los valores numéricos. Las entradas en forma de cadena se omitirán y no aparecerán en los resultados del filtro.

¿Puedo crear varios índices sobre la misma clave JSON?

No, cada clave JSON sólo admite un índice. Debe elegir un único json_cast_type que coincida con sus datos. Sin embargo, puede crear un índice en todo el objeto JSON y un índice en una clave anidada dentro de ese objeto.

¿Es posible establecer un valor por defecto en un campo JSON?

No, los campos JSON no admiten valores por defecto. Sin embargo, puede establecer nullable=True al definir el campo para permitir entradas vacías. Para más información, consulte Nullable & Default.