Temporal Document Tracking
Temporal tracking records every create, update, and access event for each document, enabling analytics, hot-docs leaderboards, and activity histograms.
Enable
Temporal tracking is disabled by default. Enable it via environment variable:
MDDB_TEMPORAL=true mddbd
Or with Docker:
environment: MDDB_TEMPORAL: "true"
Endpoints
Query Event History
POST /v1/temporal/query
Returns the full event history for a specific document.
{ "collection": "articles", "key": "my-post", "lang": "en", "eventType": "access", "from": 1700000000, "to": 1800000000, "limit": 50
}
| Field | Type | Required | Description |
|---|---|---|---|
collection | string | ✓ | Collection name |
key | string | ✓ | Document key |
lang | string | ✓ | Document language |
eventType | string | — | create, update, access — omit for all |
from | int64 | — | Unix timestamp; defaults to 30 days ago |
to | int64 | — | Unix timestamp; defaults to now |
limit | int | — | Max events returned (default 100) |
Response:
{ "collection": "articles", "docId": "en|articles|my-post", "events": [ { "docId": "...", "collection": "articles", "eventType": "access", "timestamp": 1750000000 } ], "total": 1
}
Hot Documents Leaderboard
POST /v1/temporal/hot
Returns the top-N most accessed documents in a collection.
{ "collection": "articles", "topN": 10, "since": 1700000000
}
Response:
{ "collection": "articles", "entries": [ { "docId": "en|articles|my-post", "accessCount": 142, "lastAccessAt": 1750000000, "document": { ... } } ]
}
Activity Histogram
POST /v1/temporal/histogram
Returns event frequency bucketed by day, week, or month.
{ "collection": "articles", "eventType": "access", "interval": "day", "from": 1700000000, "to": 1800000000
}
| Field | Default | Options |
|---|---|---|
eventType | access | create, update, access |
interval | day | day, week, month |
Response:
{ "collection": "articles", "eventType": "access", "interval": "day", "buckets": [ { "from": 1700000000, "to": 1700086400, "count": 23 } ]
}
Use Cases
- Analytics dashboards — chart read/write activity over time
- Recommendation engines — surface trending content via hot-docs
- Audit trails — track who updated what and when
- Cache invalidation — trigger refreshes on heavily-accessed docs