StructArrayフィールドの作成
1つのエンティティに、構造化された要素の順序付きリストを含める必要がある場合は、StructArrayフィールドを作成します。StructArrayフィールドは、要素型がStructであるArrayフィールドです。各Struct要素は同じスキーマに従い、スカラーサブフィールド、ベクトルサブフィールド、またはその両方を含むことができます。
このページでは、Structスキーマを定義し、それをStructArrayフィールドとして追加し、後の検索やフィルタリング用にサブフィールドを選択する方法、およびデータの挿入やインデックス作成前に適用されるスキーマ規則について解説します。
開始する前に
このページでは、tech_articles という名前のコレクションを使用しています。各エンティティは1つの技術記事を表しており、chunks フィールドには、チャンクレベルのデータがStruct要素として格納されています。
| フィールド | タイプ | 目的 |
|---|---|---|
doc_id | INT64 | 記事の主キー。 |
title | VARCHAR | 記事のタイトル。 |
category | VARCHAR | 記事レベルのカテゴリ。 |
title_vector | FLOAT_VECTOR | 記事レベルのベクトルフィールド。後述のハイブリッド検索の例で使用されます。 |
chunks | ARRAY | チャンクレベルのテキスト、メタデータ、および埋め込みを格納する StructArray フィールド。 |
chunks StructArray フィールドには、以下のサブフィールドが含まれます。
| サブフィールド | タイプ | 目的 |
|---|---|---|
text | VARCHAR | チャンクのテキスト。 |
section | VARCHAR | index 、search 、filter などのセクション名。 |
page | INT64 | チャンクのページ番号または論理的な位置。 |
quality_score | FLOAT | スカラーフィルタリングや範囲の例で使用されるチャンクレベルのスコア。 |
has_code | BOOL | チャンクにコードが含まれているかどうか。 |
emb_list_vector | FLOAT_VECTOR | MAX_SIM* メトリックを使用した EmbeddingList 検索のためのベクトルサブフィールド。 |
emb | FLOAT_VECTOR | 通常のベクトルメトリックを使用した要素レベル検索用のベクトルサブフィールド。 |
ベクトルフィールドまたはベクトルサブフィールドは、1 つのインデックスのみを受け入れます。EmbeddingList 検索と要素レベルの検索の両方が必要な場合は、2 つの別々のベクトルサブフィールドを定義してください。この例では、chunks[emb_list_vector] は EmbeddingList 検索用、chunks[emb] は要素レベルの検索用です。
サポートされているサブフィールドのデータ型
StructArrayフィールドは、各Structサブフィールドに対して1つの配列値を格納します。Structスキーマを定義する際は、サポートされているスカラーおよびベクトルファミリーからサブフィールドの型を選択してください。
| 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 許容の挙動、およびその他の制限については、「StructArray の制限」を参照してください。
StructArray フィールドを含むコレクションを作成する
StructArray フィールドを作成するには、まず各要素で使用される Struct スキーマを定義します。次に、Array フィールドを追加し、その要素型を Struct に設定します。
コレクションスキーマを作成します。
プライマリキーや記事レベルのフィールドなど、コレクションレベルのフィールドを追加します。
StructArray フィールド内に格納される要素用の Struct スキーマを作成します。
Structスキーマにスカラーおよびベクトルのサブフィールドを追加します。
element_type=DataType.STRUCTを指定してArrayフィールドを追加します。struct_schemaを Struct スキーマに設定します。max_capacityを設定して、各エンティティがこのフィールドに格納できる Struct 要素の数を制限します。
from pymilvus import MilvusClient, DataType
client = MilvusClient(
uri="http://localhost:19530",
token="root:Milvus",
)
schema = client.create_schema(
auto_id=False,
enable_dynamic_field=False,
)
# Collection-level fields.
schema.add_field(
field_name="doc_id",
datatype=DataType.INT64,
is_primary=True,
)
schema.add_field(
field_name="title",
datatype=DataType.VARCHAR,
max_length=512,
)
schema.add_field(
field_name="category",
datatype=DataType.VARCHAR,
max_length=128,
)
schema.add_field(
field_name="title_vector",
datatype=DataType.FLOAT_VECTOR,
dim=4,
)
# Struct schema used by each element in the StructArray field.
chunk_schema = client.create_struct_field_schema()
chunk_schema.add_field(
field_name="text",
datatype=DataType.VARCHAR,
max_length=65535,
)
chunk_schema.add_field(
field_name="section",
datatype=DataType.VARCHAR,
max_length=128,
)
chunk_schema.add_field(
field_name="page",
datatype=DataType.INT64,
)
chunk_schema.add_field(
field_name="quality_score",
datatype=DataType.FLOAT,
)
chunk_schema.add_field(
field_name="has_code",
datatype=DataType.BOOL,
)
# Vector subfield for EmbeddingList search.
chunk_schema.add_field(
field_name="emb_list_vector",
datatype=DataType.FLOAT_VECTOR,
dim=4,
)
# Vector subfield for element-level search.
chunk_schema.add_field(
field_name="emb",
datatype=DataType.FLOAT_VECTOR,
dim=4,
)
# Add the StructArray field.
schema.add_field(
field_name="chunks",
datatype=DataType.ARRAY,
element_type=DataType.STRUCT,
struct_schema=chunk_schema,
max_capacity=1000,
)
client.create_collection(
collection_name="tech_articles",
schema=schema,
)
StructArray フィールドのパスの理解
StructArray フィールドを作成したら、structArray[subfield] パス構文を使用してそのサブフィールドを参照します。インデックスの作成、ベクトルサブフィールドの検索、サブフィールドの出力、またはスカラーフィルタの構築を行う際は、この構文を使用してください。
| パス | 意味 | 一般的な使用法 |
|---|---|---|
chunks[text] | 各 Struct 要素内の `text ` サブフィールド。 | 出力フィールドまたはスカラーフィルタリング。 |
chunks[section] | 各チャンクのセクションラベル。 | スカラーフィルタリング。 |
chunks[quality_score] | チャンクレベルの品質スコア。 | スカラーフィルタリングまたはスカラーインデックス。 |
chunks[emb_list_vector] | 埋め込みリストとして使用されるベクトルサブフィールド。 | MAX_SIM* による EmbeddingList の検索。 |
chunks[emb] | 各 Struct 要素が個別に使用するベクトルサブフィールド。 | 要素レベルのベクトル検索。 |
StructArrayフィールドをNull可能にする
Milvus v3.0.x では、Null 許容の StructArray フィールドがサポートされています。Null 許容の StructArray フィールドを使用すると、エンティティは StructArray フィールド全体に対して `null ` を格納できるようになります。
schema.add_field(
field_name="chunks",
datatype=DataType.ARRAY,
element_type=DataType.STRUCT,
struct_schema=chunk_schema,
max_capacity=1000,
nullable=True,
)
警告
Nullable StructArray フィールドは、Milvus v3.0.x でのみ利用可能です。Nullable StructArray フィールドの場合、エンティティは有効な StructArray 値を指定するか、フィールド全体を `null` に設定することができます。有効な StructArray 値を挿入する場合、すべてのサブフィールドは null であるか、有効な値を持つ必要があります。 一部のサブフィールドがnullに設定され、他のサブフィールドが有効な値に設定されたエンティティを挿入すると、エラーが発生します。詳細については、「StructArrayの制限」を参照してください。
既存のコレクションに StructArray フィールドを追加する
Milvus v3.0.x では、既存のコレクションに StructArray フィールドを追加することが可能です。コレクションにすでに存在するエンティティには新しいフィールドの値がないため、追加する StructArray フィールドは null 許容型である必要があります。
既存のコレクションにStructArrayフィールドを追加するには、まずStructスキーマを定義します。次に、add_collection_struct_field() を呼び出し、nullable=True を設定します。
chunk_schema = client.create_struct_field_schema()
chunk_schema.add_field(
field_name="text",
datatype=DataType.VARCHAR,
max_length=65535,
)
chunk_schema.add_field(
field_name="section",
datatype=DataType.VARCHAR,
max_length=128,
)
chunk_schema.add_field(
field_name="page",
datatype=DataType.INT64,
)
chunk_schema.add_field(
field_name="quality_score",
datatype=DataType.FLOAT,
)
chunk_schema.add_field(
field_name="has_code",
datatype=DataType.BOOL,
)
chunk_schema.add_field(
field_name="emb_list_vector",
datatype=DataType.FLOAT_VECTOR,
dim=4,
)
chunk_schema.add_field(
field_name="emb",
datatype=DataType.FLOAT_VECTOR,
dim=4,
)
client.add_collection_struct_field(
collection_name="tech_articles",
field_name="chunks",
struct_schema=chunk_schema,
max_capacity=1000,
nullable=True,
)
StructArrayフィールドが追加されると、既存のエンティティは、その新しいフィールドのすべてのサブフィールドについてnull を返します。
StructArrayフィールドが作成された後、その既存のStructArrayフィールドに新しいサブフィールドを追加することはできません。後で追加の要素属性が必要になった場合は、drop_collection_field() を呼び出してStructArrayフィールドを削除し、更新されたStructスキーマを使用して新しいStructArrayフィールドを追加してください。
client.drop_collection_field(
collection_name="tech_articles",
field_name="chunks",
)
client.add_collection_struct_field(
collection_name="tech_articles",
field_name="chunks",
struct_schema=updated_chunk_schema,
max_capacity=1000,
nullable=True,
)
スキーマのルール
| ルール | 説明 |
|---|---|
| Struct は Array 要素型として使用されます。 | element_type=STRUCT を使用して、StructArray フィールドを Array フィールドとして作成します。Struct をトップレベルのコレクションフィールドとして作成しないでください。 |
| すべての要素は 1 つのスキーマを共有します。 | 同じ StructArray フィールド内のすべての Struct 要素は、そのフィールドに対して定義された Struct スキーマに従います。 |
max_capacity は必須です。 | これは、各エンティティが StructArray フィールドに格納できる Struct 要素の数を制限するものです。 |
| サポートされているサブフィールド型のみ使用できます。 | StructArray でサポートされているスカラーおよびベクトルサブフィールド型を使用してください。JSON、Geometry、Text、Timestamptz、SparseFloatVector、またはネストされた Struct / Array サブフィールドは定義しないでください。 |
| ベクトルサブフィールドは、検索の前にインデックスを作成する必要があります。 | ベクトル検索を実行する前に、chunks[emb_list_vector] やchunks[emb] などのパスにインデックスを作成してください。 |
| 1 つのベクトルサブフィールドには 1 つのインデックスがあります。 | EmbeddingList 検索と要素レベルの検索の両方が必要な場合は、2 つの別々のベクトルサブフィールドを作成してください。 |
| 既存の StructArray サブフィールドは固定されています。 | StructArray フィールドを作成した後、その同じ StructArray フィールドにサブフィールドを追加することはできません。 |
| Struct 内での関数の使用はサポートされていません。 | StructArray フィールド内のフィールドやサブフィールドに対して関数を定義しないでください。 |
| スカラーサブフィールドは、フィルタの要件に合致している必要があります。 | section 、quality_score 、has_code などのフィールドは、後でフィルタリング、グループ化、または出力を行う必要がある場合にのみ追加してください。 |
よくある間違い
DataType.STRUCTを、Array フィールドの要素型として使用するのではなく、最上位のコレクションフィールドとして作成してしまう。StructArray フィールドで
max_capacityを設定し忘れる。JSON、Geometry、Text、Timestamptz、SparseFloatVector、ネストされた Array、ネストされた Struct、または Array-of-Struct など、サポートされていないサブフィールド型を定義してしまう。
Stringをサブフィールド型として使用している。VARCHARを使用し、max_lengthを設定してください。EmbeddingList検索と要素レベル検索の両方に、1つのベクトルサブフィールドを使用している。
ベクトルサブフィールドのみを追加し、
section、quality_score、has_codeなど、フィルタリングに必要なスカラーサブフィールドを省略すること。ベクトルサブフィールドを、
$[...]のようなスカラー述語の入力として扱う。ベクトル検索にはベクトルサブフィールドを、スカラー述語にはスカラーサブフィールドを使用する。フィールドの作成後、既存の StructArray フィールドに新しいサブフィールドを追加できるものと仮定する。
必須のパス構文 `
chunks[emb]` または `chunks[emb_list_vector]` の代わりに、`chunks.emb` または `chunks.emb_list_vector` を使用している。Null 許容型 StructArray の挙動を、すべてのターゲットバージョンで利用可能であるかのように扱う。
次の手順
StructArray フィールドにネストされたデータを挿入するには、「StructArray フィールドへのデータの挿入」を参照してください。
ベクトルおよびスカラーインデックスを作成するには、「StructArray フィールドのインデックス付け」を参照してください。
StructArray のベクトルサブフィールドを検索するには、「StructArray を使用した基本的なベクトル検索」を参照してください。
サポートされているデータ型、Null 許容の挙動、およびバージョン固有の制限事項を確認するには、「StructArray の制限事項」を参照してください。
