Daten in StructArray-Felder einfügen

Fügen Sie Daten in ein StructArray-Feld ein, wenn jede Entität eine geordnete Liste strukturierter Elemente enthält. In der Einfüge-Nutzlast wird ein StructArray-Feld als Array von Objekten dargestellt. Jedes Objekt repräsentiert ein Struct-Element und verwendet die im Sammlungsschema definierten Namen der Struct-Unterfelder.

Auf dieser Seite wird die Sammlung „ tech_articles “ aus dem Abschnitt „Erstellen eines StructArray-Feldes“ verwendet. Jede Entität ist ein technischer Artikel, und das Feld „ chunks “ speichert Artikelabschnitte als Struct-Elemente.

Bevor Sie beginnen

Stellen Sie sicher, dass das Sammlungsschema bereits das StructArray-Feld „ chunks “ enthält.

Feld	Typ	Wert einfügen
doc_id	INT64	Artikel-ID.
title	VARCHAR	Artikeltitel.
category	VARCHAR	Artikelkategorie.
title_vector	FLOAT_VECTOR	Einbettung auf Artikelebene.
chunks	ARRAY	Eine Liste von Chunk-Objekten.

Jedes Objekt in „ chunks “ muss dem Struct-Schema entsprechen.

Unterfeld	Typ	Wert einfügen
text	VARCHAR	Chunk-Text.
section	VARCHAR	Abschnittsname, z. B. „ index “, „ search “ oder „ filter “.
page	INT64	Seitennummer oder logische Position.
quality_score	FLOAT	Bewertung auf Chunk-Ebene.
has_code	BOOL	Angabe, ob der Textblock Code enthält.
emb_list_vector	FLOAT_VECTOR	Für die EmbeddingList-Suche erstellter Vektor.
emb	FLOAT_VECTOR	Vektor, der für die Suche auf Elementebene erstellt wurde.

Die Struktur der Einfüge-Nutzdaten verstehen

Der Wert „ chunks “ ist ein Array aus Struct-Elementen. Jedes Element ist ein Objekt, dessen Schlüssel die Namen von Unterfeldern sind.

{
  "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 und „ emb “ sind separate Vektor-Unterfelder, da sie unterschiedliche Suchmodi unterstützen. Die „EmbeddingList“-Suche behandelt alle Vektoren in einem „StructArray“-Feld als eine einzige Einbettungsliste und gibt Ergebnisse auf Entitätsebene mit „ MAX_SIM* “-Metriken zurück. Die Suche auf Elementebene durchsucht jedes „Struct“-Element unabhängig und kann den Offset des übereinstimmenden Elements zurückgeben. In diesem Beispiel werden der Einfachheit halber in beiden Feldern dieselben Vektorwerte gespeichert. In einer Produktionsanwendung können Sie in beiden Unterfeldern dieselben Einbettungen speichern, wenn beide Suchmodi dieselbe Chunk-Einbettung verwenden, oder unterschiedliche Einbettungen speichern, wenn die beiden Suchmodi unterschiedliche Darstellungen nutzen.

Zeilen einfügen

Verwenden Sie „ client.insert() “, um Zeilen einzufügen, die StructArray-Werte enthalten.

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)

Einfügen in nullfähige „StructArray“-Felder

Wenn das „ chunks “-Feld nullfähig ist, kann eine Entität das gesamte „ chunks “-Feld auf null setzen. Verwenden Sie in Python „ None “, um einen Nullwert darzustellen.

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

Wenn ein nullfähiges „StructArray“-Feld einen gültigen „StructArray“-Wert enthält, sollten alle Unterfelder in diesem Wert entweder null sein oder gültige Werte aufweisen. Das Einfügen einer Entität, bei der einige Unterfelder auf null und andere auf gültige Werte gesetzt sind, führt zu einem Fehler.

Eingefügte Daten validieren

Sie können die Sammlung abfragen und das StructArray-Feld oder ausgewählte Unterfelder zurückgeben.

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)

Verwenden Sie StructArray-Feldpfade wie „ chunks[text] “ nur bei Abfragen, Suchvorgängen, Filterungen oder beim Erstellen von Indizes. Bei Einfügungen sollten weiterhin verschachtelte Objekte unter „ chunks “ verwendet werden.

Einfüge-Regeln

Regel	Erläuterung
Verwenden Sie für ein StructArray-Feld ein Array von Objekten.	Der Wert von „ chunks “ ist eine Liste, und jedes Element in der Liste ist ein Struct-Element.
Verwenden Sie Unterfeldnamen innerhalb jedes Struct-Elements.	Fügen Sie „ {"text": "...", "emb": [...]} “ innerhalb von „ chunks “ ein, nicht innerhalb von „ {"chunks[text]": "..."} “.
Halten Sie sich an das Struct-Schema.	Jedes Struct-Element muss die im Struct-Schema definierten Unterfelder verwenden.
Die Vektordimensionen müssen übereinstimmen.	Die Vektorwerte müssen mit den für ihre Vektor-Unterfelder konfigurierten „ dim “ übereinstimmen.
Beachten Sie die „ max_capacity “.	Die Anzahl der Struct-Elemente in einer Entität darf die im StructArray-Feld konfigurierte „ max_capacity “ nicht überschreiten.
Verwenden Sie separate Vektor-Unterfelder für separate Suchmodi.	Wenn sowohl die EmbeddingList-Suche als auch die Suche auf Elementebene erforderlich sind, schreiben Sie Vektorwerte in beide Vektor-Unterfelder.
Verwenden Sie „ null “ nur, wenn das Feld nullfähig ist.	Nicht-nullfähige StructArray-Felder erfordern gültige StructArray-Werte.

Häufige Fehler

• Verwendung von Feldpfaden wie „ chunks[text] “ in Einfüge-Payloads.

• Das Weglassen erforderlicher Unterfelder aus einem Struct-Element.

• Einfügen von Vektoren mit falscher Dimension.

• Einfügen von mehr Struct-Elementen, als „ max_capacity “ zulässt.

• Nur ein Unterfeld auf „ null “ setzen, während andere Unterfelder im selben „StructArray“-Wert gültig sind.

• Das Schreiben von Vektoren ausschließlich in „ emb_list_vector “ und der anschließende Versuch, eine Suche auf Elementebene in „ chunks[emb] “ durchzuführen.

• Das Schreiben von Vektoren ausschließlich in „ emb “, gefolgt vom Versuch, eine „EmbeddingList“-Suche auf „ chunks[emb_list_vector] “ durchzuführen.

Nächste Schritte

1. Informationen zum Erstellen von Indizes für „ chunks[emb_list_vector] “, „ chunks[emb] “ und skalare Unterfelder finden Sie unter „Index StructArray Fields“.

2. Informationen zur Suche in StructArray-Vektor-Unterfeldern finden Sie unter „Grundlegende Vektorsuche mit StructArray“.

3. Informationen zum Verhalten bei nullfähigen Werten und zu versionsspezifischen Einschränkungen finden Sie unter „StructArray-Einschränkungen“.