StructArray 限制

StructArray 的支援範圍涵蓋模式定義、插入資料、建立索引、搜尋模式，以及 StructArray 專屬的篩選器。在生產環境中依賴 StructArray 的運作行為之前，請將此頁面作為限制參考。

大多數 StructArray 限制源自以下三個方面之一：StructArray 模式模型、您為向量子欄位選擇的搜尋模式，以及您的集合所運行的 Milvus 版本。

限制一覽

範疇	限制
模式結構	Struct 僅可作為 Array 欄位的元素類型使用。Struct 不支援作為頂層集合欄位。
子欄位模式	同一 StructArray 字段中的所有 Struct 元素共用一個預定義的 Struct 模式。
容量	max_capacity 此屬性為必填，並限制單一實體可在 StructArray 欄位中儲存的 Struct 元素數量。
子欄位變更	StructArray 欄位建立後，您無法向該現有的 StructArray 欄位新增子欄位。
子欄位路徑	請使用structArray[subfield] 路徑（例如chunks[emb] ）作為索引、搜尋目標、輸出欄位及篩選條件。請勿使用chunks.emb 。
插入結構	請將 StructArray 欄位插入為物件陣列。請勿在插入載入資料中使用路徑語法。
向量索引	向量欄位或向量子欄位僅接受一個索引。請分別使用不同的向量子欄位進行 EmbeddingList 搜尋與元素層級搜尋。
函式	StructArray 欄位內的欄位或子欄位不支援欄位函式。
可為空的欄位	可為空的 StructArray 欄位受版本限制。當支援此功能時，空值適用於整個 StructArray 欄位，而非獨立套用至個別的 Struct 元素。
動態新增欄位	將 StructArray 欄位新增至現有集合的功能受版本限制，且新增的欄位必須為可為空欄位。

架構限制

限制	詳細資訊
Struct 並非頂層欄位類型。	建立一個 StructArray 欄位，格式為datatype=DataType.ARRAY ，並使用element_type=DataType.STRUCT 及struct_schema 。
所有元素共用一個架構。	StructArray 欄位中的每個 Struct 元素均遵循相同的子欄位清單和子欄位資料類型。
max_capacity 此欄位為必填。	單一實體中的 Struct 元素數量不得超過為 StructArray 欄位所設定的max_capacity 。
現有的子欄位是固定的。	您無法將新子欄位附加到現有的 StructArray 欄位上。若要變更子欄位架構，請刪除 StructArray 欄位，然後使用更新的架構重新新增該欄位。
不支援嵌套的 StructArray。	StructArray 欄位不得包含嵌套的Array 、ArrayOfVector 、Struct 或ArrayOfStruct 子欄位。
StructArray 內部不支援函式。	請勿為 StructArray 欄位或其子欄位定義欄位函式。

有關模式建立的範例，請參閱「建立 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 欄位不支援嵌套的陣列、向量陣列、Struct 或 Array-of-Struct 子欄位。

可為空與動態模式限制

可為空的 StructArray 行為以及動態 StructArray 欄位的新增功能，受版本限制。

功能	限制
可為空的 StructArray 欄位	僅在包含可為空 StructArray 及可為空向量陣列支援的版本中提供。
Python 中的空值	請使用 `None ` 在 Python 中插入空的 StructArray 值。請勿使用 `Null ` 或 `null`。
空值作用域	空值適用於整個 StructArray 欄位。例如，chunks=None 僅在chunks 為可為空時才有效。
部分可為空的 StructArray 值	當 StructArray 欄位包含有效的陣列值時，請勿在同一個值中混合使用可為 null 的子欄位陣列與有效的子欄位陣列。
動態新增 StructArray 欄位	僅在包含動態 StructArray 欄位支援的版本中，才支援將 StructArray 欄位新增至現有集合。
動態新增的可為空要求	新增至現有集合的 StructArray 欄位必須為可為空，因為現有實體對於新欄位尚無值。
動態新增後的既有實體	現有實體針對新增的 StructArray 欄位及其所有子欄位，均會回傳 `null `。

在 Milvus v3.0.x 中，支援可為空的 StructArray 欄位、可為空的向量陣列，以及動態新增 StructArray 欄位。

有關可為空 StructArray 欄位的插入範例，請參閱《將資料插入 StructArray 欄位》。

插入限制

限制	詳細資訊
有效載荷形狀	將 StructArray 欄位插入為 Struct 物件的陣列，例如chunks: [{"text": "...", "emb": [...]}] 。
子欄位名稱	在每個 Struct 物件內部，請使用子欄位名稱（例如text 和emb ），而非路徑（例如chunks[text] ）。
架構對齊	每個 Struct 元素都必須符合 Struct 模式。
容量	單一實體中的 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] 進行元素層級搜尋。

在規劃您的集合架構時，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 運算子》。