JSON-Indizierung

JSON-Felder bieten eine flexible Möglichkeit zur Speicherung strukturierter Metadaten in Milvus. Ohne Indizierung erfordern Abfragen von JSON-Feldern Scans der gesamten Kollektion, die mit wachsendem Datenbestand langsam werden. Die JSON-Indizierung ermöglicht schnelle Abfragen durch die Erstellung von Indizes in Ihren JSON-Daten.

JSON-Indizierung ist ideal für:

• Strukturierte Schemata mit konsistenten, bekannten Schlüsseln

• Gleichheits- und Bereichsabfragen auf bestimmten JSON-Pfaden

• Szenarien, in denen Sie genau steuern müssen, welche Schlüssel indiziert werden

• Speichereffiziente Beschleunigung von gezielten Abfragen

JSON-Indizierungssyntax

Wenn Sie einen JSON-Index erstellen, geben Sie an:

• JSON-Pfad: Den genauen Ort der Daten, die Sie indizieren möchten

• Typ der Datenaufbereitung: Wie die indizierten Werte zu interpretieren und zu speichern sind

• Optionale Typkonvertierung: Daten während der Indizierung umwandeln, falls erforderlich

Hier ist die Syntax für die Indizierung eines JSON-Feldes:

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

Parameter	Beschreibung	Wert / Beispiel
field_name	Der Name Ihres JSON-Feldes im Sammlungsschema.	"metadata"
index_type	Muss "AUTOINDEX" oder "INVERTED" für JSON-Indizierung sein.	"AUTOINDEX"
index_name	Eindeutiger Bezeichner für diesen Index.	"category_index"
json_path	Der Pfad zu dem Schlüssel, den Sie innerhalb Ihres JSON-Objekts indizieren möchten.	Schlüssel der obersten Ebene: 'metadata["category"]' Verschachtelter Schlüssel: 'metadata["supplier"]["contact"]["email"]' Ganzes JSON-Objekt: "metadata" Unter-Objekt: 'metadata["supplier"]'
json_cast_type	Der Datentyp, der bei der Interpretation und Indizierung des Wertes verwendet werden soll. Muss mit dem tatsächlichen Datentyp des Schlüssels übereinstimmen. Eine Liste der verfügbaren Cast-Typen finden Sie unter Unterstützte Cast-Typen unten.	"VARCHAR"
json_cast_function	(Optional) Konvertiert die ursprünglichen Schlüsselwerte zum Zeitpunkt der Indexierung in einen Zieltyp. Diese Konfiguration ist nur erforderlich, wenn Schlüsselwerte in einem falschen Format gespeichert sind und Sie den Datentyp während der Indizierung konvertieren möchten. Eine Liste der verfügbaren Cast-Funktionen finden Sie unter Unterstützte Cast-Funktionen weiter unten.	"STRING_TO_DOUBLE"

Unterstützte Cast-Typen

Milvus unterstützt die folgenden Datentypen für das Casting zur Indexierungszeit. Diese Typen stellen sicher, dass Ihre Daten für eine effiziente Filterung korrekt interpretiert werden.

Cast-Typ	Beschreibung	Beispiel JSON-Wert
BOOL / bool	Wird verwendet, um boolesche Werte zu indizieren und Abfragen zu ermöglichen, die nach wahr/falsch-Bedingungen filtern.	true, false
DOUBLE / double	Wird für numerische Werte verwendet, einschließlich ganzer Zahlen und Gleitkommazahlen. Sie ermöglicht die Filterung auf der Grundlage von Bereichen oder Gleichheit (z. B. >, <, ==).	42, 99.99
VARCHAR / varchar	Wird für die Indizierung von String-Werten verwendet, was für textbasierte Daten wie Namen, Kategorien oder IDs üblich ist.	"electronics", "BrandA"
ARRAY_BOOL / array_bool	Wird verwendet, um ein Array mit booleschen Werten zu indizieren.	[true, false, true]
ARRAY_DOUBLE / array_double	Wird verwendet, um ein Array mit numerischen Werten zu indizieren.	[1.2, 3.14, 42]
ARRAY_VARCHAR / array_varchar	Dient zur Indizierung eines Arrays von Strings, was ideal für eine Liste von Tags oder Schlüsselwörtern ist.	["tag1", "tag2", "tag3"]
JSON / json	Ganze JSON-Objekte oder Unterobjekte mit automatischer Typinferenz und Flattening. Die Indizierung ganzer JSON-Objekte erhöht die Indexgröße. Für Szenarien mit vielen Schlüsseln empfiehlt sich JSON Shredding.	Jedes JSON-Objekt

Unterstützte Cast-Funktionen

Wenn Ihr JSON-Feldschlüssel Werte in einem falschen Format enthält (z. B. Zahlen, die als Strings gespeichert sind), können Sie eine Cast-Funktion an das Argument json_cast_function übergeben, um diese Werte zum Zeitpunkt der Indexierung zu konvertieren.

Bei Cast-Funktionen wird die Groß- und Kleinschreibung nicht berücksichtigt. Die folgenden Funktionen werden unterstützt:

Cast-Funktion	Konvertiert von → nach	Anwendungsfall
STRING_TO_DOUBLE / string_to_double	String → Numerisch (double)	Konvertiert "99.99" in 99.99

JSON-Indizes erstellen

In diesem Abschnitt wird anhand von praktischen Beispielen gezeigt, wie Indizes für verschiedene Arten von JSON-Daten erstellt werden können. Alle Beispiele verwenden die unten gezeigte Beispiel-JSON-Struktur und gehen davon aus, dass Sie bereits eine Verbindung zu MilvusClient mit einem ordnungsgemäß definierten Sammelschema hergestellt haben.

Beispiel-JSON-Struktur

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

Grundlegende Einrichtung

Bevor Sie JSON-Indizes erstellen, bereiten Sie Ihre Indexparameter vor:

# Prepare index params
index_params = MilvusClient.prepare_index_params()

Beispiel 1: Index für einen einfachen JSON-Schlüssel

Erstellen Sie einen Index für das Feld category, um eine schnelle Filterung nach Produktkategorie zu ermöglichen:

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

Beispiel 2: Index für einen verschachtelten Schlüssel

Erstellen Sie einen Index für das tief verschachtelte Feld email für die Suche nach Lieferantenkontakten:

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

Beispiel 3: Datentyp zur Indexzeit konvertieren

Manchmal werden numerische Daten fälschlicherweise als Zeichenketten gespeichert. Verwenden Sie die Funktion STRING_TO_DOUBLE cast, um sie richtig zu konvertieren und zu indizieren:

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

Wichtig: Wenn die Konvertierung für ein Dokument fehlschlägt (z. B. für eine nicht numerische Zeichenkette wie "invalid"), wird der Wert dieses Dokuments aus dem Index ausgeschlossen und erscheint nicht in den gefilterten Ergebnissen.

Beispiel 4: Ganze Objekte indizieren

Indizieren Sie das gesamte JSON-Objekt, um Abfragen auf jedes Feld darin zu ermöglichen. Wenn Sie json_cast_type="JSON" verwenden, wird das System automatisch:

• Verflacht die JSON-Struktur: Verschachtelte Objekte werden für eine effiziente Indizierung in flache Pfade umgewandelt.

• Ermittelt Datentypen: Jeder Wert wird auf der Grundlage seines Inhalts automatisch als numerisch, String, boolesch oder Datum kategorisiert.

• Erzeugt eine umfassende Abdeckung: Alle Schlüssel und verschachtelten Pfade innerhalb des Objekts werden durchsuchbar

Für die obige JSON-Beispielstruktur indizieren Sie das gesamte Objekt 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"
    }
)

Sie können auch nur einen Teil der JSON-Struktur indizieren, z. B. alle supplier Informationen:

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

Anwenden der Indexkonfiguration

Nachdem Sie alle Indexparameter definiert haben, wenden Sie sie auf Ihre Sammlung an:

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

Sobald die Indizierung abgeschlossen ist, werden Ihre JSON-Feldabfragen automatisch diese Indizes verwenden, um die Leistung zu steigern.

FAQ

Was passiert, wenn der Filterausdruck einer Abfrage einen anderen Typ verwendet als der indizierte Cast-Typ?

Wenn Ihr Filterausdruck einen anderen Typ verwendet als der Index json_cast_type, wird Milvus den Index nicht verwenden und kann auf einen langsameren Brute-Force-Scan zurückgreifen, wenn die Daten dies zulassen. Um die beste Leistung zu erzielen, sollten Sie Ihren Filterausdruck immer an den Cast-Typ des Indexes anpassen. Wenn zum Beispiel ein numerischer Index mit json_cast_type="double" erstellt wird, werden nur numerische Filterbedingungen den Index nutzen.

Was passiert bei der Erstellung eines JSON-Index, wenn ein JSON-Schlüssel inkonsistente Datentypen für verschiedene Entitäten aufweist?

Inkonsistente Typen können zu einer teilweisen Indizierung führen. Wenn zum Beispiel ein Feld metadata["price"] sowohl als Zahl (99.99) als auch als Zeichenkette ("99.99") gespeichert ist und Sie einen Index mit json_cast_type="double" erstellen, werden nur die numerischen Werte indiziert. Die Einträge in String-Form werden übersprungen und erscheinen nicht in den Filterergebnissen.

Kann ich mehrere Indizes für denselben JSON-Schlüssel erstellen?

Nein, jeder JSON-Schlüssel unterstützt nur einen Index. Sie müssen einen einzigen json_cast_type wählen, der Ihren Daten entspricht. Sie können jedoch einen Index für das gesamte JSON-Objekt und einen Index für einen verschachtelten Schlüssel innerhalb dieses Objekts erstellen.

Unterstützt ein JSON-Feld die Festlegung eines Standardwerts?

Nein, JSON-Felder unterstützen keine Standardwerte. Sie können jedoch nullable=True festlegen, wenn Sie das Feld definieren, um leere Einträge zuzulassen. Weitere Informationen finden Sie unter Nullable & Default.