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

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

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

概要​

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

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

Q3LawAQIKht1FKbsM3EcoQAHnvc

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

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

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

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": "John", "year": 2020, "tags": ["fiction"], "genre": "fantasy"} になります。

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

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

    エンティティの extras フィールドを修正済みの JSON データでアップサートする場合、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)

# Output
# {'upsert_count': 3}

パーティション内のエンティティをアップサートする​

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

該当パーティション内に既存のエンティティが存在する場合、リクエストに含まれるエンティティによって上書きされます。

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)

# Output
# {'upsert_count': 3}

マージモードでエンティティをアップサートする​

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

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

📘Notes

マージモードでアップサートを実行する際は、リクエストに関与するエンティティが同一のフィールドセットを持つことを確認してください。たとえば、以下のコードスニペットのように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)

# Output
# {'upsert_count': 2}