Ein StructArray-Feld erstellen

Erstellen Sie ein StructArray-Feld, wenn eine Entität eine geordnete Liste strukturierter Elemente enthalten soll. Ein StructArray-Feld ist ein Array-Feld, dessen Elementtyp „Struct“ ist. Jedes Struct-Element folgt demselben Schema und kann skalare Unterfelder, Vektor-Unterfelder oder beides enthalten.

Auf dieser Seite erfahren Sie, wie Sie ein Struct-Schema definieren, es als StructArray-Feld hinzufügen, Unterfelder für die spätere Suche und Filterung auswählen und die geltenden Schemaregeln verstehen, bevor Sie Daten einfügen oder indizieren.

Bevor Sie beginnen

Auf dieser Seite wird eine Sammlung namens „ tech_articles “ verwendet. Jede Entität repräsentiert einen technischen Artikel, und das Feld „ chunks “ speichert Daten auf Chunk-Ebene als Struct-Elemente.

Feld	Typ	Zweck
doc_id	INT64	Primärschlüssel für den Artikel.
title	VARCHAR	Artikeltitel.
category	VARCHAR	Kategorie auf Artikelebene.
title_vector	FLOAT_VECTOR	Vektorfeld auf Artikelebene, das später in Beispielen zur hybriden Suche verwendet wird.
chunks	ARRAY	„StructArray“-Feld, das Text auf Chunk-Ebene, Metadaten und Einbettungen speichert.

Das StructArray-Feld „ chunks “ enthält die folgenden Unterfelder.

Unterfeld	Typ	Zweck
text	VARCHAR	Chunk-Text.
section	VARCHAR	Abschnittsname, z. B. „ index “, „ search “ oder „ filter “.
page	INT64	Seitennummer oder logische Position des Chunks.
quality_score	FLOAT	Bewertung auf Chunk-Ebene, die in den Beispielen zur skalaren Filterung und zum Bereich verwendet wird.
has_code	BOOL	Angabe, ob der Textblock Code enthält.
emb_list_vector	FLOAT_VECTOR	Vektor-Unterfeld für die EmbeddingList-Suche mit „ MAX_SIM* “-Metriken.
emb	FLOAT_VECTOR	Vektor-Unterfeld für die Suche auf Elementebene mit regulären Vektormetriken.

Unterstützte Datentypen für Unterfelder

Ein „StructArray“-Feld speichert für jedes „Struct“-Unterfeld einen Array-Wert. Wenn Sie ein „Struct“-Schema definieren, wählen Sie die Unterfeldtypen aus den unterstützten Skalar- und Vektorfamilien aus.

Physikalischer Typ eines Struct-Unterfelds	Unterstützung	Hinweise
Array	Unterstützt	Definieren Sie das Unterfeld als „ DataType.BOOL “.
Array	Unterstützt	Definieren Sie das Unterfeld als „ DataType.INT8 “, „ DataType.INT16 “, „ DataType.INT32 “ oder „ DataType.INT64 “.
Array	Unterstützt	Definieren Sie das Unterfeld als „ DataType.FLOAT “ oder „ DataType.DOUBLE “.
Array	Unterstützt	Definieren Sie das Unterfeld als „ DataType.VARCHAR “ und legen Sie „ max_length “ fest.
ArrayOfVector	Unterstützt	Definieren Sie das Unterfeld als „ DataType.FLOAT_VECTOR “ und legen Sie „ dim “ fest.
ArrayOfVector	Unterstützt	Definieren Sie das Unterfeld als „ DataType.FLOAT16_VECTOR “ und legen Sie „ dim “ fest.
ArrayOfVector	Unterstützt	Definieren Sie das Unterfeld als „ DataType.BFLOAT16_VECTOR “ und legen Sie „ dim “ fest.
ArrayOfVector	Unterstützt	Definieren Sie das Unterfeld als „ DataType.INT8_VECTOR “ und legen Sie „ dim “ fest.
ArrayOfVector	Unterstützt	Definieren Sie das Unterfeld als „ DataType.BINARY_VECTOR “ und legen Sie „ dim “ fest.
ArrayOfVector	Nicht unterstützt	Sparse-Vektor-Teilfelder werden in StructArray-Feldern nicht unterstützt.
Array	Nicht unterstützt	Verwenden Sie „ VARCHAR “ und nicht „ String “.
Array	Nicht unterstützt	JSON-Unterfelder werden in StructArray-Feldern nicht unterstützt.
Array	Nicht unterstützt	Geometrie-Unterfelder und GIS-Funktionen werden in StructArray-Feldern nicht unterstützt.
Array	Nicht unterstützt	Text-Unterfelder werden in StructArray-Feldern nicht unterstützt.
Array	Nicht unterstützt	Timestamptz-Unterfelder und zeitbezogene Ausdrücke werden in StructArray-Feldern nicht unterstützt.
Verschachtelte „ Array “, „ ArrayOfVector “, „ Struct “ oder ArrayOfStruct	Nicht unterstützt	Ein StructArray-Feld darf keine verschachtelten Arrays, verschachtelten Vektor-Arrays, verschachtelten Struct-Felder oder verschachtelten Array-of-Struct-Felder enthalten.

Informationen zur versionsspezifischen Unterstützung, zum Verhalten bei nullfähigen Werten und zu weiteren Einschränkungen finden Sie unter „StructArray-Einschränkungen“.

Erstellen einer Sammlung mit einem StructArray-Feld

Um ein StructArray-Feld zu erstellen, definieren Sie zunächst das Struct-Schema, das von jedem Element verwendet wird. Fügen Sie anschließend ein Array-Feld hinzu und legen Sie dessen Elementtyp auf „Struct“ fest.

1. Erstellen Sie das Sammlungsschema.

2. Fügen Sie Felder auf Sammlungsebene hinzu, z. B. den Primärschlüssel und Felder auf Artikelebene.

3. Erstellen Sie ein „Struct“-Schema für die im „StructArray“-Feld gespeicherten Elemente.

4. Fügen Sie dem „Struct“-Schema Skalar- und Vektor-Unterfelder hinzu.

5. Fügen Sie ein Array-Feld mit der Eigenschaft „ element_type=DataType.STRUCT “ hinzu.

6. Legen Sie „ struct_schema “ auf das „Struct“-Schema fest.

7. Legen Sie „ max_capacity “ fest, um zu begrenzen, wie viele „Struct“-Elemente jede Entität in dem Feld speichern kann.

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

StructArray-Feldpfade verstehen

Nachdem Sie ein „StructArray“-Feld erstellt haben, verweisen Sie mit der „ structArray[subfield] “-Pfadsyntax auf dessen Unterfelder. Verwenden Sie diese Syntax, wenn Sie Indizes erstellen, Vektor-Unterfelder durchsuchen, Unterfelder ausgeben oder skalare Filter erstellen.

Pfad	Bedeutung	Häufige Verwendung
chunks[text]	Das Unterfeld „ text “ innerhalb jedes Struct-Elements.	Ausgabefeld oder skalare Filterung.
chunks[section]	Die Abschnittsbezeichnung für jeden Chunk.	Skalare Filterung.
chunks[quality_score]	Der Qualitätswert auf Chunk-Ebene.	Skalare Filterung oder skalarer Index.
chunks[emb_list_vector]	Das Vektor-Teilfeld, das als Einbettungsliste verwendet wird.	Suche in der Einbettungsliste mit „ MAX_SIM* “.
chunks[emb]	Das Vektor-Teilfeld, das von jedem Struct-Element unabhängig verwendet wird.	Vektorsuche auf Elementebene.

Ein StructArray-Feld als nullfähig definieren

Milvus v3.0.x unterstützt nullfähige StructArray-Felder. Ein nullfähiges StructArray-Feld ermöglicht es einer Entität, für das gesamte StructArray-Feld „ null “ zu speichern.

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

Hinzufügen eines StructArray-Feldes zu einer bestehenden Sammlung

Milvus v3.0.x unterstützt das Hinzufügen eines StructArray-Feldes zu einer bestehenden Sammlung. Das hinzugefügte StructArray-Feld muss nullfähig sein, da Entitäten, die bereits in der Sammlung vorhanden sind, keine Werte für das neue Feld haben.

Um ein StructArray-Feld zu einer bestehenden Sammlung hinzuzufügen, definieren Sie zunächst das Struct-Schema. Rufen Sie anschließend „ add_collection_struct_field() “ auf und setzen Sie „ 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,
)

Nachdem das StructArray-Feld hinzugefügt wurde, geben vorhandene Entitäten für das neue Feld über alle seine Unterfelder hinweg den Wert „ null “ zurück.

Nachdem ein „StructArray“-Feld erstellt wurde, können Sie diesem bestehenden „StructArray“-Feld keine neuen Unterfelder hinzufügen. Wenn Sie später zusätzliche Elementattribute benötigen, rufen Sie „ drop_collection_field() “ auf, um das „StructArray“-Feld zu entfernen, und fügen Sie anschließend ein neues „StructArray“-Feld mit dem aktualisierten „Struct“-Schema hinzu.

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

Schema-Regeln

Regel	Erläuterung
„Struct“ wird als Array-Elementtyp verwendet.	Erstellen Sie ein StructArray-Feld als Array-Feld mit „ element_type=STRUCT “. Erstellen Sie Struct nicht als Sammlungsfeld auf oberster Ebene.
Alle Elemente teilen sich ein gemeinsames Schema.	Jedes „Struct“-Element im selben „StructArray“-Feld folgt dem für dieses Feld definierten „Struct“-Schema.
max_capacity ist erforderlich.	Es begrenzt die Anzahl der „Struct“-Elemente, die jede Entität im „StructArray“-Feld speichern kann.
Es sind nur unterstützte Unterfeldtypen zulässig.	Verwenden Sie die von StructArray unterstützten Skalar- und Vektor-Unterfeldtypen. Definieren Sie keine JSON-, Geometry-, Text-, Timestamptz-, SparseFloatVector- oder verschachtelten Struct-/Array-Unterfelder.
Vektor-Unterfelder benötigen vor der Suche Indizes.	Erstellen Sie Indizes auf Pfaden wie chunks[emb_list_vector] oder chunks[emb], bevor Sie eine Vektorsuche ausführen.
Ein Vektor-Unterfeld hat einen Index.	Wenn Sie sowohl eine EmbeddingList-Suche als auch eine Suche auf Elementebene benötigen, erstellen Sie zwei separate Vektor-Unterfelder.
Vorhandene „StructArray“-Unterfelder sind fest vorgegeben.	Nachdem Sie ein StructArray-Feld erstellt haben, können Sie diesem StructArray-Feld keine weiteren Unterfelder mehr hinzufügen.
Funktionen werden innerhalb von „Struct“ nicht unterstützt.	Definieren Sie keine Funktionen für Felder oder Unterfelder innerhalb eines StructArray-Feldes.
Skalare Unterfelder sollten den Filteranforderungen entsprechen.	Fügen Sie Felder wie „ section “, „ quality_score “ oder „ has_code “ nur dann hinzu, wenn Sie diese später filtern, gruppieren oder ausgeben müssen.

Häufige Fehler

• „ DataType.STRUCT “ als Sammlungsfeld auf oberster Ebene anlegen, anstatt es als Elementtyp eines Array-Feldes zu verwenden.

• Das Vergessen, „ max_capacity “ für das StructArray-Feld festzulegen.

• Definition nicht unterstützter Unterfeldtypen wie JSON, Geometry, Text, Timestamptz, SparseFloatVector, verschachteltes Array, verschachtelte Struktur oder Array-of-Struct.

• Verwendung von „ String “ als Unterfeldtyp. Verwenden Sie „ VARCHAR “ und setzen Sie „ max_length “.

• Verwendung eines einzigen Vektor-Unterfelds sowohl für die „EmbeddingList“-Suche als auch für die Suche auf Elementebene.

• Das Hinzufügen ausschließlich von Vektor-Unterfeldern und das Auslassen von für die Filterung benötigten Skalar-Unterfeldern wie „ section “, „ quality_score “ oder „ has_code “.

• Vektor-Unterfelder werden als skalare Prädikate für $[...] behandelt. Vektor-Unterfelder werden für die Vektorsuche verwendet, skalare Unterfelder für skalare Prädikate.

• Annahme, dass einem bestehenden StructArray-Feld nach dessen Erstellung neue Teilfelder hinzugefügt werden können.

• Verwendung von chunks.emb oder chunks.emb_list_vector anstelle der erforderlichen Pfadsyntax chunks[emb] oder chunks[emb_list_vector].

• Das Verhalten von nullfähigen StructArrays wird so behandelt, als wäre es in jeder Zielversion verfügbar.

Nächste Schritte

1. Informationen zum Einfügen verschachtelter Daten in das StructArray-Feld finden Sie unter „Daten in StructArray-Felder einfügen“.

2. Informationen zum Erstellen von Vektor- und Skalarindizes finden Sie unter „StructArray-Felder indizieren“.

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

4. Informationen zu unterstützten Datentypen, dem Verhalten bei nullfähigen Werten und versionsspezifischen Einschränkungen finden Sie unter „Einschränkungen von StructArray“.