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

Collection TTL の設定

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

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

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

  • Entity-level TTL — 各エンティティが専用の TIMESTAMPTZ フィールドに独自の絶対有効期限時刻を持ち、そのフィールドは ttl_field プロパティを通じて TTL フィールドとしてマークされます。

📘Notes

この機能はマネージドコレクションにのみ適用されます。

制限​

  • 2 つの TTL モードは相互に排他的です。コレクションで collection.ttl.seconds と ttl_field の両方を同時に設定することはできません。切り替えるには、2 つのモード間で移行するを参照してください。

  • Collection-level TTL は、コレクション全体に 1 つの期間を適用します。単一の行に異なる有効期間が必要な場合は、entity-level TTL を使用してください。

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

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

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

概要​

展開

TTL を使用する場合​

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

典型的なシナリオ:

  • 時間ウィンドウ付きデータセット。 ログ、メトリクス、イベント、または短命の特徴量キャッシュの直近 N 日分のみを保持します。

  • マルチテナントコレクション。 同じコレクション内で異なるテナントが異なる保持期間を持ちます。

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

  • Hot / cold データの混在。 同じコレクション内で短命のエンティティと長期のエンティティが共存します。

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

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

📘Notes

期限切れのエンティティは、検索またはクエリの結果に一切表示されません。ただし、それらは後続のデータコンパクションまでストレージに残る場合があり、これは次の 24 時間以内に実行されるはずです。

TTL モード​

2 つのモードは、異なる保持に関する問いに答えます。

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

  • Entity-level TTL では、すべてのエンティティが TIMESTAMPTZ フィールドに独自の絶対有効期限時刻を保存できます。そのフィールドの NULL は、エンティティが期限切れにならないことを意味します。

コレクションは一度に 1 つ のモードを使用します。この 2 つは相互に排他的です。これらを切り替えるには複数ステップの操作が必要です。2 つのモード間で移行するを参照してください。

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

状況が次の場合…使用するもの
コレクション内のすべてのエンティティが同じ保持期間に従う必要があるCollection-level TTL
保持が「挿入の瞬間から N 秒保持する」であるCollection-level TTL
同じコレクション内の異なるエンティティに異なる有効期間が必要である（テナントごと、hot/cold、ドキュメントごと）Entity-level TTL
保持が絶対的な実時刻（例: 2027-01-01T00:00:00Z）であるEntity-level TTL
保持が挿入タイムスタンプではなく、ビジネスタイムスタンプによって決まるEntity-level TTL
挿入後にエンティティの有効期間を更新または延長したいEntity-level TTL
一部のエンティティは期限切れにせず、他のエンティティは期限切れにしたいEntity-level TTL（期限切れにしないものには NULL を使用）

Collection-level TTL を設定する​

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

新しいコレクションで有効にする​

作成時に 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
    },
)

既存のコレクションで有効にする​

すでに使用中のコレクションに TTL を適用するには、properties マップに collection.ttl.seconds を指定して alter_collection_properties を呼び出します。

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 設定を削除する​

コレクション内のデータを無期限に保持することにした場合は、そのコレクションから 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 コレクションプロパティを通じて TTL フィールドとしてマークします。

新しい collection で有効化する​

作成時に entity レベル TTL を有効化するには、同じ create_collection 呼び出しで 2 つの追加が必要です。schema 内の TIMESTAMPTZ field と、その field を指す ttl_field property です。

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 timestamp 文字列を持つ 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 filter を自動的に挿入します。自分で記述する必要はなく、期限切れの 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)

同じ自動 filter は client.search() にも適用されます。

compaction によって物理的に削除される前に entity の有効期間を延長するには、より後の有効期限 timestamp（または 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 column を追加し、alter_collection_properties でそれを TTL field としてマークします。必要に応じて、過去の row を upsert して有効期限 timestamp をバックフィルできます。バックフィルしない row は 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 column 自体は schema 上に残るため、通常の field として引き続き 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 に対する自動 filter は無効になりますが、すでに期限切れになっていた entity が自動的に再表示されるわけではありません。以前に期限切れになった entity を表示可能にするには、None または将来の有効期限 timestamp で upsert します。同じ load session 内で期限切れ row へのアクセスを復元する唯一の方法です。

2 つのモード間を移行する | PRIVATE​

2 つの TTL モードは相互に排他的であるため、切り替えは複数ステップの操作になります。

collection レベル TTL から entity レベル TTL に切り替える​

collection が collection.ttl.seconds で作成されており、entity ごとの有効期限に切り替えたい場合は、次の 4 つの手順に従います。ステップ 1 を省略すると、ステップ 3 は collection TTL is already set, cannot be set ttl field で失敗します。

python
import random
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

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

expire_at をバックフィルしない過去の entity では、その column は NULL になり、期限切れにならないことを意味します。有限の有効期間を持つべき row のみをバックフィルしてください。

entity レベル TTL から collection レベル TTL に切り替える​

反対方向に移行するには、ttl_field を削除し、collection.ttl.seconds を設定します。

python
from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT")

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

FAQ​

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

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

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

データが期限切れになると、どの search results にも含まれなくなります。ただし、物理的に削除されるのは、cluster の compaction ポリシーに従って、その後のシステム compaction が実行された後です。

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

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

cluster の CU 容量は、メモリ使用量とストレージ使用量のうち高い方です。ストレージ使用量が該当する場合、期限切れデータが物理的に削除された後、Zilliz Cloud console で CU 容量の減少を確認できます。

Ctrl I