设置 Collection 生存时间

数据插入 Collection 后，默认情况下仍保留在该 Collection 中。但是，在某些情况下，您可能希望在一定期限后删除或清理数据。在这种情况下，您可以配置 Collection 的生存时间（TTL）属性，以便 Zilliz Cloud 在TTL到期后自动删除数据。

概述

生存时间（TTL）通常用于如下场景：数据库中的数据在插入或修改后只能保持有效或可访问一段时间。然后，数据需要被自动删除。

例如，如果您希望所有插入某个 Collection 的数据仅需要保留 14 天，您就可以通过为该 Collection 配置生存时间属性来要求 Zilliz Cloud 在数据插入 14 x 24 x 3600 = 1209600 秒后自动删除数据。这就保证了 Collection 中只保存最多 14 天的数据。

📘说明

过期数据不会出现在搜索和查询结果中，并会在下一次数据压缩时删除。数据压缩间隔通常不会超过 24 小时。

在 Zilliz Cloud 中， TTL 的值是一个单位为秒的正整数。一旦设置了该参数，所有生存时间超过该参数值的数据都会被删除。

值得注意的是，数据删除操作是异步的。这就意味着当某些数据超期后并不会马上被删除。在数据被删除和数据不可查之间有一定的延迟。这是由垃圾回收（GC）机制和数据压缩耗时决定的。Zilliz Cloud 会不定期的触发这些操作。

相关示例

总体来说，Collection 生存时间可能与 Collection 中开启 TTL 设置的时间、Entity 插入及更新时间有关。请务必阅读如下示例，以便更好地理解 Collection 生存时间的运作机制。

示例 1：在创建 Collection 时设置 TTL

在创建 Collection 时，您将 Collection 的 TTL 属性设置为 2592000（30天）。

在 1 月 1 日 00:00，您向 Collection 中插入了 100 亿 Entity。此后，再未进行任何写操作。

那么在 1 月 31 日 00:00 之后，这 100 亿 Entity 将不会再出现在任何搜索（Search）结果中。此时，您执行输出字段为 count(*) 的查询（Query）时，结果亦为 0。

示例 2：为既有 Collection 设置 TTL

您已经创建了一个未设置 TTL 属性的 Collection。

在 1 月 1 日 00:00，您向 Collection 中插入了 100 亿 Entity。

在 1 月 31 日 00:00，您又向该 Collection 中插入了 200 亿 Entity。

在 2 月 28 日 10:00，您将该 Collection 的 TTL 属性设置为 2592000（30天）。

那么在 TTL 设置生效时，您在 1 月 1 日插入的 100 亿数据将立即变为不可查询。此时，您执行输出字段为 count(*) 的查询（Query）时，结果亦为 200 亿。

示例 3：Upsert entity

在创建 Collection 时，您将 Collection 的 TTL 属性设置为 2592000（30天）。

在 1 月 1 日 00:00，您向 Collection 中插入了 200 亿 Entity。此后，再未进行任何写操作。

在 1 月15 日 00:00 至 23:59:59 间，您分批次的以合并的方式更新了这 200 亿 Entity。此后，再未进行任何写操作。

在 1 月 31 日 到 2 月 13 日期间，这 200 亿 Entity 仍旧可查询，并且在执行输出字段为 count(*) 的查询时，结果为 200 亿。

但从 1 月 14 日 00:00 起，Entity 数量逐渐减少，并在 2 月 15 日 00:00 时变为 0。

设置 TTL

您可以在如下情况下设置 TTL

• 在创建 Collection 时，或

• 需要修改指定 Collection 的 TTL 时。

在创建 Collection 时设置 TTL

如下示例演示了如何在创建 Collection 时设置 TTL。

Python

from pymilvus import MilvusClient

# With TTL
client.create_collection(
    collection_name="my_collection",
    schema=schema,
    # highlight-start
    properties={
        "collection.ttl.seconds": 1209600
    }
    # highlight-end
)

Java

import io.milvus.v2.service.collection.request.CreateCollectionReq;
import io.milvus.v2.service.collection.request.AlterCollectionReq;
import io.milvus.param.Constant;
import java.util.HashMap;
import java.util.Map;

// With TTL
CreateCollectionReq customizedSetupReq = CreateCollectionReq.builder()
        .collectionName("my_collection")
        .collectionSchema(schema)
        // highlight-next-line
        .property(Constant.TTL_SECONDS, "1209600")
        .build();
client.createCollection(customizedSetupReq);

NodeJS

const createCollectionReq = {
    collection_name: "my_collection",
    schema: schema,
    // highlight-start
    properties: {
        "collection.ttl.seconds": 1209600
    }
    // highlight-end
}

Go

err = client.CreateCollection(ctx, milvusclient.NewCreateCollectionOption("my_collection", schema).
    WithProperty(common.CollectionTTLConfigKey, 1209600)) //  TTL in seconds
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

cURL

export params='{
    "ttlSeconds": 1209600
}'

export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/collections/create" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d "{
    \"collectionName\": \"my_collection\",
    \"schema\": $schema,
    \"params\": $params
}"

修改指定 Collection 的 TTL

如下示例演示了如何修改指定 Collection 的 TTL。

Python

client.alter_collection_properties(
    collection_name="my_collection",
    properties={"collection.ttl.seconds": 1209600}
)

Java

AlterCollectionPropertiesReq alterCollectionReq = AlterCollectionPropertiesReq.builder()
        .collectionName("my_collection")
        .property(Constant.TTL_SECONDS, "1209600")
        .build();

client.alterCollectionProperties(alterCollectionReq);

NodeJS

res = await client.alterCollection({
    collection_name: "my_collection",
    properties: {
        "collection.ttl.seconds": 1209600
    }
})

Go

err = client.AlterCollectionProperties(ctx, milvusclient.NewAlterCollectionPropertiesOption("my_collection").
    WithProperty(common.CollectionTTLConfigKey, 60))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

cURL

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/collections/alter_properties" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d "{
    \"collectionName\": \"my_collection\",
    \"properties\": {
        \"collection.ttl.seconds\": 1209600
    }
}"

重置 TTL

如果您希望 Collection 中的数据能够永久保存，您可以通过重置 TTL 设置来实现这一点。

Python

client.drop_collection_properties(
    collection_name="my_collection",
    property_keys=["collection.ttl.seconds"]
)

Java

client.dropCollectionProperties(DropCollectionPropertiesReq.builder()
        .collectionName("my_collection")
        .propertyKeys(Collections.singletonList(Constant.TTL_SECONDS))
        .build());

NodeJS

res = await client.dropCollectionProperties({
    collection_name: "my_collection",
    properties: ["collection.ttl.seconds"]
})

Go

err = client.DropCollectionProperties(ctx, milvusclient.NewDropCollectionPropertiesOption("my_collection", common.CollectionTTLConfigKey))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

cURL

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/collections/drop_properties" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d "{
    \"collectionName\": \"my_collection\",
    \"propertyKeys\": [
        \"collection.ttl.seconds\"
    ]
}"

常见问题

插入 Collection 中的数据到底何时会根据 TTL 设置失效？

Zilliz Cloud 会根据TTL 设置及数据的插入或更新时间来确定其失效时间。失效的数据将不会出现在任何搜索结果中。具体可参考相关示例。

失效数据何时会删除？

当数据失效后，这些数据将不会出现在任何搜索结果中，但是，只有在 Zilliz Cloud 根据集群的数据压缩策略执行下一次压缩时，这些数据才会被删除。

如果您希望在数据失效后的较短时间内删除这些数据，请联系 Zilliz Cloud 技术支持。

Zilliz Cloud 集群的 CU 容量何时会开始降低？

集群的 CU 容量会取内存使用量和存储使用量中的最大值。如果 CU 容量当前取的是存储使用量，您可以在失效数据被删除后，在 Zilliz Cloud 控制台中观察到 CU 容量的减少。