跳到主要内容
版本：v3.0.x

StructArray Limits

StructArray 支持覆盖 Schema 定义、Insert payload、索引、Search mode，以及 StructArray 专用 Filter。在生产环境依赖 StructArray 行为前，请先将本页作为限制参考。

大多数 StructArray 限制来自以下三类因素之一：StructArray Schema 模型、你为 vector subfield 选择的 search mode，以及 Collection 运行所用的 Milvus 版本。

限制速览​

AreaLimit
Schema shapeStruct 只能用作 Array 字段的元素类型。不支持将 Struct 作为顶层 Collection 字段。
Subfield schema同一个 StructArray 字段中的所有 Struct 元素共享一个预定义的 Struct Schema。
Capacitymax_capacity 为必填项，用于限制单个 Entity 可在 StructArray 字段中存储的 Struct 元素数量。
Subfield changes创建 StructArray 字段后，不能向该现有 StructArray 字段添加 subfield。
Subfield path对于索引、搜索目标、输出字段和 Filter，请使用 structArray[subfield] 路径，例如 chunks[emb]。不要使用 chunks.emb。
Insert shape插入 StructArray 字段时，应使用对象数组。不要在插入 payload 中使用路径语法。
Vector indexes一个向量字段或向量 subfield 只能接受一个索引。对于 EmbeddingList Search 和元素级搜索，请使用不同的向量 subfield。
FunctionsStructArray 字段内的字段或 subfield 不支持 Field functions。
Nullable fieldsNullable StructArray 字段受版本限制。支持该能力时，NULL 适用于整个 StructArray 字段，而不是独立适用于单个 Struct 元素。
Dynamic add field向现有 Collection 添加 StructArray 字段受版本限制，并且要求新增字段为 nullable。

Schema limits​

限制详情
Struct 不是顶层字段类型。如需创建 StructArray 字段，请设置 datatype=DataType.ARRAY、element_type=DataType.STRUCT，并指定 struct_schema。
所有元素共享同一个 Schema。StructArray 字段中的每个 Struct 元素都遵循相同的子字段列表和子字段数据类型。
max_capacity 为必填项。单个 Entity 中的 Struct 元素数量不得超过为 StructArray 字段配置的 max_capacity。
已有子字段固定不变。你不能向已有 StructArray 字段追加新的子字段。如需更改子字段 Schema，请先删除该 StructArray 字段，再使用更新后的 Schema 重新添加。
不支持嵌套 StructArray。StructArray 字段不能包含嵌套的 Array、ArrayOfVector、Struct 或 ArrayOfStruct 子字段。
StructArray 内不支持 Function。不要为 StructArray 字段或其子字段定义字段 Function。

有关创建 Schema 的示例，请参阅 Create a StructArray Field。

Supported subfield data types​

StructArray subfield 会映射到物理的数组式存储。下表列出了支持和不支持的物理类型。

Struct subfield 物理类型支持情况说明
Array支持将 subfield 定义为 DataType.BOOL。
Array支持将 subfield 定义为 DataType.INT8、DataType.INT16、DataType.INT32 或 DataType.INT64。
Array支持将 subfield 定义为 DataType.FLOAT 或 DataType.DOUBLE。
Array支持将 subfield 定义为 DataType.VARCHAR 并设置 max_length。
ArrayOfVector支持将 subfield 定义为 DataType.FLOAT_VECTOR 并设置 dim。
ArrayOfVector支持将 subfield 定义为 DataType.FLOAT16_VECTOR 并设置 dim。
ArrayOfVector支持将 subfield 定义为 DataType.BFLOAT16_VECTOR 并设置 dim。
ArrayOfVector支持将 subfield 定义为 DataType.INT8_VECTOR 并设置 dim。
ArrayOfVector支持将 subfield 定义为 DataType.BINARY_VECTOR 并设置 dim。
ArrayOfVector不支持StructArray field 不支持 Sparse vector subfield。
Array不支持使用 VARCHAR，而不是 String。
Array不支持StructArray field 不支持 JSON subfield。
Array不支持StructArray field 不支持 Geometry subfield 和 GIS 函数。
Array不支持StructArray field 不支持 Text subfield。
Array不支持StructArray field 不支持 Timestamptz subfield 和时间相关表达式。
嵌套的 Array、ArrayOfVector、Struct 或 ArrayOfStruct不支持StructArray field 不支持嵌套的 array、vector-array、Struct 或 Array-of-Struct subfield。

Nullable 和 dynamic schema 限制​

Nullable StructArray 的行为以及动态添加 StructArray 字段受版本限制。

CapabilityLimit
Nullable StructArray field仅在包含 nullable StructArray 和 nullable vector-array 支持的版本中支持。
Python 中的 NULL 值在 Python 中插入 NULL StructArray 值时使用 None。不要使用 Null 或 null。
Null 作用范围Null 适用于整个 StructArray 字段。例如，只有当 chunks 为 nullable 时，chunks=None 才有效。
部分为 NULL 的 StructArray 值当 StructArray 字段包含有效数组值时，不要在同一个值中混用 NULL 子字段数组和有效子字段数组。
动态添加 StructArray 字段仅在包含动态 StructArray 字段支持的版本中支持向现有 collection 添加 StructArray 字段。
动态添加的 nullable 要求添加到现有 collection 的 StructArray 字段必须为 nullable，因为现有 entity 没有该新字段的值。
动态添加后的现有 entity现有 entity 会在新增 StructArray 字段及其各个子字段中返回 null。

在 Milvus v3.0.x 中，可以使用 nullable StructArray 字段、nullable vector array，以及动态添加 StructArray 字段。

有关 nullable StructArray 字段的插入示例，请参阅 向 StructArray 字段插入数据。

Insert limits​

限制详细信息
Payload shape将 StructArray 字段作为 Struct 对象数组插入，例如 chunks: [{"text": "...", "emb": [...]}]。
Subfield names在每个 Struct 对象内，使用 text 和 emb 等 subfield 名称，而不是 chunks[text] 等路径。
Schema alignment每个 Struct 元素都必须与 Struct schema 匹配。
Capacity单个 Entity 中的 Struct 元素数量不得超过 max_capacity。
Vector dimensionsVector 值必须与其 vector subfield 配置的 dim 匹配。
Search-mode duplication如果需要同时使用 EmbeddingList search 和 element-level search，请将 vector 写入两个独立的 vector subfield。

Index 和 Metric 限制​

StructArray vector subfield 可以为 EmbeddingList search 或 element-level search 创建索引。同一个 vector subfield 不能同时使用这两类 metric family，因为每个 vector field 或 vector subfield 只能接受一个 index。

搜索模式Metric family结果级别
EmbeddingList searchMAX_SIM、MAX_SIM_COSINE、MAX_SIM_IP、MAX_SIM_L2，或二进制 MAX_SIM_* metricsEntity-level 结果。
Element-level search常规 vector metrics，例如 L2、IP、COSINE、HAMMING 或 JACCARDElement-level 结果，可包含匹配元素的 offset。

如果需要同时使用两种模式，请使用不同的 vector subfield。例如，使用 chunks[emb_list_vector] 执行 EmbeddingList search，使用 chunks[emb] 执行 element-level search。

规划 collection schema 时，StructArray vector subfield 会计入 vector subfield 数量。请确保 vector field 和 vector subfield 的总数不超过目标版本和服务层级的限制。

如需查看支持的 index-type 与 metric-type 矩阵，请参阅 Index StructArray Fields。

Search limits​

Search behavior支持和限制
Basic EmbeddingList search支持在使用 MAX_SIM* metrics 建立索引的 StructArray vector subfields 上执行。返回 Entity 级别的结果。
Basic element-level search支持在使用常规 vector metrics 建立索引的 StructArray vector subfields 上执行。可返回匹配元素的 offsets。
Range search按目标版本的搜索模式以及 Index/metric 支持情况提供支持。对于 element-level StructArray 请求中的 hybrid search range 行为，请检查你的目标版本。
Grouping searchElement-level grouping search 可返回 offsets。Element-level StructArray 请求的 hybrid search group-by 行为受版本限制。
Hybrid searchHybrid search 请求只能在目标版本支持对应搜索组合时包含 StructArray vector subfield 请求。每个请求仍遵循已建立索引的 vector subfield 的 metric family。
Offset outputOffset 可用于 element-level search 结果。EmbeddingList search 返回 Entity 级别的结果，不以元素 offset 作为主要结果单位。

Filter 和 operator 限制​

StructArray 标量过滤由 StructArray operator 处理，例如 element_filter 和 MATCH_* 系列。详细的 predicate 支持矩阵请参阅 StructArray Operators。

从整体上看：

  • 仅在 StructArray operator 内使用 $[subfield]。

  • 标量 predicate 应使用标量子字段。

  • 不要将向量子字段作为 $[...] 标量 predicate 的输入。

  • StructArray 元素级 predicate 不支持 JSON path 语法、JSON 函数、array container 函数、text match 函数、Geometry / GIS 函数和 Timestamptz 表达式。

  • 优先使用显式布尔比较，例如 $[has_code] == true，而不是单独的布尔表达式。

  1. 如需创建 StructArray 字段，请参阅 创建 StructArray 字段。

  2. 如需插入数据，请参阅 将数据插入 StructArray 字段。

  3. 如需创建 vector 和 scalar index，请参阅 为 StructArray 字段创建 Index。

  4. 如需查看 StructArray filter 语法，请参阅 StructArray Operators。