メインコンテンツまでスキップ
バージョン: User Guides (Cloud)

エンティティのアップサート

upsert操作は、コレクション内のエンティティを挿入または更新するための便利な方法を提供します。

概要​

アップサートリクエストで指定された主キーがコレクションに存在するかどうかに応じて、upsertを使用して新しいエンティティを挿入するか、既存のエンティティを更新することができます。主キーが見つからない場合は、挿入操作が行われます。それ以外の場合は、更新操作が実行されます。

アップサートリクエストは挿入と削除を組み合わせたものです。既存のエンティティに対するupsertリクエストを受信した際、Zilliz Cloudはリクエストペイロードに含まれるデータを挿入し、同時にデータで指定された元の主キーを持つ既存のエンティティを削除します。

Q3LawAQIKht1FKbsM3EcoQAHnvc

対象のコレクションで主キーにautoidが有効になっている場合、Zilliz Cloudはリクエストペイロードに含まれるデータに対して新しい主キーを生成してから挿入します。

nullableが有効になっているフィールドについては、更新が必要ない場合はupsertリクエストで省略できます。

マージモードでのアップサート
Public Preview
​

partial_updateフラグを使用して、アップサートリクエストをマージモードで動作させることもできます。これにより、リクエストペイロードに更新が必要なフィールドのみを含めることができます。

NZNKwxm9ahmi87b487TcuCrNn4c

マージを実行するには、upsertリクエストで主キーと新しい値で更新するフィールドとともに、partial_updateをTrueに設定します。

そのようなリクエストを受信した際、Zilliz Cloudは強力な一貫性を持つクエリを実行してエンティティを取得し、リクエスト内のデータに基づいてフィールド値を更新し、変更されたデータを挿入し、リクエストで指定された元の主キーを持つ既存のエンティティを削除します。

アップサートの動作: 特記事項​

マージ機能を使用する前に考慮すべき特別な注意点がいくつかあります。以下の場合では、titleおよびissueという名前の2つのスカラーフィールドと、主キーid、およびvectorという名前のベクトルフィールドを持つコレクションがあると仮定します。

  • nullableが有効なフィールドのアップサート

    issueフィールドがnullになる可能性があるとします。これらのフィールドをアップサートする際は、以下の点に注意してください。

    • upsertリクエストでissueフィールドを省略し、partial_updateを無効にした場合、issueフィールドは元の値を保持するのではなく、nullに更新されます。

    • issueフィールドの元の値を保持するには、partial_updateを有効にしてissueフィールドを省略するか、upsertリクエストで元の値を持つissueフィールドを含める必要があります。

  • 動的フィールドのキーのアップサート

    サンプルコレクションで動的キーが有効になっており、エンティティの動的フィールド内のキーバリューペアが{"author": "John", "year": 2020, "tags": ["fiction"]}に似ていると仮定します。

    author、year、またはtagsなどのキーを持つエンティティをアップサートするか、他のキーを追加する場合、以下の点に注意してください。

    • partial_updateを無効にしてアップサートする場合、デフォルトの動作は上書きです。つまり、動的フィールドの値は、リクエストに含まれるスキーマ定義されていないすべてのフィールドとその値で上書きされます。

      たとえば、リクエストに含まれるデータが{"author": "Jane", "genre": "fantasy"}の場合、対象エンティティの動的フィールド内のキーバリューペアはそれになります。

    • partial_updateを有効にしてアップサートする場合、デフォルトの動作はマージです。つまり、動的フィールドの値は、リクエストに含まれるスキーマ定義されていないすべてのフィールドとその値とマージされます。

      たとえば、リクエストに含まれるデータが{"author": "John", "year": 2020, "tags": ["fiction"]}の場合、対象エンティティの動的フィールド内のキーバリューペアはアップサート後に{"author": "Jane", "year": 2020, "tags": ["fiction"], "genre": "fantasy"}になります。

  • JSONフィールドのアップサート

    サンプルコレクションにextrasという名前のスキーマ定義されたJSONフィールドがあり、エンティティのこのJSONフィールド内のキーバリューペアが{"author": "John", "year": 2020, "tags": ["fiction"]}に似ていると仮定します。

    修正されたJSONデータでエンティティのextrasフィールドをアップサートする際、JSONフィールドは全体として扱われ、個々のキーを個別に更新することはできないことに注意してください。言い換えれば、JSONフィールドはマージモードでのアップサートをサポートしません。

制限事項と制約​

上記の内容に基づき、従うべき制限事項と制約がいくつかあります。

  • upsertリクエストには、対象エンティティの主キーを常に含める必要があります。

  • 対象のコレクションはロードされており、クエリが可能である必要があります。

  • リクエストで指定されたすべてのフィールドは、対象コレクションのスキーマに存在している必要があります。

  • リクエストで指定されたすべてのフィールドの値は、スキーマで定義されたデータ型と一致する必要があります。

  • 関数を使用して別のフィールドから派生したフィールドについては、Zilliz Cloudは再計算を可能にするためにアップサート時に派生フィールドを削除します。

コレクションへのエンティティのアップサート​

このセクションでは、my_collectionという名前のコレクションにエンティティをアップサートします。このコレクションには、id、vector、title、およびissueという名前の4つのフィールドのみがあります。idフィールドは主キーフィールドであり、titleフィールドとissueフィールドはスカラー値フィールドです。

アップサートリクエストに含まれる3つのエンティティが、コレクション内に存在する場合、それらはリクエストに含まれたもので上書きされます。

from pymilvus import MilvusClient

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

data=[
    {
        "id": 0,
        "vector": [-0.619954382375778, 0.4479436794798608, -0.17493894838751745, -0.4248030059917294, -0.8648452746018911],
        "title": "Artificial Intelligence in Real Life",
        "issue": "vol.12"
    }, {
        "id": 1,
        "vector": [0.4762662251462588, -0.6942502138717026, -0.4490002642657902, -0.628696575798281, 0.9660395877041965],
        "title": "Hollow Man",
        "issue": "vol.19"
    }, {
        "id": 2,
        "vector": [-0.8864122635045097, 0.9260170474445351, 0.801326976181461, 0.6383943392381306, 0.7563037341572827],
        "title": "Treasure Hunt in Missouri",
        "issue": "vol.12"
    }
]

res = client.upsert(
    collection_name='my_collection',
    data=data
)

print(res)

# 出力
# {'upsert_count': 3}

パーティションへのエンティティのアップサート​

指定したパーティションにエンティティをアップサートすることもできます。以下のコードスニペットでは、コレクションにPartitionAという名前のパーティションが存在すると仮定しています。

リクエストに含まれる3つのエンティティが、パーティション内に存在する場合、それらはリクエストに含まれたもので上書きされます。

data=[
    {
        "id": 10,
        "vector": [0.06998888224297328, 0.8582816610326578, -0.9657938677934292, 0.6527905683627726, -0.8668460657158576],
        "title": "Layour Design Reference",
        "issue": "vol.34"
    },
    {
        "id": 11,
        "vector": [0.6060703043917468, -0.3765080534566074, -0.7710758854987239, 0.36993888322346136, 0.5507513364206531],
        "title": "Doraemon and His Friends",
        "issue": "vol.2"
    },
    {
        "id": 12,
        "vector": [-0.9041813104515337, -0.9610546012461163, 0.20033003106083358, 0.11842506351635174, 0.8327356724591011],
        "title": "Pikkachu and Pokemon",
        "issue": "vol.12"
    },
]

res = client.upsert(
    collection_name="my_collection",
    data=data,
    partition_name="partitionA"
)

print(res)

# 出力
# {'upsert_count': 3}

マージモードでのエンティティのアップサート
Public Preview
​

以下のコード例は、部分更新でエンティティをアップサートする方法を示しています。更新が必要なフィールドとその新しい値のみを指定し、明示的な部分更新フラグを提供します。

以下の例では、アップサートリクエストで指定されたエンティティのissueフィールドは、リクエストに含まれた値に更新されます。

📘注意

マージモードでアップサートを行う際は、リクエストに関与するエンティティが同じフィールドセットを持っていることを確認してください。アップサートされるエンティティが2つ以上ある場合、以下に示すコードスニペットのように、エラーを防ぎデータの整合性を維持するために同一のフィールドを含めていることが重要です。

data=[
    {
        "id": 1,
        "issue": "vol.14"
    },
    {
        "id": 2,
        "issue": "vol.7"
    }
]

res = client.upsert(
    collection_name="my_collection",
    data=data,
    partial_update=True
)

print(res)

# 出力
# {'upsert_count': 2}