メインコンテンツまでスキップ

StructArray フィールドを作成する

1 つのエンティティに構造化要素の順序付きリストを格納する必要がある場合は、StructArray フィールドを作成します。StructArray フィールドは、要素タイプが Struct である Array フィールドです。各 Struct 要素は同じスキーマに従い、スカラーサブフィールド、ベクトルサブフィールド、またはその両方を含めることができます。

このページでは、Struct スキーマを定義し、それを StructArray フィールドとして追加し、後で検索やフィルタリングに使用するサブフィールドを選択する方法と、データを挿入またはインデックス作成する前に適用されるスキーマルールについて説明します。

事前準備​

Zilliz Cloud では、NULL 許容の StructArray フィールド、NULL 許容のベクトル配列、および StructArray フィールドの動的追加は、3.0.x 系の Milvus 3.0.0 以降を実行する On-Demand クラスターでサポートされています。Serving クラスターでは、これらの機能はサポートされていません。

作成、NULL 許容での作成、およびフィールド追加の例は、代替のワークフローです。同じコレクションに対してこれらを順番に実行しないでください。後続の例では、選択した言語のクライアント初期化を再利用してください。

このページでは、tech_articles という名前のコレクションを使用します。各エンティティは 1 つの技術記事を表し、chunks フィールドはチャンクレベルのデータを Struct 要素として格納します。

フィールド型用途
doc_idINT64記事の主キーです。
titleVARCHAR記事のタイトルです。
categoryVARCHAR記事レベルのカテゴリです。
title_vectorFLOAT_VECTOR記事レベルのベクトルフィールドです。後でハイブリッド検索の例で使用します。
chunksARRAYチャンクレベルのテキスト、メタデータ、埋め込みを格納する StructArray フィールドです。

chunks StructArray フィールドには、以下のサブフィールドが含まれます。

サブフィールド型用途
textVARCHARチャンクのテキストです。
sectionVARCHARindex、search、filter などのセクション名です。
pageINT64チャンクのページ番号または論理位置です。
quality_scoreFLOATスカラーフィルタリングと範囲の例で使用されるチャンクレベルのスコアです。
has_codeBOOLチャンクにコードが含まれているかどうかです。
emb_list_vectorFLOAT_VECTORMAX_SIM* メトリクスを使用した EmbeddingList 検索用のベクトルサブフィールドです。
embFLOAT_VECTOR通常のベクトルメトリクスを使用した要素レベル検索用のベクトルサブフィールドです。
📘Notes

ベクトルフィールドまたはベクトルサブフィールドは、1 つのインデックスのみを受け付けます。EmbeddingList 検索と要素レベル検索の両方が必要な場合は、2 つの個別のベクトルサブフィールドを定義します。この例では、chunks[emb_list_vector] は EmbeddingList 検索用、chunks[emb] は要素レベル検索用です。

サポートされるサブフィールドのデータ型​

StructArray フィールドは、Struct の各サブフィールドに対して 1 つの配列値を格納します。Struct スキーマを定義するときは、サブフィールドの型を、サポート対象のスカラー型ファミリーとベクトル型ファミリーから選択します。

Struct サブフィールドの物理型サポート注意
Array<Bool>サポート対象サブフィールドを DataType.BOOL として定義します。
Array<Int8/Int16/Int32/Int64>サポート対象サブフィールドを DataType.INT8、DataType.INT16、DataType.INT32、DataType.INT64 のいずれかとして定義します。
Array<Float/Double>サポート対象サブフィールドを DataType.FLOAT または DataType.DOUBLE として定義します。
Array<VarChar>サポート対象サブフィールドを DataType.VARCHAR として定義し、max_length を設定します。
ArrayOfVector<FloatVector>サポート対象サブフィールドを DataType.FLOAT_VECTOR として定義し、dim を設定します。
ArrayOfVector<Float16Vector>サポート対象サブフィールドを DataType.FLOAT16_VECTOR として定義し、dim を設定します。
ArrayOfVector<BFloat16Vector>サポート対象サブフィールドを DataType.BFLOAT16_VECTOR として定義し、dim を設定します。
ArrayOfVector<Int8Vector>サポート対象サブフィールドを DataType.INT8_VECTOR として定義し、dim を設定します。
ArrayOfVector<BinaryVector>サポート対象サブフィールドを DataType.BINARY_VECTOR として定義し、dim を設定します。
ArrayOfVector<SparseFloatVector>非サポートスパースベクトルサブフィールドは StructArray フィールドではサポートされていません。
Array<String>非サポートString ではなく VARCHAR を使用します。
Array<JSON>非サポートJSON サブフィールドは StructArray フィールドではサポートされていません。
Array<Geometry>非サポートGeometry サブフィールドと GIS 関数は StructArray フィールドではサポートされていません。
Array<Text>非サポートText サブフィールドは StructArray フィールドではサポートされていません。
Array<Timestamptz>非サポートTimestamptz サブフィールドと時間固有の式は StructArray フィールドではサポートされていません。
ネストされた Array、ArrayOfVector、Struct、または ArrayOfStruct非サポートStructArray フィールドでは、ネストされた配列、ベクトル配列、Struct、または Array-of-Struct のサブフィールドはサポートされていません。

バージョン固有のサポート、null 許容の動作、その他の制限については、StructArray Limits を参照してください。

StructArray フィールドを含むコレクションを作成する​

StructArray フィールドを作成するには、まず各要素が使用する Struct スキーマを定義します。次に、Array フィールドを追加し、その要素タイプを Struct に設定します。

  1. コレクションスキーマを作成します。

  2. 主キーや記事レベルのフィールドなど、コレクションレベルのフィールドを追加します。

  3. StructArray フィールド内に格納する要素の Struct スキーマを作成します。

  4. Struct スキーマにスカラーサブフィールドとベクトルサブフィールドを追加します。

  5. element_type=DataType.STRUCT を指定して Array フィールドを追加します。

  6. struct_schema を Struct スキーマに設定します。

  7. max_capacity を設定して、各エンティティがフィールドに格納できる Struct 要素の数を制限します。

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN",
)

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 許容にする​

NULL 許容の StructArray フィールドでは、上記の可用性の条件に従い、エンティティはフィールド全体に NULL を格納できます。以下は、前述のコレクション作成例を完全に置き換える代替例です。tech_articles が存在しない場合にのみ実行してください。コレクションを作成する前に、StructArray の親で nullable を設定します。

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN",
)

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,
    nullable=True,
    max_capacity=1000,
)

client.create_collection(
    collection_name="tech_articles",
    schema=schema,
)
📘Notes

NULL は StructArray フィールド全体に適用されます。個々の Struct サブフィールドを独立して NULL 許容に設定しないでください。有効な StructArray 値を指定する場合は、NULL のサブフィールド配列と有効なサブフィールド配列を混在させないでください。詳細は、StructArray Limits を参照してください。

既存のコレクションに StructArray フィールドを追加する​

上記の可用性の条件に従い、既存のコレクションに StructArray フィールドを追加できます。追加する StructArray フィールドは NULL 許容である必要があります。これは、コレクションに既に存在するエンティティには、新しいフィールドの値がないためです。

この代替ワークフローでは、最初の例に含まれる 4 つのコレクションレベルのフィールドを持ち、chunks フィールドを持たない tech_articles から始めます。選択した言語で初期化したクライアントを再利用します。完全な Struct スキーマを定義し、親を NULL 許容としてマークしたうえでフィールドを追加します。このスキーマ操作は、コレクションの動的フィールド設定（enable_dynamic_field）とは独立しており、Struct 内で任意のサブフィールドを有効にするものではありません。

python
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 フィールドを作成した後は、その既存のフィールドにサブフィールドを追加することはできません。次の別の例では、chunks を、元の 7 つのサブフィールドと新しい source 文字列サブフィールドを含むスキーマに置き換えます。

フィールドを削除すると、そのデータも削除されます。再度追加しても以前の値は復元されません。必要なデータを保持し、Alter コレクション スキーマ の事前準備に従ってから、置き換えたフィールドにデータを再入力し、インデックスを再作成してください。この例ではコレクションレベルの title_vector フィールドを保持するため、chunks を削除してもコレクションからすべてのベクトルフィールドが削除されることはありません。

python
updated_chunk_schema = client.create_struct_field_schema()
updated_chunk_schema.add_field(
    field_name="text",
    datatype=DataType.VARCHAR,
    max_length=65535,
)
updated_chunk_schema.add_field(
    field_name="section",
    datatype=DataType.VARCHAR,
    max_length=128,
)
updated_chunk_schema.add_field(
    field_name="page",
    datatype=DataType.INT64,
)
updated_chunk_schema.add_field(
    field_name="quality_score",
    datatype=DataType.FLOAT,
)
updated_chunk_schema.add_field(
    field_name="has_code",
    datatype=DataType.BOOL,
)
updated_chunk_schema.add_field(
    field_name="emb_list_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)
updated_chunk_schema.add_field(
    field_name="emb",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

updated_chunk_schema.add_field(
    field_name="source",
    datatype=DataType.VARCHAR,
    max_length=256,
)

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 の要素タイプとして使用します。StructArray フィールドは、element_type=STRUCT を指定した 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 を設定してください。

  • 1 つのベクトルサブフィールドを EmbeddingList 検索と要素レベル検索の両方に使用する。

  • ベクトルサブフィールドのみを追加し、section、quality_score、has_code などフィルタリングに必要なスカラーサブフィールドを忘れる。

  • ベクトルサブフィールドを $[...] スカラー述語の入力として扱う。ベクトル検索にはベクトルサブフィールドを使用し、スカラー述語にはスカラーサブフィールドを使用してください。

  • フィールドの作成後に、既存の StructArray フィールドに新しいサブフィールドを追加できると想定する。

  • 必須のパス構文 chunks[emb] または chunks[emb_list_vector] を使用せず、chunks.emb または chunks.emb_list_vector を使用する。

  • null 許容の StructArray の動作がすべてのターゲットバージョンで利用可能であると見なす。

次のステップ​

  1. StructArray フィールドにネストされたデータを挿入するには、Insert Data into StructArray Fields を参照してください。

  2. ベクトルインデックスとスカラーインデックスを作成するには、Index StructArray Fields を参照してください。

  3. StructArray のベクトルサブフィールドを検索するには、Basic ベクトル Search with StructArray を参照してください。

  4. サポートされるデータ型、null 許容の動作、バージョン固有の制限を確認するには、StructArray Limits を参照してください。

このページは役に立ちましたか？
Ctrl I