Overview
tif1 implements a multi-tier caching architecture that reduces redundant network requests. The SQLite-backed Cache consists of:
- Parsed-object LRUs: Decoded JSON payloads (128 items) and telemetry payloads (256 items); fixed size
- Blob LRUs: Serialized JSON bytes (1024 items) and telemetry bytes (2048 items); sized by
memory_cache_max_itemsandmemory_telemetry_cache_max_items - SQLite payload tables: Durable
cacheandtelemetry_cachetables that survive across processes - SQLite frame tiers: Materialized telemetry DataFrames and the processed laps DataFrame of a session. Pandas telemetry frames live in
telemetry_frames_drv, one typed-columnar row per driver.telemetry_framesholds per-lap pandas rows from earlier releases, and frames with a column outside the telemetry dtype contract. Polars telemetry frames live intelemetry_frames_pl_ipc, one Arrow IPC row per driver.telemetry_frames_plholds per-lap polars rows from earlier releases, and rows for drivers whose laps have different schemas. The laps DataFrame lives inlaps_frames/laps_frames_pl. Both tiers derive from the payload tables, and the loader rebuilds missing rows. SQLite’sPRAGMA user_versionversions the telemetry frame tables (_FRAME_TIER_SCHEMA_VERSION, now1). A cache file with an older version drops these two tables once - Negative-verdict tier: The
missing_payloadstable remembers payloads that every CDN reported missing, formissing_payloads_ttl_days(default 7 days)
cache table also holds one TTL-scoped row per live season, f1schedule/schedule_{year}.json, written by tif1.events. After schedule_ttl_hours (default 6) the stale row is still served, and a background thread fetches the new file.
Two more tiers live outside Cache: the per-session SessionMemo (Session._memo) and the process-global backend lap LRU (get_backend_lap_cache). Hot data comes from memory (microsecond latency). Cold data comes from disk (millisecond latency) instead of a network request (latency of a second or more). The cache is thread-safe and supports synchronous and asynchronous operations.
tif1.Cache (the exported name) is the FastF1-compatible helper class in tif1.fastf1_compat. tif1.get_cache() returns the SQLite-backed tif1.cache.Cache that this page documents.Cache Architecture
The cache stores two primary types of data:- JSON Data: Session metadata, lap data, driver information, weather data, and race control messages in a key-value table
- Telemetry Data: High-frequency sensor data (speed, throttle, brake, gear, RPM, DRS). Stored in the dedicated
telemetry_cachetable with a composite primary key on (year, gp, session, driver, lap)
enable_cache on (the default), Session.load() caches all data that it fetches. The Cache API gives manual control.
Getting the Cache Instance
get_cache()
Cache instance used throughout the library. This is the primary entry point for all cache operations.
The cache is initialized lazily on first access and configured based on environment variables and .tif1rc settings. The same instance is shared across all sessions and operations in the application.
Returns: Cache - The global cache singleton
Thread Safety: The cache instance is thread-safe and can be safely accessed from multiple threads.
Example:
Cache reads all of them except TIF1_ENABLE_CACHE when it is created (the first get_cache() call):
TIF1_CACHE_DIR: Custom cache directory (default: OS-dependent; see the platform defaults in the configuration reference)TIF1_ENABLE_CACHE: Set to"false"so that sessions neither read nor write the cacheTIF1_MEMORY_CACHE_MAX_ITEMS/TIF1_MEMORY_TELEMETRY_CACHE_MAX_ITEMS: Size of the JSON and telemetry blob LRUs (defaults1024and2048)TIF1_MISSING_PAYLOADS_TTL_DAYS: Lifetime of all-CDN-missing verdicts in days (default7.0)
Cache Management Operations
clear()
cache, telemetry_cache, telemetry_frames_drv, telemetry_frames, telemetry_frames_pl, telemetry_frames_pl_ipc, laps_frames, laps_frames_pl, and missing_payloads tables. This operation is irreversible and forces all later data requests to fetch from the CDN.
Use Cases:
- Clearing corrupted cache data
- Freeing disk space
- Forcing a complete data refresh
- Troubleshooting data inconsistencies
invalidate()
cache.sqlite.
Parameters:
scope("all" | "memory" | "json" | "telemetry"): The tier to drop"all"- Every tier, memory and SQLite; equivalent toclear()"memory"- Only the four in-memory LRU tiers and the in-memory verdict mirror; SQLite rows persist"json"- The JSON payload tier: thecachetable,missing_payloads, the derivedlaps_frames/laps_frames_plrows, and the JSON LRUs"telemetry"- The telemetry tier:telemetry_cache,telemetry_frames_drv,telemetry_frames,telemetry_frames_pl,telemetry_frames_pl_ipc,laps_frames/laps_frames_pl,missing_payloads, and the telemetry LRUs
ValueError. The method first joins pending background frame writers, so a late write cannot re-insert cleared rows.
Example:
has_session_data()
gp and session first, then scans the JSON blob LRU for the {year}/{gp}/{session}/ prefix and the SQLite cache and telemetry_cache tables. On a probe error it returns True to keep cache reads enabled.
Parameters:
year(int): Season year (for example,2024,2023)gp(str): Grand Prix name, plain ("Monaco Grand Prix") or URL-encoded as held insession.gp("Monaco%20Grand%20Prix")session(str): Session name, plain ("Practice 1") or URL-encoded as held insession.session("Race","Qualifying","Practice%201","Sprint%20Qualifying")
Only
has_session_data() normalizes its arguments. The cache keys themselves use the URL-encoded names of the CDN paths, so get(), get_telemetry() and the batch readers need the encoded form (session.gp, session.session). A snake_case name such as "Monaco_Grand_Prix" matches nothing in either method.bool - True if any JSON or telemetry data exists for the session, False otherwise
Use Cases:
- Checking cache availability before loading
- Building cache status dashboards
- Implementing cache warming strategies
- Conditional data loading logic
close()
get_cache() singleton, an atexit handler runs it when the Python process exits. A private Cache() instance also closes when it is garbage-collected. Invoke it manually for fine-grained resource management.
When to Use:
- Releasing the SQLite handle of a separate
Cache()instance after maintenance work - Testing scenarios that build and discard throwaway
Cache()instances
close() sets the connection to None and clears every in-memory tier. There is no reconnect: every later read returns None and every later write is a no-op. Do not close the singleton from get_cache() before the process exits; the atexit handler closes it. For maintenance work, construct a separate Cache(cache_dir) instance and close that one.
Example:
General Cache Access (JSON Data)
These methods provide low-level access to the cache’s key-value store for JSON-serializable data. Most users will not need these methods directly, asSession.load() handles caching automatically. However, they are useful for advanced use cases like custom data pipelines or cache inspection.
get()
key(str): Cache key in the format"{year}/{gp}/{session}/{path}"wherepathis the CDN payload path, for example:drivers.json- Driver list and metadatasession_laptimes.json- Session lap timesrcm.json- Race control messagesweather.json- Weather conditionscorners.json- Circuit corner markers{driver}/laptimes.json- Per-driver lap times{driver}/{lap}_tel.json- Per-lap telemetry payload
Any | None - The cached data (typically a dict or list), or None if not found
Example:
set()
key(str): Cache key in the format"{year}/{gp}/{session}/{path}"data(Any): JSON-serializable data to cache (dict, list, str, int, float, bool, None)
orjson for performance. Ensure that the data contains only JSON-compatible types.
Compression: Serialized rows of 4096 bytes or more are compressed at the SQLite boundary with zstd level 1. Without a zstd binding, zlib level 3 is used. The in-memory LRU keeps the plain bytes.
Example:
set_raw()
compression.zstd binding and 3.11-3.13 use the zstandard package; both write identical frames.
Parameters:
key(str): Cache key in the format"{year}/{gp}/{session}/{path}"blob(bytes | bytearray | memoryview): UTF-8 JSON bytes
Telemetry Cache Access
Telemetry data (high-frequency sensor readings) lives in the dedicatedtelemetry_cache SQLite table, optimized for lap-by-lap queries. This separation improves performance for telemetry-heavy workloads and enables efficient batch operations.
Telemetry Data Structure
Each telemetry entry is the raw CDN payload of a single lap: a dict of parallel lists with lowercase keys.time- Seconds from the start of the lapspeed- Vehicle speed in km/hrpm- Engine revolutions per minutegear- Current gear (0-8, where 0 is neutral)throttle- Throttle position (0-100%)brake- Brake applied (0 or 1)drs- DRS flag (0=closed, 1=open)distance,rel_distance- Distance in meters and as a fraction of the lapacc_x,acc_y,acc_z- Accelerationsx,y,z- 3D position coordinatesDriverAhead,DistanceToDriverAhead- Car ahead and the gap to itdataKey- A string label of the lap (for example"2024-Monaco Grand Prix-Race-ALB-1"), not a list
Telemetry frames rename these keys (Time, Speed, nGear, …). The raw payload keeps the lowercase names.
get_telemetry()
None if the telemetry is not cached.
Parameters:
year(int): Season year (for example,2024)gp(str): URL-encoded Grand Prix name, as insession.gp(for example,"Monaco%20Grand%20Prix")session(str): URL-encoded session name, as insession.session(for example,"Race","Practice%201")driver(str): Three-letter driver code (for example,"VER","HAM","LEC")lap(int): Lap number (1-indexed)
Any | None - Telemetry data structure (typically a dict with arrays), or None if not found
Performance: Single telemetry lookup is optimized with a composite index on (year, gp, session, driver, lap).
Example:
set_telemetry()
telemetry_cache table.
Parameters:
year(int): Season yeargp(str): Grand Prix identifiersession(str): Session typedriver(str): Three-letter driver codelap(int): Lap numberdata(Any): Telemetry data structure to cache
orjson before storage.
Compression: Serialized rows of 4096 bytes or more are compressed at the SQLite boundary (zstd level 1), as for set().
Example:
get_telemetry_batch()
get_telemetry() multiple times, as it uses a single SQL query with an IN clause.
Parameters:
year(int): Season yeargp(str): Grand Prix identifiersession(str): Session typedriver_laps(list[tuple[str, int]]): List of (driver_code, lap_number) tuples to fetch
dict[tuple[str, int], Any] - Dictionary mapping (driver, lap) tuples to telemetry data. Missing entries are not included in the result.
Performance Benefits:
- Single database query instead of N queries
- Reduced Python-SQLite round trips
- Optimized for bulk telemetry analysis
- Ideal for comparing multiple drivers/laps
get_telemetry_frames_batch()
telemetry_frames_drv, one typed-columnar blob per driver. The blob holds the raw bytes of every block over all laps of the driver, behind a small header, compressed with lz4 (zstd as fallback). Each lap frame is a set of views into the driver’s arrays, built without the DataFrame constructor. Refs not found there fall back to the per-lap telemetry_frames rows (typed-columnar or pickle, written by earlier releases). When a session serves 32 or more laps that way, a background thread rewrites them as driver rows. Polars frames come from telemetry_frames_pl_ipc, one Arrow IPC blob per driver with the lap boundaries alongside. A lap is a slice of the driver frame. Refs not found there fall back to the per-lap telemetry_frames_pl rows. The method never returns rows from the other backend. Refs without a frame row, or with a corrupt row, are absent from the result. They fall through to the payload tier.
Parameters:
year,gp,session: Session identity, as forget_telemetry_batch()driver_laps(list[tuple[str, int]]):(driver, lap)refs to readlib("pandas"or"polars"): Backend whose frame table to readwhole_driver(bool): pandas only. Also return the other laps stored in each driver row the batch touches. The session memoizes them, so the next lap of that driver is a memo hit.frame_class(type or None): pandas only. DataFrame subclass to build, for exampleTelemetry. Its_metadataattributes start asNone.
dict[tuple[str, int], Any] - (driver, lap) to DataFrame; empty when the connection is closed or no frame codec is available
get_driver_merged_frame()
laps back to back, in the given order, from the driver’s telemetry_frames_drv row. Laps.telemetry uses it for a single driver. Each run of laps stored consecutively in one layout group is a slice of the group arrays; several runs are concatenated. Returns None when the tier has no row for the driver, the row cannot be read, or a lap is not stored in it. The caller then concatenates per-lap frames.
set_telemetry_frames_batch()
frames(list[tuple[str, int, Any]]):(driver, lap, DataFrame)tuples to persistlib("pandas"or"polars"): Backend whose frame table to write
int - Number of frames written; 0 when the tier is unavailable
get_laps_frame() / set_laps_frame()
(year, gp, session) and backend, stored in laps_frames (pandas) or laps_frames_pl (polars) with the same pickle-and-compress format as the telemetry frames. get_laps_frame() returns the DataFrame, or None on a miss, a corrupt row, or a row written by the other backend. set_laps_frame() returns 1 when the row was written and 0 when the tier is unavailable. invalidate("json"), invalidate("telemetry") and clear() drop these rows; the loader rebuilds them from the payloads.
Negative-Verdict Tier
When every CDN returns a 4xx other than 408 or 429 for a payload, the loader records the key in themissing_payloads table. Later loads skip the network probe for that key until the verdict expires. The lifetime is missing_payloads_ttl_days (TIF1_MISSING_PAYLOADS_TTL_DAYS, default 7.0). The verdicts load lazily from SQLite once per process.
is_known_missing()
True when key has an unexpired all-CDN-missing verdict. Keys use the JSON-tier format "{year}/{gp}/{session}/{path}", also for telemetry paths. An expired verdict is discarded on read and returns False.
record_missing()
key with the current timestamp, in memory and in SQLite. A later set() for the same key removes the verdict from memory and from SQLite.
discard_missing()
key from memory and SQLite, so the next load probes the CDNs again.
Example:
Async Methods
The main read and write methods have async variants for use in async contexts. These methods enable high-performance async applications to interact with the cache without blocking the event loop.Async Method Overview
Implementation Details
Async methods useloop.run_in_executor(None, ...) to run the synchronous SQLite operations in the default thread pool. This keeps the event loop free and preserves the thread safety of the sync methods.
get_async()
set_async()
get_telemetry_async()
set_telemetry_async()
get_telemetry_batch_async()
Cache Instance Attributes
TheCache instance exposes several attributes for inspecting cache configuration and state.
cache_dir
%LOCALAPPDATA%/Temp/tif1, macOS ~/Library/Caches/tif1, and Linux/other POSIX ~/.cache/tif1 when ~/.cache exists (otherwise ~/.tif1). It can be customized via TIF1_CACHE_DIR or .tif1rc.
Example:
db_path
cache.sqlite). This file contains all persistent cache data.
Use Cases:
- Backing up the cache database
- Checking database file size
- Manually inspecting cache with SQLite tools
read_only
False attribute. No configuration option or environment variable sets it, so the cache is always writable. Write methods check it internally, but there is no supported read-only mode.
Module-Level Cache API
Besides theCache class, tif1.cache exposes the building blocks of the memory tiers.
LRUCache
maxsize is MAX_CACHE_SIZE (100) from tif1.core_utils.constants; the Cache tiers pass their own configured limits. Thread-safe bounded LRU cache. It is the single LRU implementation backing the Cache in-memory tiers and the process-global backend lap caches. Reads support a lock-free fast path (get(key, ordered=False)); writes refresh LRU order and evict oldest-first at maxsize.
Methods: get(key, *, ordered=True), set(key, value), clear(), pop(key, default=None), plus in, len(), and iteration support.
get_backend_lap_cache
"{year}_{gp}_{session}_laps". One cache per backend; shared across sessions in the same process.
clear_lap_cache
Cache.get_entry / Cache.set_entry
CacheKind is "json" (a str path key) or "telemetry" (a (year, gp, session, driver, lap) tuple key). get()/set() and get_telemetry()/set_telemetry() are thin wrappers over these. Any other kind raises ValueError. The kinds "telemetry_payload" and "telemetry_df" belong to SessionMemo, not to Cache.
SessionMemo
Per-session memo tier held as Session._memo. It consolidates the session-scoped caches behind the same kind-based interface. It also owns the fastest-lap-reference memo, the persistent-cache probe result (has_session_data), and per-driver telemetry failure tracking. Not internally synchronized. The owning session’s access patterns are single-threaded per event loop.
Cache Statistics and Monitoring
TheCache class does not expose built-in statistics methods. Query the SQLite database directly for monitoring purposes. The payload tables are cache and telemetry_cache; the derived tables are telemetry_frames_drv, telemetry_frames, telemetry_frames_pl, telemetry_frames_pl_ipc, laps_frames, laps_frames_pl, and missing_payloads.
Example - Cache Size Analysis
Example - Session Coverage Report
Performance Considerations
Cache Hit Rates
The cache is most effective when:- Loading the same session multiple times
- Analyzing historical data that does not change
- Working with telemetry-heavy workloads
- Running batch analyses across multiple sessions
Memory Management
Each in-memory LRU tier has a size limit to prevent excessive memory usage. The blob tiers default to 1024 JSON and 2048 telemetry items (memory_cache_max_items, memory_telemetry_cache_max_items). The parsed-object tiers are fixed at 128 and 256 items. A full tier evicts its least-recently-used entries (they remain in SQLite).
Disk Space
The SQLite database grows as more data is cached. A session with full telemetry adds onetelemetry_cache row per driver lap, plus the derived frame rows. Telemetry takes most of the file size.
Disk Space Management:
Optimization Tips
- Use Batch Operations:
get_telemetry_batch()is faster than multipleget_telemetry()calls - Selective Loading: Only load the data that is needed (for example,
session.load(laps=True, telemetry=False)) - Async for Concurrency: Use the async methods to read the cache from async code without blocking the event loop
- Cache Warming: Pre-load frequently accessed sessions during off-peak hours
- Selective Invalidation: Use
cache.invalidate("telemetry")to drop the telemetry payloads and derived frames while the JSON payloads stay cached
Common Use Cases
Use Case 1: Cache Status Dashboard
Use Case 2: Selective Cache Clearing
Prefercache.invalidate(scope) over raw SQL. It clears the matching memory tiers and the derived SQLite rows together.
invalidate() has no per-session scope. A per-session purge needs raw SQL and must cover the derived tables too. Otherwise telemetry_frames_drv, telemetry_frames, telemetry_frames_pl, telemetry_frames_pl_ipc, laps_frames, laps_frames_pl, and missing_payloads keep stale rows for the session.
tif1.get_cache().invalidate("memory") after the purge. invalidate("memory") also drops the in-memory mirror of the verdicts, and the next probe reloads them from SQLite. Call cache.discard_missing(key) to delete one verdict outright.
Use Case 3: Cache Export/Import
Do not close theget_cache() singleton to copy the file: close() disables caching for the rest of the process. Run the copy from a separate process, or before the first get_cache() call, and resolve the path from the config. To restore a backup, copy it into a cache directory that no running tif1 process has open. Use a fresh directory, or the real one after every tif1 process exited. Then point TIF1_CACHE_DIR at it.
cache.sqlite-wal. Copy the file only while no tif1 process uses the cache.
Use Case 4: Cache Validation
Caching Strategy
Cache architecture
Config
Cache configuration
Performance
Optimization
Troubleshooting
Cache Not Working
Symptoms: Data is fetched from CDN every time, even for previously loaded sessions. Solutions:-
Check if caching is enabled:
-
Verify cache directory is writable:
-
Check environment variables:
Database Locked Errors
Symptoms:sqlite3.OperationalError: database is locked
Causes:
- Multiple processes accessing the cache simultaneously
- Long-running transactions
- Improper connection handling
-
Raise the SQLite busy timeout before the first
get_cache()call: - Avoid concurrent writes from multiple processes
-
Give each writer process its own
TIF1_CACHE_DIRfor heavy parallel writes
Cache Corruption
Symptoms: Errors when reading cached data, invalid JSON, or database integrity errors. Solutions:-
Clear and rebuild the cache:
-
Stop every tif1 process, then delete the database file and its WAL files manually (Linux default path):
-
Verify database integrity:
High Memory Usage
Symptoms: Python process consuming excessive RAM. Causes:- Large in-memory LRU cache
- Loading many sessions with telemetry
-
Reduce the blob LRU sizes with
TIF1_MEMORY_CACHE_MAX_ITEMSandTIF1_MEMORY_TELEMETRY_CACHE_MAX_ITEMS(orconfig.set()before the firstget_cache()call) -
Load data selectively:
-
Process data in batches:
Slow Cache Performance
Symptoms: Cache reads are slower than expected. Solutions:-
Use batch operations for telemetry:
-
Optimize the database with
VACUUM. Run it from a separate process while no tif1 process uses the cache: -
Check disk I/O performance:
Related Pages
Caching Strategy
Understand the multi-tier cache architecture.
Config API
Configure cache behavior and location.
Performance Guide
Optimization techniques and best practices.
Core API
Learn how sessions interact with the cache.