MooseStack

Moose OLAP

TTL (Time-to-Live)

TTL (Time-to-Live) for ClickHouse Tables

Moose lets you declare ClickHouse TTL directly in your data model:

  • Table-level TTL via the ttl option on OlapTable config
  • Column-level TTL via ClickHouseTTL on individual fields

When to use TTL

  • Automatically expire old rows to control storage cost
  • Mask or drop sensitive columns earlier than the full row expiry

TypeScript

import { OlapTable, ClickHouseEngines, Key, DateTime, ClickHouseTTL } from "@514labs/moose-lib";
 
interface Event {
  id: Key<string>;
  timestamp: DateTime;
  email: string & ClickHouseTTL<"timestamp + INTERVAL 30 DAY">; // column TTL
}
 
export const Events = new OlapTable<Event>("Events", {
  engine: ClickHouseEngines.MergeTree,
  orderByFields: ["id", "timestamp"],
  // Provide the ClickHouse TTL expression without the leading 'TTL'
  ttl: "timestamp + INTERVAL 90 DAY DELETE", // table TTL
});

Python

from typing import Annotated
from moose_lib import OlapTable, OlapConfig, Key, ClickHouseTTL
from pydantic import BaseModel
from datetime import datetime
 
class Event(BaseModel):
    id: Key[str]
    timestamp: datetime
    email: Annotated[str, ClickHouseTTL("timestamp + INTERVAL 30 DAY")]
 
events = OlapTable[Event](
    "Events",
    OlapConfig(
        order_by_fields=["id", "timestamp"],
        ttl="timestamp + INTERVAL 90 DAY DELETE",
    ),
)

Notes

  • Expressions must be valid ClickHouse TTL expressions, but do not include the leading TTL keyword.
  • Column TTLs are independent from the table TTL and can be used together.
  • Moose will apply TTL changes via migrations using ALTER TABLE ... MODIFY TTL and MODIFY COLUMN ... TTL.

Related

  • See Modeling Tables for defining your schema
  • See Applying Migrations to roll out TTL changes

Supported Types

Schema Optimization