[superset] branch master updated: docs(caching): Restructure and improve caching docs (#22687)

[vi...@apache.org]

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

villebro 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 8fa7a75a3b docs(caching): Restructure and improve caching docs (#22687)
8fa7a75a3b is described below

commit 8fa7a75a3b67ca59c76cd3f74d57aa9c7956a253
Author: Reid Beels <ma...@reidbeels.com>
AuthorDate: Thu Jan 12 22:48:56 2023 -0800

    docs(caching): Restructure and improve caching docs (#22687)
---
 docs/docs/installation/cache.mdx | 70 +++++++++++++++++++++++++++++-----------
 1 file changed, 52 insertions(+), 18 deletions(-)

diff --git a/docs/docs/installation/cache.mdx b/docs/docs/installation/cache.mdx
index 4838fc47e6..58b4bcb2b0 100644
--- a/docs/docs/installation/cache.mdx
+++ b/docs/docs/installation/cache.mdx
@@ -7,19 +7,49 @@ version: 1
 
 ## Caching
 
-Superset uses [Flask-Caching](https://flask-caching.readthedocs.io/) for caching purposes. Configuring caching is as easy as providing a custom cache config in your
-`superset_config.py` that complies with [the Flask-Caching specifications](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching).
-Flask-Caching supports various caching backends, including Redis, Memcached, SimpleCache (in-memory), or the
-local filesystem. Custom cache backends are also supported. See [here](https://flask-caching.readthedocs.io/en/latest/#custom-cache-backends) for specifics.
-The following cache configurations can be customized:
-- Metadata cache (optional): `CACHE_CONFIG`
-- Charting data queried from datasets (optional): `DATA_CACHE_CONFIG`
-- SQL Lab query results (optional): `RESULTS_BACKEND`. See [Async Queries via Celery](/docs/installation/async-queries-celery) for details
+Superset uses [Flask-Caching](https://flask-caching.readthedocs.io/) for caching purposes.
+Flask-Caching supports various caching backends, including Redis (recommended), Memcached,
+SimpleCache (in-memory), or the local filesystem.
+[Custom cache backends](https://flask-caching.readthedocs.io/en/latest/#custom-cache-backends)
+are also supported.
+
+Caching can be configured by providing a dictionaries in
+`superset_config.py` that comply with[the Flask-Caching config specifications](https://flask-caching.readthedocs.io/en/latest/#configuring-flask-caching).
+
+The following cache configurations can be customized in this way:
 - Dashboard filter state (required): `FILTER_STATE_CACHE_CONFIG`.
 - Explore chart form data (required): `EXPLORE_FORM_DATA_CACHE_CONFIG`
+- Metadata cache (optional): `CACHE_CONFIG`
+- Charting data queried from datasets (optional): `DATA_CACHE_CONFIG`
+
+For example, to configure the filter state cache using redis:
+
+```python
+FILTER_STATE_CACHE_CONFIG = {
+    'CACHE_TYPE': 'RedisCache',
+    'CACHE_DEFAULT_TIMEOUT': 86400,
+    'CACHE_KEY_PREFIX': 'superset_filter_cache',
+    'CACHE_REDIS_URL': 'redis://localhost:6379/0'
+}
+```
+
+### Dependencies
+
+In order to use dedicated cache stores, additional python libraries must be installed
+
+- For Redis: we recommend the [redis](https://pypi.python.org/pypi/redis) Python package
+- Memcached: we recommend using [pylibmc](https://pypi.org/project/pylibmc/) client library as
+  `python-memcached` does not handle storing binary data correctly.
+
+These libraries can be installed using pip.
+
+### Fallback Metastore Cache
+
+Note, that some form of Filter State and Explore caching are required. If either of these caches
+are undefined, Superset falls back to using a built-in cache that stores data in the metadata
+database. While it is recommended to use a dedicated cache, the built-in cache can also be used
+to cache other data.
 
-Please note, that Dashboard and Explore caching is required. If these caches are undefined, Superset falls back to using a built-in cache that stores data
-in the metadata database. While it is recommended to use a dedicated cache, the built-in cache can also be used to cache other data.
 For example, to use the built-in cache to store chart data, use the following config:
 
 ```python
@@ -30,17 +60,21 @@ DATA_CACHE_CONFIG = {
 }
 ```
 
-- Redis (recommended): we recommend the [redis](https://pypi.python.org/pypi/redis) Python package
-- Memcached: we recommend using [pylibmc](https://pypi.org/project/pylibmc/) client library as
-  `python-memcached` does not handle storing binary data correctly.
+### Chart Cache Timeout
+
+The cache timeout for charts may be overridden by the settings for an individual chart, dataset, or
+database. Each of these configurations will be checked in order before falling back to the default
+value defined in `DATA_CACHE_CONFIG.
+
+### SQL Lab Query Results
 
-Both of these libraries can be installed using pip.
+Caching for SQL Lab query results is used when async queries are enabled and is configured using
+`RESULTS_BACKEND`.
 
-For chart data, Superset goes up a “timeout search path”, from a slice's (chart's) configuration
-to the dataset’s, the database’s, then ultimately falls back to the global default
-defined in `DATA_CACHE_CONFIG`.
+Note that this configuration does not use a flask-caching dictionary for its configuration, but
+instead requires a cachelib object.
 
-## Celery beat
+See [Async Queries via Celery](/docs/installation/async-queries-celery) for details.
 
 ### Caching Thumbnails