From 632859d9e2f8f6c8dfaa18844a4886a063561e4c Mon Sep 17 00:00:00 2001
From: kenneth <kenneth@logicalclocks.com>
Date: Tue, 2 Dec 2025 14:52:01 +0100
Subject: [PATCH] add ttl example

---
 docs/user_guides/fs/feature_group/index.md |  3 +-
 docs/user_guides/fs/feature_group/ttl.md   | 92 ++++++++++++++++++++++
 mkdocs.yml                                 |  1 +
 3 files changed, 95 insertions(+), 1 deletion(-)
 create mode 100644 docs/user_guides/fs/feature_group/ttl.md

diff --git a/docs/user_guides/fs/feature_group/index.md b/docs/user_guides/fs/feature_group/index.md
index f08e15f26..0a2e1fbc3 100644
--- a/docs/user_guides/fs/feature_group/index.md
+++ b/docs/user_guides/fs/feature_group/index.md
@@ -8,4 +8,5 @@ This section serves to provide guides and examples for the common usage of abstr
 - [Data Types and Schema management](data_types.md)
 - [Statistics](statistics.md)
 - [Data Validation](data_validation.md)
-- [Feature Monitoring](feature_monitoring.md)
\ No newline at end of file
+- [Feature Monitoring](feature_monitoring.md)
+- [Time-To-Live (TTL)](ttl.md)
\ No newline at end of file
diff --git a/docs/user_guides/fs/feature_group/ttl.md b/docs/user_guides/fs/feature_group/ttl.md
new file mode 100644
index 000000000..b2ef62152
--- /dev/null
+++ b/docs/user_guides/fs/feature_group/ttl.md
@@ -0,0 +1,92 @@
+## Feature Group TTL Usage Guide
+
+Below are examples showing how to work with TTL (Time To Live) on feature groups.
+
+---
+
+### 1. Create a Feature Group with TTL Enabled
+
+```python
+from datetime import datetime, timezone
+import pandas as pd
+
+# Assume you already have a feature store handle
+# fs = ...
+
+now = datetime.now(timezone.utc)
+df = pd.DataFrame(
+    {
+        "id": [0, 1, 2],
+        "timestamp": [now, now, now],
+        "feature1": [10, 20, 30],
+        "feature2": ["a", "b", "c"],
+    }
+)
+
+fg = fs.create_feature_group(
+    name="fg_ttl_example",
+    version=1,
+    primary_key=["id"],
+    event_time="timestamp",
+    online_enabled=True,
+    ttl=60,  # TTL in seconds
+)
+
+fg.insert(
+    df,
+    write_options={
+        "start_offline_materialization": False,
+        "wait_for_online_ingestion": True,
+    },
+)
+
+fg.read(online=True)  # return empty df after ttl 
+```
+
+---
+
+### 2. Update the TTL Value
+
+```python
+# Example: change TTL to a new value (in seconds)
+new_ttl_seconds = 120
+# Later, update TTL
+fg.enable_ttl(new_ttl_seconds)
+
+---
+
+### 3. Disable TTL and Enable It Again
+
+```python
+# Disable TTL
+fg.disable_ttl()
+
+# ... time passes, you decide to enforce TTL again ...
+
+# Re‑enable TTL with a new value (in seconds)
+fg.enable_ttl()  # If ttl is not set, the feature group will be enabled with the last TTL value being set.
+
+# Or Re‑enable TTL with a new value (in seconds)
+fg.enable_ttl(ttl=90)
+```
+
+---
+
+### 4. Enable TTL on an Existing Feature Group (Created Without TTL)
+
+```python
+# Assume this FG was created earlier without TTL
+fg = fs.get_feature_group(
+    name="fg_existing_no_ttl",
+    version=1,
+)
+
+# Enable TTL for the first time
+fg.enable_ttl(ttl=60)  # seconds
+
+```
+
+
+### Reference
+
+API reference on all possible types of ttl value can be found [here.](https://docs.hopsworks.ai/hopsworks-api/latest/generated/api/feature_group_api/#enable_ttl)
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 32b3a9bca..be01750f3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -87,6 +87,7 @@ nav:
               - Notification: user_guides/fs/feature_group/notification.md
               - On-Demand Transformations: user_guides/fs/feature_group/on_demand_transformations.md
               - Online Ingestion Observability: user_guides/fs/feature_group/online_ingestion_observability.md
+              - Time-To-Live (TTL): user_guides/fs/feature_group/ttl.md
           - Feature View:
               - user_guides/fs/feature_view/index.md
               - Overview: user_guides/fs/feature_view/overview.md