(superset) branch master updated: docs(cache): document native filter option cache warm-up strategy (#42953)

[jl...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sadpandajoe pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git


The following commit(s) were added to refs/heads/master by this push:
     new 7dc2afd377b docs(cache): document native filter option cache warm-up strategy (#42953)
7dc2afd377b is described below

commit 7dc2afd377b46c7c181600b5982d99bac56796f8
Author: Evan Rusackas <ev...@preset.io>
AuthorDate: Mon Aug 10 10:28:36 2026 -0700

    docs(cache): document native filter option cache warm-up strategy (#42953)
    
    Co-authored-by: Claude <no...@anthropic.com>
---
 docs/admin_docs/configuration/cache.mdx | 44 +++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/admin_docs/configuration/cache.mdx b/docs/admin_docs/configuration/cache.mdx
index f7a02df9817..efb2587646e 100644
--- a/docs/admin_docs/configuration/cache.mdx
+++ b/docs/admin_docs/configuration/cache.mdx
@@ -134,6 +134,50 @@ CELERY_CONFIG = CustomCeleryConfig
 This will cache the top 5 most popular dashboards every hour. For other
 strategies, check the `superset/tasks/cache.py` file.
 
+### Warming Up Native Filter Options
+
+Native filter Value-type dropdown option queries (e.g. `SELECT DISTINCT column FROM table`) are
+cached the same way as chart data, via `DATA_CACHE_CONFIG`. However, the strategies above only warm
+up chart render queries, so the first user to open a dashboard's filter dropdown after a cache entry
+expires still triggers a fresh database query.
+
+The `native_filter_options` strategy pre-populates the cache for these dropdown queries. It reads
+each dashboard's `native_filter_configuration`, builds the same `filter_select` chart-data query the
+frontend would send, and executes it as the configured `SUPERSET_CACHE_WARMUP_USER`:
+
+```python
+class CustomCeleryConfig(CeleryConfig):
+    beat_schedule = {
+        **CeleryConfig.beat_schedule,
+        'cache-warmup-native-filters': {
+            'task': 'cache-warmup',
+            'schedule': crontab(minute=0, hour=3),  # daily at 03:00
+            'kwargs': {
+                'strategy_name': 'native_filter_options',
+                'dashboard_ids': [1, 2, 3],
+            },
+        },
+    }
+```
+
+Requirements and limitations:
+
+- `SUPERSET_CACHE_WARMUP_USER` must be set to a user with access to the dashboards and datasets
+  referenced by the native filters.
+- `DATA_CACHE_CONFIG` must use a backend that actually persists entries (Redis recommended); the
+  default `NullCache` discards writes, so warming has nothing to warm. The effective timeout also
+  needs to be positive — `NATIVE_FILTER_OPTIONS_CACHE_TIMEOUT = -1` disables cache writes for these
+  queries entirely, even with a working backend.
+- Schedule the warm-up at least as often as the effective native filter cache timeout (whichever of
+  `NATIVE_FILTER_OPTIONS_CACHE_TIMEOUT`, the chart/dataset/database timeout, or `DATA_CACHE_CONFIG`'s
+  default applies). A looser schedule still leaves a window of cold, unwarmed queries between expiry
+  and the next run — the daily example above assumes a TTL of a day or more.
+- Cache entries are warmed under the warm-up user's own cache partition, the same entry that user
+  would create by opening the filter dropdown manually. Users with a different role set or row-level
+  security context may still see a cache miss on first load.
+- Cascading/dependent native filters and search-term variants of filter option queries are not
+  warmed by this strategy.
+
 ## Caching Thumbnails
 
 This is an optional feature that can be turned on by activating its [feature flag](/admin-docs/configuration/configuring-superset#feature-flags) on config: