StructArray 限制

StructArray 的支持范围涵盖 Schema 定义、插入有效载荷、索引、搜索模式以及 StructArray 专用的过滤器。在生产环境中依赖 StructArray 的行为之前，请将本页面作为限制参考。

大多数 StructArray 限制源自以下三个方面之一：StructArray 模式 Schema、您为向量字段选择的搜索模式，以及您的 Collection 所运行的 Milvus 版本。

限制一览

领域	限制
Schema结构	Struct 只能用作 Array 字段的元素类型。不支持将 Struct 用作顶级 Collection 字段。
子字段Schema	同一 StructArray 字段中的所有 Struct 元素共享一个预定义的 Struct Schema。
容量	max_capacity 是必填字段，用于限制一个实体在 StructArray 字段中可存储的 Struct 元素数量。
子字段更改	StructArray 字段创建后，无法向该现有 StructArray 字段添加子字段。
子字段路径	请使用structArray[subfield] 路径（例如chunks[emb] ）作为索引、搜索目标、输出字段和过滤器。请勿使用chunks.emb 。
插入结构	将 StructArray 字段作为对象数组插入。请勿在插入有效载荷中使用路径语法。
向量索引	向量字段或向量子字段仅接受一个索引。请分别使用独立的向量子字段进行 EmbeddingList 搜索和元素级搜索。
函数	StructArray 字段内的字段或子字段不支持字段函数。
可为空字段	可为空的 StructArray 字段受版本限制。当受支持时，空值适用于整个 StructArray 字段，而非独立作用于单个 Struct 元素。
动态添加字段	向现有 Collection 添加 StructArray 字段受版本限制，且要求所添加的字段为可空字段。

Schema限制

限制	详细信息
Struct 不是顶级字段类型。	将 StructArray 字段创建为datatype=DataType.ARRAY ，其element_type=DataType.STRUCT 和struct_schema 。
所有元素共享一个Schema。	StructArray 字段中的每个 Struct 元素都遵循相同的子字段列表和子字段数据类型。
max_capacity 是必需的。	一个实体中的 Struct 元素数量不得超过为 StructArray 字段配置的max_capacity 。
现有的子字段是固定的。	您无法将新子字段追加到现有的 StructArray 字段中。要更改子字段 Schema，请删除 StructArray 字段，然后使用更新的 Schema 再次添加该字段。
不支持嵌套的 StructArray。	StructArray 字段不能包含嵌套的Array 、ArrayOfVector 、Struct 或ArrayOfStruct 子字段。
StructArray内部不支持函数。	请勿为 StructArray 字段或其子字段定义字段函数。

有关 Schema 创建示例，请参阅“创建 StructArray 字段”。

支持的子字段数据类型

StructArray 子字段映射到物理数组风格的存储空间。下表列出了受支持和不受支持的物理类型。

Struct 子字段的物理类型	支持	备注
Array	受支持	将子字段定义为DataType.BOOL 。
Array	受支持	将子字段定义为DataType.INT8 、DataType.INT16 、DataType.INT32 或DataType.INT64 。
Array	受支持	将子字段定义为DataType.FLOAT 或DataType.DOUBLE 。
Array	受支持	将子字段定义为DataType.VARCHAR ，并设置max_length 。
ArrayOfVector	受支持	将子字段定义为DataType.FLOAT_VECTOR ，并设置dim 。
ArrayOfVector	受支持	将子字段定义为DataType.FLOAT16_VECTOR ，并设置dim 。
ArrayOfVector	受支持	将子字段定义为DataType.BFLOAT16_VECTOR ，并设置dim 。
ArrayOfVector	受支持	将子字段定义为DataType.INT8_VECTOR ，并设置dim 。
ArrayOfVector	受支持	将子字段定义为DataType.BINARY_VECTOR ，并将dim 设置为。
ArrayOfVector	不支持	StructArray 字段不支持稀疏向量子场。
Array	不支持	请使用VARCHAR ，而非String 。
Array	不支持	StructArray 字段不支持 JSON 子字段。
Array	不支持	StructArray 字段不支持几何子字段和 GIS 函数。
Array	不支持	StructArray 字段不支持文本子字段。
Array	不支持	StructArray 字段不支持 Timestamptz 子字段和特定时间的表达式。
嵌套的Array 、ArrayOfVector 、Struct 或ArrayOfStruct	不支持	StructArray 字段不支持嵌套的 array、向量-array、Struct 或 Array-of-Struct 子字段。

可为空和动态Schema限制

可为空的 StructArray 行为和动态 StructArray 字段添加受版本限制。

功能	限制
可空 StructArray 字段	仅在包含可空 StructArray 和可空向量数组支持的版本中受支持。
Python 中的空值	请使用None 在Python中插入空的StructArray值。请勿使用Null 或null 。
空值作用域	空值适用于整个 StructArray 字段。例如，chunks=None 仅在chunks 可为空时才有效。
部分为空的 StructArray 值	当 StructArray 字段包含有效的数组值时，请勿在同一值中将可为空的子字段数组与有效的子字段数组混合使用。
动态添加 StructArray 字段	仅在支持动态 StructArray 字段的版本中，才支持向现有 Collection 添加 StructArray 字段。
动态添加的空值要求	添加到现有 Collection 中 StructArray 字段必须为可空，因为现有实体对于该新字段尚无值。
动态添加后的现有实体	现有实体对其新增的 StructArray 字段及其所有子字段均返回null 。

在 Milvus v3.0.x 中，支持可空的 StructArray 字段、可空的向量数组以及动态添加 StructArray 字段。

有关带可空 StructArray 字段的插入示例，请参阅《将数据插入 StructArray 字段》。

插入限制

限制	详细信息
有效载荷形状	将 StructArray 字段作为 Struct 对象的数组插入，例如chunks: [{"text": "...", "emb": [...]}] 。
子字段名称	在每个 Struct 对象内部，请使用诸如text 和emb 这样的子字段名称，而不是诸如chunks[text] 这样的路径。
Schema对齐	每个 Struct 元素必须与 Struct Schema 相匹配。
容量	一个实体中的 Struct 元素数量不得超过max_capacity 。
向量维度	向量值必须与为其向量子字段配置的dim 相匹配。
搜索模式的重复	如果您同时需要 EmbeddingList 搜索和元素级搜索，请将向量写入两个独立的向量子字段中。

索引和度量限制

StructArray 向量子字段可针对 EmbeddingList 搜索或元素级搜索进行索引。同一个向量子字段不能同时使用这两种度量族，因为每个向量字段或向量子字段仅接受一种索引。

搜索模式	度量族	结果级别
EmbeddingList 搜索	MAX_SIM、MAX_SIM_COSINE 、MAX_SIM_IP 、MAX_SIM_L2 或二进制MAX_SIM_* 度量	实体级结果。
元素级搜索	常规向量指标，例如L2 、IP 、COSINE 、HAMMING 或JACCARD	可包含匹配元素偏移量的元素级结果。

当需要同时使用这两种模式时，请使用独立的向量字段。例如，使用chunks[emb_list_vector] 进行 EmbeddingList 搜索，使用chunks[emb] 进行元素级搜索。

在规划 Collection 架构时，StructArray 向量字段应计入向量字段的总数。请确保向量字段和向量子字段的总数在目标版本和服务层级的限制范围内。

有关受支持的索引类型和指标类型的矩阵，请参阅《索引 StructArray 字段》。

搜索限制

搜索行为	支持与限制
基本 EmbeddingList 搜索	支持对使用MAX_SIM* 度量进行索引的StructArray向量进行搜索。返回实体级别的结果。
基本元素级搜索	支持在采用常规向量度量作为索引的 StructArray 向量子字段上进行搜索。可返回匹配元素的偏移量。
范围搜索	根据搜索模式以及目标版本对索引/度量的支持情况而定。若要了解针对元素级 StructArray 请求的混合搜索范围行为，请查阅目标版本文档。
分组搜索	元素级分组搜索可返回偏移量。针对元素级 StructArray 请求的混合搜索分组行为受版本限制。
混合搜索	混合搜索请求仅在目标版本支持该搜索组合时，才可包含 StructArray 向量子场请求。每个请求仍遵循已索引向量子场所属的指标家族。
偏移量输出	元素级搜索结果支持偏移量。EmbeddingList 搜索返回实体级结果，且不使用元素偏移量作为主要结果单位。

过滤器和操作符限制

StructArray标量过滤由StructArray操作符处理，例如element_filter 和MATCH_* 系列。详细的谓词支持矩阵请参见StructArray操作符文档。

总体而言：

• 仅在 StructArray 操作符内部使用 `$[subfield] `。

• 请使用标量子字段作为标量谓词的输入。

• 请勿将向量字段用作$[...] 标量谓词的输入。

• StructArray 元素级谓词不支持 JSON 路径语法、JSON 函数、数组容器函数、文本匹配函数、几何/GIS 函数以及 Timestamptz 表达式。

• 建议使用显式的布尔比较（如 `$[has_code] == true `），而非裸布尔表达式。

相关页面

1. 要创建 StructArray 字段，请参阅《创建 StructArray 字段》。

2. 要插入数据，请参阅《将数据插入 StructArray 字段》。

3. 要创建向量和标量索引，请参阅《索引 StructArray 字段》。

4. 要复习 StructArray 过滤器语法，请参阅《StructArray 操作符》。