Creazione di un campo StructArray

Creare un campo StructArray quando un'entità deve contenere un elenco ordinato di elementi strutturati. Un campo StructArray è un campo Array il cui tipo di elemento è Struct. Ogni elemento Struct segue lo stesso schema e può contenere sottocampi scalari, sottocampi vettoriali o entrambi.

Questa pagina illustra come definire uno schema Struct, aggiungerlo come campo StructArray, scegliere i sottocampi per la ricerca e il filtraggio successivi e comprendere le regole dello schema applicabili prima di inserire o indicizzare i dati.

Prima di iniziare

Questa pagina utilizza una raccolta denominata tech_articles. Ogni entità rappresenta un articolo tecnico e il campo chunks memorizza i dati a livello di blocco come elementi Struct.

Campo	Tipo	Scopo
doc_id	INT64	Chiave primaria dell’articolo.
title	VARCHAR	Titolo dell'articolo.
category	VARCHAR	Categoria a livello di articolo.
title_vector	FLOAT_VECTOR	Campo vettoriale a livello di articolo, utilizzato in seguito negli esempi di ricerca ibrida.
chunks	ARRAY	Campo StructArray che memorizza il testo a livello di blocco, i metadati e gli embedding.

Il campo StructArray " chunks " contiene i seguenti sottocampi.

Sottocampo	Tipo	Scopo
text	VARCHAR	Testo del chunk.
section	VARCHAR	Nome della sezione, ad esempio index, search o filter.
page	INT64	Numero di pagina o posizione logica del blocco.
quality_score	FLOAT	Punteggio a livello di blocco utilizzato negli esempi di filtraggio scalare e di intervallo.
has_code	BOOL	Se il blocco contiene codice.
emb_list_vector	FLOAT_VECTOR	Sottocampo vettoriale per la ricerca EmbeddingList con metriche MAX_SIM*.
emb	FLOAT_VECTOR	Sottocampo vettoriale per la ricerca a livello di elemento con metriche vettoriali regolari.

Tipi di dati supportati per i sottocampi

Un campo StructArray memorizza un valore di array per ciascun sottocampo Struct. Quando si definisce uno schema Struct, scegliere i tipi dei sottocampi tra le famiglie scalari e vettoriali supportate.

Tipo fisico dei sottocampi Struct	Supporto	Note
Array	Supportato	Definire il sottocampo come DataType.BOOL.
Array	Supportato	Definire il sottocampo come DataType.INT8, DataType.INT16, DataType.INT32 o DataType.INT64.
Array	Supportato	Definire il sottocampo come DataType.FLOAT o DataType.DOUBLE.
Array	Supportato	Definire il sottocampo come DataType.VARCHAR e impostare max_length.
ArrayOfVector	Supportato	Definire il sottocampo come DataType.FLOAT_VECTOR e impostare dim.
ArrayOfVector	Supportato	Definire il sottocampo come DataType.FLOAT16_VECTOR e impostare dim.
ArrayOfVector	Supportato	Definire il sottocampo come DataType.BFLOAT16_VECTOR e impostare dim.
ArrayOfVector	Supportato	Definire il sottocampo come DataType.INT8_VECTOR e impostare dim.
ArrayOfVector	Supportato	Definire il sottocampo come " DataType.BINARY_VECTOR " e impostare " dim".
ArrayOfVector	Non supportato	I sottocampi vettoriali sparsi non sono supportati nei campi StructArray.
Array	Non supportato	Utilizzare VARCHAR, non String.
Array	Non supportato	I sottocampi JSON non sono supportati nei campi StructArray.
Array	Non supportato	I sottocampi Geometry e le funzioni GIS non sono supportati nei campi StructArray.
Array	Non supportato	I sottocampi di tipo testo non sono supportati nei campi StructArray.
Array	Non supportato	I sottocampi "timestamptz" e le espressioni relative al tempo non sono supportati nei campi StructArray.
Array, ArrayOfVector, Struct o ArrayOfStruct	Non supportato	Un campo StructArray non può contenere array annidati, array vettoriali annidati, campi Struct annidati o campi Array-of-Struct annidati.

Per informazioni sul supporto specifico per versione, sul comportamento dei valori null e su altri limiti, vedere Limiti di StructArray.

Creazione di una raccolta con un campo StructArray

Per creare un campo StructArray, definire innanzitutto lo schema Struct utilizzato da ciascun elemento. Aggiungere quindi un campo Array e impostare il tipo dell’elemento su Struct.

1. Creare lo schema della raccolta.

2. Aggiungere campi a livello di raccolta, come la chiave primaria e i campi a livello di articolo.

3. Creare uno schema Struct per gli elementi memorizzati all’interno del campo StructArray.

4. Aggiungere sottocampi scalari e vettoriali allo schema Struct.

5. Aggiungere un campo Array con l'opzione " element_type=DataType.STRUCT".

6. Impostare ` struct_schema ` sullo schema `Struct`.

7. Impostare " max_capacity " per limitare il numero di elementi Struct che ciascuna entità può memorizzare nel campo.

from pymilvus import MilvusClient, DataType

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus",
)

schema = client.create_schema(
    auto_id=False,
    enable_dynamic_field=False,
)

# Collection-level fields.
schema.add_field(
    field_name="doc_id",
    datatype=DataType.INT64,
    is_primary=True,
)
schema.add_field(
    field_name="title",
    datatype=DataType.VARCHAR,
    max_length=512,
)
schema.add_field(
    field_name="category",
    datatype=DataType.VARCHAR,
    max_length=128,
)
schema.add_field(
    field_name="title_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Struct schema used by each element in the StructArray field.
chunk_schema = client.create_struct_field_schema()
chunk_schema.add_field(
    field_name="text",
    datatype=DataType.VARCHAR,
    max_length=65535,
)
chunk_schema.add_field(
    field_name="section",
    datatype=DataType.VARCHAR,
    max_length=128,
)
chunk_schema.add_field(
    field_name="page",
    datatype=DataType.INT64,
)
chunk_schema.add_field(
    field_name="quality_score",
    datatype=DataType.FLOAT,
)
chunk_schema.add_field(
    field_name="has_code",
    datatype=DataType.BOOL,
)

# Vector subfield for EmbeddingList search.
chunk_schema.add_field(
    field_name="emb_list_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Vector subfield for element-level search.
chunk_schema.add_field(
    field_name="emb",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Add the StructArray field.
schema.add_field(
    field_name="chunks",
    datatype=DataType.ARRAY,
    element_type=DataType.STRUCT,
    struct_schema=chunk_schema,
    max_capacity=1000,
)

client.create_collection(
    collection_name="tech_articles",
    schema=schema,
)

Comprendere i percorsi dei campi StructArray

Dopo aver creato un campo StructArray, fare riferimento ai suoi sottocampi utilizzando la sintassi del percorso structArray[subfield]. Utilizzare questa sintassi quando si creano indici, si effettuano ricerche nei sottocampi vettoriali, si generano sottocampi di output o si creano filtri scalari.

Percorso	Significato	Uso comune
chunks[text]	Il sottocampo text all'interno di ciascun elemento Struct.	Campo di output o filtraggio scalare.
chunks[section]	L'etichetta della sezione per ciascun blocco.	Filtraggio scalare.
chunks[quality_score]	Il punteggio di qualità a livello di blocco.	Filtraggio scalare o indice scalare.
chunks[emb_list_vector]	Il sottocampo vettoriale utilizzato come lista di embedding.	Ricerca EmbeddingList con MAX_SIM*.
chunks[emb]	Il sottocampo vettoriale utilizzato in modo indipendente da ciascun elemento Struct.	Ricerca vettoriale a livello di elemento.

Rendere un campo StructArray nullabile

Milvus v3.0.x supporta i campi StructArray nullabili. Un campo StructArray nullabile consente a un'entità di memorizzare valori di tipo ` null ` per l'intero campo StructArray.

schema.add_field(
    field_name="chunks",
    datatype=DataType.ARRAY,
    element_type=DataType.STRUCT,
    struct_schema=chunk_schema,
    max_capacity=1000,
    nullable=True,
)

Aggiunta di un campo StructArray a una raccolta esistente

Milvus v3.0.x supporta l’aggiunta di un campo StructArray a una collezione esistente. Il campo StructArray aggiunto deve essere nullable, poiché le entità già presenti nella collezione non dispongono di valori per il nuovo campo.

Per aggiungere un campo StructArray a una collezione esistente, definire innanzitutto lo schema Struct. Quindi chiamare ` add_collection_struct_field() ` e impostare ` nullable=True`.

chunk_schema = client.create_struct_field_schema()
chunk_schema.add_field(
    field_name="text",
    datatype=DataType.VARCHAR,
    max_length=65535,
)
chunk_schema.add_field(
    field_name="section",
    datatype=DataType.VARCHAR,
    max_length=128,
)
chunk_schema.add_field(
    field_name="page",
    datatype=DataType.INT64,
)
chunk_schema.add_field(
    field_name="quality_score",
    datatype=DataType.FLOAT,
)
chunk_schema.add_field(
    field_name="has_code",
    datatype=DataType.BOOL,
)
chunk_schema.add_field(
    field_name="emb_list_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)
chunk_schema.add_field(
    field_name="emb",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

client.add_collection_struct_field(
    collection_name="tech_articles",
    field_name="chunks",
    struct_schema=chunk_schema,
    max_capacity=1000,
    nullable=True,
)

Una volta aggiunto il campo StructArray, le entità esistenti restituiscono ` null ` per il nuovo campo in tutti i suoi sottocampi.

Una volta creato un campo StructArray, non è possibile aggiungere nuovi sottocampi a quel campo StructArray esistente. Se in seguito sono necessari ulteriori attributi degli elementi, chiamare ` drop_collection_field() ` per eliminare il campo StructArray, quindi aggiungere un nuovo campo StructArray con lo schema Struct aggiornato.

client.drop_collection_field(
    collection_name="tech_articles",
    field_name="chunks",
)

client.add_collection_struct_field(
    collection_name="tech_articles",
    field_name="chunks",
    struct_schema=updated_chunk_schema,
    max_capacity=1000,
    nullable=True,
)

Regole dello schema

Regola	Spiegazione
Struct viene utilizzato come tipo di elemento Array.	Creare un campo StructArray come campo Array con element_type=STRUCT. Non creare Struct come campo di raccolta di primo livello.
Tutti gli elementi condividono un unico schema.	Ogni elemento Struct nello stesso campo StructArray segue lo schema Struct definito per quel campo.
max_capacity è obbligatorio.	Limita il numero di elementi Struct che ciascuna entità può memorizzare nel campo StructArray.
Sono consentiti solo i tipi di sottocampo supportati.	Utilizzare i tipi di sottocampo scalari e vettoriali supportati da StructArray. Non definire sottocampi JSON, Geometry, Text, Timestamptz, SparseFloatVector o sottocampi Struct / Array annidati.
I sottocampi vettoriali richiedono indici prima della ricerca.	Creare indici su percorsi come chunks[emb_list_vector] o chunks[emb] prima di eseguire la ricerca vettoriale.
Un sottocampo vettoriale ha un solo indice.	Se sono necessarie sia la ricerca EmbeddingList che quella a livello di elemento, creare due sottocampi vettoriali separati.
I sottocampi StructArray esistenti sono fissi.	Dopo aver creato un campo StructArray, non è possibile aggiungere ulteriori sottocampi a quello stesso campo StructArray.
Le funzioni non sono supportate all’interno di Struct.	Non definire funzioni per campi o sottocampi all'interno di un campo StructArray.
I sottocampi scalari dovrebbero soddisfare le esigenze di filtraggio.	Aggiungere campi quali section, quality_score o has_code solo quando è necessario filtrarli, raggrupparli o visualizzarli in un secondo momento.

Errori comuni

• Creare ` DataType.STRUCT ` come campo di raccolta di primo livello invece di utilizzarlo come tipo di elemento di un campo `Array`.

• Dimenticare di impostare " max_capacity " sul campo StructArray.

• Definizione di tipi di sottocampo non supportati, come JSON, Geometry, Text, Timestamptz, SparseFloatVector, Array annidato, Struct annidato o Array-of-Struct.

• Utilizzo di ` String ` come tipo di sottocampo. Utilizzare ` VARCHAR ` e impostare ` max_length`.

• Utilizzo di un unico sottocampo vettoriale sia per la ricerca EmbeddingList che per quella a livello di elemento.

• Aggiunta solo di sottocampi vettoriali e omissione dei sottocampi scalari necessari per il filtraggio, come section, quality_score o has_code.

• Trattare i sottocampi vettoriali come input di predicati scalari $[...]. Utilizzare i sottocampi vettoriali per la ricerca vettoriale e i sottocampi scalari per i predicati scalari.

• Ipotizzare che sia possibile aggiungere nuovi sottocampi a un campo StructArray esistente dopo la creazione del campo stesso.

• Utilizzo di chunks.emb o chunks.emb_list_vector invece della sintassi del percorso richiesta chunks[emb] o chunks[emb_list_vector].

• Considerare il comportamento di StructArray con valori null come disponibile in ogni versione di destinazione.

Prossimi passi

1. Per inserire dati annidati nel campo StructArray, consultare Inserimento di dati nei campi StructArray.

2. Per creare indici vettoriali e scalari, consultare Indice dei campi StructArray.

3. Per effettuare ricerche nei sottocampi vettoriali di StructArray, consultare Ricerca vettoriale di base con StructArray.

4. Per esaminare i tipi di dati supportati, il comportamento nullable e le limitazioni specifiche per versione, consultare Limiti di StructArray.