"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = { code: "code", p: "p", ..._provideComponents(), ...props.components }, {Heading, Mermaid} = _components; if (!Heading) _missingMdxReference("Heading", true); if (!Mermaid) _missingMdxReference("Mermaid", true); return _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: [_jsx(_components.code, { children: "tif1" }), " uses a sophisticated multi-layer caching system to minimize network requests and maximize performance."] }), "\n", _jsx(Heading, { level: "2", id: "cache-architecture", children: "Cache Architecture" }), "\n", _jsx(Mermaid, { chart: "graph TD\n A[User Request] --> B{Memory Cache?}\n B -->|Hit| C[Return Data]\n B -->|Miss| D{SQLite Cache?}\n D -->|Hit| E[Load to Memory]\n E --> C\n D -->|Miss| F[Fetch from CDN]\n F --> G[Store in SQLite]\n G --> E\n```python\n\n## Layer 1: Memory Cache (LRU)\n\nThe first layer is an in-memory LRU (Least Recently Used) cache that stores recently accessed data.\n\n### Characteristics\n\n- Fastest access (microseconds)\n- Limited size (default: 100 items)\n- Process-specific (not shared across processes)\n- Cleared when process exits\n\n### Configuration\n\n```python\nimport tif1\n\n# Configure memory cache size\nconfig = tif1.get_config()\nconfig.memory_cache_size = 200 # Store 200 items\n\n# Or via environment variable\n# export TIF1_MEMORY_CACHE_SIZE=200\n```yaml\n\n### What gets cached\n\n- Session metadata\n- Lap DataFrames\n- Telemetry DataFrames\n- Weather data\n- Race control messages\n\n### Cache Keys\n\nCache keys are generated from request parameters:\n\n```python\n# Key format: {year}_{event}_{session_type}_{data_type}\n# Example: 2025_monaco_race_laps\n```yaml\n\n## Layer 2: sqlite persistent cache\n\nThe second layer is a SQLite database that persists data across sessions.\n\n### Characteristics\n\n- Fast access (milliseconds)\n- Unlimited size (disk-limited)\n- Shared across processes\n- Survives process restarts\n\n### Location\n\nDefault cache location:\n\n```bash\n~/.tif1/cache/tif1_cache.db\n```python\n\nCustom location:\n\n```python\nimport tif1\n\nconfig = tif1.get_config()\nconfig.cache_dir = \"/custom/cache/path\"\n```yaml\n\n### Schema\n\nThe cache database has a simple schema:\n\n```sql\nCREATE TABLE cache (\n key TEXT PRIMARY KEY,\n value BLOB,\n created_at TIMESTAMP,\n accessed_at TIMESTAMP,\n size_bytes INTEGER\n);\n\nCREATE INDEX idx_accessed_at ON cache(accessed_at);\n```python\n\n### Data Storage\n\nData is stored as compressed Parquet blobs:\n\n1. DataFrame → Parquet bytes\n2. Compress with zstd\n3. Store in SQLite BLOB column\n\nThis provides:\n- Fast serialization/deserialization\n- Efficient compression (60-80% size reduction)\n- Type preservation\n\n## Cache Operations\n\n### Reading from Cache\n\n```python\nimport tif1\n\n# First access - fetches from CDN\nsession = tif1.get_session(2025, \"Monaco\", \"Race\")\nlaps = session.laps # ~2.5s (cold)\n\n# Second access - from SQLite cache\nsession2 = tif1.get_session(2025, \"Monaco\", \"Race\")\nlaps2 = session2.laps # ~50ms (warm)\n\n# Third access - from memory cache\nlaps3 = session2.laps # ~1ms (hot)\n```python\n\n### Cache Statistics\n\n```python\nimport tif1\n\ncache = tif1.get_cache()\n\n# Get cache stats\nstats = cache.get_stats()\nprint(f\"Total entries: {stats['total_entries']}\")\nprint(f\"Total size: {stats['total_size_mb']:.2f} MB\")\nprint(f\"Hit rate: {stats['hit_rate']:.1%}\")\n```python ### Clearing Cache\n\n```python\nimport tif1\n\ncache = tif1.get_cache()\n\n# Clear all cache\ncache.clear()\n\n# Clear specific session\ncache.clear_session(2025, \"Monaco\", \"Race\")\n\n# Clear old entries (older than 30 days)\ncache.clear_old(days=30)\n```python\n\n## Cache Invalidation\n\n### Manual Invalidation\n\n```python\nimport tif1\n\n# Disable cache for specific request\nsession = tif1.get_session(\n 2025,\n \"Monaco\",\n \"Race\",\n enable_cache=False # Skip cache, always fetch fresh\n)\n```python\n\n### Automatic Invalidation\n\nCache entries are automatically invalidated when:\n\n1. Data structure changes (detected by schema version)\n2. CDN data is updated (detected by ETag/Last-Modified headers)\n3. Cache corruption is detected\n\n### Time-Based Invalidation\n\n```python\nimport tif1\nfrom datetime import timedelta\n\nconfig = tif1.get_config()\n\n# Set cache TTL (time to live)\nconfig.cache_ttl = timedelta(days=7)\n\n# Entries older than 7 days will be refetched\n```python\n\n## Cache Warming\n\nPre-populate cache for better performance.\n\n### Warm entire season\n\n```python\nimport tif1\nimport asyncio\n\nasync def warm_season(year: int):\n \"\"\"Pre-cache all races for a season.\"\"\"\n events = tif1.get_events(year)\n\n tasks = []\n for event in events:\n session = tif1.get_session(year, event, \"Race\")\n tasks.append(session.laps_async())\n\n await asyncio.gather(*tasks)\n print(f\"Cached {len(events)} races\")\n\n# Run warming\nasyncio.run(warm_season(2025))\n```python\n\n### Warm specific data\n\n```python\nimport tif1\n\ndef warm_telemetry(year: int, event: str):\n \"\"\"Pre-cache telemetry for all drivers.\"\"\"\n session = tif1.get_session(year, event, \"Race\")\n\n # This fetches and caches all telemetry\n tels = session.get_fastest_laps_tels(by_driver=True)\n\n print(f\"Cached telemetry for {len(tels)} drivers\")\n\nwarm_telemetry(2025, \"Monaco\")\n```python\n\n## Cache Performance\n\n### Benchmark Results\n\n| Operation | Cold Cache | Warm Cache | Hot Cache |\n| :--- | :--- | :--- | :--- |\n| Load 20 drivers laps | ~2.5s | ~50ms | ~1ms |\n| Load telemetry | ~400ms | ~20ms | ~1ms |\n| Load weather | ~100ms | ~5ms | <1ms |\n\n### Memory Usage\n\nTypical memory usage per cached session:\n\n- Lap data: 2-5 MB\n- Telemetry (all drivers): 10-20 MB\n- Weather: <1 MB\n- Race control: <1 MB\n\n## Cache Maintenance\n\n### Monitoring cache size\n\n```python\nimport tif1\n\ncache = tif1.get_cache()\n\n# Check cache size\nsize_mb = cache.get_size_mb()\nprint(f\"Cache size: {size_mb:.2f} MB\")\n\n# List cached sessions\nsessions = cache.list_sessions()\nfor session in sessions:\n print(f\"{session['year']} {session['event']} - {session['size_mb']:.2f} MB\")\n```python\n\n### Automatic Cleanup\n\nConfigure automatic cleanup:\n\n```python\nimport tif1\n\nconfig = tif1.get_config()\n\n# Enable automatic cleanup\nconfig.cache_auto_cleanup = True\n\n# Max cache size (in MB)\nconfig.cache_max_size_mb = 1000\n\n# When cache exceeds max size, remove oldest entries\n```python\n\n## Cache in Production\n\n### Shared Cache\n\nFor multi-process applications, use a shared cache directory:\n\n```python\nimport tif1\n\n# All processes use same cache\nconfig = tif1.get_config()\nconfig.cache_dir = \"/shared/cache/tif1\"\n```python ### Read-Only Cache\n\nFor read-only deployments:\n\n```python\nimport tif1\n\nconfig = tif1.get_config()\nconfig.cache_readonly = True # Prevent writes\n\n# Will read from cache but not write new entries\n```python\n\n### Cache Replication\n\nReplicate cache across servers:\n\n```bash\n# On server 1: export cache\ntar -czf tif1_cache.tar.gz ~/.tif1/cache/\n\n# On server 2: import cache\ntar -xzf tif1_cache.tar.gz -C ~/\n```python\n\n## Troubleshooting\n\n### Cache Corruption\n\nIf you encounter cache errors:\n\n```python\nimport tif1\n\ncache = tif1.get_cache()\n\n# Verify cache integrity\nif not cache.verify():\n print(\"Cache corrupted, clearing...\")\n cache.clear()\n```python\n\n### Cache Not Working\n\nCheck cache configuration:\n\n```python\nimport tif1\n\nconfig = tif1.get_config()\n\nprint(f\"Cache enabled: {config.cache_enabled}\")\nprint(f\"Cache dir: {config.cache_dir}\")\nprint(f\"Cache writable: {os.access(config.cache_dir, os.W_OK)}\")\n```python\n\n### Performance Issues\n\nIf cache is slow:\n\n```python\nimport tif1\n\ncache = tif1.get_cache()\n\n# Rebuild cache indexes\ncache.rebuild_indexes()\n\n# Vacuum database (reclaim space)\ncache.vacuum()\n```python\n\n## Best Practices\n\n\n \n Only disable for debugging or testing.\n \n \n Pre-cache frequently accessed sessions.\n \n \n Set up alerts for cache size limits.\n \n \n Clear old entries periodically.\n \n\n\n---\n\n## Related Pages\n\n\n \n Cache management\n \n \n Optimization\n \n \n System design\n \n" })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }

Get Started

Guides

Concepts

Advanced

Reference

​Cache Architecture

Cache Architecture