Indicizzazione JSON

I campi JSON offrono un modo flessibile per memorizzare metadati strutturati in Milvus. Senza indicizzazione, le interrogazioni sui campi JSON richiedono la scansione dell'intera collezione, che diventa lenta con la crescita del set di dati. L'indicizzazione JSON consente di effettuare ricerche rapide creando indici all'interno dei dati JSON.

L'indicizzazione JSON è ideale per:

• Schemi strutturati con chiavi coerenti e note

• Query di uguaglianza e di intervallo su percorsi JSON specifici

• scenari in cui è necessario un controllo preciso sulle chiavi indicizzate

• Accelerazione efficiente in termini di storage di query mirate

Sintassi dell'indicizzazione JSON

Quando si crea un indice JSON, si specifica:

• Percorso JSON: La posizione esatta dei dati che si desidera indicizzare.

• Tipo di cast dei dati: Come interpretare e memorizzare i valori indicizzati

• Conversione di tipo opzionale: Trasformare i dati durante l'indicizzazione, se necessario

Ecco la sintassi per indicizzare 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
    }
)

Parametro	Descrizione	Valore / Esempio
field_name	Il nome del campo JSON nello schema della raccolta.	"metadata"
index_type	Deve essere "AUTOINDEX" o "INVERTED" per l'indicizzazione JSON.	"AUTOINDEX"
index_name	Identificatore univoco per questo indice.	"category_index"
json_path	Il percorso della chiave che si vuole indicizzare nell'oggetto JSON.	Chiave di primo livello: 'metadata["category"]' Chiave annidata: 'metadata["supplier"]["contact"]["email"]' Intero oggetto JSON: "metadata" Sotto-oggetto: 'metadata["supplier"]'
json_cast_type	Il tipo di dati da usare per interpretare e indicizzare il valore. Deve corrispondere al tipo di dati effettivo della chiave. Per un elenco dei tipi di cast disponibili, vedere Tipi di cast supportati di seguito.	"VARCHAR"
json_cast_function	(Facoltativo) Converte i valori originali della chiave in un tipo di destinazione al momento dell'indicizzazione. Questa configurazione è necessaria solo quando i valori delle chiavi sono memorizzati in un formato errato e si desidera convertire il tipo di dati durante l'indicizzazione. Per un elenco delle funzioni di cast disponibili, vedere Funzioni di cast supportate di seguito.	"STRING_TO_DOUBLE"

Tipi di cast supportati

Milvus supporta i seguenti tipi di dati per il casting al momento dell'indicizzazione. Questi tipi garantiscono la corretta interpretazione dei dati per un filtraggio efficiente.

Tipo di cast	Descrizione	Esempio di valore JSON
BOOL / bool	Utilizzato per indicizzare valori booleani, consentendo query che filtrano su condizioni di vero/falso.	true, false
DOUBLE / double	Utilizzato per i valori numerici, compresi i numeri interi e a virgola mobile. Consente di filtrare in base a intervalli o uguaglianze (ad esempio, >, <, ==).	42, 99.99
VARCHAR / varchar	Utilizzato per indicizzare valori stringa, comune per i dati basati sul testo come nomi, categorie o ID.	"electronics", "BrandA"
ARRAY_BOOL / array_bool	Utilizzato per indicizzare un array di valori booleani.	[true, false, true]
ARRAY_DOUBLE / array_double	Utilizzato per indicizzare una matrice di valori numerici.	[1.2, 3.14, 42]
ARRAY_VARCHAR / array_varchar	Utilizzato per indicizzare un array di stringhe, ideale per un elenco di tag o parole chiave.	["tag1", "tag2", "tag3"]
JSON / json	Interi oggetti o sotto-oggetti JSON con inferenza automatica del tipo e appiattimento. L'indicizzazione di interi oggetti JSON aumenta le dimensioni dell'indice. Per scenari con molte chiavi, considerare la triturazione JSON.	Qualsiasi oggetto JSON

Funzioni di cast supportate

Se la chiave del campo JSON contiene valori in un formato non corretto (ad esempio, numeri memorizzati come stringhe), è possibile passare una funzione di cast all'argomento json_cast_function per convertire questi valori al momento dell'indicizzazione.

Le funzioni di cast non fanno distinzione tra maiuscole e minuscole. Sono supportate le seguenti funzioni:

Funzione di fusione	Converte da → a	Caso d'uso
STRING_TO_DOUBLE / string_to_double	Stringa → Numerico (doppio)	Convertire "99.99" in 99.99

Creare indici JSON

Questa sezione mostra come creare indici su diversi tipi di dati JSON utilizzando esempi pratici. Tutti gli esempi utilizzano la struttura JSON di esempio mostrata di seguito e presuppongono che sia già stata stabilita una connessione a MilvusClient con uno schema di raccolta correttamente definito.

Struttura JSON di esempio

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

Impostazione di base

Prima di creare indici JSON, preparare i parametri dell'indice:

# Prepare index params
index_params = MilvusClient.prepare_index_params()

Esempio 1: indicizzare una semplice chiave JSON

Creare un indice sul campo category per consentire un filtraggio rapido per categoria di prodotto:

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

Esempio 2: indicizzare una chiave annidata

Creare un indice sul campo email profondamente annidato per la ricerca dei contatti dei fornitori:

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

Esempio 3: Convertire il tipo di dati al momento dell'indice

A volte i dati numerici vengono erroneamente memorizzati come stringhe. Utilizzare la funzione di cast di STRING_TO_DOUBLE per convertirli e indicizzarli correttamente:

# 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: se la conversione fallisce per un documento (ad esempio, una stringa non numerica come "invalid"), il valore di quel documento sarà escluso dall'indice e non apparirà nei risultati filtrati.

Esempio 4: indicizzare interi oggetti

Indicizzare l'intero oggetto JSON per consentire interrogazioni su qualsiasi campo al suo interno. Quando si utilizza json_cast_type="JSON", il sistema automaticamente:

• Appiattisce la struttura JSON: Gli oggetti annidati vengono convertiti in percorsi piatti per un'indicizzazione efficiente.

• Inferire i tipi di dati: Ogni valore viene automaticamente classificato come numerico, stringa, booleano o data in base al suo contenuto.

• Crea una copertura completa: Tutte le chiavi e i percorsi annidati all'interno dell'oggetto diventano ricercabili.

Per la struttura JSON di esempio qui sopra, indicizzare l'intero oggetto 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"
    }
)

È anche possibile indicizzare solo una parte della struttura JSON, ad esempio tutte le informazioni di 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"
    }
)

Applicare la configurazione dell'indice

Dopo aver definito tutti i parametri dell'indice, applicarli alla raccolta:

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

Una volta completata l'indicizzazione, le query sui campi JSON utilizzeranno automaticamente gli indici per ottenere prestazioni più veloci.

DOMANDE FREQUENTI

Cosa succede se l'espressione del filtro di una query utilizza un tipo diverso dal tipo di cast indicizzato?

Se l'espressione del filtro utilizza un tipo diverso da quello dell'indice json_cast_type, Milvus non utilizzerà l'indice e potrà tornare a una scansione bruta più lenta, se i dati lo consentono. Per ottenere prestazioni ottimali, allineare sempre l'espressione del filtro al tipo di cast dell'indice. Ad esempio, se un indice numerico viene creato con json_cast_type="double", solo le condizioni di filtro numeriche sfrutteranno l'indice.

Quando si crea un indice JSON, cosa succede se una chiave JSON ha tipi di dati incoerenti tra le diverse entità?

I tipi incoerenti possono portare a un'indicizzazione parziale. Ad esempio, se un campo metadata["price"] è memorizzato sia come numero (99.99) che come stringa ("99.99") e si crea un indice con json_cast_type="double", solo i valori numerici saranno indicizzati. Le voci in forma di stringa verranno saltate e non appariranno nei risultati dei filtri.

È possibile creare più indici sulla stessa chiave JSON?

No, ogni chiave JSON supporta un solo indice. È necessario scegliere un singolo json_cast_type che corrisponda ai dati. Tuttavia, è possibile creare un indice sull'intero oggetto JSON e un indice su una chiave nidificata all'interno di tale oggetto.

Un campo JSON supporta l'impostazione di un valore predefinito?

No, i campi JSON non supportano valori predefiniti. Tuttavia, è possibile impostare nullable=True quando si definisce il campo per consentire l'inserimento di voci vuote. Per ulteriori informazioni, consultare Nullable e Default.