@st.cache_data Implementation for High-Performance Spatial Dashboards

Spatial dashboards built on Streamlit suffer a specific class of latency problem: every user interaction that touches a map layer, CRS transformation, or spatial join can trigger a full re-execution of Python code that reads from disk, hits a database, or reprojects tens of thousands of geometries. Without a disciplined caching layer, UI threads block, memory climbs with each new session, and dashboards that perform acceptably on a developer’s laptop collapse under modest concurrent load in production.

@st.cache_data is Streamlit’s function-level memoization primitive. It intercepts calls to decorated functions, serializes the return value to an in-memory or disk-backed store keyed by the function’s inputs, and short-circuits all subsequent calls with identical arguments. For geospatial workloads this decorator is not optional polish — it is the primary mechanism for keeping tile renders, boundary lookups, and spatial aggregations inside acceptable latency budgets. This guide builds a complete, production-ready implementation workflow, from the first decorator to distributed deployment, with specific attention to the hashing failures that catch GIS engineers off guard.

Jump to heading# The Problem: Why Spatial Pipelines Break Without Memoization

A typical sequence in a Streamlit mapping dashboard might look like: read an administrative boundary GeoPackage, reproject from EPSG:27700 to EPSG:4326, dissolve by region, then join with a PostGIS query result. Each of those steps is expensive. Without caching, Streamlit re-runs the entire script on every widget interaction — slider move, dropdown change, map click. A 200 MB GeoPackage that takes 1.8 seconds to read and reproject will do so on every re-run. With five concurrent users, that is a sustained 9-second I/O load per widget event.

@st.cache_data breaks this loop. Once the function’s result is stored, re-runs return it in microseconds from the in-process dictionary. The cache key is derived from the function’s source code hash and its argument values, so different inputs still trigger real computation while identical inputs are served from memory. Crucially, the decorator also isolates serialized copies between sessions — unlike @st.cache_resource, which returns a shared mutable reference — which matters enormously for GeoDataFrames that users might filter or modify after retrieval.

Jump to heading# Prerequisites

The following environment baseline is required before implementing this pattern. For broader context on where function-level caching fits in your overall architecture, see Caching Strategies & Async Performance Tuning.

• Python 3.9 or later. Required for stable asyncio.to_thread bridging; Python 3.11+ is recommended for TaskGroup support if you pair caching with Async Data Loading Patterns.
• streamlit>=1.18.0 — the release that introduced the stable @st.cache_data API and formally deprecated @st.cache. Do not mix the old and new decorators in the same codebase.
• Geospatial stack: geopandas>=0.12, shapely>=2.0, pyarrow. Shapely 2.0’s vectorized geometry engine is meaningfully faster to serialize than 1.x, which reduces cache write overhead. pyarrow is required if you use Streamlit’s Arrow-backed caching path.
• Optional: rasterio and xarray for raster pipelines; psycopg2 or asyncpg for PostGIS connectivity.
• Operational: set STREAMLIT_SERVER_FILE_WATCHER_TYPE=none in production to prevent the file-watcher from invalidating caches on every hot-reload cycle. Point any persist="disk" cache to a persistent, high-throughput volume — not the container’s ephemeral /tmp.

A working knowledge of Session State Patterns is assumed. Understanding how Streamlit’s reactive execution model re-runs scripts top-to-bottom on each interaction is the conceptual prerequisite for reasoning about what to cache and what to exclude.

Jump to heading# Data-Flow Architecture

The diagram below shows how @st.cache_data sits between the raw I/O layer and Streamlit’s rendering pipeline, intercepting repeated requests and routing them to the memory or disk store rather than back to the source.

Jump to heading# Core Implementation Workflow

Jump to heading# Step 1 — Identify Cache Boundaries and Function Signatures

Isolate functions that perform expensive, deterministic operations: reading GeoJSON or GeoPackage files, executing geopandas.sjoin(), projecting coordinate reference systems via to_crs(), computing spatial indices via .sindex, or running PostGIS queries. These functions are cache candidates. Exclude from caching anything that returns mutable UI components, reads st.session_state, or produces randomized outputs.

The cache key is derived from the function’s source code hash and its argument values. Any non-deterministic input — a live database connection object, a current timestamp, a floating-point result of a prior step — will produce cache misses even when the underlying data has not changed. Design function signatures so every argument is either a primitive, a file path string, or a hashable value you control.

Jump to heading# Step 2 — Apply the Decorator with GIS-Safe Parameter Types

Wrap the target function with @st.cache_data. When working with GeoDataFrames, pass the file path or a versioned URI rather than the DataFrame object itself. Streamlit’s serialization engine relies on pickle, which struggles with C-level geometry buffers. By caching at the I/O boundary you guarantee that identical file paths produce identical cache keys.

import geopandas as gpd
import streamlit as st

@st.cache_data(ttl=3600, max_entries=50, persist="disk")
def load_admin_boundaries(file_path: str, target_crs: str = "EPSG:4326") -> gpd.GeoDataFrame:
    """Load and project administrative boundaries with deterministic caching."""
    gdf = gpd.read_file(file_path)
    return gdf.to_crs(target_crs)


# Called on every Streamlit re-run — result served from cache after first load
boundaries = load_admin_boundaries(
    "data/lad_boundaries_2023.gpkg",
    target_crs="EPSG:4326"
)

The ttl=3600 argument invalidates the entry after one hour. max_entries=50 caps the in-memory dictionary to prevent unbounded growth. persist="disk" writes a serialized copy to disk so the cache survives app restarts — important when container memory is recycled but a shared volume is mounted.

Jump to heading# Step 3 — Configure Lifecycle and Memory Parameters

Tune ttl and max_entries to match your data refresh cadence and infrastructure limits.

Always set max_entries explicitly. Leaving it unbounded means a dashboard that serves hundreds of unique bounding-box filter combinations will grow its cache dictionary without limit until the worker OOM-kills. A reasonable starting value is 100 entries for large GeoDataFrames, adjusted down if RSS monitoring shows excess memory pressure.

Jump to heading# Step 4 — Validate Cache Behaviour and Hit Ratios

During development, call st.cache_data.clear() to force invalidation and verify that your pipeline correctly rebuilds the cache from scratch. Use Streamlit’s built-in cache inspector in the sidebar to observe hit and miss events interactively.

import streamlit as st
import time

@st.cache_data(ttl=1800, max_entries=30)
def expensive_spatial_join(left_path: str, right_path: str) -> "gpd.GeoDataFrame":
    import geopandas as gpd
    t0 = time.perf_counter()
    left = gpd.read_file(left_path)
    right = gpd.read_file(right_path)
    result = gpd.sjoin(left, right, how="inner", predicate="intersects")
    elapsed = time.perf_counter() - t0
    # Log to app console so you can verify cache hits eliminate this output
    print(f"[cache miss] spatial join took {elapsed:.2f}s, {len(result)} rows")
    return result

A healthy spatial pipeline should achieve a cache hit rate above 85 % under normal concurrency. If you observe frequent misses despite identical inputs, inspect your function signatures for hidden mutable state — default arguments that reference a module-level object, dynamic CRS strings assembled at call time, or timestamp-derived paths.

Jump to heading# Step 5 — Integrate with Async and Query Layers

When spatial queries originate from external databases or cloud storage, pair @st.cache_data with Async Data Loading Patterns to prevent blocking the main thread during the cold-cache path. For database-backed workloads, implement Query Result Caching to intercept SQL and GeoServer responses before they reach the Python layer.

import asyncio
import geopandas as gpd
import streamlit as st

@st.cache_data(ttl=900, max_entries=20)
def load_postgis_layer(dsn: str, table: str, bbox: tuple[float, float, float, float]) -> gpd.GeoDataFrame:
    """Cache PostGIS spatial query results keyed by DSN, table, and bounding box."""
    import sqlalchemy
    engine = sqlalchemy.create_engine(dsn)
    west, south, east, north = bbox
    sql = f"""
        SELECT geom, name, region_code
        FROM {table}
        WHERE geom && ST_MakeEnvelope({west}, {south}, {east}, {north}, 4326)
    """
    return gpd.read_postgis(sql, engine, geom_col="geom", crs="EPSG:4326")

This layered approach decouples I/O latency from rendering performance, ensuring that heavy geospatial payloads served from a warm cache never block the UI thread.

Jump to heading# Advanced Patterns

Every advanced pattern below is, at heart, a decision about how Streamlit derives a stable cache key from a non-trivial argument. The flow chart maps each GIS argument type to the technique that keeps it deterministic — and shows which path raises UnhashableParamError if you skip it.

Jump to heading# Pattern 1 — Custom hash_funcs for Complex GIS Objects

Geospatial workflows frequently need to pass pyproj.CRS objects, Shapely geometry instances, or other C-extension types as function arguments. These are unhashable by default and will raise UnhashableParamError. Supply a hash_funcs mapping that extracts only the deterministic component from each type.

import geopandas as gpd
import streamlit as st
from pyproj import CRS
from shapely.geometry.base import BaseGeometry

@st.cache_data(
    ttl=1800,
    max_entries=25,
    hash_funcs={
        gpd.GeoDataFrame: lambda gdf: hash(gdf.to_wkb().tobytes()),
        CRS: lambda crs: crs.to_epsg(),
        BaseGeometry: lambda geom: hash(geom.wkb),
    }
)
def clip_to_aoi(
    gdf: gpd.GeoDataFrame,
    aoi: BaseGeometry,
    target_crs: CRS
) -> gpd.GeoDataFrame:
    """Clip a GeoDataFrame to an area of interest, projecting to target CRS."""
    clipped = gdf.clip(aoi)
    return clipped.to_crs(target_crs)

hash_funcs keys must be the actual type object (e.g., gpd.GeoDataFrame), not a string such as "geopandas.GeoDataFrame". String-based keys are silently ignored by @st.cache_data.

Jump to heading# Pattern 2 — Versioned Cache Keys for Dataset Refresh Cycles

Static boundary files rarely change, but when they do — a new ONS release, an updated census boundary — you need explicit invalidation without restarting the application. Encode a version string or a dataset checksum as a function argument so that a new dataset version automatically creates a distinct cache entry.

import hashlib
import pathlib
import geopandas as gpd
import streamlit as st

def file_md5(path: str) -> str:
    """Return the MD5 digest of a file — stable cache key for versioned datasets."""
    h = hashlib.md5()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(65536), b""):
            h.update(chunk)
    return h.hexdigest()

@st.cache_data(ttl=None, max_entries=10)
def load_boundaries_versioned(file_path: str, version_hash: str) -> gpd.GeoDataFrame:
    """version_hash is derived from the file's MD5 so stale entries self-expire on dataset update."""
    gdf = gpd.read_file(file_path)
    return gdf.to_crs("EPSG:4326")

# At call site — recompute hash on each run (cheap) so cache key tracks dataset changes
boundaries = load_boundaries_versioned(
    "data/lad_2024.gpkg",
    version_hash=file_md5("data/lad_2024.gpkg")
)

Jump to heading# Pattern 3 — Redis-Backed Warm Cache for Distributed Workers

Single-node persist="disk" caches become fragmented when multiple Streamlit workers or containerized replicas each maintain their own serialized store. For cross-worker cache warming, use Redis as a shared key-value store and call it from within the @st.cache_data function body. The outer decorator still short-circuits at the process level; the inner Redis call handles cross-process sharing.

import geopandas as gpd
import io
import redis
import streamlit as st

_redis = redis.Redis(host="redis", port=6379, db=0)

@st.cache_data(ttl=600, max_entries=5)
def load_layer_distributed(layer_key: str, file_path: str) -> gpd.GeoDataFrame:
    """
    Process-local cache via @st.cache_data.
    Cross-worker warm cache via Redis using Parquet serialization.
    """
    raw = _redis.get(layer_key)
    if raw is not None:
        return gpd.read_parquet(io.BytesIO(raw))

    gdf = gpd.read_file(file_path).to_crs("EPSG:4326")
    buf = io.BytesIO()
    gdf.to_parquet(buf, index=False, compression="snappy")
    _redis.setex(layer_key, 600, buf.getvalue())
    return gdf

Parquet with Snappy compression is substantially faster to serialize and deserialize than pickle for large GeoDataFrames, and it preserves columnar structure that Arrow-backed rendering tools can consume without an intermediate copy.

Jump to heading# Verification and Testing

Confirm that caching is active and performing as expected before deploying to production.

import time
import geopandas as gpd
import streamlit as st

@st.cache_data(ttl=3600, max_entries=10)
def load_test_layer(path: str) -> gpd.GeoDataFrame:
    return gpd.read_file(path).to_crs("EPSG:4326")

# First call — cold cache
t0 = time.perf_counter()
gdf_a = load_test_layer("data/lad_boundaries_2023.gpkg")
cold_time = time.perf_counter() - t0

# Second call — should be served from cache (orders of magnitude faster)
t1 = time.perf_counter()
gdf_b = load_test_layer("data/lad_boundaries_2023.gpkg")
warm_time = time.perf_counter() - t1

assert warm_time < cold_time * 0.05, (
    f"Cache not active: cold={cold_time:.3f}s warm={warm_time:.3f}s"
)
# Both calls should return structurally equivalent DataFrames
assert list(gdf_a.columns) == list(gdf_b.columns)
assert len(gdf_a) == len(gdf_b)
print(f"Cache working: {cold_time:.2f}s cold → {warm_time:.4f}s warm")

For memory profiling, use tracemalloc or memory_profiler to snapshot RSS before and after warming the cache. Target a growth rate below 50 MB per 100 unique cache entries for typical boundary datasets. If growth is higher, reduce max_entries or switch to Parquet-backed serialization.

Jump to heading# Troubleshooting

Jump to heading# Performance Considerations

Payload size thresholds. Functions returning GeoDataFrames under 50 MB are straightforward candidates for @st.cache_data with default settings. Between 50 MB and 200 MB, switch to persist="disk" and Parquet serialization. Above 200 MB, consider whether caching the full object is the right strategy — it may be cheaper to cache only the result of a spatial filter applied to the full dataset, rather than the full dataset itself.

Cache key design. The cache key includes a hash of the function’s source code. Refactoring a cached function’s internals while keeping its signature identical does not automatically invalidate existing entries — only a change to the source code that inspect.getsource() would detect triggers invalidation. When you fix a bug in a cached function, bump a version: int = 1 argument or call st.cache_data.clear() explicitly during deployment.

Async vs sync trade-offs. @st.cache_data is synchronous — the cold-cache execution path blocks the script thread. For I/O-bound operations (large file reads, network requests to OGC endpoints), pair the decorator with asyncio.to_thread or use a ThreadPoolExecutor to move the blocking call off the main thread during the miss path. Once the result is cached, subsequent calls return synchronously at negligible cost. For detailed guidance see Async Data Loading Patterns.

Thread safety. @st.cache_data is thread-safe by design: concurrent requests for the same key block on the first computation and then all receive the cached result. However, never mutate a cached GeoDataFrame in-place. Always produce a new copy before applying user-driven filters: gdf_filtered = gdf.copy().loc[mask].

Memory Limit Management integration. Cache sizing and memory budgets must be planned together. Set the container’s memory limit first, allocate a fixed fraction (typically 30–40 %) to the cache store, and derive max_entries from that budget divided by your average object size. Adjust after observing actual RSS under load.

Jump to heading# Frequently Asked Questions

Back to Caching Strategies & Async Performance Tuning

Related

• Query Result Caching for Spatial Dashboards — intercept PostGIS and GeoServer responses before they reach the Python layer
• Async Data Loading Patterns — concurrent tile and vector fetching to keep the cold-cache path non-blocking
• Memory Limit Management — size cache stores and container limits together
• Fixing Cache Invalidation for Dynamic Spatial Queries — deterministic key generation for geometry-dependent queries