Indexation JSON

Les champs JSON constituent un moyen souple de stocker des métadonnées structurées dans Milvus. Sans indexation, les requêtes sur les champs JSON nécessitent des balayages complets de la collection, ce qui devient lent au fur et à mesure que votre ensemble de données s'accroît. L'indexation JSON permet des recherches rapides en créant des index à l'intérieur de vos données JSON.

L'indexation JSON est idéale pour

• les schémas structurés avec des clés cohérentes et connues

• Les requêtes d'égalité et de plage sur des chemins JSON spécifiques

• Scénarios dans lesquels vous avez besoin d'un contrôle précis sur les clés indexées

• Accélération efficace du stockage des requêtes ciblées

Syntaxe d'indexation JSON

Lorsque vous créez un index JSON, vous spécifiez :

• le chemin JSON: l'emplacement exact des données que vous souhaitez indexer

• Le type de distribution des données: Comment interpréter et stocker les valeurs indexées

• Conversion de type facultative: Transformer les données pendant l'indexation si nécessaire

Voici la syntaxe pour indexer un champ 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
    }
)

Paramètre	Description de la valeur	Valeur / Exemple
field_name	Le nom du champ JSON dans le schéma de la collection.	"metadata"
index_type	Doit être "AUTOINDEX" ou "INVERTED" pour l'indexation JSON.	"AUTOINDEX"
index_name	Identifiant unique pour cet index.	"category_index"
json_path	Le chemin d'accès à la clé que vous souhaitez indexer dans votre objet JSON.	Clé de premier niveau : 'metadata["category"]' Clé imbriquée : 'metadata["supplier"]["contact"]["email"]' Objet JSON entier : "metadata" Sous-objet : 'metadata["supplier"]'
json_cast_type	Le type de données à utiliser lors de l'interprétation et de l'indexation de la valeur. Il doit correspondre au type de données réel de la clé. Pour une liste des types de conversion disponibles, voir Types de conversion pris en charge ci-dessous.	"VARCHAR"
json_cast_function	(Facultatif) Convertit les valeurs de clé originales en un type cible au moment de l'indexation. Cette configuration n'est nécessaire que lorsque les valeurs des clés sont stockées dans un format incorrect et que vous souhaitez convertir le type de données lors de l'indexation. Pour obtenir une liste des fonctions de conversion disponibles, voir Fonctions de conversion prises en charge ci-dessous.	"STRING_TO_DOUBLE"

Types de conversion pris en charge

Milvus prend en charge les types de données suivants pour la conversion au moment de l'indexation. Ces types garantissent que vos données sont interprétées correctement pour un filtrage efficace.

Type de fonte	Description	Exemple Valeur JSON
BOOL / bool	Utilisé pour indexer les valeurs booléennes, permettant des requêtes qui filtrent sur des conditions vrai/faux.	true, false
DOUBLE / double	Utilisé pour les valeurs numériques, y compris les nombres entiers et les nombres à virgule flottante. Il permet de filtrer sur la base d'intervalles ou d'égalités (par exemple, >, <, ==).	42, 99.99
VARCHAR / varchar	Utilisé pour indexer les chaînes de caractères, ce qui est courant pour les données textuelles telles que les noms, les catégories ou les identifiants.	"electronics", "BrandA"
ARRAY_BOOL / array_bool	Utilisé pour indexer un tableau de valeurs booléennes.	[true, false, true]
ARRAY_DOUBLE / array_double	Permet d'indexer un tableau de valeurs numériques.	[1.2, 3.14, 42]
ARRAY_VARCHAR / array_varchar	Permet d'indexer un tableau de chaînes de caractères, ce qui est idéal pour une liste de tags ou de mots-clés.	["tag1", "tag2", "tag3"]
JSON / json	Objets ou sous-objets JSON entiers avec inférence de type et aplatissement automatiques. L'indexation d'objets JSON entiers augmente la taille de l'index. Pour les scénarios à clés multiples, envisagez le déchiquetage JSON.	Tout objet JSON

Fonctions de conversion prises en charge

Si votre clé de champ JSON contient des valeurs dans un format incorrect (par exemple, des nombres stockés sous forme de chaînes), vous pouvez transmettre une fonction de conversion à l'argument json_cast_function pour convertir ces valeurs au moment de l'indexation.

Les fonctions de conversion ne sont pas sensibles à la casse. Les fonctions suivantes sont prises en charge :

Fonction de conversion	Convertit de → en	Cas d'utilisation
STRING_TO_DOUBLE / string_to_double	Chaîne → Numérique (double)	Convertir "99.99" en 99.99

Créer des index JSON

Cette section montre comment créer des index sur différents types de données JSON à l'aide d'exemples pratiques. Tous les exemples utilisent l'exemple de structure JSON présenté ci-dessous et supposent que vous avez déjà établi une connexion à MilvusClient avec un schéma de collecte correctement défini.

Exemple de structure JSON

{
  "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"
      }
    }
  }
}

Configuration de base

Avant de créer des index JSON, préparez vos paramètres d'index :

# Prepare index params
index_params = MilvusClient.prepare_index_params()

Exemple 1 : Indexer une clé JSON simple

Créez un index sur le champ category pour permettre un filtrage rapide par catégorie de produit :

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
    }
)

Exemple 2 : Indexer une clé imbriquée

Créer un index sur le champ email profondément imbriqué pour les recherches de contacts de fournisseurs :

# 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
    }
)

Exemple 3 : Conversion du type de données au moment de l'indexation

Il arrive que des données numériques soient stockées par erreur sous forme de chaînes de caractères. Utilisez la fonction de conversion STRING_TO_DOUBLE pour les convertir et les indexer correctement :

# 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
    }
)

Important: si la conversion échoue pour un document (par exemple, une chaîne non numérique comme "invalid"), la valeur de ce document sera exclue de l'index et n'apparaîtra pas dans les résultats filtrés.

Exemple 4 : indexer des objets entiers

L'indexation d'un objet JSON complet permet d'effectuer des requêtes sur n'importe quel champ qu'il contient. Lorsque vous utilisez json_cast_type="JSON", le système procède automatiquement aux opérations suivantes

• Aplatit la structure JSON: Les objets imbriqués sont convertis en chemins plats pour une indexation efficace.

• déduit les types de données: Chaque valeur est automatiquement classée comme numérique, chaîne de caractères, booléenne ou date en fonction de son contenu.

• Création d'une couverture complète: Toutes les clés et tous les chemins imbriqués dans l'objet peuvent faire l'objet d'une recherche.

Pour l'exemple de structure JSON ci-dessus, indexez l'intégralité de l'objet 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"
    }
)

Vous pouvez également n'indexer qu'une partie de la structure JSON, par exemple toutes les informations 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"
    }
)

Appliquer la configuration de l'index

Après avoir défini tous vos paramètres d'indexation, appliquez-les à votre collection :

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

Une fois l'indexation terminée, vos requêtes sur les champs JSON utiliseront automatiquement ces index pour des performances accrues.

FAQ

Que se passe-t-il si l'expression de filtre d'une requête utilise un type différent du type de cast indexé ?

Si votre expression de filtre utilise un type différent de celui de l'index json_cast_type, Milvus n'utilisera pas l'index et pourra revenir à une analyse brute plus lente si les données le permettent. Pour des performances optimales, alignez toujours votre expression de filtre sur le type de distribution de l'index. Par exemple, si un index numérique est créé avec json_cast_type="double", seules les conditions de filtrage numériques exploiteront l'index.

Lors de la création d'un index JSON, que se passe-t-il si une clé JSON a des types de données incohérents dans différentes entités ?

Les types incohérents peuvent entraîner une indexation partielle. Par exemple, si un champ metadata["price"] est stocké à la fois sous forme de nombre (99.99) et de chaîne ("99.99") et que vous créez un index avec json_cast_type="double", seules les valeurs numériques seront indexées. Les entrées sous forme de chaîne seront ignorées et n'apparaîtront pas dans les résultats du filtre.

Puis-je créer plusieurs index sur la même clé JSON ?

Non, chaque clé JSON ne supporte qu'un seul index. Vous devez choisir un seul json_cast_type qui correspond à vos données. Toutefois, vous pouvez créer un index sur l'ensemble de l'objet JSON et un index sur une clé imbriquée dans cet objet.

Un champ JSON permet-il de définir une valeur par défaut ?

Non, les champs JSON ne prennent pas en charge les valeurs par défaut. Toutefois, vous pouvez définir nullable=True lors de la définition du champ pour autoriser les entrées vides. Pour plus d'informations, voir Nullable & Default.