StructArrayフィールドへのデータの挿入

各エンティティが構造化された要素の順序付きリストを含む場合、StructArrayフィールドにデータを挿入します。挿入ペイロードにおいて、StructArrayフィールドはオブジェクトの配列として表現されます。各オブジェクトは1つのStruct要素を表し、コレクションスキーマで定義されたStructサブフィールド名を使用します。

このページでは、「StructArrayフィールドの作成」のtech_articles コレクションを使用しています。各エンティティは技術記事であり、chunks フィールドには、記事のチャンクがStruct要素として格納されています。

開始する前に

コレクションスキーマに、chunks というStructArrayフィールドがすでに含まれていることを確認してください。

フィールド	タイプ	値の挿入
`doc_id`	`INT64`	記事 ID。
`title`	`VARCHAR`	記事のタイトル。
`category`	`VARCHAR`	記事のカテゴリ。
`title_vector`	`FLOAT_VECTOR`	記事レベルの埋め込み。
`chunks`	`ARRAY`	チャンク・オブジェクトのリスト。

chunks 内の各オブジェクトは、Struct スキーマに従う必要があります。

サブフィールド	タイプ	挿入値
`text`	`VARCHAR`	チャンクテキスト。
`section`	`VARCHAR`	`index` 、`search` 、`filter` などのセクション名。
`page`	`INT64`	ページ番号または論理的な位置。
`quality_score`	`FLOAT`	チャンクレベルのスコア。
`has_code`	`BOOL`	チャンクにコードが含まれているかどうか。
`emb_list_vector`	`FLOAT_VECTOR`	EmbeddingList 検索用に記述されたベクトル。
`emb`	`FLOAT_VECTOR`	要素レベルの検索用に記述されたベクトル。

挿入ペイロードでは、chunks は、値が Struct オブジェクトの配列である通常のフィールドです。各オブジェクト内では、text やemb などのサブフィールド名を使用してください。chunks[text] やchunks[emb] などのパス構文は、挿入後のインデックスの作成、検索の実行、フィルタの構築、または出力フィールドの指定時にのみ使用してください。

挿入ペイロードの形状を理解する

chunks の値は、Struct要素の配列です。各要素は、キーがサブフィールド名であるオブジェクトです。

{
  "doc_id": 1,
  "title": "StructArray indexing patterns",
  "category": "index",
  "title_vector": [0.12, 0.08, 0.32, 0.48],
  "chunks": [
    {
      "text": "Create one index for each vector subfield.",
      "section": "index",
      "page": 1,
      "quality_score": 0.96,
      "has_code": false,
      "emb_list_vector": [0.10, 0.20, 0.30, 0.40],
      "emb": [0.10, 0.20, 0.30, 0.40]
    },
    {
      "text": "Use MAX_SIM metrics for EmbeddingList search.",
      "section": "index",
      "page": 2,
      "quality_score": 0.91,
      "has_code": true,
      "emb_list_vector": [0.16, 0.24, 0.35, 0.45],
      "emb": [0.16, 0.24, 0.35, 0.45]
    }
  ]
}

emb_list_vector およびemb は、サポートする検索モードが異なるため、別々のベクトルサブフィールドです。EmbeddingList 検索は、StructArray フィールド内のすべてのベクトルを 1 つの埋め込みリストとして扱い、MAX_SIM* メトリクスを使用したエンティティレベルの結果を返します。要素レベル検索は、各 Struct 要素を個別に検索し、一致した要素のオフセットを返すことができます。この例では、簡略化のため、両方のフィールドに同じベクトル値を格納しています。本番環境のアプリケーションでは、両方の検索モードで同じチャンク埋め込みが使用される場合は、両方のサブフィールドに同じ埋め込みを格納し、2つの検索モードで異なる表現が使用される場合は、異なる埋め込みを格納することができます。

行の挿入

client.insert() を使用して、StructArray 値を含む行を挿入します。

from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus",
)

data = [
    {
        "doc_id": 1,
        "title": "StructArray indexing patterns",
        "category": "index",
        "title_vector": [0.12, 0.08, 0.32, 0.48],
        "chunks": [
            {
                "text": "Create one index for each vector subfield.",
                "section": "index",
                "page": 1,
                "quality_score": 0.96,
                "has_code": False,
                "emb_list_vector": [0.10, 0.20, 0.30, 0.40],
                "emb": [0.10, 0.20, 0.30, 0.40],
            },
            {
                "text": "Use MAX_SIM metrics for EmbeddingList search.",
                "section": "index",
                "page": 2,
                "quality_score": 0.91,
                "has_code": True,
                "emb_list_vector": [0.16, 0.24, 0.35, 0.45],
                "emb": [0.16, 0.24, 0.35, 0.45],
            },
        ],
    },
    {
        "doc_id": 2,
        "title": "Filtered StructArray search",
        "category": "filter",
        "title_vector": [0.20, 0.18, 0.22, 0.40],
        "chunks": [
            {
                "text": "Use element_filter to match scalar conditions within the same Struct element.",
                "section": "filter",
                "page": 1,
                "quality_score": 0.93,
                "has_code": True,
                "emb_list_vector": [0.21, 0.18, 0.33, 0.44],
                "emb": [0.21, 0.18, 0.33, 0.44],
            },
            {
                "text": "MATCH_LEAST checks how many elements satisfy a predicate.",
                "section": "filter",
                "page": 2,
                "quality_score": 0.88,
                "has_code": False,
                "emb_list_vector": [0.24, 0.22, 0.31, 0.39],
                "emb": [0.24, 0.22, 0.31, 0.39],
            },
        ],
    },
    {
        "doc_id": 3,
        "title": "Element-level search with offsets",
        "category": "search",
        "title_vector": [0.33, 0.11, 0.29, 0.37],
        "chunks": [
            {
                "text": "Element-level search can return the offset of the matched Struct element.",
                "section": "search",
                "page": 1,
                "quality_score": 0.95,
                "has_code": False,
                "emb_list_vector": [0.32, 0.14, 0.28, 0.41],
                "emb": [0.32, 0.14, 0.28, 0.41],
            }
        ],
    },
]

result = client.insert(
    collection_name="tech_articles",
    data=data,
)

print(result)

Null 許容の StructArray フィールドへの挿入

chunks フィールドがnull許容型の場合、エンティティはchunks フィールド全体をnullに設定できます。Pythonでは、None を使用してnull値を表現します。

client.insert(
    collection_name="tech_articles",
    data=[
        {
            "doc_id": 10,
            "title": "Article without chunks yet",
            "category": "draft",
            "title_vector": [0.05, 0.10, 0.15, 0.20],
            "chunks": None,
        }
    ],
)

Null 許容の StructArray フィールドに有効な StructArray 値が含まれている場合、その値内のすべてのサブフィールドは null であるか、有効な値を持つ必要があります。一部のサブフィールドが null に設定され、他のサブフィールドが有効な値に設定されたエンティティを挿入すると、エラーが発生します。

警告 Nullable StructArrayフィールドは、Milvus v3.0.xでのみ利用可能です。既存のコレクションにStructArrayフィールドを動的に追加する場合、追加するフィールドはNullableでなければならず、既存のエンティティは、その新しいフィールドのすべてのサブフィールドに対してnull を返します。

挿入データの検証

コレクションをクエリし、StructArrayフィールドまたは選択したサブフィールドを返すことができます。

rows = client.query(
    collection_name="tech_articles",
    filter="doc_id in [1, 2, 3]",
    output_fields=[
        "doc_id",
        "title",
        "chunks[text]",
        "chunks[section]",
        "chunks[quality_score]",
    ],
)

for row in rows:
    print(row)

chunks[text] などの StructArray フィールドパスは、クエリ、検索、フィルタリング、またはインデックスの作成時のみ使用してください。挿入ペイロードでは、引き続きchunks の下にあるネストされたオブジェクトを使用する必要があります。

挿入ルール

ルール	説明
StructArray フィールドには、オブジェクトの配列を使用してください。	`chunks` の値はリストであり、リストの各項目は Struct 要素です。
各 Struct 要素内でサブフィールド名を使用します。	`{"text": "...", "emb": [...]}` は、`{"chunks[text]": "..."}` ではなく、`chunks` 内に挿入してください。
Structスキーマに準拠してください。	各 Struct 要素は、Struct スキーマで定義されたサブフィールドを使用する必要があります。
ベクトルの次元を一致させてください。	ベクトルの値は、そのベクトルサブフィールドに対して設定された`dim` と一致している必要があります。
`max_capacity` を遵守してください。	1 つのエンティティに含まれる Struct 要素の数は、StructArray フィールドの`max_capacity` を超えてはなりません。
検索モードごとに個別のベクトルサブフィールドを使用してください。	EmbeddingList 検索と要素レベルの検索の両方が必要な場合は、両方のベクトルサブフィールドにベクトル値を書き込んでください。
`null` は、フィールドが null 許容である場合にのみ使用してください。	Null 許容ではない StructArray フィールドには、有効な StructArray 値を指定する必要があります。

よくある間違い

挿入ペイロードで、chunks[text] などのフィールドパスを使用すること。
Struct 要素から必須のサブフィールドを省略してしまう。
間違った次元のベクトルを挿入すること。
max_capacity で許可されている数よりも多くの Struct 要素を挿入すること。
null に 1 つのサブフィールドのみを設定し、同じ StructArray 値内の他のサブフィールドが有効である場合。
ベクトルをemb_list_vector にのみ書き込んだ後、chunks[emb] で要素レベルの検索を実行しようとした。
ベクトルをemb にのみ書き込んだ後、chunks[emb_list_vector] に対してEmbeddingList検索を実行しようとした場合。

次の手順

chunks[emb_list_vector] 、chunks[emb] 、およびスカラーサブフィールドのインデックスを作成するには、「StructArray フィールドのインデックス作成」を参照してください。
StructArray のベクトルサブフィールドを検索するには、「StructArray を使用した基本的なベクトル検索」を参照してください。
Null 許容の挙動やバージョン固有の制限事項を確認するには、「StructArray の制限事項」を参照してください。

翻訳 DeepL

マネージド Milvus を無料で試す

Zilliz Cloud は手間いらず、Milvus を基盤に 10 倍高速です。

始める

フィードバック

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