Inserimento di dati nei campi StructArray

Inserire dati in un campo StructArray quando ogni entità contiene un elenco ordinato di elementi strutturati. Nel payload di inserimento, un campo StructArray è rappresentato come un array di oggetti. Ogni oggetto rappresenta un elemento Struct e utilizza i nomi dei sottocampi Struct definiti nello schema della raccolta.

Questa pagina utilizza la collezione " tech_articles " descritta nella sezione "Creazione di un campo StructArray". Ogni entità è un articolo tecnico e il campo " chunks " memorizza i segmenti dell'articolo come elementi Struct.

Prima di iniziare

Assicurarsi che lo schema della raccolta contenga già il campo StructArray denominato " chunks ".

Campo	Tipo	Valore di inserimento
doc_id	INT64	ID articolo.
title	VARCHAR	Titolo dell'articolo.
category	VARCHAR	Categoria dell'articolo.
title_vector	FLOAT_VECTOR	Incorporamento a livello di articolo.
chunks	ARRAY	Un elenco di oggetti chunk.

Ogni oggetto in chunks deve seguire lo schema Struct.

Sottocampo	Tipo	Inserisci valore
text	VARCHAR	Testo del chunk.
section	VARCHAR	Nome della sezione, ad esempio index, search o filter.
page	INT64	Numero di pagina o posizione logica.
quality_score	FLOAT	Punteggio a livello di blocco.
has_code	BOOL	Se il blocco contiene codice.
emb_list_vector	FLOAT_VECTOR	Vettore scritto per la ricerca EmbeddingList.
emb	FLOAT_VECTOR	Vettore scritto per la ricerca a livello di elemento.

Comprendere la struttura del payload di inserimento

Il valore di ` chunks ` è un array di elementi `Struct`. Ciascun elemento è un oggetto le cui chiavi sono nomi di sottocampi.

{
  "doc_id": 1,
  "title": "StructArray indexing patterns",
  "category": "index",
  "title_vector": [0.12, 0.08, 0.32, 0.48],
  "chunks": [
    {
      "text": "Create one index for each vector subfield.",
      "section": "index",
      "page": 1,
      "quality_score": 0.96,
      "has_code": false,
      "emb_list_vector": [0.10, 0.20, 0.30, 0.40],
      "emb": [0.10, 0.20, 0.30, 0.40]
    },
    {
      "text": "Use MAX_SIM metrics for EmbeddingList search.",
      "section": "index",
      "page": 2,
      "quality_score": 0.91,
      "has_code": true,
      "emb_list_vector": [0.16, 0.24, 0.35, 0.45],
      "emb": [0.16, 0.24, 0.35, 0.45]
    }
  ]
}

emb_list_vector e emb sono sottocampi vettoriali distinti poiché supportano modalità di ricerca diverse. La ricerca EmbeddingList tratta tutti i vettori in un campo StructArray come un unico elenco di embedding e restituisce risultati a livello di entità con metriche MAX_SIM*. La ricerca a livello di elemento esegue la ricerca su ciascun elemento Struct in modo indipendente e può restituire l’offset dell’elemento corrispondente. Per semplicità, questo esempio memorizza gli stessi valori vettoriali in entrambi i campi. In un’applicazione di produzione, è possibile memorizzare gli stessi embedding in entrambi i sottocampi quando entrambe le modalità di ricerca utilizzano lo stesso embedding a blocchi, oppure memorizzare embedding diversi quando le due modalità di ricerca utilizzano rappresentazioni diverse.

Inserimento di righe

Utilizzare ` client.insert() ` per inserire righe contenenti valori `StructArray`.

from pymilvus import MilvusClient

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

data = [
    {
        "doc_id": 1,
        "title": "StructArray indexing patterns",
        "category": "index",
        "title_vector": [0.12, 0.08, 0.32, 0.48],
        "chunks": [
            {
                "text": "Create one index for each vector subfield.",
                "section": "index",
                "page": 1,
                "quality_score": 0.96,
                "has_code": False,
                "emb_list_vector": [0.10, 0.20, 0.30, 0.40],
                "emb": [0.10, 0.20, 0.30, 0.40],
            },
            {
                "text": "Use MAX_SIM metrics for EmbeddingList search.",
                "section": "index",
                "page": 2,
                "quality_score": 0.91,
                "has_code": True,
                "emb_list_vector": [0.16, 0.24, 0.35, 0.45],
                "emb": [0.16, 0.24, 0.35, 0.45],
            },
        ],
    },
    {
        "doc_id": 2,
        "title": "Filtered StructArray search",
        "category": "filter",
        "title_vector": [0.20, 0.18, 0.22, 0.40],
        "chunks": [
            {
                "text": "Use element_filter to match scalar conditions within the same Struct element.",
                "section": "filter",
                "page": 1,
                "quality_score": 0.93,
                "has_code": True,
                "emb_list_vector": [0.21, 0.18, 0.33, 0.44],
                "emb": [0.21, 0.18, 0.33, 0.44],
            },
            {
                "text": "MATCH_LEAST checks how many elements satisfy a predicate.",
                "section": "filter",
                "page": 2,
                "quality_score": 0.88,
                "has_code": False,
                "emb_list_vector": [0.24, 0.22, 0.31, 0.39],
                "emb": [0.24, 0.22, 0.31, 0.39],
            },
        ],
    },
    {
        "doc_id": 3,
        "title": "Element-level search with offsets",
        "category": "search",
        "title_vector": [0.33, 0.11, 0.29, 0.37],
        "chunks": [
            {
                "text": "Element-level search can return the offset of the matched Struct element.",
                "section": "search",
                "page": 1,
                "quality_score": 0.95,
                "has_code": False,
                "emb_list_vector": [0.32, 0.14, 0.28, 0.41],
                "emb": [0.32, 0.14, 0.28, 0.41],
            }
        ],
    },
]

result = client.insert(
    collection_name="tech_articles",
    data=data,
)

print(result)

Inserimento in campi StructArray nullabili

Se il campo ` chunks ` è nullable, un'entità può impostare l'intero campo ` chunks ` su `null`. In Python, utilizzare ` None ` per rappresentare un valore `null`.

client.insert(
    collection_name="tech_articles",
    data=[
        {
            "doc_id": 10,
            "title": "Article without chunks yet",
            "category": "draft",
            "title_vector": [0.05, 0.10, 0.15, 0.20],
            "chunks": None,
        }
    ],
)

Quando un campo StructArray nullabile contiene un valore StructArray valido, tutti i sottocampi di quel valore devono essere null o avere valori validi. L'inserimento di un'entità con alcuni sottocampi impostati su null e altri su valori validi genera un errore.

Convalida dei dati inseriti

È possibile eseguire una query sulla collezione e restituire il campo StructArray o i sottocampi selezionati.

rows = client.query(
    collection_name="tech_articles",
    filter="doc_id in [1, 2, 3]",
    output_fields=[
        "doc_id",
        "title",
        "chunks[text]",
        "chunks[section]",
        "chunks[quality_score]",
    ],
)

for row in rows:
    print(row)

Utilizzare i percorsi dei campi StructArray, come chunks[text], solo quando si eseguono query, ricerche, filtri o si creano indici. I payload di inserimento devono comunque utilizzare oggetti annidati sotto chunks.

Regole di inserimento

Regola	Spiegazione
Utilizzare un array di oggetti per un campo StructArray.	Il valore di chunks è un elenco e ogni elemento dell'elenco è un elemento Struct.
Utilizzare i nomi dei sottocampi all'interno di ciascun elemento Struct.	Inserire ` {"text": "...", "emb": [...]} ` all'interno di ` chunks`, non in ` {"chunks[text]": "..."}`.
Rispettare lo schema della Struct.	Ogni elemento Struct deve utilizzare i sottocampi definiti nello schema Struct.
Rispettare le dimensioni dei vettori.	I valori dei vettori devono corrispondere a dim configurati per i relativi sottocampi vettoriali.
Rispettare l’ max_capacity.	Il numero di elementi Struct in un'entità non deve superare l'max_capacity del campo StructArray.
Utilizzare sottocampi vettoriali separati per le diverse modalità di ricerca.	Se sono richieste sia la ricerca EmbeddingList che quella a livello di elemento, scrivere i valori vettoriali in entrambi i sottocampi vettoriali.
Utilizzare null solo quando il campo è nullable.	I campi StructArray non nullabili richiedono valori StructArray validi.

Errori comuni

• Utilizzo di percorsi di campo come chunks[text] nei payload di inserimento.

• Omissione di sottocampi obbligatori da un elemento Struct.

• Inserimento di vettori con la dimensione errata.

• Inserimento di un numero di elementi Struct superiore a quello consentito da max_capacity.

• Impostare un solo sottocampo su null mentre altri sottocampi nello stesso valore StructArray sono validi.

• Scrittura di vettori solo su emb_list_vector e successivo tentativo di eseguire una ricerca a livello di elemento su chunks[emb].

• Scrittura di vettori solo in ` emb `, seguita dal tentativo di eseguire una ricerca EmbeddingList su ` chunks[emb_list_vector]`.

Prossimi passi

1. Per creare indici per i sottocampi chunks[emb_list_vector], chunks[emb] e scalari, consultare la sezione “Indice dei campi StructArray”.

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

3. Per esaminare il comportamento dei valori null e le limitazioni specifiche della versione, consultare Limiti di StructArray.