milvus-io--milvus/docs/design-docs/design_docs/20260306-struct.md

Struct Data Type

Summary

Introduce a new Struct data type in Milvus as the element type of DataType.ARRAY, enabling an Array of Struct composite data model — logically binding multiple scalar and vector fields together within each array element.

Motivation

Users frequently need to store multiple related embeddings and metadata per row. For example, a video may contain multiple clips, each with its own embedding and tags. Currently this requires either splitting data across multiple collections or using unstructured JSON fields, sacrificing query efficiency and schema enforcement.

The Struct type allows vectors to exist inside array elements. Prior to Struct, DataType.ARRAY could not contain vector fields. With Struct, Milvus natively supports:

• Embedding List — each row contains multiple vectors, with multi-to-multi vector similarity search using metrics such as MaxSim.
• Element Filter & Element-Level Search — filtering and searching at the granularity of individual array elements. Element Filter evaluates filter conditions independently on each array element; Element-Level Search performs vector search at the granularity of each embedding in the Embedding List. The two can be used together.
• Match Family — a set of array-level quantified filtering operators (ANY / ALL / LEAST / MOST / EXACT), supporting same-element multi-field matching for Struct arrays (nested semantics).

Additionally, Struct enforces strong typing on sub-fields (types, dimensions, etc.) via StructFieldSchema, making it safer and more efficient than JSON-based approaches.

Design

Schema

Struct can only be used as the element_type of a DataType.ARRAY field. Each Struct field is defined by a StructFieldSchema that specifies its sub-fields.

Allowed sub-field types: scalar types (INT64, VARCHAR, FLOAT, etc.), scalar ARRAY, and vector types (FLOAT_VECTOR, etc.).

Not allowed: nested Struct, JSON, primary key, or auto-id.

struct_schema = client.create_struct_field_schema()
struct_schema.add_field("clip_embedding", DataType.FLOAT_VECTOR, dim=128)
struct_schema.add_field("clip_id", DataType.INT64)
struct_schema.add_field("clip_tags", DataType.ARRAY,
                        element_type=DataType.VARCHAR, max_capacity=10)

schema.add_field("clips", datatype=DataType.ARRAY,
                 element_type=DataType.STRUCT,
                 struct_schema=struct_schema, max_capacity=1000)

Proto changes:

message CollectionSchema {
    ...
    repeated StructFieldSchema struct_fields = 9;
}

message StructFieldSchema {
  int64 fieldID = 1;
  string name = 2;
  string description = 3;
  repeated FieldSchema fields = 4;
  repeated common.KeyValuePair type_params = 5;
}

Storage

Each sub-field of a Struct is physically stored as an independent column, typed as ARRAY of <field_type>. For example, a clip_id (INT64) sub-field under a Struct array is stored identically to a regular ARRAY<INT64> column.

This design avoids defining a new composite physical type and reuses the existing columnar storage and serialization infrastructure. The system maintains a metadata mapping from the Struct field name to its set of physical columns (e.g., "clips" -> {clip_embedding, clip_id, clip_tags}).

Vector Index (Embedding List Index)

All vectors across array elements within a row are flattened and passed to knowhere along with per-row offset information to build the index:

• float* — all vectors concatenated
• offsets — cumulative element counts per row, e.g., row sizes [3, 2] yield offsets [0, 3, 5]

Aspect	Supported
Index types	HNSW, IVF_FLAT, DISKANN
Metric types	MAX_SIM_COSINE, MAX_SIM_IP
Vector types	FLOAT_VECTOR, BinaryVector, Float16, BFloat16, Int8

Scalar Index (Nested Index)

Scalar indexes on Struct sub-fields use nested semantics: each array element is indexed as an independent document, preserving positional information. This is the foundation for both element_filter and Match Family operations.

==== milvus format ====
row0:
  element[0]: { "color": "Red",  "size": "L" }
  element[1]: { "color": "Blue", "size": "M" }

row1:
  element[0]: { "color": "Blue",   "size": "L" }
  element[1]: { "color": "Yellow", "size": "XS" }
  element[2]: { "color": "Blue",   "size": "LL" }

==== nested index ====
doc 0: {"color": "Red",    "size": "L"}    <- row0, element[0]
doc 1: {"color": "Blue",   "size": "M"}    <- row0, element[1]
doc 2: {"color": "Blue",   "size": "L"}    <- row1, element[0]
doc 3: {"color": "Yellow", "size": "XS"}   <- row1, element[1]
doc 4: {"color": "Blue",   "size": "LL"}   <- row1, element[2]

offsets: [0, 2, 5]  (row0 has 2 elements, row1 has 3 elements)

The offset array maps element IDs back to row IDs at query time.

Element Filter

element_filter filters Struct arrays at the granularity of individual array elements. $[subFieldName] references a sub-field of the current element. It can be combined with row-level filter conditions:

filter = 'price > 100 && element_filter(clips, $[tag] == "sports" && $[score] > 0.8)'

Constraint: element_filter may appear at most once per filter expression and must be the last operand.

Match Family

A set of operators that apply a predicate to each element of an array and quantify the number of matches to determine whether the row passes. For Struct arrays, all sub-field conditions in the predicate must be satisfied by the same element (nested semantics).

Operator	Semantics
MATCH_ANY(field, pred)	At least one element matches
MATCH_ALL(field, pred)	All elements match
MATCH_LEAST(field, pred, count=N)	At least N elements match
MATCH_MOST(field, pred, count=N)	At most N elements match
MATCH_EXACT(field, pred, count=N)	Exactly N elements match

# Row 0: [{Red, L}, {Blue, M}] -> match (Red and L on the same element)
# Row 1: [{Blue, L}, {Red, LL}] -> no match (Red and L on different elements)
MATCH_ANY(structA, ($[color] == "Red") && $[size] == "L")

Implementation reuses the element-level filtering mechanism: evaluate the predicate at element-level, then aggregate per-doc bit patterns to apply the quantifier semantics (any/all/least/most/exact), producing a final doc-level result.

Limitations

• Struct can only be used as the element type of ARRAY, not as a standalone field
• Sub-fields cannot be Struct, Array, or JSON
• Sub-fields do not support nullable