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

コレクションの TTL を設定する

Zilliz Cloud では、Time-to-Live（TTL） ポリシーを使用してエンティティを自動的に期限切れにできます。期限切れのエンティティはクエリおよび検索結果にすぐに表示されなくなり、次の Compaction サイクルでストレージから物理的に削除されます。通常、これは 24 時間以内に実行されます。

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

  • コレクションレベルの TTL — すべてのエンティティで共有される単一の保持期間です。collection.ttl.seconds プロパティで設定します。

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

📘Notes

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

制限​

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

  • コレクションレベルの TTL は、コレクション全体に 1 つの保持期間を適用します。特定の行に異なる有効期間が必要な場合は、エンティティレベルの TTL を使用してください。

  • エンティティレベルの TTL に使用するフィールドは TIMESTAMPTZ である必要があります。その他の型は拒否されます。

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

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

概要​

展開

TTL を使用する場合​

保持が ポリシー である場合、TTL が適切な手段です。特定のエンティティが最終的に削除されるべきであることを事前に把握しており、cron ジョブを作成することなくクラスターにそのポリシーを適用したい場合に使用します。

一般的なシナリオは次のとおりです。

  • 時間枠で区切られたデータセット。 ログ、メトリクス、イベント、または短命な特徴量キャッシュの直近 N 日分のみを保持します。

  • マルチテナントのコレクション。 同じコレクション内で、テナントごとに異なる保持期間を設定します。

  • レコード単位の保持ポリシー。 IoT パイプライン、ドキュメントストア、または MLOps 特徴量ストアで、ドキュメントごとの有効期間を設定します。

  • ホットデータとコールドデータの混在。 短命なエンティティと長期間保持するエンティティを同じコレクション内に共存させます。

  • コンプライアンスに基づく期限切れ。 各レコードが独自の「削除期限」を持つ、GDPR 形式のデータ最小化です。

  • ビジネス上の時刻に基づく期限切れ。 エンティティが、特定の絶対時点（キャンペーンの終了、セッションの期限切れなど）までのみ有効なレコードを表す場合に使用します。

📘Notes

期限切れのエンティティは、検索結果やクエリ結果に表示されません。ただし、後続のデータ Compaction が実行されるまでストレージに残る可能性があります。この Compaction は、次の 24 時間以内に実行される必要があります。

TTL モード​

2 つのモードは、保持に関する異なる課題に対応します。

  • コレクションレベルの TTL は、すべてのエンティティに単一の保持期間を適用します。各エンティティは insert_ts + ttl_seconds で期限切れになります。

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

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

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

状況が次の場合…

使用するモード

コレクション内のすべてのエンティティが同じ保持期間に従う場合

コレクションレベルの TTL

保持期間が「挿入時点から N 秒間保持する」という条件である場合

コレクションレベルの TTL

同じコレクション内でエンティティごとに異なる有効期間が必要な場合（テナント別、hot/cold, ドキュメント別）

エンティティレベルの TTL

保持期間が絶対的な実時刻（たとえば 2027-01-01T00:00:00Z）である場合

エンティティレベルの TTL

保持期間が挿入タイムスタンプではなくビジネス上のタイムスタンプに基づく場合

エンティティレベルの TTL

挿入後にエンティティの有効期間を更新または延長する場合

エンティティレベルの TTL

一部のエンティティは期限切れにせず、他のエンティティは期限切れにする場合

エンティティレベルの TTL（期限切れにしないエンティティには NULL を使用）

コレクションレベルの TTL を設定する​

コレクション内のすべてのエンティティが同じ保持期間に従う場合は、コレクションレベルの TTL を使用してください。

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

作成時に、collection.ttl.seconds（整数、秒単位）を properties マップで指定します。

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT", token="YOUR_CLUSTER_TOKEN")

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", token="YOUR_CLUSTER_TOKEN")

# 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", token="YOUR_CLUSTER_TOKEN")

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

エンティティレベルの TTL を設定する​

Public Preview

エンティティレベルの TTL では、各エンティティが独自の絶対有効期限を持ちます。この時刻は、スキーマで宣言する専用の TIMESTAMPTZ 列に保存され、コレクションの ttl_field プロパティを通じて TTL フィールドとして指定されます。

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

作成時にエンティティレベルの TTL を有効にするには、同じ create_collection 呼び出しで 2 つの項目を追加します。スキーマに TIMESTAMPTZ フィールドを追加し、そのフィールドを指す ttl_field プロパティを設定します。

python
from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT", token="YOUR_CLUSTER_TOKEN")

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

コレクションを作成したら、ISO 8601 のタイムスタンプ文字列を使用してエンティティを挿入します。

python
import random
from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT", token="YOUR_CLUSTER_TOKEN")

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

すべてのクエリとベクトル検索で、サーバーは TTL フィルターを自動的に挿入します。フィルターを自分で記述する必要はなく、期限切れのエンティティが結果に表示されることもありません。

python
from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT", token="YOUR_CLUSTER_TOKEN")

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 によってエンティティが物理的に削除される前にその有効期間を延長するには、より後の有効期限タイムスタンプ、または None を指定して upsert し、エンティティをクエリ可能なセットに戻します。

python
import random
from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT", token="YOUR_CLUSTER_TOKEN")

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

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

コレクションがすでに存在し、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", token="YOUR_CLUSTER_TOKEN")

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

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

python
from pymilvus import MilvusClient

client = MilvusClient(uri="YOUR_CLUSTER_ENDPOINT", token="YOUR_CLUSTER_TOKEN")

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

ttl_field を削除すると、以降のクエリでは自動フィルターが無効になりますが、すでに期限切れになったエンティティが自動的に再表示されることはありません。以前に期限切れになったエンティティを表示するには、None または将来の有効期限タイムスタンプを指定して upsert してください。これが、同じロードセッション内で期限切れの行へのアクセスを復元する唯一の方法です。

2 つのモード間の移行​

2 つの TTL モードは相互に排他的であるため、モードを切り替えるには複数の手順を実行する必要があります。

コレクションレベルの TTL からエンティティレベルの TTL に切り替える​

コレクションを collection.ttl.seconds で作成し、エンティティごとの期限切れに切り替える場合は、以下の手順に従ってください。ステップ 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",
    token="YOUR_CLUSTER_TOKEN"
)

# 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 をバックフィルしない既存のエンティティは、その列に NULL が入り、期限切れになることはありません。有効期間を有限にする必要がある行のみをバックフィルしてください。

エンティティレベルの TTL からコレクションレベルの TTL に切り替える​

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

python
from pymilvus import MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

# 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 された時点に基づいて期限切れになります。期限切れのデータは検索結果に表示されません。詳細については、例 を参照してください。

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

データは期限切れになると、検索結果に含まれなくなります。ただし、クラスターの Compaction ポリシーに従い、次のシステム Compaction が実行された後にのみ物理的に削除されます。

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

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

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

このページは役に立ちましたか？
Ctrl I