跳到主要内容
版本：BYOC 开发指南

Upsert Entity

使用 upsert 操作可以方便地在 Collection 中插入或更新 Entity。

概述​

您可以使用 upsert 操作来插入新 Entity 或更新现有 Entity，具体取决于该请求中提供的主键是否存在于 Collection 中。如果未找到主键，则执行插入操作。否则，将执行更新操作。

Milvus中的插入更新操作可以在覆盖或合并模式下工作。

在覆盖模式下进行 Upsert​

以覆盖模式工作的插入更新请求。当收到针对现有 Entity 的 upsert 请求时，Zilliz Cloud 会插入请求负载中携带的数据，同时删除数据中指定的具有原始主键的现有 Entity。

Af76wmsgbh7C0cbfQ36cTbUonpe

如果目标 Collection 在其主键字段上启用了 AutoID，Zilliz Cloud 将在插入请求负载中携带的数据之前为其生成一个新的主键。

对于启用了允许为空的字段，如果不需要更新，则可以在 upsert 请求中省略它们。

在合并模式下进行 Upsert
公测版
​

您还可以使用 partial_update 标志，使 upsert 请求以合并模式工作。这允许您仅在请求负载中包含需要更新的字段。

HM2awm23ShMHaBb3p1HcMtZnnU4

若要执行合并操作，请在 upsert 中将 partial_update 设置为True 并在请求中指定主键和要更新的字段以及它们的值。

收到此类请求后，Zilliz Cloud 会执行强一致性查询以检索 Entity，根据请求中的数据更新字段值，插入修改后的数据，然后删除请求中携带的具有原始主键的现有 Entity。

Upsert 的行为：特别说明​

在使用合并功能之前，您应该考虑以下几个特别注意事项。以下情况假设您有一个 Collection，其中包含两个标量字段，分别名为标题和问题，以及一个主键id和一个名为向量的向量字段。

  • 更新插入字段，允许为空已启用。

    假设 issue 字段可以为空。当您更新插入这些字段时，请注意：

    • 如果您在 upsert 请求中省略 issue 字段并禁用 partial_update，则 issue 字段将更新为 null，而不是保留其原始值。

    • 要保留 issue 字段的原始值，您需要启用 partial_update 并省略 issue 字段，或者在 upsert 请求中包含带有其原始值的 issue 字段。

  • 在 Dynamic Field 中更新插入键。

    假设您已在示例 Collection 中启用 Dynamic Field，并且 Entity Dynamic Field中的键值对类似于{"author": "John", "year": 2020, "tags": ["fiction"]}。

    当你使用键（如 author、year 或 tags）更新插入 Entity，或添加其他键时，请注意：

    • 如果在禁用 partial_update 的情况下进行 upsert 操作，默认行为是覆盖。这意味着 Dynamic Field 的值将被请求中包含的所有非模式定义字段及其值覆盖。

      例如，如果请求中包含的数据是{"author": "Jane", "genre": "fantasy"}，则目标 Entity Dynamic Field中的键值对将更新为该数据。

    • 如果在启用部分更新的情况下进行插入或更新操作，默认行为是合并。这意味着Dynamic Field的值将与请求中包含的所有非模式定义字段及其值进行合并。

      例如，如果请求中包含的数据是{"author": "John", "year": 2020, "tags": ["fiction"]}，则目标 Entity Dynamic Field 中的键值对在插入更新后将变为{"author": "Jane", "year": 2020, "tags": ["fiction"], "genre": "fantasy"}。

  • 更新插入一个 JSON 字段。

    假设示例 Collection 有一个名为 extras 的 JSON 字段，并且 Entity 的这个 JSON 字段中的键值对类似于{"author": "John", "year": 2020, "tags": ["fiction"]}。

    当您使用修改后的JSON数据更新 Entity 的 extras 字段时，请注意：

    • 如果在禁用 partial_update 的情况下进行插入或更新操作，默认行为是覆盖。这意味着请求中包含的JSON字段的值将覆盖目标 Entity 的 JSON 字段的原始值。

      例如，如果请求中包含的数据是{extras: {"author": "Jane", "genre": "fantasy"}}，则目标Entity 的 extras 字段中的键值对将更新为{"author": "Jane", "genre": "fantasy"}。

    • 如果在启用 partial_update 的情况下进行 upsert 操作，默认行为是合并。这意味着请求中包含的JSON 字段的值将与目标 Entity 的 JSON 字段的原始值合并。

      例如，如果请求中包含的数据是{extras: {"author": "Jane", "genre": "fantasy"}}，则更新后目标 Entity 的extras字段中的键值对将变为{"author": "Jane", "year": 2020, "tags": ["fiction"], "genre": "fantasy"}。

限制与约束​

根据上述内容，有若干限制和约束需要遵循：

  • upsert 请求必须始终包含目标 Entity 的主键。

  • 目标 Collection 必须已加载且可用于查询。

  • 请求中指定的所有字段必须存在于目标 Collection 的 Schema 中。

  • 请求中指定的所有字段的值必须与 Schema 中定义的数据类型相匹配。

  • 对于任何使用 Function 从其他字段派生而来的字段，Zilliz Cloud 将在 upsert 期间移除派生字段，以便重新计算。

在 Collection 中 Upsert Entity​

在本节中，我们将向名为my_collection的 Collection 中 Upsert Entity 。这个 Collection 只有两个字段，分别名为id、vector、title和issue。id字段是主键字段，而title和issue字段是标量字段。

如果 Collection 中存在这三个实体，它们将被包含在更新插入请求中的实体覆盖。

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}

在 Partition 中 Upsert Entity​

您还可以将 Entity Upsert 到指定 Partition 中。以下代码片段假定您的 Collection 中有一个名为 PartitionA 的 Partition。

如果 Partition 中存在这三个 Entity，它们将被请求中包含的 Entity 覆盖。

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}

在合并模式下 Upsert Entity
公测版
​

以下代码示例展示了如何通过部分更新来 Upsert Entity。只需提供需要更新的字段及其新值，同时设置显式的部分更新标志。

在以下示例中，upsert 请求中指定的 Entity 的 issue 字段将更新为请求中包含的值。

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}