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

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

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

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

事前準備​

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

フィールド型挿入値
doc_idINT64記事 ID。
titleVARCHAR記事のタイトル。
categoryVARCHAR記事のカテゴリ。
title_vectorFLOAT_VECTOR記事レベルの埋め込み。
chunksARRAYチャンクオブジェクトのリスト。

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

サブフィールド型挿入値
textVARCHARチャンクテキスト。
sectionVARCHARindex、search、filter などのセクション名。
pageINT64ページ番号または論理位置。
quality_scoreFLOATチャンクレベルのスコア。
has_codeBOOLチャンクにコードが含まれているかどうか。
emb_list_vectorFLOAT_VECTOREmbeddingList 検索用に書き込まれるベクトル。
embFLOAT_VECTOR要素レベルの検索用に書き込まれるベクトル。
📘Notes

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

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

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

json
{
  "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 つの検索モードで異なる表現を使用する場合は異なる埋め込みを格納できます。

行を挿入する​

insert 操作を使用して、次の 3 つのエンティティを書き込みます。各エンティティには、必須の Struct サブフィールドがすべて含まれます。Go の例では列ベースの入力を使用します。各マップは、1 つのエンティティのサブフィールド配列をグループ化します。

python
from pymilvus import MilvusClient

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

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 許容を有効にして作成された場合にのみ、このオプションの例を実行してください。NULL はフィールド全体に適用され、個々の Struct 要素やサブフィールドには適用されません。空の配列は存在する値であり、NULL ではありません。

python
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 値では、必須のすべてのサブフィールドに有効な値を指定します。同じエンティティ内で、NULL のサブフィールド配列と有効なサブフィールド配列を混在させないでください。

📘Notes

バージョンとデプロイにおける利用可否については、StructArray の制限 を参照してください。既存のコレクションに追加する StructArray フィールドは NULL 許容である必要があります。既存のエンティティでは、追加されたフィールド全体が NULL になります。

挿入したデータを検証する​

コレクションをロードする前に、StructArray フィールドのインデックス作成 の説明に従って、必要なベクトルインデックスを作成してください。次の例では、ロードが完了するまで待機してから、選択したサブフィールドをクエリします。cURL の場合は、ロード状態の応答を確認するために jq をインストールします。Bounded Staleness 整合性では、挿入直後のクエリに新しい行が含まれない可能性があります。書き込みが可視になった後にクエリを繰り返すか、例のコレクションを作成するときに Strong 整合性を設定してください。

python
client.load_collection("tech_articles")

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 要素内ではサブフィールド名を使用します。chunks 内には {"text": "...", "emb": [...]} を挿入し、{"chunks[text]": "..."} は挿入しません。
Struct スキーマに一致させます。各 Struct 要素は、Struct スキーマで定義されたサブフィールドを使用する必要があります。
ベクトルの次元を一致させます。ベクトル値は、それぞれのベクトルサブフィールドに設定された dim と一致する必要があります。
max_capacity を遵守します。1 つのエンティティ内の Struct 要素数は、StructArray フィールドの max_capacity を超えてはなりません。
検索モードごとに別々のベクトルサブフィールドを使用します。EmbeddingList 検索と要素レベルの検索の両方が必要な場合は、両方のベクトルサブフィールドにベクトル値を書き込みます。
フィールドが null を許容する場合にのみ null を使用します。null を許容しない StructArray フィールドには、有効な StructArray 値が必要です。

よくある間違い​

  • 挿入ペイロードで chunks[text] などのフィールドパスを使用しています。

  • Struct 要素から必須サブフィールドを省略しています。

  • 誤った次元のベクトルを挿入しています。

  • max_capacity で許可される数を超える Struct 要素を挿入しています。

  • 同じ StructArray 値内の他のサブフィールドが有効であるにもかかわらず、1 つのサブフィールドだけを null に設定しています。

  • emb_list_vector にのみベクトルを書き込み、その後 chunks[emb] で要素レベルの検索を実行しようとしています。

  • emb にのみベクトルを書き込み、その後 chunks[emb_list_vector] で EmbeddingList 検索を実行しようとしています。

次のステップ​

  1. chunks[emb_list_vector]、chunks[emb]、およびスカラーサブフィールドのインデックスを作成するには、StructArray フィールドのインデックス作成 を参照してください。

  2. StructArray のベクトルサブフィールドを検索するには、StructArray での基本的なベクトル検索 を参照してください。

  3. null 許容の動作とバージョン固有の制限を確認するには、StructArray の制限 を参照してください。

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