StructArray の制限事項
StructArray のサポート範囲は、スキーマ定義、挿入ペイロード、インデックス作成、検索モード、および StructArray 固有のフィルターに及びます。本番環境で StructArray の動作に依存する前に、このページを制限事項のリファレンスとしてご利用ください。
StructArray の制限のほとんどは、StructArray スキーマモデル、ベクトルサブフィールドに選択した検索モード、およびコレクションが実行されている Milvus のバージョンのいずれかから生じます。
制限事項の概要
| 領域 | 制限 |
|---|---|
| スキーマの形状 | Structは、Arrayフィールドの要素型としてのみ使用できます。Structは、トップレベルのコレクションフィールドとしてはサポートされていません。 |
| サブフィールドのスキーマ | 同じ StructArray フィールド内のすべての Struct 要素は、1 つの事前定義された Struct スキーマを共有します。 |
| 容量 | max_capacity は必須であり、1つのエンティティが StructArray フィールドに格納できる Struct 要素の数を制限します。 |
| サブフィールドの変更 | StructArray フィールドが作成された後、その既存の StructArray フィールドにサブフィールドを追加することはできません。 |
| サブフィールドのパス | インデックス、検索対象、出力フィールド、およびフィルタには、chunks[emb] などのstructArray[subfield] パスを使用してください。chunks.emb は使用しないでください。 |
| シェイプの挿入 | StructArrayフィールドをオブジェクトの配列として挿入します。挿入ペイロード内ではパス構文を使用しないでください。 |
| ベクトルインデックス | ベクトルフィールドまたはベクトルサブフィールドは、1つのインデックスのみを受け付けます。EmbeddingList検索と要素レベルの検索には、それぞれ個別のベクトルサブフィールドを使用してください。 |
| 関数 | StructArrayフィールド内のフィールドまたはサブフィールドでは、フィールド関数はサポートされていません。 |
| Null 許容フィールド | Null 許容の StructArray フィールドはバージョンに依存します。サポートされている場合、Null は個々の Struct 要素ごとに独立して適用されるのではなく、StructArray フィールド全体に適用されます。 |
| 動的なフィールドの追加 | 既存のコレクションへの StructArray フィールドの追加はバージョン制限があり、追加するフィールドは null 許容である必要があります。 |
スキーマの制限
| 制限 | 詳細 |
|---|---|
| Struct はトップレベルのフィールド型ではありません。 | StructArray フィールドを、datatype=DataType.ARRAY 、element_type=DataType.STRUCT 、およびstruct_schema として作成します。 |
| すべての要素は 1 つのスキーマを共有します。 | StructArray フィールド内のすべての Struct 要素は、同じサブフィールドリストおよびサブフィールドのデータ型に従います。 |
max_capacity は必須です。 | 1 つのエンティティに含まれる 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 | サポート対象サブフィールドを xml-ph-0000@deepl.internal または xml-ph-0001@deepl.internal として定義します。 | サブフィールドを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 フィールドでは、Geometry サブフィールドおよび GIS 関数はサポートされていません。 |
Array | サポートされていません | StructArray フィールドでは、Text サブフィールドはサポートされていません。 |
Array | サポートされていません | StructArray フィールドでは、Timestamptz サブフィールドおよび時刻指定式はサポートされていません。 |
StructArray フィールドでは、Array 、ArrayOfVector 、Struct 、またはArrayOfStruct | サポートされていません | StructArray フィールドは、ネストされた配列、ベクトル配列、Struct、または Array-of-Struct サブフィールドをサポートしていません。 |
Null 許容および動的スキーマの制限
Null 許容 StructArray の動作および動的な StructArray フィールドの追加は、バージョンによって制限されます。
| 機能 | 制限 |
|---|---|
| Null 許容 StructArray フィールド | Null 許容 StructArray および Null 許容ベクトル配列のサポートが含まれるバージョンでのみ利用可能です。 |
| Python における null 値 | PythonでStructArrayのnull値を挿入するには、None を使用してください。Null やnull は使用しないでください。 |
| Nullの適用範囲 | NullはStructArrayフィールド全体に適用されます。たとえば、chunks=None は、chunks がNull可能である場合にのみ有効です。 |
| 部分的にNullなStructArrayの値 | StructArrayフィールドに有効な配列値が含まれている場合、同じ値内でnullのサブフィールド配列と有効なサブフィールド配列を混在させてはなりません。 |
| StructArray フィールドの動的追加 | 既存のコレクションへの StructArray フィールドの動的追加は、動的な StructArray フィールドのサポートが含まれるバージョンでのみサポートされています。 |
| 動的追加における null 許容要件 | 既存のコレクションに StructArray フィールドを追加する場合、既存のエンティティには新しいフィールドの値がないため、そのフィールドは null 許容でなければなりません。 |
| 動的追加後の既存のエンティティ | 既存のエンティティは、追加されたStructArrayフィールドのサブフィールド全体について、null を返します。 |
Milvus v3.0.x では、Null 許容の StructArray フィールド、Null 許容のベクトル配列、および動的な StructArray フィールドの追加が利用可能です。
Null 許容の StructArray フィールドを使用した挿入の例については、「StructArray フィールドへのデータの挿入」を参照してください。
挿入の制限
| 制限 | 詳細 |
|---|---|
| ペイロードの形状 | StructArray フィールドを、chunks: [{"text": "...", "emb": [...]}] のような Struct オブジェクトの配列として挿入します。 |
| サブフィールド名 | 各 Struct オブジェクト内では、chunks[text] のようなパスではなく、text やemb のようなサブフィールド名を使用してください。 |
| スキーマとの整合性 | 各 Struct 要素は、Struct スキーマと一致している必要があります。 |
| 容量 | 1 つのエンティティに含まれる Struct 要素の数は、max_capacity を超えてはなりません。 |
| ベクトルの次元 | ベクトル値は、そのベクトルサブフィールドに対して設定されたdim と一致している必要があります。 |
| 検索モードの重複 | EmbeddingList 検索と要素レベルの検索の両方が必要な場合は、ベクトルを 2 つの別々のベクトルサブフィールドに書き込んでください。 |
インデックスおよびメトリックの制限
StructArray ベクトルサブフィールドは、EmbeddingList 検索または要素レベル検索のいずれかに対してインデックス付けできます。各ベクトルフィールドまたはベクトルサブフィールドは 1 つのインデックスのみを受け入れるため、同じベクトルサブフィールドで両方のメトリックファミリーを使用することはできません。
| 検索モード | メトリックファミリー | 結果レベル |
|---|---|---|
| EmbeddingList検索 | MAX_SIM、MAX_SIM_COSINE 、MAX_SIM_IP 、MAX_SIM_L2 、またはバイナリMAX_SIM_* メトリック | エンティティレベルの結果。 |
| 要素レベルの検索 | L2 、IP 、COSINE 、HAMMING などの通常のベクトルメトリクス、またはJACCARD | 一致した要素のオフセットを含めることができる要素レベルの結果。 |
両方のモードが必要な場合は、別々のベクトルサブフィールドを使用してください。たとえば、EmbeddingList 検索にはchunks[emb_list_vector] を、要素レベルの検索にはchunks[emb] を使用します。
コレクションスキーマを設計する際、StructArray のベクトルサブフィールドはベクトルサブフィールドとしてカウントされます。ベクトルフィールドとベクトルサブフィールドの合計数が、対象のバージョンおよびサービスティアの制限内になるようにしてください。
サポートされているインデックス型およびメトリック型のマトリックスについては、「インデックスの StructArray フィールド」を参照してください。
検索の制限
| 検索の動作 | サポートと制限 |
|---|---|
| 基本的な EmbeddingList 検索 | MAX_SIM* メトリックでインデックス付けされた StructArray ベクトルサブフィールドでサポートされています。エンティティレベルの結果を返します。 |
| 基本的な要素レベル検索 | 通常のベクトルメトリクスでインデックス付けされたStructArrayベクトルサブフィールドでサポートされています。一致した要素のオフセットを返すことができます。 |
| 範囲検索 | 検索モードおよび対象バージョンのインデックス／メトリック対応状況に応じてサポートされます。要素レベルの StructArray リクエストにおけるハイブリッド検索範囲の動作については、対象バージョンを確認してください。 |
| グループ化検索 | 要素レベルのグループ化検索では、オフセットを返すことができます。要素レベルのStructArrayリクエストにおけるハイブリッド検索のグループ化動作は、バージョンに依存します。 |
| ハイブリッド検索 | ハイブリッド検索リクエストには、対象バージョンがその検索の組み合わせをサポートしている場合にのみ、StructArrayベクトルサブフィールドのリクエストを含めることができます。各リクエストは、引き続きインデックス化されたベクトルサブフィールドのメトリックファミリーに従います。 |
| オフセット出力 | オフセットは、要素レベルの検索結果で利用可能です。EmbeddingList検索はエンティティレベルの結果を返し、主要な結果単位として要素オフセットを使用しません。 |
フィルタおよび演算子の制限
StructArrayのスカラーフィルタリングは、element_filter やMATCH_* ファミリーなどのStructArray演算子によって処理されます。詳細な述語サポートマトリックスについては、「StructArray演算子」を参照してください。
大まかに言えば：
$[subfield]は、StructArray演算子の内部でのみ使用してください。スカラー述語には、スカラーサブフィールドを使用してください。
$[...]のスカラー述語の入力として、ベクトルサブフィールドを使用しないでください。JSONパス構文、JSON関数、配列コンテナ関数、テキスト一致関数、Geometry / GIS関数、およびTimestamptz式は、StructArrayの要素レベルの述語ではサポートされていません。
単純なブール式ではなく、
$[has_code] == trueなどの明示的なブール比較を使用することを推奨します。
関連ページ
StructArray フィールドを作成するには、「StructArray フィールドの作成」を参照してください。
データを挿入するには、「StructArray フィールドへのデータの挿入」を参照してください。
ベクトルおよびスカラーインデックスを作成するには、「StructArray フィールドのインデックス作成」を参照してください。
StructArray のフィルタ構文を確認するには、「StructArray 演算子」を参照してください。
