docs - models and caching (#43681)

docs/configuring-metabase/caching.md

@@ -117,3 +117,7 @@ To clear the cache for a question or dashboard and refresh the results: click th
 If you're self-hosting Metabase, cached question results will be saved to your [application database](../installation-and-operation/configuring-application-database.md).
 
 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.)
+
+## Further reading
+
+- [Model persistence](../data-modeling/model-persistence.md)
\ No newline at end of file

docs/data-modeling/model-persistence.md

+---
+title: Model persistence
+---
+
+# Model persistence
+
+> Currently available for PostgreSQL, MySQL, and Redshift.
+
+Metabase can persist the results of your models so that your models (and the questions based on those models) load faster.
+
+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.
+
+> Model persistence doesn't work with [data sandboxing](../permissions/data-sandboxes.md).
+
+## Turn on model persistence in Metabase
+
+To persist models for faster loading, you'll need to turn on model persistence for:
+
+1. [Your Metabase](#turn-on-model-persistence-for-your-metabase)
+2. [Individual databases](#turn-on-model-persistence-for-each-database)
+3. [(Optional) individual models](#turn-on-model-persistence-for-individual-models)
+
+### Turn on model persistence for your Metabase
+
+To turn on model persistence for your Metabase, go to **Admin settings** > **Performance** > **Model persistence**.
+
+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 update frequency.
+
+The cron scheduler uses the [Report Timezone](../configuring-metabase/localization.md#report-timezone) if selected. Otherwise the scheduler will use the System Timezone (which defaults to GMT in [Metabase Cloud](https://www.metabase.com/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](./models.md#edit-a-models-query), any question based on that model will re-run the model's query until the next scheduled model refresh.
+
+## Turn on model persistence for each database
+
+Once you've turned on model persistence for your Metabase, you'll need to set it up for each specific database, as Metabase will need to create a schema in your data warehouse to store the persisted models.
+
+1. Go to **Admin settings** > **Databases** > [your database] > **Turn model persistence on**. If the credentials you've given Metabase to connect to your database are permissive, Metabase should do all the work for you: Metabase will check if the schema already exists, or otherwise attempt to create it. If the connection's credentials _lack_ the necessary permissions to create the schema in your database, you'll need to create the schema in the database yourself.
+
+2. To manually create the schema in your data warehouse, click on the **info icon** to get the schema name.
+
+3. Create the schema in your database---make sure you use the exact schema name from step 1. For example, if you're running PostgreSQL as your data warehouse, you'd create the schema by running `CREATE SCHEMA IF NOT EXISTS schema_name`, with `schema_name` being whatever Metabase showed you in the info icon.
+
+4. Ensure that the credentials Metabase uses to connect to your data warehouse can manage and write to that schema.
+
+## Turn on model persistence for individual models
+
+{% include plans-blockquote.html feature="Individual model persistence" %}
+
+You can also toggle persistence on or off for individual models. When viewing a model, click on the **...** in the upper right and select **Turn model persistence on/off** (you'll need [Curate access](../permissions/collections.md#curate-access) to the model's collection to do this).
+
+Toggling persistence for individual models is useful for models with data that updates at different frequencies than the schedule you set for other models in that database, or for models that are used more or less than other models in that database.
+
+## Refreshing a model's persisted results
+
+To refresh a model's results, go to the model and click on the **i** info icon. In the info sidebar that opens, you'll see a note about when Metabase last refreshed the model's results, and an icon to refresh the results.
+
+## View model persistence logs
+
+You can view the logs for model caching by clicking on the **gear** icon in the upper right and selecting **Admin settings** > **Tools** > **Model caching logs**. See [Admin tools](../usage-and-performance-tools/tools.md).
+
+## Difference between persisted models and caching
+
+Persisted models differ from [cached results](../configuring-metabase/caching.md):
+
+- **Models are persisted in your data warehouse, cached results are stored in the application database**. Metabase stores cached results in its application database. Metabase persists models in your connected data warehouse as materialized views.
+- **Metabase refreshes model results and invalidates cached results**. Metabase will refresh results of models according to the schedule you set. That is, Metabase will re-run the model's query and store the results in your data warehouse. For cached results of saved questions and dashboards, Metabase won't run the queries automatically; it will cached results when people view the question or dashboard, and invalidate the cached results according to the caching policy you set.
+
+## Further reading
+
+- [Models](./models.md)
+- [Caching policies](../configuring-metabase/caching.md)

docs/data-modeling/models.md

@@ -14,6 +14,7 @@ Models:
 - Show up higher in search results and get highlighted when other users start new questions to promote reuse.
 - Live in collections to keep them separate from messy database schemas.
 - Can [surface individual records in search results](#surface-individual-records-in-search-by-matching-against-this-column).
+- Can be [persisted for faster loading](./model-persistence.md).
 
 For a deep dive on why and how to use models, check out our [Learn article on models][learn-models].
 
@@ -173,56 +174,7 @@ Just like with a question, admins can verify models. Verifying a model will give
 
 ## Model persistence
 
-_Currently available for PostgreSQL, MySQL, and Redshift_.
-
-Metabase can persist the results of your models so that your models (and the questions based on those models) load faster.
-
-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.
-
-> Model persistence doesn't work with [data sandboxing](../permissions/data-sandboxes.md).
-
-### Turn on model persistence in Metabase
-
-To persist models for faster loading, go to **Admin settings** > **Performance** > **Model persistence**.
-
-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.
-
-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 re-run the query until the next scheduled model refresh.
-
-### Create a schema to store cached models
-
-Go to **Admin settings** > **Databases** > your database > **Turn model caching on**.
-
-![Cache models UI](./images/cache-model-schema.png)
-
-If the credentials you've given Metabase to connect to your database are permissive, Metabase should do all the work for you: Metabase will check if the schema exists, or otherwise attempt to create it.
-
-If the connection's credentials lack the necessary permissions to create the schema in your database, you'll need to create the schema in the database yourself:
-
-1. Click on the **info icon** to get the schema name.
-
-   > In the above image, the schema name is "metabase_cache_134ba_7", but your schema name will differ.
-
-2. Create the schema in your database---make sure you use the exact schema name from step 1.
-3. Ensure that the credentials Metabase uses can manage and write to that schema.
-
-### Refreshing a model's cached results
-
-To refresh a model's cached results, go to the model and click on the **i** info icon. In the info sidebar that opens, you'll see a note about when Metabase last refreshed the model's cache, and an icon to refresh the cache.
-
-### View model caching logs
-
-You can view the logs for model caching by clicking on the **gear** icon in the upper right and selecting **Admin settings** > **Tools** > **Model caching logs**. See [Admin tools](../usage-and-performance-tools/tools.md).
-
-### Caching individual models
-
-{% include plans-blockquote.html feature="Caching individual models" %}
-
-On some paid plans, you can also toggle caching on or off for individual models. When viewing a model, click on the **...** in the upper right and select **Turn model caching on/off**.
+See [Model persistence](./model-persistence.md)
 
 ## Further reading
 

docs/paid-features/overview.md

@@ -83,6 +83,10 @@ All Metabase editions include global caching controls. Paid plans includes addit
 - [Caching dashboards](../configuring-metabase/caching.md#caching-per-dashboard)
 - [Caching databases](../configuring-metabase/caching.md#caching-per-database)
 
+## Model persistence for individual models
+
+- [Toggle persistence for individual models](../data-modeling/model-persistence.md#turn-on-model-persistence-for-individual-models)
+
 ## Usage analytics
 
 See how people are using your Metabase.

e2e/test/scenarios/admin/databases/reproductions/26470-model-cache-enable-button.cy.spec.js

@@ -11,9 +11,9 @@ describe("issue 26470", { tags: "@external" }, () => {
   it("Model Cache enable / disable button should update button text", () => {
     cy.clock(Date.now());
     cy.visit(`/admin/databases/${WRITABLE_DB_ID}`);
-    cy.button("Turn model caching on").click();
+    cy.button("Turn model persistence on").click();
     cy.button(/Done/).should("exist");
     cy.tick(6000);
-    cy.button("Turn model caching off").should("exist");
+    cy.button("Turn model persistence off").should("exist");
   });
 });

enterprise/frontend/src/metabase-enterprise/caching/components/ModelPersistenceConfiguration.tsx

@@ -144,7 +144,9 @@ export const ModelPersistenceConfiguration = () => {
               {" "}
               <ExternalLink
                 key="model-caching-link"
-                href={MetabaseSettings.docsUrl("data-modeling/models")}
+                href={MetabaseSettings.docsUrl(
+                  "data-modeling/model-persistence",
+                )}
               >{t`Learn more`}</ExternalLink>
             </>
           )}

enterprise/frontend/src/metabase-enterprise/model_persistence/index.ts

@@ -20,7 +20,9 @@ if (hasPremiumFeature("cache_granular_controls")) {
     const isPersisted = model.isPersisted();
 
     return {
-      title: isPersisted ? t`Turn model caching off` : t`Turn model caching on`,
+      title: isPersisted
+        ? t`Turn model persistence off`
+        : t`Turn model persistence on`,
       action: () => toggleModelPersistence(model, onChange),
       icon: "database",
     };

frontend/src/metabase/admin/databases/components/DatabaseEditApp/Sidebar/ModelCachingControl/ModelCachingControl.tsx

@@ -38,13 +38,13 @@ function FeatureDescription({ schemaName }: { schemaName: string }) {
   const docsLink = (
     <ExternalLink
       key="model-caching-link"
-      href={MetabaseSettings.docsUrl("data-modeling/models")}
+      href={MetabaseSettings.docsUrl("data-modeling/model-persistence")}
     >{t`Learn more.`}</ExternalLink>
   );
   return (
     <PopoverContent>
-      <FeatureTitle>{t`Cache models`}</FeatureTitle>
-      <FeatureDescriptionText>{jt`We'll create tables with model data and refresh them on a schedule you define. To enable it, you need to grant this connection credential read and write permissions on the "${schemaName}" schema or grant create schema permissions. ${docsLink}`}</FeatureDescriptionText>
+      <FeatureTitle>{t`Persist models`}</FeatureTitle>
+      <FeatureDescriptionText>{jt`We'll create tables with model data and refresh them on a schedule you define. To enable model persistence, you need to grant this connection's credentials read and write permissions on the "${schemaName}" schema or grant create schema permissions. ${docsLink}`}</FeatureDescriptionText>
     </PopoverContent>
   );
 }
@@ -61,8 +61,8 @@ function ModelCachingControl({ database }: Props) {
   const isEnabled = database.isPersisted();
 
   const normalText = isEnabled
-    ? t`Turn model caching off`
-    : t`Turn model caching on`;
+    ? t`Turn model persistence off`
+    : t`Turn model persistence on`;
 
   const siteUUID = MetabaseSettings.get("site-uuid") || "";
   const cacheSchemaName = getModelCacheSchemaName(databaseId, siteUUID);

frontend/src/metabase/admin/databases/components/DatabaseEditApp/Sidebar/Sidebar.unit.spec.tsx

@@ -245,10 +245,10 @@ describe("DatabaseEditApp/Sidebar", () => {
       setup({ isModelPersistenceEnabled: false });
 
       expect(
-        screen.queryByText(/Turn model caching on/i),
+        screen.queryByText(/Turn model persistence on/i),
       ).not.toBeInTheDocument();
       expect(
-        screen.queryByText(/Turn model caching off/i),
+        screen.queryByText(/Turn model persistence off/i),
       ).not.toBeInTheDocument();
     });
 
@@ -261,18 +261,20 @@ describe("DatabaseEditApp/Sidebar", () => {
       });
 
       expect(
-        screen.queryByText(/Turn model caching on/i),
+        screen.queryByText(/Turn model persistence on/i),
       ).not.toBeInTheDocument();
       expect(
-        screen.queryByText(/Turn model caching off/i),
+        screen.queryByText(/Turn model persistence off/i),
       ).not.toBeInTheDocument();
     });
 
     it("offers to enable caching when it's enabled on the instance and supported by a database", () => {
       setup({ isModelPersistenceEnabled: true });
-      expect(screen.getByText(/Turn model caching on/i)).toBeInTheDocument();
       expect(
-        screen.queryByText(/Turn model caching off/i),
+        screen.getByText(/Turn model persistence on/i),
+      ).toBeInTheDocument();
+      expect(
+        screen.queryByText(/Turn model persistence off/i),
       ).not.toBeInTheDocument();
     });
 
@@ -283,9 +285,11 @@ describe("DatabaseEditApp/Sidebar", () => {
           features: [...COMMON_DATABASE_FEATURES, "persist-models-enabled"],
         }),
       });
-      expect(screen.getByText(/Turn model caching off/i)).toBeInTheDocument();
       expect(
-        screen.queryByText(/Turn model caching on/i),
+        screen.getByText(/Turn model persistence off/i),
+      ).toBeInTheDocument();
+      expect(
+        screen.queryByText(/Turn model persistence on/i),
       ).not.toBeInTheDocument();
     });
   });