StructArray 概述

当某个实体需要存储结构化元素的有序列表时，应使用 StructArray，例如包含多个片段的文档、包含多个视觉片段的页面，或包含多个视频片段的视频。StructArray 将这些元素保存在父实体内部，同时仍允许对每个元素内部的字段进行向量搜索和标量过滤。

什么是 StructArray？

StructArray（也称为结构体数组）在每个实体中存储一组有序的 Struct 元素。数组中的每个 Struct 元素都遵循相同的 Schema。一个 Struct 元素可以包含标量子字段、向量字段，或两者兼有。

例如，一个Collection可以将一篇文章作为实体存储，并将该文章的片段存储在名为chunks 的StructArray字段中。每个片段可以包含文本、章节元数据、质量评分以及一个或多个向量嵌入。

{
  "doc_id": 1,
  "title": "Vector search tuning guide",
  "category": "search",
  "title_vector": [0.10, 0.20, 0.30, 0.40],
  "chunks": [
    {
      "text": "Use HNSW efSearch to trade recall for latency.",
      "section": "index",
      "page": 1,
      "quality_score": 0.92,
      "has_code": true,
      "emb_list_vector": [0.11, 0.21, 0.31, 0.41],
      "emb": [0.12, 0.20, 0.33, 0.39]
    },
    {
      "text": "Range search returns vectors within a distance boundary.",
      "section": "search",
      "page": 2,
      "quality_score": 0.86,
      "has_code": false,
      "emb_list_vector": [0.18, 0.23, 0.29, 0.36],
      "emb": [0.19, 0.24, 0.30, 0.37]
    }
  ]
}

何时使用 StructArray

当您希望返回的自然单位大于用于搜索或过滤的自然单位时，请使用 StructArray。

用例	StructArray 的优势	典型的 StructArray 字段
文档检索	将一个文档作为实体存储，同时对其各分块进行搜索。	chunks
延迟交互检索	将文档或页面存储为Embeddings列表，并使用MAX_SIM* 进行评分。	chunks[emb_list_vector] 或patches[emb]
元素级检索	返回相关性最高的片段、剪辑、补丁或观测结果，并包含其数组偏移量。	chunks[emb]
结构化过滤	根据 Struct 元素内的标量子字段（如 section、score、page 或 flags）进行过滤。	chunks[section],chunks[quality_score]
减少重复的父级结果	将子元素保留在同一父实体下，而不是将每个子元素作为单独的一行存储。	chunks,clips,patches

决策矩阵

使用以下矩阵选择合适的 StructArray 路径。

目标	推荐路径	结果粒度	从这里开始
模型一个具有多个结构化子对象的父对象。	创建一个 StructArray 字段。	实体包含有序的 Struct 元素。	创建 StructArray 字段
插入包含嵌套子数据的父记录。	插入其 StructArray 字段为 Struct 对象列表的实体。	实体级插入。	将数据插入 StructArray 字段
运行 ColBERT、ColPali 或文档级延迟交互检索。	使用MAX_SIM* 索引进行EmbeddingList搜索。	实体级别。	使用Embeddings列表进行搜索
搜索单个片段、剪辑或片段。	使用常规向量度量进行元素级搜索。	结构元素级别，如有偏移量则包含偏移量。	使用 StructArray 进行基本向量搜索
将元素级向量搜索限制为满足标量条件的元素。	使用element_filter 。	元素级过滤；结果形状取决于搜索类型。	使用 StructArray 进行过滤搜索
根据满足条件的 Struct 元素数量来选择实体。	使用MATCH_ANY 、MATCH_ALL 、MATCH_LEAST 、MATCH_MOST 或MATCH_EXACT 。	实体级别。	StructArray 操作符
在 StructArray 向量上使用分数或距离边界。	使用元素级范围搜索。	结构元素级别。	使用 StructArray 进行范围搜索
在元素级搜索后，每个父实体最多返回一个结果。	使用主键进行分组搜索。	分组后的实体级别。	使用 StructArray 进行分组搜索
将 StructArray 元素搜索与另一个向量字段结合使用。	使用混合搜索，其中一个 AnnSearchRequest 针对 StructArray 的向量字段。	元素级子搜索，实体级重新排序。	基于 StructArray 的混合搜索

了解两种搜索模型

EmbeddingList 搜索	元素级搜索
EmbeddingList搜索将StructArray向量子字段中的向量视为父实体的单一嵌入列表。查询同样是一个嵌入列表。Milvus通过MAX_SIM* 度量将查询嵌入列表与存储的嵌入列表进行比对，并返回匹配的实体。 查询数据：嵌入列表。 度量家族：MAX_SIM* 。 结果粒度：实体级别。 最适合：文档级或页面级的后期交互检索。	元素级搜索将每个 Struct 元素视为独立的向量搜索候选项。每个命中结果代表 StructArray 字段中匹配的元素，且未分组的结果可显示该元素的偏移量。 查询数据：常规向量。 度量标准家族：常规向量度量标准。 结果粒度：Struct 元素级别。 最适合：片段级、剪辑级或补丁级检索。

文档地图

StructArray 文档分为建模页面和搜索页面。请使用建模页面来定义和准备数据，使用搜索页面来选择合适的检索和过滤行为。

Area	页面	用途
建模	创建 StructArray 字段	定义结构体 Schema 并添加一个 StructArray 字段。
建模	将数据插入 StructArray 字段	准备并插入嵌套的 StructArray 数据。
建模	为 StructArray 字段建立索引	在 StructArray 子字段上创建向量和标量索引。
参考	StructArray 限制	检查Schema、数据类型、索引、搜索、过滤和版本限制。
搜索	使用 StructArray 进行基本向量搜索	比较 EmbeddingList 搜索与元素级向量搜索。
搜索	使用 StructArray 进行范围搜索	在 StructArray 向量子字段中使用范围约束。
搜索	使用 StructArray 进行分组搜索	按主键对元素级搜索结果进行分组。
搜索	结合 StructArray 进行混合搜索	将 StructArray 元素级搜索与其他向量搜索相结合。
搜索	使用 StructArray 进行过滤搜索	在搜索、查询和混合搜索中使用 StructArray 过滤器。
搜索	使用Embeddings列表进行搜索	利用 StructArray 构建 ColBERT 和 ColPali 风格的检索系统。
筛选	StructArray 操作符	element_filter 和MATCH_* 操作符的参考语法。

首先需检查的关键限制

• Struct 可用作 Array 字段的元素类型，但不能用作顶级 Collection 字段。

• 同一 StructArray 字段中的所有 Struct 元素共享一个预定义的 Schema。

• 向量字段需要索引。EmbeddingList 搜索使用MAX_SIM* 度量，而元素级搜索则使用常规向量度量。

• element_filter MATCH_* 适用于 StructArray 字段内的标量子字段。请仅在这些操作符内部使用 。$[subfield]

• 某些搜索组合受版本限制或仅在特定模式下可用。在依赖范围搜索、分组搜索、混合搜索、可空字段或动态添加的字段之前，请先查阅StructArray 限制。

后续步骤

1. 要设计 Schema，请阅读《创建 StructArray 字段》。

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

3. 要选择索引，请阅读《为StructArray 字段建立索引》。

4. 若要搜索 StructArray 向量子字段，请从《StructArray 的基本向量搜索》开始。

5. 若要过滤 StructArray 标量子字段，请参阅《StructArray 操作符》和《使用 StructArray 进行过滤搜索》。