docs - caching updates (#42857)

docs/configuring-metabase/caching.md

@@ -7,121 +7,113 @@ redirect_from:
 
 # Caching query results
 
-If your question results don't change frequently, you may want to store the results in Metabase so that the next time you visit the question, Metabase can retrieve the stored results rather than query the database again.
-
-For example, if your data only updates once a day, there's no point in querying the database more than once a day, as they data won't have changed. Returning cached results can be significantly faster, as the database won't have to recompute the results to load your question.
-
-Metabase gives you the ability to automatically cache question results that meet a [minimum query duration](#minimum-query-duration).
-
-If your questions share a common model, you can enable [model caching](../data-modeling/models.md#model-caching) instead.
+{% include plans-blockquote.html feature="Advanced caching controls" %}
 
-## Enabling global caching
+If your question results don't change frequently, you may want to store the results so that the next time anyone visits the question, Metabase can retrieve the stored results rather than query the database again.
 
-1. Go to **Admin settings** > **Caching** (in the sidebar).
-2. Click the toggle under **Saved Questions**.
+For example, if your data only updates once a day, there's no point in querying the database more than once a day, as they data won't have changed. Returning cached results can be significantly faster, as the database won't have to recompute the results to load your question.
 
-Once you've enabled caching, you can choose when and what to cache from your [caching settings](#caching-settings).
+## Cache invalidation policies
 
-By default, questions will get cached once their [average execution time](#average-query-execution-time) meets a [minimum query duration](#minimum-query-duration) of 60 seconds.
+These policies determines how long cached results will be stored.
 
-## Caching location
+- [Duration](#duration-caching-policy)
+- [Schedule](#schedule-caching-policy)
+- [Adaptive](#adaptive-caching-policy)
+- [Don't cache results](#dont-cache-results)
 
-If you're self-hosting Metabase, cached question results will be saved to your [application database](../installation-and-operation/configuring-application-database.md).
+### Duration caching policy
 
-If you're using Metabase Cloud, cached question results will be saved to Metabase's servers in the United States.
+{% include plans-blockquote.html feature="Duration caching policy" %}
 
-## Last updated at
+Keep the cache for a number of hours. When someone runs a query, Metabase will first check if it's cached the results. If not, it runs the query and caches the results for as long as you set the duration.
 
-Questions that use the cache will display a "last cached at" timestamp in the question's **info** panel.
+### Schedule caching policy
 
-## Getting fresh results
+{% include plans-blockquote.html feature="Schedule caching policy" %}
 
-To override a cached question result, re-run the question using the **refresh** button (counterclockwise arrow).
+Pick when to regularly invalidate the cache. Metabase will only store results when people run a query, and it will clear the cached results according to the cadence you set here.
 
-## Average query execution time
+You can schedule caching to invalidate:
 
-Your Metabase instance keeps track of how long it takes each question to run. The average query execution time is used in your [caching settings](#caching-settings).
+- Hourly
+- Daily
+- Weekly
+- Monthly
 
-On [paid plans](https://www.metabase.com/pricing/), you can view statistics about query execution time from your [auditing tools](../usage-and-performance-tools/audit.md).
+We do not yet support lunar cycles.
 
-## Caching settings
+### Adaptive caching policy
 
-You can tell Metabase when and what to cache from **Admin settings** > **Caching**:
+Use a query’s average execution time to determine how long to cache the query's results.
 
-- [Minimum query duration](#minimum-query-duration)
-- [Cache time-to-live (TTL) multiplier](#cache-time-to-live-ttl-multiplier)
-- [Max cache entry size](#max-cache-entry-size)
 
-### Minimum query duration
+- **Minimum query duration**: Metabase will cache this question if it has an average query execution time greater than this many seconds.
+- **Multiplier**: Metabase will cache questions with an average query execution time greater than this many seconds. For example, if a question takes on average 10s to return results. If you set a multiplier of 100, Metabase will store the cache for 1000 seconds (~16 minutes).
 
-Metabase uses this number to decide whether a question will be cached or not.
+On [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans, you can view querying and caching stats in the [Metabase analytics](../usage-and-performance-tools/usage-analytics.md).
 
-Choose a duration (in seconds) that will trigger the cache. For example, you'd enter "60" if you want to cache all questions that take longer than 1 minute to load ([on average](#average-query-execution-time)).
+### Don’t cache results
 
-### Cache time-to-live (TTL) multiplier
+Always re-run the query to refresh results.
 
-The TTL multiplier tells Metabase how long to persist a cached question result:
+## Set caching policies at different levels
 
-> Cache lifetime per question = TTL multiplier x [average execution time](#average-query-execution-time) per question
+{% include plans-blockquote.html feature="Advanced caching controls" %}
 
-For example, if you enter a TTL multiplier of 10, a question that takes 5 seconds on average will be cached for 50 seconds. A question that takes 10 minutes will be cached for 100 minutes. This way, each question's cache lifetime is proportional to that question's execution time.
+You can set up caching at different levels, from largest to smallest scope. Policies set at more restricted scopes override policies set at larger scopes. So a policy set on a question will take precedence over a dashboard, database, or default policy.
 
-### Max cache entry size
+- [Setting a default caching policy](#default-caching-policy)
+- [Database caching policy (specific to each connected database)](#database-caching-policy)*
+- [Dashboard caching](#dashboard-caching-policy)*
+- [Question caching](#question-caching-policy)*
 
-To prevent cached results from taking up too much space on your server, you can set the maximum size of the cache (per question) in kilobytes.
+_* Denotes [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) features._
 
-## Advanced caching controls
+### Default caching policy
 
-{% include plans-blockquote.html feature="Advanced caching controls" %}
+![Data caching settings in the Admin settings under the Performance tab](./images/data-caching-settings.png)
 
-All Metabase editions include global caching controls. On [paid plans](https://www.metabase.com/pricing/), you can override your global [time-to-live (TTL) setting](#cache-time-to-live-ttl-multiplier) to set different cache lifetimes for specific databases, questions, or dashboards.
+To set up a default caching policy for your Metabase: Hit Cmd/Ctrl + k to bring up the command palette and search for **Performance**. Or, click through **Gear** settings icon > **Admin settings** > **Performance** > **Data caching settings**.
 
-### Caching per database
+Click on the button next to **Default policy**, and select a [cache invalidation policy](#cache-invalidation-policies).
 
-This setting tells Metabase how long to keep the cached results from a specific database.
+### Database caching policy
 
-1. Make sure [caching is enabled](#enabling-global-caching).
-2. Go to **Admin settings** > **Databases** and select your database.
-3. Open **Advanced options** and find the **Default result cache duration**.
-4. Click **Custom** and enter a cache duration in hours.
+{% include plans-blockquote.html feature="Database caching controls" %}
 
-The cache duration setting is useful for databases that take longer to query, or databases that are kept up to date on a special cadence.
+Same as the default caching policy, though you can set a caching policy for specific databases.
 
-This setting will override your [global cache duration](#cache-time-to-live-ttl-multiplier).
+### Dashboard caching policy
 
-### Caching per question
+{% include plans-blockquote.html feature="Dashboard caching controls" %}
 
-You can tell Metabase how long to keep the cached results for specific questions. You'll only find these cache settings on questions that exceed the [minimum query duration](#minimum-query-duration).
+To set a caching policy for a dashboard, you must have [curate access](../permissions/collections.md#curate-access) to the dashboard's collection.
 
-1. Make sure [caching is enabled](#enabling-global-caching).
-2. Go to your question.
-3. Click on the **info** icon.
-4. Click **Cache configuration**.
-5. Enter a cache duration in hours.
-6. Click **Save changes**.
+1. Go to your dashboard.
+2. Click on the **info** icon.
+3. Click **Caching policy**.
+4. Select the [caching invalidation policy](#cache-invalidation-policies).
+5. Save your changes.
 
-You can use this setting to update questions on the same cadence as your data. For example, if your data gets updated daily, you can set the **Cache configuration** to 24 hours.
+### Question caching policy
 
-If set, your question cache duration will override the:
+{% include plans-blockquote.html feature="Question caching controls" %}
 
-- [global cache duration](#cache-time-to-live-ttl-multiplier)
-- [database cache duration](#caching-per-database)
+To set a caching policy for a question, you must have [curate access](../permissions/collections.md#curate-access) to the question's collection.
 
-### Caching per dashboard
+1. Go to your question.
+2. Click on the **info** icon.
+3. Click **Caching policy**.
+4. Select the [caching invalidation policy](#cache-invalidation-policies).
+5. Save your changes.
 
-You can tell Metabase how long to keep the cached results for each of the questions on a dashboard.
+## Clearing the cache
 
-1. Make sure [caching is enabled](#enabling-global-caching).
-2. Go to your dashboard.
-3. Click on the **info** icon.
-4. Click **Cache configuration**.
-5. Enter a cache duration in hours.
-6. Click **Save changes**.
+To clear the cache for a question or dashboard and refresh the results: click through the **Info > Caching policy > Clear cache** (the "Clear cache" button is at the bottom of the sidebar).
 
-> This setting won't cache the entire dashboard at once. The dashboard cache duration will only apply to questions that exceed the [minimum query duration](#minimum-query-duration).
+## Caching location
 
-If set, your dashboard cache duration will override the:
+If you're self-hosting Metabase, cached question results will be saved to your [application database](../installation-and-operation/configuring-application-database.md).
 
-- [global cache duration](#cache-time-to-live-ttl-multiplier)
-- [database cache duration](#caching-per-database)
-- [question cache duration](#caching-per-question)
+If you're using Metabase Cloud, cached question results will be saved to Metabase's servers in the United States (as our Cloud service manages your application database for you.)

docs/data-modeling/models.md

@@ -23,7 +23,7 @@ You can use models to:
 
 - Create, uh, models, with model here meaning an intuitive description of some concept in your business that you codify as a set of columns. An example model could be a "customer", which is a table that pulls together customer information from multiple tables and adds computed columns, like adding a lifetime value (LTV) column. This model represents the [measures and dimensions][measures-dimensions] that you think are relevant to your understanding of your customers.
 - Let people explore the results of SQL queries with the drill-through menu and query builder (provided you [set the column types](#column-type)).
-- Create summary tables that aggregate data from multiple tables.
+- Create summary tables that pull in or aggregate data from multiple tables.
 - Clean up tables with unnecessary columns and rows filtered out.
 
 The idea with models is to give other people a good "starting point table" that makes it easier to answer any questions they have about the subject being modeled.
@@ -171,28 +171,27 @@ See [History](../exploration-and-organization/history.md).
 
 Just like with a question, admins can verify models. Verifying a model will give it a check mark to let others know an admin vetted the model. If anyone makes any changes to the model, the check mark will disappear. An admin will have to verify the question again to restore the check mark.
 
-## Model caching
+## Model persistence
 
 _Currently available for PostgreSQL, MySQL, and Redshift_.
 
-Metabase can cache the results of your models so that the models load faster. Metabase caches models by creating tables in a bespoke schema in your data warehouse, and saves the results of the queries that underlie your models in those tables. When people ask questions based on your models, Metabase will substitute those cached results in place of running the model's query.
+Metabase can persist the results of your models so that your models (and the questions based on those models) load faster.
 
-To set up model caching:
+You can think of persisted models as materialized views. Metabase will store model results in tables in a bespoke schema in your data warehouse (not the Metabase application database). When people ask questions based on your models, Metabase will use those stored results instead of re-running the model's query.
 
-1. [Enable model caching in Metabase](#enable-model-caching-in-metabase).
-2. [Create a schema to store cached models](#create-a-schema-to-store-cached-models).
+> Model persistence doesn't work with [data sandboxing](../permissions/data-sandboxes.md).
 
-> Model caching doesn't work with [data sandboxing](../permissions/data-sandboxes.md).
+### Turn on model persistence in Metabase
 
-### Enable model caching in Metabase
+To persist models for faster loading, go to **Admin settings** > **Performance** > **Model persistence**.
 
-Go to **Admin settings** > **Settings** > **Caching** > **Models** to turn the feature on.
+You can set models to refresh based on one of the default frequencies (every 1 hour, 2 hours, etc.), or select the **Custom** option to use [cron syntax](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html) to specify your own caching update frequency.
 
-![Model caching](./images/model-caching-custom.png)
+The cron scheduler uses the [Report Timezone](../configuring-metabase/localization.md#report-timezone) if selected and otherwise uses the System Timezone (which defaults to GMT in Metabase Cloud).
 
-You can set models to refresh based on one of the default frequencies, or select the **Custom** option to use [cron syntax](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html) to specify your own caching update frequency. We recommend scheduling the cache to refresh on a frequency that makes sense with how often your source tables update with new data. The cron scheduler uses the [Report Timezone](../configuring-metabase/localization.md#report-timezone) if selected and otherwise uses the System Timezone (which defaults to GMT in Metabase Cloud).
+We recommend scheduling your models to refresh on a frequency that makes sense with how often your source tables update with new data.
 
-If someone [changes the query definition of a model](#edit-a-models-query), any question based on that model will skip the cache until the next cache refresh.
+If someone [changes the query definition of a model](#edit-a-models-query), any question based on that model will re-run the query until the next scheduled model refresh.
 
 ### Create a schema to store cached models
 

docs/paid-features/overview.md

@@ -79,8 +79,9 @@ Tools for keeping your Metabase organized, so people can find your most importan
 
 All Metabase editions include global caching controls. Paid plans includes additional caching options that let you control caching for individual questions.
 
-- [Caching controls for individual questions](../configuring-metabase/caching.md#caching-per-question)
-- [Caching control per database](../configuring-metabase/caching.md#caching-per-database)
+- [Caching questions](../configuring-metabase/caching.md#caching-per-question)
+- [Caching dashboards](../configuring-metabase/caching.md#caching-per-dashboard)
+- [Caching databases](../configuring-metabase/caching.md#caching-per-database)
 
 ## Usage analytics
 

docs/questions/native-editor/writing-sql.md

@@ -91,6 +91,10 @@ Visualizations created with SQL do not have [drill-through][drill-through] capab
 2. [Edit the column metadata](../../data-modeling/metadata-editing.md#column-field-settings) in the model's settings. Make sure to set the data types for all the columns.
 3. [Create a Query Builder question](../query-builder/introduction.md#creating-a-new-question-with-the-query-builder) based on the model. You should be able to use drill-through on this question, if you configured the metadata correctly.
 
+## Caching results
+
+See [Caching question policies](../../configuring-metabase/caching.md#question-caching-policy).
+
 ## Learn more
 
 - [Best practices for writing SQL queries](https://www.metabase.com/learn/sql-questions/sql-best-practices.html)

docs/questions/query-builder/introduction.md

@@ -235,6 +235,10 @@ You can also convert the question to a [native editor question](../native-editor
 
 Conversion is a one-way street: you can't convert a SQL question back into a query builder question.
 
+## Caching question results
+
+See [Caching question results](../../configuring-metabase/caching.md#question-caching-policy).
+
 ## Play around with saved questions
 
 Each time you start modifying a saved question, Metabase will create a new question for you. The query builder will display the name of your starting question under **Data**.

docs/troubleshooting-guide/timeout.md

@@ -16,7 +16,7 @@ If your queries are hanging or timing out, the problem could be coming from your
 
 Fixes for timeout problems will depend on your specific setup. These resources may help:
 
-- [Configuring Jetty connectors][configuring-jetty]
+- [Jetty connectors][configuring-jetty]
 - [EC2 Troubleshooting][ec2-troubleshooting]
 - [Elastic Load Balancing Connection Timeout Management][elb-timeout]
 - [App Engine: Dealing with DeadlineExceededErrors][app-engine-timeout]