[nightly] release-x.63.x -> release-x.63.x

_docs/v0.63/embedding/guest-embedding.md

@@ -204,6 +204,8 @@ See [Modular embedding parameters](./parameters#pass-parameter-values-to-embedde
 
 Locked parameters let you filter data without exposing the filter to the end-user. Locking parameters is useful for restricting data based on who's viewing the embed (for example, showing each customer only their own data).
 
+![Locked parameters](./images/locked-parameters.png)
+
 To use locked parameters, you need to:
 
 1. Set the parameter to **Locked** in the embed settings.

_docs/v0.63/embedding/tenants.md

@@ -315,6 +315,8 @@ For an overview of how data permissions work in Metabase, see [Data permissions]
 
   If every tenant has their data in a separate database, then instead of using permissions for data access control, you can use [**database routing**](../permissions/database-routing) to route queries to appropriate databases directly.
 
+  For a comparison of data isolation methods, see [Choosing a data isolation method](../permissions/data-isolation-methods).
+
 - **Create queries** controls whether tenant users can create queries on the data they see. If you want to give your tenant users the ability to drill through (e.g., through `drills` parameter in [modular embedding](../embedding/modular-embedding)), you need to give them "Create queries" permissions, because a drill through is a new query.
 
 - **Download results** controls, unsurprisingly, whether people can download results of queries. You need to set download permissions if you want to give your users the option to download their data as a spreadsheet (for example, through `with-downloads` parameter in [modular embedding](../embedding/modular-embedding)).
@@ -444,3 +446,4 @@ If you disable multi-tenant strategy, _all your tenant users will be deactivated
 - [Embedding overview](./start)
 - [JWT authentication](../people-and-groups/authenticating-with-jwt)
 - [Permissions overview](../permissions/start)
+- [Data isolation methods](../permissions/data-isolation-methods)

_docs/v0.63/permissions/data-isolation-methods.md

@@ -0,0 +1,97 @@
+---
+version: v0.63
+has_magic_breadcrumbs: true
+show_category_breadcrumb: true
+show_title_breadcrumb: true
+category: Permissions
+title: 'Data isolation methods'
+source_url: 'https://github.com/metabase/metabase/blob/master/docs/permissions/data-isolation-methods.md'
+layout: new-docs
+summary: 'Compare the ways Metabase can restrict data access for internal analytics or multi-tenant setups, including row and column security, impersonation, database routing, and locked parameters.'
+---
+
+# Data isolation methods
+
+> Row and column security, impersonation, and database routing are only available on Metabase [Pro](/product/pro) and [Enterprise](/product/enterprise) plans.
+
+Metabase offers several ways to ensure people only see the data they're supposed to see, whether you're restricting data by team for internal analytics or isolating customer data in a multi-tenant setup. The best method depends on how you store your data and where you want to enforce access rules:
+
+- If all data lives in the same tables, use [row and column security](#row-and-column-security) to filter data in Metabase, or [impersonation](#impersonation) to enforce access rules at the database level.
+- If each customer or team has their own database, use [database routing](#database-routing).
+- If you're embedding dashboards for people without Metabase accounts, use [locked parameters](#locked-parameters).
+
+You can combine these methods. For example, you can use locked parameters for a guest embed while using row and column security for signed-in users.
+
+## Row and column security
+
+[Row and column security](./row-and-column-security) lets you control which rows and columns each group can see. You can define rules that filter data based on [user attributes](../people-and-groups/managing#adding-a-user-attribute). Metabase applies your rules to questions you build in the query builder.
+
+![Row and column security](./images/row-and-column-level-security.png)
+
+Use row and column security when:
+
+- You need granular control over which rows and columns each group or customer can see.
+- You want to manage access rules in the Metabase UI instead of in your database.
+
+Don't use row and column security when:
+
+- People need to write native SQL queries. Row and column security doesn't apply to the SQL editor.
+- You need column-level security on MongoDB or Druid, which only support row-level security.
+
+## Impersonation
+
+[Impersonation](./impersonation) lets your database control what each person can see. You define roles and row-level security policies in your database. Metabase connects using the role specified by each person's [user attribute](../people-and-groups/managing#adding-a-user-attribute), and your database enforces what that role can see.
+
+![Impersonation](./images/connection-impersonation.png)
+
+Use impersonation when:
+
+- You want to centralize access logic in your database instead of in Metabase.
+- People need to write native SQL queries. Since your database enforces the rules, the rules apply in the SQL editor too.
+
+Don't use impersonation when:
+
+- Your database [doesn't support it](./impersonation#databases-that-support-impersonation).
+- You don't want to set up and maintain roles and policies in your database.
+- You rely heavily on caching. You can't share cached results between roles.
+
+## Database routing
+
+[Database routing](./database-routing) sends each person's queries to their own database. You build questions and dashboards once against a primary database, and Metabase routes queries to the right destination database based on each person's [user attribute](../people-and-groups/managing#adding-a-user-attribute). Database routing requires that each group's data lives in a separate database, and that all destination databases have identical schemas.
+
+![Database routing](./images/database-routing-diagram.png)
+
+Use database routing when:
+
+- You want the strongest isolation. Each group's data lives in a separate database.
+- You want to avoid one group's queries affecting the performance of another group's queries.
+
+Don't use database routing when:
+
+- Groups share tables. Use [row and column security](#row-and-column-security) or [impersonation](#impersonation) instead.
+- You want to manage access rules in the Metabase UI instead of maintaining a separate database for each group.
+
+## Locked parameters
+
+[Locked parameters](../embedding/guest-embedding#locked-parameters) filter an embedded dashboard or question before Metabase displays it. Your app passes the filter value in a signed JWT. The filter is invisible to the person viewing the embed, and they can't change it.
+
+![Locked parameters](../embedding/images/locked-parameters.png)
+
+Use locked parameters when:
+
+- You want to restrict data without setting up Metabase accounts, user attributes, or permissions.
+- You want to filter data without exposing the filter or its values to the people viewing the embed.
+
+Don't use locked parameters when:
+
+- You want account-level or role-based access control across your Metabase.
+- You're working with sensitive data. Use a method that enforces access at the permissions or database level instead, like [row and column security](#row-and-column-security), [impersonation](#impersonation), or [database routing](#database-routing).
+
+## Further reading
+
+- [Permissions overview](./start)
+- [Tenants](../embedding/tenants)
+- [Row and column security](./row-and-column-security)
+- [Impersonation](./impersonation)
+- [Database routing](./database-routing)
+- [Locked parameters for guest embeds](../embedding/guest-embedding#locked-parameters)

_docs/v0.63/permissions/database-routing.md

@@ -16,6 +16,8 @@ summary: 'Route queries to different databases based on who''s viewing them. Gre
 
 With database routing, an admin can build a question once using one database, and the question will run its query against a different database with the same schema depending on who is viewing the question.
 
+![Database routing diagram](./images/database-routing-diagram.png)
+
 Database routing is useful for:
 
 - Managing modular and full app embedding setups where each customer has their own database with identical schemas.

_docs/v0.63/permissions/impersonation.md

@@ -17,6 +17,8 @@ This page covers the [View data](./data#view-data-permissions) permission level
 
 **Impersonation access** allows admins to "outsource" View data permissions to roles in your database. Admins can associate user attributes with database-defined roles and their privileges. If someone is in a group with their View data permission set to Impersonation, the person will be able to view and query data based on the privileges granted to the role specified by their user attribute.
 
+![Connection impersonation](./images/connection-impersonation.png)
+
 ## Databases that support impersonation
 
 For now, impersonation access is only available for the following databases:

_docs/v0.63/permissions/row-and-column-security.md

@@ -21,6 +21,8 @@ Row and column security lets you give granular permissions for different groups
 
 You can use row and column security to set up [self-service analytics](/learn/metabase-basics/embedding/multi-tenant-self-service-analytics), so that each of your customers can only view the rows that match their customer ID. For example, if you have an Accounts table with information about your customers, you can add permissions to the table so that each customer only sees the data relevant to them.
 
+![Row and column security](./images/row-and-column-level-security.png)
+
 > Row and column security was formerly called data sandboxing. It's the same feature, it just now has a more descriptive name.
 
 ## Row and column security examples

_docs/v0.63/permissions/start.md

@@ -35,6 +35,10 @@ Granting group access to different Metabase features.
 
 Setting up row and column security to restrict access to rows and columns in tables.
 
+## [Choosing a data isolation method](./data-isolation-methods)
+
+Compare row and column security, impersonation, database routing, and locked parameters for multi-tenant setups.
+
 ## [Snippet folder permissions](./snippets)
 
 Organize snippets into folders that require permissions to view.