تعيين TTL TTL للمجموعة

يمكن ل Milvus إنهاء صلاحية الكيانات تلقائيًا من خلال سياسة وقت الحياة (TTL). تتوقف الكيانات منتهية الصلاحية عن الظهور في نتائج الاستعلام والبحث على الفور، ويتم إزالتها فعليًا من التخزين في دورة الضغط التالية - عادةً خلال 24 ساعة.

هناك وضعان لسياسة TTL:

• TTL TTL على مستوى المجموعة - نافذة احتفاظ واحدة مشتركة بين كل كيان، يتم تعيينها من خلال الخاصية collection.ttl.seconds.

• TTL TTLعلى مستوى الكيان - يحمل كل كيان وقت انتهاء الصلاحية المطلق الخاص به في حقل TIMESTAMPTZ مخصص، يتم تعيينه كحقل TTL من خلال الخاصية ttl_field.

الحدود

• وضعان TTL TTL متنافيان. لا يمكن أن تحتوي المجموعة على كل من collection.ttl.seconds و ttl_field في نفس الوقت. للتبديل، راجع الترحيل بين الوضعين.

• تطبق TTL على مستوى المجموعة نافذة واحدة على المجموعة بأكملها. إذا كان صف واحد يحتاج إلى عمر افتراضي مختلف، استخدم TTL TTL على مستوى الكيان.

• يجب أن يكون حقل TTL TTL على مستوى الكيان TIMESTAMPTZ. يتم رفض الأنواع الأخرى.

• حقل TTL TTL واحد لكل مجموعة. قد يحتوي المخطط على عدة حقول TIMESTAMPTZ ، ولكن يمكن تسمية حقل واحد فقط في ttl_field.

• لا يؤدي إسقاط ttl_field إلى إعادة ظهور الكيانات منتهية الصلاحية. لاستعادة كيان منتهي الصلاحية، قم بإعادة إدراجه مع NULL أو الطابع الزمني لانتهاء الصلاحية في المستقبل.

نظرة عامة

توسيع

متى تستخدم TTL

TTL هي الأداة الصحيحة عندما يكون الاحتفاظ سياسة - أنت تعرف مسبقًا أن كيانات معينة يجب أن تختفي في نهاية المطاف، وتريد أن تقوم المجموعة بفرضها دون أن تكتب مهمة موقتة.

سيناريوهات نموذجية:

• مجموعات بيانات ذات فترة زمنية محددة. احتفظ فقط بآخر N أيام من السجلات أو المقاييس أو الأحداث أو ذاكرات التخزين المؤقت للميزات قصيرة العمر.

• مجموعات متعددة المستأجرين. المستأجرون المختلفون لديهم نوافذ احتفاظ مختلفة في نفس المجموعة.

• نُهج الاحتفاظ لكل سجل. عمر كل مستند في خطوط أنابيب إنترنت الأشياء أو مخازن المستندات أو مخازن ميزات MLOps.

• مزيج البيانات الساخنة/الباردة. تتعايش الكيانات قصيرة الأجل مع الكيانات طويلة الأجل في نفس المجموعة.

• انتهاء الصلاحية المدفوع بالامتثال. تقليل البيانات على غرار اللائحة العامة لحماية البيانات حيث يحمل كل سجل تاريخ "الحذف بحلول" الخاص به.

• انتهاء الصلاحية في وقت العمل. يمثل الكيان سجلاً صالحًا فقط حتى لحظة ما مطلقة (انتهاء الحملة أو انتهاء صلاحية الجلسة).

لن تظهر الكيانات منتهية الصلاحية في أي نتائج بحث أو استعلام. ومع ذلك، فإنها قد تبقى في المخزن حتى يتم ضغط البيانات اللاحق، والذي يجب أن يتم في غضون الـ 24 ساعة القادمة.

يمكنك التحكم في وقت تشغيل ضغط البيانات عن طريق تعيين عنصر التكوين dataCoord.compaction.expiry.tolerance في ملف تكوين Milvus الخاص بك.

يتم تعيين عنصر التكوين هذا افتراضيًا إلى -1 ، مما يشير إلى تطبيق الفاصل الزمني الحالي لضغط البيانات. ومع ذلك، عندما تقوم بتغيير قيمته إلى عدد صحيح موجب، مثل 12 ، سيتم تشغيل ضغط البيانات بعدد الساعات المحددة بعد انتهاء صلاحية أي كيانات.

أوضاع TTL

يجيب الوضعان على أسئلة الاحتفاظ المختلفة:

• تطبقTTL TTL على مستوى المجموعة مدة احتفاظ واحدة على كل كيان. تنتهي صلاحية كل كيان عند insert_ts + ttl_seconds.

• تسمحTTL TTL على مستوى الكيان بتخزين وقت انتهاء الصلاحية المطلق الخاص بكل كيان في حقل TIMESTAMPTZ. يعني وجود NULL في هذا الحقل أن الكيان لا تنتهي صلاحيته أبدًا.

تستخدم المجموعة وضعًا واحدًا في كل مرة - والوضعان متنافيان. التبديل بينهما عملية متعددة الخطوات؛ انظر الترحيل بين الوضعين.

استخدم هذا الجدول لاختيار الوضع:

إذا كان وضعك...	استخدم
يجب أن يتبع كل كيان في المجموعة نفس نافذة الاستبقاء	TTL على مستوى المجموعة
الاحتفاظ "من لحظة الإدراج، احتفظ بـ N ثانية"	TTL على مستوى المجموعة
تحتاج الكيانات المختلفة إلى أعمار مختلفة في نفس المجموعة (لكل مستأجر، ساخن/بارد، لكل مستند)	TTL TTL على مستوى الكيان
الاحتفاظ هو وقت ساعة حائط مطلق (على سبيل المثال، 2027-01-01T00:00:00:00Z)	TTL TTL على مستوى الكيان
يتم الاحتفاظ حسب الطابع الزمني للعمل، وليس الطابع الزمني للإدراج	TTL TTL على مستوى الكيان
إذا كنت ترغب في تحديث أو تمديد عمر الكيان بعد الإدراج	TTL TTL على مستوى الكيان
يجب ألا تنتهي صلاحية بعض الكيانات أبدًا بينما يجب ألا تنتهي صلاحية كيانات أخرى	TTL TTL على مستوى الكيان (استخدم NULL للكيانات الخالدة)

تعيين TTL TTL على مستوى المجموعة

استخدم TTL TTL على مستوى المجموعة عندما يجب أن يتبع كل كيان في المجموعة نفس نافذة الاحتفاظ.

تمكين على مجموعة جديدة

مرر collection.ttl.seconds (عدد صحيح، بالثواني) من خلال خريطة properties في وقت الإنشاء.

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="http://localhost:19530")

schema = client.create_schema(auto_id=False, enable_dynamic_field=False)
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)
schema.add_field("vector", DataType.FLOAT_VECTOR, dim=128)

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="vector", index_type="AUTOINDEX", metric_type="COSINE"
)

client.create_collection(
    collection_name="my_collection",
    schema=schema,
    index_params=index_params,
    properties={
        "collection.ttl.seconds": 1209600  # 14 days
    },
)

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.common.DataType;
import io.milvus.v2.common.IndexParam;
import io.milvus.v2.service.collection.request.AddFieldReq;
import io.milvus.v2.service.collection.request.CreateCollectionReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build());

CreateCollectionReq.CollectionSchema schema = CreateCollectionReq.CollectionSchema.builder().build();
schema.addField(AddFieldReq.builder().fieldName("id").dataType(DataType.Int64)
        .isPrimaryKey(true).autoID(false).build());
schema.addField(AddFieldReq.builder().fieldName("vector").dataType(DataType.FloatVector)
        .dimension(128).build());

IndexParam indexParam = IndexParam.builder().fieldName("vector")
        .indexType(IndexParam.IndexType.AUTOINDEX)
        .metricType(IndexParam.MetricType.COSINE).build();

Map<String, String> properties = new HashMap<>();
properties.put("collection.ttl.seconds", "1209600"); // 14 days

client.createCollection(CreateCollectionReq.builder()
        .collectionName("my_collection")
        .collectionSchema(schema)
        .indexParams(Collections.singletonList(indexParam))
        .properties(properties)
        .build());

const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node");

const client = new MilvusClient({ address: "http://localhost:19530" });

await client.createCollection({
  collection_name: "my_collection",
  fields: [
    { name: "id", data_type: DataType.Int64, is_primary_key: true, autoID: false },
    { name: "vector", data_type: DataType.FloatVector, dim: 128 },
  ],
  index_params: [
    { field_name: "vector", index_type: "AUTOINDEX", metric_type: "COSINE" },
  ],
  properties: {
    "collection.ttl.seconds": 1209600, // 14 days
  },
});

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
}

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

export CLUSTER_ENDPOINT="http://localhost:19530"
export TOKEN="root:Milvus"

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

تمكين على مجموعة موجودة

استدعاء alter_collection_properties مع collection.ttl.seconds في خريطة properties لتطبيق TTL على مجموعة قيد الاستخدام بالفعل.

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="http://localhost:19530")

# Assumes "my_collection" was created earlier without TTL
schema = client.create_schema(auto_id=False, enable_dynamic_field=False)
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)
schema.add_field("vector", DataType.FLOAT_VECTOR, dim=128)

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="vector", index_type="AUTOINDEX", metric_type="COSINE"
)

if not client.has_collection("my_collection"):
    client.create_collection(
        collection_name="my_collection",
        schema=schema,
        index_params=index_params,
    )

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

import java.util.HashMap;
import java.util.Map;

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.collection.request.AlterCollectionPropertiesReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build());

// Assumes "my_collection" was created earlier without TTL.

Map<String, String> properties = new HashMap<>();
properties.put("collection.ttl.seconds", "1209600");

client.alterCollectionProperties(AlterCollectionPropertiesReq.builder()
        .collectionName("my_collection")
        .properties(properties)
        .build());

const { MilvusClient } = require("@zilliz/milvus2-sdk-node");

const client = new MilvusClient({ address: "http://localhost:19530" });

// Assumes "my_collection" was created earlier without TTL.
await client.alterCollectionProperties({
  collection_name: "my_collection",
  properties: { "collection.ttl.seconds": 1209600 },
});

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

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

أسقط إعداد TTL

إذا قررت الاحتفاظ بالبيانات في مجموعة إلى أجل غير مسمى، يمكنك ببساطة إسقاط إعداد TTL من تلك المجموعة.

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

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

import java.util.Collections;

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.collection.request.DropCollectionPropertiesReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build());

client.dropCollectionProperties(DropCollectionPropertiesReq.builder()
        .collectionName("my_collection")
        .propertyKeys(Collections.singletonList("collection.ttl.seconds"))
        .build());

const { MilvusClient } = require("@zilliz/milvus2-sdk-node");

const client = new MilvusClient({ address: "http://localhost:19530" });

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

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

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

تعيين TTL على مستوى الكيانCompatible with Milvus 3.0.x

تتيح TTL TTL على مستوى الكيان أن يحمل كل كيان وقت انتهاء الصلاحية المطلق الخاص به. يتم تخزين الوقت في عمود TIMESTAMPTZ مخصص تقوم بتعيينه في المخطط، وتضع علامة على هذا العمود كحقل TTL من خلال خاصية المجموعة ttl_field.

التمكين على مجموعة جديدة

يستلزم تمكين TTL على مستوى الكيان في وقت الإنشاء إضافتين في نفس الاستدعاء create_collection: حقل TIMESTAMPTZ في المخطط، والخاصية ttl_field التي تشير إلى هذا الحقل.

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="http://localhost:19530")

schema = client.create_schema(enable_dynamic_field=False)
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)
schema.add_field("expire_at", DataType.TIMESTAMPTZ, nullable=True)
schema.add_field("vector", DataType.FLOAT_VECTOR, dim=128)

index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_type="AUTOINDEX",
                       metric_type="COSINE")

client.create_collection(
    collection_name="my_collection",
    schema=schema,
    index_params=index_params,
    properties={"ttl_field": "expire_at"},
)

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.common.DataType;
import io.milvus.v2.common.IndexParam;
import io.milvus.v2.service.collection.request.AddFieldReq;
import io.milvus.v2.service.collection.request.CreateCollectionReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build());

CreateCollectionReq.CollectionSchema schema = CreateCollectionReq.CollectionSchema.builder().build();
schema.addField(AddFieldReq.builder().fieldName("id").dataType(DataType.Int64)
        .isPrimaryKey(true).autoID(false).build());
schema.addField(AddFieldReq.builder().fieldName("expire_at").dataType(DataType.Timestamptz)
        .isNullable(true).build());
schema.addField(AddFieldReq.builder().fieldName("vector").dataType(DataType.FloatVector)
        .dimension(128).build());

IndexParam indexParam = IndexParam.builder().fieldName("vector")
        .indexType(IndexParam.IndexType.AUTOINDEX)
        .metricType(IndexParam.MetricType.COSINE).build();

Map<String, String> properties = new HashMap<>();
properties.put("ttl_field", "expire_at");

client.createCollection(CreateCollectionReq.builder()
        .collectionName("my_collection")
        .collectionSchema(schema)
        .indexParams(Collections.singletonList(indexParam))
        .properties(properties)
        .build());

const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node");

const client = new MilvusClient({ address: "http://localhost:19530" });

await client.createCollection({
  collection_name: "my_collection",
  fields: [
    { name: "id", data_type: DataType.Int64, is_primary_key: true, autoID: false },
    { name: "expire_at", data_type: DataType.Timestamptz, nullable: true },
    { name: "vector", data_type: DataType.FloatVector, dim: 128 },
  ],
  index_params: [
    { field_name: "vector", index_type: "AUTOINDEX", metric_type: "COSINE" },
  ],
  properties: { ttl_field: "expire_at" },
});

// go

# restful

بمجرد وجود المجموعة، أدرج الكيانات مع سلاسل الطابع الزمني ISO 8601.

import random
from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

# Assumes "my_collection" was created earlier with `ttl_field`: "expire_at"
rows = [
    # Never expires
    {"id": 1, "expire_at": None,
     "vector": [random.random() for _ in range(128)]},
    # Expires at 2026-12-31 UTC midnight
    {"id": 2, "expire_at": "2026-12-31T00:00:00Z",
     "vector": [random.random() for _ in range(128)]},
    # Shanghai local time — normalized to UTC internally
    {"id": 3, "expire_at": "2027-01-01T00:00:00+08:00",
     "vector": [random.random() for _ in range(128)]},
]

client.insert("my_collection", rows)

import java.util.ArrayList;
import java.util.List;
import java.util.Random;

import com.google.gson.Gson;
import com.google.gson.JsonNull;
import com.google.gson.JsonObject;

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.vector.request.InsertReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build());

// Assumes "my_collection" was created earlier with `ttl_field`: "expire_at".
Gson gson = new Gson();
Random rng = new Random();

List<Float> vector = new ArrayList<>();
for (int i = 0; i < 128; i++) vector.add(rng.nextFloat());

List<JsonObject> rows = new ArrayList<>();

// Never expires
JsonObject r1 = new JsonObject();
r1.addProperty("id", 1);
r1.add("expire_at", JsonNull.INSTANCE);
r1.add("vector", gson.toJsonTree(vector));
rows.add(r1);

// Expires at 2026-12-31 UTC midnight
JsonObject r2 = new JsonObject();
r2.addProperty("id", 2);
r2.addProperty("expire_at", "2026-12-31T00:00:00Z");
r2.add("vector", gson.toJsonTree(vector));
rows.add(r2);

// Shanghai local time — normalized to UTC internally
JsonObject r3 = new JsonObject();
r3.addProperty("id", 3);
r3.addProperty("expire_at", "2027-01-01T00:00:00+08:00");
r3.add("vector", gson.toJsonTree(vector));
rows.add(r3);

client.insert(InsertReq.builder()
        .collectionName("my_collection")
        .data(rows)
        .build());

const { MilvusClient } = require("@zilliz/milvus2-sdk-node");

const client = new MilvusClient({ address: "http://localhost:19530" });

const vector = Array.from({ length: 128 }, () => Math.random());

// Assumes "my_collection" was created earlier with `ttl_field`: "expire_at".
await client.insert({
  collection_name: "my_collection",
  data: [
    // Never expires
    { id: 1, expire_at: null, vector },
    // Expires at 2026-12-31 UTC midnight
    { id: 2, expire_at: "2026-12-31T00:00:00Z", vector },
    // Shanghai local time — normalized to UTC internally
    { id: 3, expire_at: "2027-01-01T00:00:00+08:00", vector },
  ],
});

// go

# restful

في كل استعلام وبحث متجه، يقوم الخادم تلقائيًا بإدخال عامل تصفية TTL - لا تكتب واحدًا بنفسك أبدًا، ولا تظهر الكيانات منتهية الصلاحية في النتائج أبدًا:

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

client.load_collection("my_collection")

# Expired rows are filtered out automatically
results = client.query(
    collection_name="my_collection",
    filter="id >= 0",
    output_fields=["id", "expire_at"],
    limit=10,
)
print(results)

import java.util.Arrays;

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.collection.request.LoadCollectionReq;
import io.milvus.v2.service.vector.request.QueryReq;
import io.milvus.v2.service.vector.response.QueryResp;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build());

client.loadCollection(LoadCollectionReq.builder()
        .collectionName("my_collection")
        .build());

// Expired rows are filtered out automatically
QueryResp results = client.query(QueryReq.builder()
        .collectionName("my_collection")
        .filter("id >= 0")
        .outputFields(Arrays.asList("id", "expire_at"))
        .limit(10L)
        .build());
System.out.println(results.getQueryResults());

const { MilvusClient } = require("@zilliz/milvus2-sdk-node");

const client = new MilvusClient({ address: "http://localhost:19530" });

await client.loadCollection({ collection_name: "my_collection" });

// Expired rows are filtered out automatically
const results = await client.query({
  collection_name: "my_collection",
  filter: "id >= 0",
  output_fields: ["id", "expire_at"],
  limit: 10,
});
console.log(results.data);

// go

# restful

ينطبق الفلتر التلقائي نفسه على client.search().

لتمديد عمر كيان ما قبل أن يزيله الضغط فعليًا، قم بإضافة طابع زمني لانتهاء الصلاحية لاحقًا - أو None - لإعادة الكيان إلى المجموعة القابلة للاستعلام.

import random
from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

client.upsert("my_collection", [
    {"id": 2,
     "vector": [random.random() for _ in range(128)],
     "expire_at": "2028-01-01T00:00:00Z"},
])

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Random;

import com.google.gson.Gson;
import com.google.gson.JsonObject;

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.vector.request.UpsertReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build());

Gson gson = new Gson();
Random rng = new Random();
List<Float> vector = new ArrayList<>();
for (int i = 0; i < 128; i++) vector.add(rng.nextFloat());

JsonObject row = new JsonObject();
row.addProperty("id", 2);
row.add("vector", gson.toJsonTree(vector));
row.addProperty("expire_at", "2028-01-01T00:00:00Z");

client.upsert(UpsertReq.builder()
        .collectionName("my_collection")
        .data(Collections.singletonList(row))
        .build());

const { MilvusClient } = require("@zilliz/milvus2-sdk-node");

const client = new MilvusClient({ address: "http://localhost:19530" });

const vector = Array.from({ length: 128 }, () => Math.random());

await client.upsert({
  collection_name: "my_collection",
  data: [
    { id: 2, vector, expire_at: "2028-01-01T00:00:00Z" },
  ],
});

// go

# restful

التمكين على مجموعة موجودة

إذا كانت المجموعة موجودة بالفعل ولا تحتوي على مجموعة collection.ttl.seconds ، أضف عمود TIMESTAMPTZ مع add_collection_field ، ثم ضع علامة عليه كحقل TTL مع alter_collection_properties. قم اختياريًا بإدراج الصفوف التاريخية لملء الطوابع الزمنية لانتهاء صلاحيتها - الصفوف التي لا تملأها تبقى NULL ولا تنتهي صلاحيتها أبدًا.

import random
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="http://localhost:19530")

# Step 1 — add a TIMESTAMPTZ column to the schema
client.add_collection_field(
    collection_name="my_collection",
    field_name="expire_at",
    data_type=DataType.TIMESTAMPTZ,
    nullable=True,
)

# Step 2 — mark the new column as the TTL field
client.alter_collection_properties(
    collection_name="my_collection",
    properties={"ttl_field": "expire_at"},
)

# Step 3 (optional) — backfill expiration timestamps for historical rows
client.upsert("my_collection", [
    {"id": 1,
     "vector": [random.random() for _ in range(128)],
     "expire_at": "2026-12-31T00:00:00Z"},
])

import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Random;

import com.google.gson.Gson;
import com.google.gson.JsonObject;

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.common.DataType;
import io.milvus.v2.service.collection.request.AddCollectionFieldReq;
import io.milvus.v2.service.collection.request.AlterCollectionPropertiesReq;
import io.milvus.v2.service.vector.request.UpsertReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build());

// Step 1 — add a TIMESTAMPTZ column to the schema
client.addCollectionField(AddCollectionFieldReq.builder()
        .collectionName("my_collection")
        .fieldName("expire_at")
        .dataType(DataType.Timestamptz)
        .isNullable(true)
        .build());

// Step 2 — mark the new column as the TTL field
Map<String, String> properties = new HashMap<>();
properties.put("ttl_field", "expire_at");
client.alterCollectionProperties(AlterCollectionPropertiesReq.builder()
        .collectionName("my_collection")
        .properties(properties)
        .build());

// Step 3 (optional) — backfill expiration timestamps for historical rows
Gson gson = new Gson();
Random rng = new Random();
List<Float> vector = new ArrayList<>();
for (int i = 0; i < 128; i++) vector.add(rng.nextFloat());

JsonObject row = new JsonObject();
row.addProperty("id", 1);
row.add("vector", gson.toJsonTree(vector));
row.addProperty("expire_at", "2026-12-31T00:00:00Z");

client.upsert(UpsertReq.builder()
        .collectionName("my_collection")
        .data(Collections.singletonList(row))
        .build());

const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node");

const client = new MilvusClient({ address: "http://localhost:19530" });

const vector = Array.from({ length: 128 }, () => Math.random());

// Step 1 — add a TIMESTAMPTZ column to the schema
await client.addCollectionField({
  collection_name: "my_collection",
  field: { name: "expire_at", data_type: DataType.Timestamptz, nullable: true },
});

// Step 2 — mark the new column as the TTL field
await client.alterCollectionProperties({
  collection_name: "my_collection",
  properties: { ttl_field: "expire_at" },
});

// Step 3 (optional) — backfill expiration timestamps for historical rows
await client.upsert({
  collection_name: "my_collection",
  data: [
    { id: 1, vector, expire_at: "2026-12-31T00:00:00Z" },
  ],
});

// go

# restful

أسقط إعداد TTL

استدعاء drop_collection_properties مع ttl_field في property_keys لإيقاف انتهاء الصلاحية لكل كيان. يبقى العمود TIMESTAMPTZ نفسه في المخطط - لا يزال بإمكانك الاستعلام عنه كحقل عادي.

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

client.drop_collection_properties(
    collection_name="my_collection",
    property_keys=["ttl_field"],
)

import java.util.Collections;

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.collection.request.DropCollectionPropertiesReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build());

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

const { MilvusClient } = require("@zilliz/milvus2-sdk-node");

const client = new MilvusClient({ address: "http://localhost:19530" });

await client.dropCollectionProperties({
  collection_name: "my_collection",
  properties: ["ttl_field"],
});

// go

# restful

يؤدي إسقاط ttl_field إلى تعطيل التصفية التلقائية للاستعلامات المستقبلية، ولكن الكيانات التي انتهت صلاحيتها بالفعل لا تظهر تلقائيًا مرة أخرى. لجعل كيان منتهي الصلاحية سابقًا مرئيًا، قم بإعادة إدراجه مع None أو الطابع الزمني لانتهاء الصلاحية المستقبلي - هذه هي الطريقة الوحيدة لاستعادة الوصول إلى الصفوف المنتهية الصلاحية ضمن جلسة التحميل نفسها.

الترحيل بين الوضعين

وضعي TTL متنافيان، لذا فإن التبديل بينهما عملية متعددة الخطوات.

التبديل من TTL على مستوى المجموعة إلى TTL على مستوى الكيان

إذا تم إنشاء مجموعتك باستخدام collection.ttl.seconds وتريد التبديل إلى انتهاء الصلاحية على مستوى الكيان، اتبع الخطوات الأربع التالية. يؤدي تخطي الخطوة 1 إلى فشل الخطوة 3 مع collection TTL is already set, cannot be set ttl field.

import random
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="http://localhost:19530")

# Assumes "my_collection" already exists with `collection.ttl.seconds` set.
# Step 1 — disable collection-level TTL (mandatory; the two modes are mutually exclusive)
client.drop_collection_properties(
    collection_name="my_collection",
    property_keys=["collection.ttl.seconds"],
)

# Step 2 — add a TIMESTAMPTZ column to the schema
client.add_collection_field(
    collection_name="my_collection",
    field_name="expire_at",
    data_type=DataType.TIMESTAMPTZ,
    nullable=True,
)

# Step 3 — set the ttl_field property on the column you just added
client.alter_collection_properties(
    collection_name="my_collection",
    properties={"ttl_field": "expire_at"},
)

# Step 4 (optional) — backfill expiration timestamps for historical entities
client.upsert("my_collection", [
    {"id": 1,
     "vector": [random.random() for _ in range(128)],
     "expire_at": "2026-12-31T00:00:00Z"},
])

import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Random;

import com.google.gson.Gson;
import com.google.gson.JsonObject;

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.common.DataType;
import io.milvus.v2.service.collection.request.AddCollectionFieldReq;
import io.milvus.v2.service.collection.request.AlterCollectionPropertiesReq;
import io.milvus.v2.service.collection.request.DropCollectionPropertiesReq;
import io.milvus.v2.service.vector.request.UpsertReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build());

// Assumes "my_collection" already exists with `collection.ttl.seconds` set.
// Step 1 — disable collection-level TTL (mandatory; the two modes are mutually exclusive)
client.dropCollectionProperties(DropCollectionPropertiesReq.builder()
        .collectionName("my_collection")
        .propertyKeys(Collections.singletonList("collection.ttl.seconds"))
        .build());

// Step 2 — add a TIMESTAMPTZ column to the schema
client.addCollectionField(AddCollectionFieldReq.builder()
        .collectionName("my_collection")
        .fieldName("expire_at")
        .dataType(DataType.Timestamptz)
        .isNullable(true)
        .build());

// Step 3 — set the ttl_field property on the column you just added
Map<String, String> ttlField = new HashMap<>();
ttlField.put("ttl_field", "expire_at");
client.alterCollectionProperties(AlterCollectionPropertiesReq.builder()
        .collectionName("my_collection")
        .properties(ttlField)
        .build());

// Step 4 (optional) — backfill expiration timestamps for historical entities
Gson gson = new Gson();
Random rng = new Random();
List<Float> vector = new ArrayList<>();
for (int i = 0; i < 128; i++) vector.add(rng.nextFloat());

JsonObject row = new JsonObject();
row.addProperty("id", 1);
row.add("vector", gson.toJsonTree(vector));
row.addProperty("expire_at", "2026-12-31T00:00:00Z");

client.upsert(UpsertReq.builder()
        .collectionName("my_collection")
        .data(Collections.singletonList(row))
        .build());

// nodejs

// go

# restful

الكيانات التاريخية التي لا تقوم بردمها expire_at سيكون لها NULL في هذا العمود، مما يعني أنها لا تنتهي صلاحيتها أبدًا. ردم الصفوف التي يجب أن يكون لها عمر محدد فقط.

التبديل من مستوى الكيان إلى TTL على مستوى المجموعة

للانتقال في الاتجاه الآخر، قم بإسقاط ttl_field وتعيين collection.ttl.seconds:

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

# Assumes "my_collection" already exists with `ttl_field` set.
client.drop_collection_properties(
    collection_name="my_collection",
    property_keys=["ttl_field"],
)
client.alter_collection_properties(
    collection_name="my_collection",
    properties={"collection.ttl.seconds": 1209600},  # 14 days
)

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.collection.request.AlterCollectionPropertiesReq;
import io.milvus.v2.service.collection.request.DropCollectionPropertiesReq;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .build());

// Assumes "my_collection" already exists with `ttl_field` set.
client.dropCollectionProperties(DropCollectionPropertiesReq.builder()
        .collectionName("my_collection")
        .propertyKeys(Collections.singletonList("ttl_field"))
        .build());

Map<String, String> properties = new HashMap<>();
properties.put("collection.ttl.seconds", "1209600"); // 14 days
client.alterCollectionProperties(AlterCollectionPropertiesReq.builder()
        .collectionName("my_collection")
        .properties(properties)
        .build());

// nodejs

// go

# restful

الأسئلة الشائعة

متى تنتهي صلاحية البيانات بسبب إعدادات TTL؟

في الوقت الحالي، تنتهي صلاحية البيانات بناءً على النقطة الزمنية التي تم إدراجها أو إدراجها فيها. لن يتم عرض البيانات منتهية الصلاحية في نتائج البحث. لمزيد من التفاصيل، راجع الأمثلة.

متى سيتم حذف البيانات منتهية الصلاحية فعليًا؟

بمجرد انتهاء صلاحية البيانات، لن يتم تضمينها في أي نتائج بحث. ومع ذلك، لن يتم حذفها فعليًا إلا بعد ضغط النظام اللاحق، وفقًا لسياسات الضغط الخاصة بمجموعتك.