メインコンテンツまでスキップ

Collection TTL を設定する

Zilliz Cloud は Time-to-Live (TTL) ポリシーによってエンティティを自動的に期限切れにできます。期限切れになったエンティティは、クエリおよび検索結果には即座に表示されなくなり、次回の compaction サイクルで物理的にストレージから削除されます。通常は 24 時間以内です。

TTL には 2 つのモードがあります。

  • Collection-level TTL — collection.ttl.seconds プロパティで設定される、すべてのエンティティで共有される 1 つの保持期間です。

  • Entity-level TTL — 各エンティティが専用の TIMESTAMPTZ フィールドに独自の絶対有効期限を持ち、ttl_field プロパティによって TTL フィールドとして指定されます。

Limits​

  • Collection-level TTL は collection 全体に 1 つの保持期間を適用します。1 行だけ異なる有効期間が必要な場合は、entity-level TTL を使用してください。

  • Entity-level TTL 用のフィールドは TIMESTAMPTZ である必要があります。その他の型は拒否されます。

  • 1 つの collection につき TTL フィールドは 1 つです。スキーマに複数の TIMESTAMPTZ フィールドを含めることはできますが、ttl_field で指定できるのは 1 つだけです。

  • ttl_field を削除しても、期限切れになったエンティティは再表示されません。期限切れエンティティを復元するには、NULL または将来の有効期限タイムスタンプで upsert してください。

Overview​

展開

TTL を使うべきタイミング​

TTL は、保持が ポリシー である場合に適した手段です。つまり、特定のエンティティが最終的に削除されるべきだと事前に分かっており、cron ジョブを書かずに cluster にそれを強制させたい場合です。

代表的なシナリオ:

  • 時間ウィンドウ型データセット。 ログ、メトリクス、イベント、または短命な feature cache の直近 N 日分だけを保持する。

  • マルチテナント collection。 同じ collection 内でテナントごとに異なる保持期間がある。

  • レコード単位の保持ポリシー。 IoT パイプライン、ドキュメントストア、または MLOps feature store におけるドキュメントごとの有効期間。

  • ホット / コールドデータの混在。 短命なエンティティと長期保持のエンティティが同じ collection 内に共存する。

  • コンプライアンス主導の期限切れ。 各レコードが独自の「この日までに削除」日付を持つ GDPR 型のデータ最小化。

  • ビジネス時刻による期限切れ。 エンティティが、ある絶対時刻までしか有効でないレコードを表す場合（キャンペーン終了、セッション期限切れなど）。

📘注

期限切れになったエンティティは、いかなる検索結果やクエリ結果にも表示されません。ただし、その後の data compaction が実行されるまではストレージ内に残る場合があります。これは次の 24 時間以内に実行される必要があります。

TTL モード​

2 つのモードは、それぞれ異なる保持に関する要件に対応します。

  • Collection-level TTL は、すべてのエンティティに単一の保持期間を適用します。各エンティティは insert_ts + ttl_seconds で期限切れになります。

  • Entity-level TTL では、各エンティティが TIMESTAMPTZ フィールドに独自の絶対有効期限を保存できます。そのフィールドが NULL の場合、そのエンティティは期限切れになりません。

1 つの collection が同時に使用できるモードは 1 つ だけで、2 つは相互排他的です。両者の切り替えは複数ステップの操作です。詳細は「2 つのモード間の移行」を参照してください。

モードの選択には、以下の表を使用してください。

状況が次のどれに当てはまるか…使用するもの
collection 内のすべてのエンティティが同じ保持期間に従う必要があるCollection-level TTL
保持ルールが「挿入時点から N 秒間保持」であるCollection-level TTL
同じ collection 内でエンティティごとに異なる有効期間が必要（テナント単位、ホット/コールド、ドキュメント単位）Entity-level TTL
保持ルールが絶対的な wall-clock time（例: 2027-01-01T00:00:00Z）であるEntity-level TTL
保持が insert timestamp ではなく business timestamp によって決まるEntity-level TTL
挿入後にエンティティの有効期間を更新または延長したいEntity-level TTL
一部のエンティティは期限切れにせず、他は期限切れにしたいEntity-level TTL（期限切れにしないものには NULL を使用）

Collection-level TTL を設定する​

Collection 内のすべてのエンティティが同じ保持期間に従う必要がある場合は、collection-level TTL を使用します。

新しい collection で有効化する​

作成時に properties マップを通じて collection.ttl.seconds（整数、秒単位）を渡します。

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

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
    },
)

既存の collection で有効化する​

properties マップに collection.ttl.seconds を指定して alter_collection_properties を呼び出すと、すでに使用中の collection に TTL を適用できます。

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

# 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},
)

TTL 設定を削除する​

collection 内のデータを無期限に保持することにした場合は、その collection から TTL 設定を削除するだけで済みます。

python
from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

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

Entity-level TTL を設定する | ONDEMAND​

Entity-level TTL では、各エンティティが独自の絶対有効期限を持てます。その時刻はスキーマ内で宣言する専用の TIMESTAMPTZ 列に保存され、その列を ttl_field collection プロパティによって TTL フィールドとして指定します。

新しい collection で有効にする​

entity レベルの TTL を作成時に有効にするには、同じ create_collection 呼び出し内で 2 つ追加する必要があります。スキーマ内の TIMESTAMPTZ フィールドと、そのフィールドを指す ttl_field プロパティです。

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

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"},
)

collection が作成されたら、ISO 8601 のタイムスタンプ文字列を使って entity を挿入します。

python
import random
from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

# 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)

すべての query と vector search で、サーバーは TTL フィルターを自動挿入します。自分で記述する必要はなく、有効期限切れの entity が結果に現れることはありません。

python
from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

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)

同じ自動フィルターは client.search() にも適用されます。

compaction によって物理的に削除される前に entity の有効期間を延長するには、より遅い有効期限タイムスタンプ、または None を使って upsert し、entity を再び query 可能なセットに戻します。

python
import random
from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

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

既存の collection で有効にする​

collection がすでに存在し、collection.ttl.seconds が設定されていない場合は、add_collection_field で TIMESTAMPTZ 列を追加し、その後 alter_collection_properties でそれを TTL フィールドとして指定します。必要に応じて、過去の行を upsert して有効期限タイムスタンプをバックフィルできます。バックフィルしない行は NULL のままとなり、有効期限切れにはなりません。

python
import random
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

# 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"},
])

TTL 設定を削除する​

entity ごとの有効期限を停止するには、property_keys に ttl_field を指定して drop_collection_properties を呼び出します。TIMESTAMPTZ 列自体はスキーマに残るため、通常のフィールドとして引き続き query できます。

python
from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

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

ttl_field を削除すると、今後の query に対する自動フィルターは無効になりますが、すでに有効期限切れになっていた entity が自動的に再表示されることはありません。以前に有効期限切れになった entity を再び可視化するには、None または将来の有効期限タイムスタンプで upsert する必要があります。これが、同じ load セッション内で有効期限切れの行へのアクセスを復元する唯一の方法です。

FAQ​

TTL 設定によりデータはいつ期限切れになりますか？​

現在、データは挿入または upsert された時点に基づいて期限切れになります。有効期限切れのデータは検索結果に表示されません。詳細については、例 を参照してください。

有効期限切れのデータはいつ物理的に削除されますか？​

データが有効期限切れになると、どの検索結果にも含まれなくなります。ただし、物理的に削除されるのは、その後の system compaction が実行された後であり、これは cluster の compaction ポリシーに従います。

期限切れ後すぐにデータを削除する必要がある場合は、お問い合わせください。

CU capacity はいつ減少しますか？​

cluster の CU capacity は、メモリ使用量とストレージ使用量のうち大きい方で決まります。ストレージ使用量が適用される場合、有効期限切れのデータが物理的に削除された後に、Zilliz Cloud コンソールで CU capacity の減少を確認できます。

Ctrl I