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

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

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 という名前の2つのフィールドしかありません。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}