Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs: a lot of updates (#70176)

Alex Yaroshd4a888c2ecb1
diff --git a/docs/configuring-metabase/appearance.md b/docs/configuring-metabase/appearance.md
index e8328e4dcd4..3dd42112333 100644
--- a/docs/configuring-metabase/appearance.md
+++ b/docs/configuring-metabase/appearance.md
@@ -7,12 +7,15 @@ redirect_from:
- /docs/latest/embedding/whitelabeling
- /docs/latest/embedding/fonts
- /docs/latest/embedding/customize-embeds
+summary: Configure colors, fonts, and illustrations in your Metabase.
---
# Appearance
{% include plans-blockquote.html feature="Custom appearance" %}
+_Admin > Settings > Appearance_
+
Appearance settings give admins the option to whitelabel Metabase to match your company’s branding.
If you're looking for date, time, number, or currency formatting, see [Formatting defaults](../data-modeling/formatting.md).
@@ -23,37 +26,10 @@ Hit cmd/ctrl + k to bring up the command palette and search for "Branding" and c
You can also click the **grid** icon at the bottom of the navigation sidebar and click through **Admin** > **Settings** > **Appearance**.
-Appearance settings are split across different tabs:
-
-- [Branding](#branding)
-- [Conceal Metabase](#conceal-metabase)
-
-## Dark mode
-
-People can display their Metabase in dark mode in their [account settings](../people-and-groups/account-settings.md#theme). Options are:
-
-- System default (which is also the default setting). Metabase will switch between light and dark mode when the system switches without having to reload the page.
-- Always use dark mode.
-- Always use light mode.
-
-You can quickly toggle dark mode from anywhere in Metabase by opening the [command palette](../exploration-and-organization/exploration.md#command-palette) and searching for "light" or "dark" or "theme".
-
-Dark mode is a user-level setting, not an instance-level setting. Currently, there's no way to change the theme to dark mode for the entire instance, but you can edit some [user interface colors](#user-interface-colors).
-
-## Branding
-
-In the Branding tab, you can configure your Metabase to match your brand visuals and voice.
-
-- [Color palette](#color-palette)
-- [User interface colors](#user-interface-colors)
-- [Chart colors](#chart-colors)
-- [Logo](#logo)
-- [Font](#font)
-- [Loading message](#loading-message)
-- [Favicon](#favicon)
-
## Color palette
+_Admin > Settings > Appearance > Branding_
+
You can customize colors in both the application UI and in the Metabase charts.
### User interface colors
@@ -66,62 +42,93 @@ You can customize the colors that Metabase uses throughout the app:
- **Second color:** The color of aggregations and breakouts in the graphical query builder.
- **Third color:** Color of filters in the query builder, buttons and links in filter widgets.
+![QB with custom colors](./images/qb-colors.png)
+
+When choosing interface color, keep in mind that some users of your Metabase can choose to display the interface in [dark mode](../people-and-groups/account-settings.md#theme). Pick colors that work well both in light and dark mode.
+
### Chart colors
![Chart colors](./images/chart-colors.png)
You can choose up to 24 hex values. If you choose fewer than 24 colors, Metabase will auto-generate colors to fill in the rest of the values. The order of colors doesn't apply to the order of colors for series on charts. When building a chart, Metabase will select colors to make each series easy to distinguish.
-Custom colors are unavailable for:
+You can preview what the chart colors will look like by switching to the **Preview** tab.
+
+![Preview chart](./images/preview.png)
+
+Custom colors are **unavailable** for:
-- [Number charts](../questions/visualizations/numbers.md)
- [Trend charts](../questions/visualizations/trend.md)
- [Funnel charts](../questions/visualizations/funnel.md)
-- Conditional formatting ([tables](../questions/visualizations/table.md) and [pivot tables](../questions/visualizations/pivot-table.md))
+- [Pin and grid maps](../questions/visualizations/map.md)
+
+Only a **limited subset** of custom colors will be used for:
+
+- Conditional formatting in [tables](../questions/visualizations/table.md) and [pivot tables](../questions/visualizations/pivot-table.md)
- [Maps](../questions/visualizations/map.md)
+- [Sunburst chart](../questions/visualizations/pie-or-donut-chart.md)
+
+In most cases, replacing default colors with custom chart colors will not be applied to
+
+## Icons
+
+_Admin > Settings > Appearance > Branding_
-## Logo
+### Logo
You can replace Metabase's familiar, tasteful, inspired-yet-not-threateningly-avant-garde dotted M logo with your very own logo. For things to work best, the logo you upload should be an SVG file that looks good when it's around 60px tall. (In other words, ask the nearest designer for help.)
+### Favicon
+
+The URL or image that you want to use as the favicon (the logo visible in browser tabs, address bars, bookmark lists, and other places).
+
+If you use a relative path, that path isn't relative to the Metabase JAR, but to the webserver. So unless you're using a reverse-proxy, the path will be relative to the frontend resources available to the JAR.
+
+## Dark mode
+
+People can display their Metabase in dark mode in their [account settings](../people-and-groups/account-settings.md#theme). Options are:
+
+- System default (which is also the default setting). Metabase will switch between light and dark mode when the system switches without having to reload the page.
+- Always use dark mode.
+- Always use light mode.
+
+You can quickly toggle dark mode from anywhere in Metabase by opening the [command palette](../exploration-and-organization/exploration.md#command-palette) and searching for "light" or "dark" or "theme".
+
+Dark mode is a user-level setting, not an instance-level setting. Currently, there's no way to change the theme to dark mode for the entire instance, but you can edit some [user interface colors](#user-interface-colors).
+
## Font
+_Admin > Settings > Appearance > Branding_
+
This is the primary font used in charts and throughout the Metabase application (your "instance font"). See [Fonts](./fonts.md).
## Loading message
+_Admin > Settings > Appearance > Branding_
+
This message is the text Metabase presents when it's loading a query. Options include:
- "Doing science..." (the default)
- "Running query..."
- "Loading results..."
-## Favicon
+## Names
-The URL or image that you want to use as the favicon (the logo visible in browser tabs, address bars, bookmark lists, and other places).
+_Admin > Settings > Appearance > Conceal Metabase_
-If you use a relative path, that path isn't relative to the Metabase JAR, but to the webserver. So unless you're using a reverse-proxy, the path will be relative to the frontend resources available to the JAR.
-
-## Conceal Metabase
-
-Hide or customize pieces of the Metabase product to tailor the experience to your brand and needs.
-
-- [Application name](#application-name)
-- [Documentation and references](#documentation-and-references)
-- [Help link in the settings menu](#help-link-in-the-settings-menu)
-- [Metabase illustrations](#metabase-illustrations)
-
-## Application name
+### Application name
You can change every place in the app that says “Metabase” to something like “Acme Analytics,” or whatever you want to call your Metabase app.
-## Documentation and references
+Setting a custom application name will also hide the "How to use Metabase" section in the navigation.
+
+### Documentation and references
-Control the visibility of links to official Metabase documentation and other references to Metabase in your instance.
+Control the visibility of links to official Metabase documentation and other references to Metabase in your instance outside of Admin settings.
-This setting affects all links in the product experience that point to Metabase.com URLs (with the exception of links and references in the Admin settings).
+Keep in mind that if you hide documentation links, people using your Metabase might not be able to troubleshoot their problems or learn how to use Metabase features like [custom expressions](../questions/query-builder/expressions.md).
-## Help link in the settings menu
+### Help link in the settings menu
The Settings menu (the "grid" menu in the upper right of your Metabase) includes a **Help** option that links to a [Metabase help page](https://www.metabase.com/help/) by default. You can change this menu Help item by selecting one of the following options:
@@ -131,6 +138,8 @@ The Settings menu (the "grid" menu in the upper right of your Metabase) includes
## Metabase illustrations
+_Admin > Settings > Appearance > Conceal Metabase_
+
![Lighthouse illustration](./images/lighthouse-illustration.png)
Customize each of the illustrations in Metabase.
diff --git a/docs/configuring-metabase/custom-maps.md b/docs/configuring-metabase/custom-maps.md
index 2ec94c32718..a1c847179f8 100644
--- a/docs/configuring-metabase/custom-maps.md
+++ b/docs/configuring-metabase/custom-maps.md
@@ -2,13 +2,14 @@
title: Custom maps
redirect_from:
- /docs/latest/administration-guide/20-custom-maps
+summary: Add custom region maps and customize the map tile server.
---
# Custom maps
-By default, Metabase uses OpenStreetMaps for map visualizations, but there are a few customization options.
+_Admin > Settings > Maps_
-## Map settings
+By default, Metabase uses OpenStreetMaps tiles for pin and grid map visualizations, and comes with two built-in region maps - world countries and US states. You can change the tiles used for pin and grid maps, and upload additional region maps.
To find the map settings:
@@ -22,7 +23,12 @@ To find the map settings:
By default, Metabase uses the [OpenStreetMaps](https://www.openstreetmap.org) tile server for pin and grid maps. If your organization requires a different
look or level of detail in your map visualizations, you can change the map tile server by adding the map tile server path to the first field on the page.
-The path must either be a URL that starts with `http://` or `https://` or a relative path to a local file in the JVM's classpath.
+To change the map tile server:
+
+1. Go to **Admin > Settings > Maps**.
+2. Under **Map tile server URL**, add the path to the new map tile server.
+
+ The path must either be a URL that starts with `http://` or `https://` or a relative path to a local file in the JVM's classpath.
Currently, Metabase uses a single tile server per instance. You can't specify different tiles for different maps.
@@ -32,6 +38,8 @@ Metabase comes with two built-in [region maps](../questions/visualizations/map.m
If you need a map of other regions - like EU countries or NYC neighborhoods - you can specify a GeoJSON file containing region information. You can often find GeoJSON maps by searching online for "[Your region] + geojson", like "NYC neighborhoods GeoJSON." Many community members and government organizations have already developed map files for common regions. You can also create your own GeoJSON with a tool like [MapShaper](https://mapshaper.org/) or [GeoJSON.io](https://geojson.io/).
+### Custom geoJSON requirements
+
Your GeoJSON file should:
- Be less than 5 MB in size.
@@ -39,6 +47,8 @@ Your GeoJSON file should:
- Use geographic coordinates (latitude and longitude) to define region polygons. Metabase doesn't support projected coordinates, so you'll need to convert projected coordinates to geographic coordinates.
- Accessible by a public URL. Currently, you can't upload a GeoJSON to Metabase.
+### Add a custom map
+
To add a custom map:
1. Click the **grid icon**, then go to **Admin** > **Settings** > **Maps** > **Custom Maps**.
@@ -47,11 +57,11 @@ To add a custom map:
4. Provide the URL to your GeoJSON file.
5. Specify the JSON properties that should serve as region identifier and region name.
-![Uploading a custom GeoJSON](./images/custom-geojson.png)
+ ![Uploading a custom GeoJSON](./images/custom-geojson.png)
-- **Name of the map** will be displayed in the region selector for [custom region maps](../questions/visualizations/map.md#custom-regions)
-- **Region's identifier** is a GeoJSON field that identifies your region. The values in this field should match how the regions are referenced in your data. The field does not need to match the display name .
-- **Region's display name** is a GeoJSON field that specifies how your region name will be displayed on a map. This field can be different from region's identifier.
+ - **Name of the map** will be displayed in the region selector for [custom region maps](../questions/visualizations/map.md#custom-regions).
+ - **Region's identifier** is a GeoJSON field that identifies your region. The values in this field should match how the data refers to the regions. The field doesn't need to match the display name .
+ - **Region's display name** is a GeoJSON field that specifies how maps will display region names. This field can be different from region's identifier.
To pre-load one or more region maps when Metabase starts, you can use the environment variable [`MB_CUSTOM_GEOJSON`](./environment-variables.md#mb_custom_geojson) or a [config file option](./config-file.md) `custom-geojson` .
diff --git a/docs/configuring-metabase/email.md b/docs/configuring-metabase/email.md
index 4ee5de0bbed..920fb0baac6 100644
--- a/docs/configuring-metabase/email.md
+++ b/docs/configuring-metabase/email.md
@@ -11,7 +11,7 @@ Once you connect your database to Metabase, you'll want to configure an email ac
Both admins and people with [settings access](../permissions/application.md#settings-access) can set up email.
-## Email on Metabase Cloud
+## Set up email on Metabase Cloud
_Admin > Settings > Email_
@@ -57,47 +57,103 @@ When setting up a custom SMTP server on Metabase Cloud, you'll configure these f
- **SMTP USERNAME**: Your SMTP account username.
- **SMTP PASSWORD**: Your SMTP account password.
-You'll also need to specify:
-
-- **From address**: The email address you want to use for the sender of emails.
-- **Reply-to address**: The email address you want replies to go to, if different from the From address.
+Once you set up your SMTP, you'll be able to [Configure email settings](#configure-email-settings).
You can edit these settings at any time. You can also toggle between this custom SMTP server and the server managed by Metabase Cloud.
-## Configuring your email account
+## Set up email on self-hosted Metabases
_Admin > Settings > Email_
For Metabase to send messages to people, you'll need to set up an email account to send emails via **SMTP** (simple mail transfer protocol). SMTP is an email standard that, when combined with SSL/TLS, provides security protection for emails.
-To start, go to the Admin Panel from the dropdown menu in the top right of Metabase, then from the Settings page, click on **Email** in the left menu.
+If you're on Metabase Cloud, see [Set up email on Metabase Cloud](#set-up-email-on-metabase-cloud).
-You should see this form:
+To set up email on self-hosted Metabase:
-![Email Credentials](images/EmailCredentials.png)
+1. Go to **Admin > Settings > Email**.
+2. Next to **Self-Hosted SMTP**, click **Configure**.
+3. Specify the email configuration:
-Here you'll set:
+ ![Email Credentials](images/EmailCredentials.png)
-- **SMTP HOST**: The address of the SMTP server that handles your emails.
-- **SMTP PORT**: The port your SMTP server uses for outgoing emails.
-- **SMTP SECURITY**:
+- **SMTP Host**: The address of the SMTP server that handles your emails.
+- **SMTP Port**: The port your SMTP server uses for outgoing emails.
+- **SMTP Security**:
- None
- SSL
- TLS
- STARTTLS
-- **SMTP USERNAME**: Your SMTP account username.
-- **SMTP PASSWORD**: Your SMTP account password.
+- **SMTP Username**: Your SMTP account username.
+- **SMTP Password**: Your SMTP account password.
+
+3. Click **Save changes**.
+
+## Configure email settings
-You'll also need to specify your:
+_Admin > Settings > Email_
+
+![email settings](./images/email-settings.png)
+
+### Add From and Reply-to addresses
+
+Once you set up your email, you can configure:
+- **From Name**: The name you want to use for the sender of emails.
- **From address**: The email address you want to use for the sender of emails.
- **Reply-to address**: The email address you want replies to go to, if different from the From address.
-## Add recipients as CC or BCC
+### Add recipients as CC or BCC
By default, Metabase will hide email recipients by including them in the BCC list (Blind Carbon Copy) of the email. But if you're having issues with your email provider blocking emails with BCC recipients, and you don't mind having people see who else has been copied on the email Metabase sends them, you can tell Metabase to CC (Carbon Copy) recipients instead.
-### Recommended email settings
+To configure CC/BCC:
+
+1. Go to **Admin > Settings > Email**
+2. Under **Add recipients as CC or BCC**, select how you want Metabase to handle recipients.
+
+### Approved domains for notifications
+
+{% include plans-blockquote.html feature="Approved domains for notifications" %}
+
+You can configure allowed email address domain(s) for new [dashboard subscriptions](../dashboards/subscriptions.md) and [alerts](../questions/alerts.md).
+
+Adding approved domains allows you to restrict which email addresses people can send alerts and subscriptions to. This restriction only applies to sending email to people who lack an account with that Metabase. People with Metabase accounts who aren't [restricted by row or column security](../permissions/row-and-column-security.md) will be able to email any other person with an account in that same Metabase.
+
+To configure allowed domains:
+
+1. Go to **Admin > Settings > Email**
+2. Under **Allowed domains for notifications**, add allowed domains:
+
+ - To allow all domains, leave the field empty (allowing all domains is the default).
+ - To specify multiple domains, separate each domain with a comma, with no space in between (e.g., `domain1,domain2`).
+
+You can also set this property using the environment variable [`MB_SUBSCRIPTION_ALLOWED_DOMAINS`](../configuring-metabase/environment-variables.md#mb_subscription_allowed_domains).
+
+> Changing this setting won't affect already existing subscriptions and alerts.
+
+### Suggest recipients on dashboard subscriptions and alerts
+
+{% include plans-blockquote.html feature="Configuring suggested recipients" %}
+
+You can control which recipients people can see when they create a new [dashboard subscription](../dashboards/subscriptions.md) or [alert](../questions/alerts.md).
+
+![Suggested recipients](./images/suggested-recipients.png)
+
+For example, you may want to restrict people to viewing potential recipients that belong to the same [groups](../people-and-groups/managing.md#groups) they are a member of.
+
+To configure suggested recipients for subscriptions and alerts:
+
+1. Go to **Admin > Settings > Email**.
+2. Under **Suggest recipients on dashboard subscriptions and alerts**, select one of the options:
+
+ - Suggest all users
+ - Only suggest users in the same groups
+ - Don't show suggestions
+
+People with [row or column restrictions](../permissions/row-and-column-security.md) won't see suggestions.
+
+## Email best practices
- SSL is strongly recommended because it's more secure and gives your account extra protection from threats.
- If your email service has a whitelist of email addresses that are allowed to send email, be sure to whitelist the email address that you put in the **From address** field to ensure you and your teammates receive all emails from Metabase.
@@ -110,11 +166,11 @@ By default, Metabase will hide email recipients by including them in the BCC lis
### Google Apps
-1. In the **SMTP HOST** field, enter smtp.gmail.com
-2. Fill in 465 for the **SMTP PORT** field
-3. For the **SMTP SECURITY** field, enter **SSL**
-4. In the **SMTP USERNAME** field, enter your Google Apps email address (e.g. [email protected])
-5. Enter your Google Apps password in the **SMTP PASSWORD** field
+1. In the **SMTP Host** field, enter `smtp.gmail.com`.
+2. Fill in 465 for the **SMTP Port** field.
+3. For the **SMTP Security**, select **SSL**.
+4. In the **SMTP UsernameE** field, enter your Google Apps email address (e.g. `[email protected]`).
+5. Enter your Google Apps password in the **SMTP Password** field.
6. Enter the email address you would like to be used as the sender of system notifications in the **From address** field.
### Amazon SES
@@ -135,36 +191,6 @@ Check if [email quotas](https://docs.aws.amazon.com/ses/latest/dg/quotas.html) a
3. Although Mandrill lists **port 587**, [any port supported by Mandrill](https://mailchimp.com/developer/transactional/docs/smtp-integration/#the-basics) will work for SMTP email.
4. Now you can go back to the Metabase Admin Panel form and enter the info there.
-## Approved domains for notifications
-
-{% include plans-blockquote.html feature="Approved domains for notifications" %}
-
-Allowed email address domain(s) for new [dashboard subscriptions](../dashboards/subscriptions.md) and [alerts](../questions/alerts.md).
-
-Adding approved domains allows you to restrict which email addresses people can send alerts and subscriptions to. This restriction only applies to sending email to people who lack an account with that Metabase. People with Metabase accounts who aren't [restricted by row or column security](../permissions/row-and-column-security.md) will be able to email any other person with an account in that same Metabase.
-
-To allow all domains, leave the field empty (allowing all domains is the default).
-
-To specify multiple domains, separate each domain with a comma, with no space in between (e.g., "domain1,domain2").
-
-You can also set this property using the environment variable [`MB_SUBSCRIPTION_ALLOWED_DOMAINS`](../configuring-metabase/environment-variables.md#mb_subscription_allowed_domains).
-
-> This setting doesn't affect existing subscriptions and alerts.
-
-## Suggest recipients on dashboard subscriptions and alerts
-
-{% include plans-blockquote.html feature="Configuring suggested recipients" %}
-
-Control which recipients people can see when they create a new [dashboard subscription](../dashboards/subscriptions.md) or [alert](../questions/alerts.md). For example, you may want to restrict people to viewing potential recipients that belong to the same [groups](../people-and-groups/managing.md#groups) they are a member of.
-
-Options include:
-
-- Suggest all users
-- Only suggest users in the same groups
-- Don't show suggestions
-
-People with [row or column restrictions](../permissions/row-and-column-security.md) won't see suggestions.
-
## Further reading
- [Alerts](../questions/alerts.md)
diff --git a/docs/configuring-metabase/fonts.md b/docs/configuring-metabase/fonts.md
index 78c885bec2d..d133681e456 100644
--- a/docs/configuring-metabase/fonts.md
+++ b/docs/configuring-metabase/fonts.md
@@ -7,15 +7,21 @@ redirect_from:
# Fonts
-{% include plans-blockquote.html feature="Customizable font" %}
+{% include plans-blockquote.html feature="Customizable fonts" is_plural=true%}
On Pro and Enterprise plans, you can customize the font Metabase uses (the default is [Lato](https://fonts.google.com/specimen/Lato)). You can choose from a curated set of Google Fonts that accommodate the regular, bold, and heavy font weights that Metabase relies on for its various UI elements.
-## Included fonts
+![Font settings](./images/font-settings.png)
-To change your Metabase font, click the **grid** icon in the upper right of the screen and select **Admin** > **Settings** > **Appearance**. Under **Font**, select from a list of included fonts.
+## Configure fonts
+
+To change your Metabase font:
+
+1. Click the **grid** icon in the upper right of the screen.
+2. Select **Admin**.
+3. In Admin console, go to **Settings** > **Appearance** > **Branding**
+4. Under **Font**, select from a list of included fonts:
-- [Custom font](#custom-fonts)
- [Lato](https://fonts.google.com/specimen/Lato)
- [Lora](https://fonts.google.com/specimen/Lora)
- [Merriweather](https://fonts.google.com/specimen/Merriweather)
@@ -35,16 +41,23 @@ To change your Metabase font, click the **grid** icon in the upper right of the
- [Slabo 27px](https://fonts.google.com/specimen/Slabo+27px)
- Source Sans Pro
- [Ubuntu](https://fonts.google.com/specimen/Ubuntu)
+- [Custom font](#add-custom-fonts)
Comic Sans is currently not included.
-## Custom fonts
+You can also upload your own custom font.
+
+## Add custom fonts
-To set a custom font, click the **grid** icon in the upper right of the screen and select **Admin** > **Settings** > **Appearance**.
+To set a custom font:
-For **Font**, select **Custom...** and enter URLs to your font files.
+1. Click the **grid** icon in the upper right of the screen.
+2. Select **Admin**.
+3. In the Admin console, go to **Settings** > **Appearance** > **Branding**.
+4. Under **Fonts**, click the dropdown and select **Custom...**
+5. Enter URLs to your font files.
-## Font style options
+### Custom font style options
You can set three different font styles with three different URLs, one for each font style (size and weight) that Metabase will use to display its user interface properly. The font weights are:
@@ -60,7 +73,7 @@ For best results, set at least the 400 and 700 styles. If you have a single font
For custom fonts, Metabase supports woff, woff2, ttf files. If the URL you provide lacks a specific file extension, Metabase will assume it's a woff2 file.
-## Google Font URLs
+### Google Font URLs
To get a URL for a [Google Font](https://fonts.google.com/), visit the Google Font page and select the style you want to use. Then make an HTTP request to get the URL of the tff file. For example, say we want to use Roboto Mono: here's how we could get the font file URLs for both the 400 and 700 styles:
@@ -95,7 +108,7 @@ For latin text, we'd copy the relevant src URLs for each style, in this case:
And paste those URLS in the relevant input fields in **Admin** > **Settings** > **Appearance** > **Font** section where it says "Tell us where to find the file for each font weight. You don’t need to include all of them, but it’ll look better if you do."
-## Hosting fonts on GitHub
+### Hosting fonts on GitHub
If you host a font on GitHub, the font should be in a public repository, and you'll need to link to the raw font file(s) served from the raw.githubusercontent.com domain.
@@ -115,13 +128,13 @@ raw.githubusercontent.com/${user}/${repo}/${branch}/${path}
Note that in the raw link, there is no `/blob/` directory in the URL.
-## Supporting multiple languages
+### Supporting multiple languages
To support multiple character sets, for example both Latin and Cyrillic, you'll need to merge font files.
## Customizing the font for individual embedded items
-When configuring [guest embeds](../embedding/guest-embedding.md), you can select from any of the [included fonts](#included-fonts). If you've set a custom font for your Metabase, you can also select "Use instance font" to use your custom font in the embed.
+When configuring [guest embeds](../embedding/guest-embedding.md), you can select from any of the [included fonts](#configure-fonts). If you've set a custom font for your Metabase, you can also select "Use instance font" to use your custom font in the embed.
## Further reading
diff --git a/docs/configuring-metabase/images/EmailCredentials.png b/docs/configuring-metabase/images/EmailCredentials.png
index 7d04032cd8f..afa130964fe 100644
Binary files a/docs/configuring-metabase/images/EmailCredentials.png and b/docs/configuring-metabase/images/EmailCredentials.png differ
diff --git a/docs/configuring-metabase/images/chart-colors.png b/docs/configuring-metabase/images/chart-colors.png
index e19016a0b91..6a6e37a1c8e 100644
Binary files a/docs/configuring-metabase/images/chart-colors.png and b/docs/configuring-metabase/images/chart-colors.png differ
diff --git a/docs/configuring-metabase/images/email-settings.png b/docs/configuring-metabase/images/email-settings.png
new file mode 100644
index 00000000000..aafdf46f848
Binary files /dev/null and b/docs/configuring-metabase/images/email-settings.png differ
diff --git a/docs/configuring-metabase/images/font-settings.png b/docs/configuring-metabase/images/font-settings.png
new file mode 100644
index 00000000000..6c490efabaf
Binary files /dev/null and b/docs/configuring-metabase/images/font-settings.png differ
diff --git a/docs/configuring-metabase/images/map-settings.png b/docs/configuring-metabase/images/map-settings.png
new file mode 100644
index 00000000000..b0354d67da0
Binary files /dev/null and b/docs/configuring-metabase/images/map-settings.png differ
diff --git a/docs/configuring-metabase/images/preview.png b/docs/configuring-metabase/images/preview.png
new file mode 100644
index 00000000000..6063b890391
Binary files /dev/null and b/docs/configuring-metabase/images/preview.png differ
diff --git a/docs/configuring-metabase/images/qb-colors.png b/docs/configuring-metabase/images/qb-colors.png
new file mode 100644
index 00000000000..8d896f388a5
Binary files /dev/null and b/docs/configuring-metabase/images/qb-colors.png differ
diff --git a/docs/configuring-metabase/images/suggested-recipients.png b/docs/configuring-metabase/images/suggested-recipients.png
new file mode 100644
index 00000000000..d46bb303a57
Binary files /dev/null and b/docs/configuring-metabase/images/suggested-recipients.png differ
diff --git a/docs/configuring-metabase/images/user-interface-colors.png b/docs/configuring-metabase/images/user-interface-colors.png
index fbe8bd3c542..52b19352a83 100644
Binary files a/docs/configuring-metabase/images/user-interface-colors.png and b/docs/configuring-metabase/images/user-interface-colors.png differ
diff --git a/docs/configuring-metabase/localization.md b/docs/configuring-metabase/localization.md
index fd5b612f3c3..992cb87adb1 100644
--- a/docs/configuring-metabase/localization.md
+++ b/docs/configuring-metabase/localization.md
@@ -6,15 +6,122 @@ redirect_from:
# Languages and localization
+_Admin > Settings > Localization_
+
Admins can update the localization settings for the instance:
1. Click the **grid** icon in the upper right.
-2. Click **Admin**.
+2. Select **Admin**.
3. In the **Settings** tab, click on **Localization** in the left sidebar.
These localization settings allow you to set global language and formatting defaults for dates, times, numbers, and currencies.
-You can also override these localization options for specific fields or questions. For more info, see [Formatting](../data-modeling/formatting.md).
+People can also override these localization options for specific fields or questions. For more info, see [Formatting](../data-modeling/formatting.md).
+
+## Instance settings
+
+### Set default instance language
+
+_Admin > Settings > Localization > Instance settings > Instance language_
+
+You can set the default language (also called the "instance language") across your Metabase UI, system [emails](./email.md), [dashboard subscriptions](../dashboards/subscriptions.md), and [alerts](../questions/alerts.md).
+
+People can override these settings in their personal [account settings](../people-and-groups/account-settings.md).
+
+To set the instance-wider language:
+
+1. Go to **Admin > Settings > Localization**.
+2. Under **Instance language**, pick the language for your instance.
+
+ See [List of supported languages](#supported-languages). Some translations are created by the Metabase community, and might not be perfect.
+
+### Set default instance report timezone
+
+_Admin > Settings > Localization > Instance settings > Report timezone_
+
+Use **report timezone** to set a default display time zone for dates and times in Metabase. The report timezone setting is a display setting only, so changing the report timezone won't affect the time zone of any data in your database.
+
+Report timezone doesn't apply to `timestamp without time zone` data types, including the output of [`convertTimezone`](../questions/query-builder/expressions/converttimezone.md) expressions. For example:
+
+| Raw timestamp in your database | Data type | Report time zone | Displayed as |
+| ---------------------------------------- | ----------------------------- | ---------------- | ---------------------- |
+| `2022-12-28T12:00:00 AT TIME ZONE 'CST'` | `timestamp with time zone` | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM |
+| `2022-12-28T12:00:00-06:00` | `timestamp with offset` | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM |
+| `2022-12-28T12:00:00` | `timestamp without time zone` | 'Canada/Eastern' | Dec 28, 2022, 12:00 AM |
+
+Report timezone is only supported for the following databases:
+
+- BigQuery
+- Druid
+- MySQL
+- Oracle
+- PostgreSQL
+- Presto
+- Redshift
+- Vertica
+
+To set report timezone:
+
+1. Go to **Admin > Settings > Localization**.
+2. Under **Report timezone**, pick the default report timezone.
+
+### First day of the week
+
+_Admin > Settings > Localization > Instance settings > First day of the week_
+
+If you need to, you can change the first day of the week for your instance (the default is Sunday).
+
+Setting the first day of the week affects how the [query builder](../questions/query-builder/editor.md) filters or groups by week. People can, however, use the `week` function to override this default when filtering or grouping by week of year. See [using a different first week of the year](../questions/query-builder/expressions/week.md#using-a-different-first-week-of-the-year).
+
+This setting doesn't affect [SQL queries](../questions/native-editor/writing-sql.md).
+
+## Dates and times display settings
+
+You can configure the default formatting for dates and times.
+
+Note that people can also override these localization options for specific fields or questions. For more info, see [Formatting](../data-modeling/formatting.md).
+
+To configure default date and time format settings:
+
+1. Go to **Admin > Settings > Localization**.
+2. Under **Dates and times**, configure your settings:
+ - **Date style:** the way dates should be displayed in tables, axis labels, and tooltips.
+ - **Date separators:** you can choose between slashes (`2022/12/14`), dashes (`2022-12-14`), and dots (`2022.12.14`).
+ - **Abbreviate names of days and months:** whenever a date is displayed with the day of the week and/or the month written out, turning this setting on will display e.g. "January" as "Jan" or "Monday" as "Mon".
+ - **Time style:** choose to display the time using either a 12 or 24-hour clock (e.g., 3:00 PM or 15:00).
+
+## Number display settings
+
+_Admin > Settings > Localization_
+
+Some people use commas to separate thousands places, and others use periods. You can configure which camp you belong to.
+
+Note that people can also override these localization options for specific fields or questions. For more info, see [Formatting](../data-modeling/formatting.md).
+
+To configure default separator settings:
+
+1. Go to **Admin > Settings > Localization**.
+2. Under **Number**, configure the **Separator style**.
+
+## Currency display settings
+
+_Admin > Settings > Localization_
+
+You can choose how should currency fields be displayed by default (you can to configure _which_ fields should be displayed as currency in table metadata or in question formatting setting, see [Formatting](../data-modeling/formatting.md) )
+
+Note that people can also override these localization options for specific fields or questions.
+
+To configure default currency settings:
+
+1. Go to **Admin > Settings > Localization**.
+2. Under **Currency**, configure currency settings:
+
+ - **Unit of currency:** if you do most of your business in a particular currency, you can specify that here.
+ - **Currency label style:** whether you want to have your currencies labeled with a symbol, a code (like "USD"), or its full name.
+
+## Localizing embedded Metabase
+
+You can translate both Metabase UI elements (like button labels) and content (like dashboard names) in guest embeds. See [Setting the language for guest embeds](../embedding/guest-embedding.md) and [Translating embedded dashboards and questions](../embedding/translations.md).
## Supported languages
@@ -78,65 +185,3 @@ Note that while we only remove languages in major releases, we are happy to add
### Contributing to translations for Metabase
If you'd like to help make Metabase available in a language you're fluent in, we'd love your help! Check out our [Crowdin project](https://crowdin.com/project/metabase-i18n).
-
-## Instance settings
-
-### Instance language
-
-Here you can set the default language (also called the "instance language") across your Metabase UI, system [emails](./email.md), [dashboard subscriptions](../dashboards/subscriptions.md), and [alerts](../questions/alerts.md).
-
-People can override these settings in their personal [account settings](../people-and-groups/account-settings.md).
-
-Some translations are created by the Metabase community, and might not be perfect.
-
-### Report timezone
-
-Use **report timezone** to set a default display time zone for dates and times in Metabase. The report timezone setting is a display setting only, so changing the report timezone won't affect the time zone of any data in your database.
-
-Report timezone doesn't apply to `timestamp without time zone` data types, including the output of [`convertTimezone`](../questions/query-builder/expressions/converttimezone.md) expressions. For example:
-
-| Raw timestamp in your database | Data type | Report time zone | Displayed as |
-| ---------------------------------------- | ----------------------------- | ---------------- | ---------------------- |
-| `2022-12-28T12:00:00 AT TIME ZONE 'CST'` | `timestamp with time zone` | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM |
-| `2022-12-28T12:00:00-06:00` | `timestamp with offset` | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM |
-| `2022-12-28T12:00:00` | `timestamp without time zone` | 'Canada/Eastern' | Dec 28, 2022, 12:00 AM |
-
-Report timezone is only supported for the following databases:
-
-- BigQuery
-- Druid
-- MySQL
-- Oracle
-- PostgreSQL
-- Presto
-- Redshift
-- Vertica
-
-### First day of the week
-
-If you need to, you can change the first day of the week for your instance (the default is Sunday).
-
-Setting the first day of the week affects how the [query builder](../questions/query-builder/editor.md) filters or groups by week. People can, however, use the `week` function to override this default when filtering or grouping by week of year. See [using a different first week of the year](../questions/query-builder/expressions/week.md#using-a-different-first-week-of-the-year).
-
-This setting doesn't affect [SQL queries](../questions/native-editor/writing-sql.md).
-
-## Dates and times
-
-- **Date style:** the way dates should be displayed in tables, axis labels, and tooltips.
-- **Date separators:** you can choose between slashes (`2022/12/14`), dashes (`2022-12-14`), and dots (`2022.12.14`).
-- **Abbreviate names of days and months:** whenever a date is displayed with the day of the week and/or the month written out, turning this setting on will display e.g. "January" as "Jan" or "Monday" as "Mon".
-- **Time style:** choose to display the time using either a 12 or 24-hour clock (e.g., 3:00 PM or 15:00).
-
-## Numbers
-
-- **Separator style:** some people use commas to separate thousands places, and others use periods. Here's where you can indicate which camp you belong to.
-
-## Currency
-
-- **Unit of currency:** if you do most of your business in a particular currency, you can specify that here.
-- **Currency label style:** whether you want to have your currencies labeled with a symbol, a code (like "USD"), or its full name.
-- **Where to display the unit of currency:** this pertains specifically to tables, and lets you choose whether you want the currency labels to appear only in the column heading, or next to each value in the column.
-
-## Localizing embedded Metabase
-
-You can translate both Metabase UI elements (like button labels) and content (like dashboard names) in guest embeds. See [Setting the language for guest embeds](../embedding/guest-embedding.md) and [Translating embedded dashboards and questions](../embedding/translations.md).
diff --git a/docs/configuring-metabase/log-configuration.md b/docs/configuring-metabase/log-configuration.md
index 452c092463d..d876d7f8213 100644
--- a/docs/configuring-metabase/log-configuration.md
+++ b/docs/configuring-metabase/log-configuration.md
@@ -25,16 +25,21 @@ Metabase uses [Log4j](https://logging.apache.org/log4j/2.x/) for logging configu
### Temporary override logging configuration
-To temporarily adjust the logging configuration, go to **Admin** > **Tools** > **Logs** and click on **Customize log levels**.
+_Admin > Tools > Logs_.
-You can select from log level presets for common troubleshooting tasks (for example, troubleshooting sync issues), or provide your own configuration as a JSON. For example, here's an override configuration that increases logging for troubleshooting linked filters:
+To temporarily adjust the logging configuration:
-```json
-{
- "metabase.parameters.chain-filter": "debug",
- "metabase.parameters.chain-filter.dedupe-joins": "debug"
-}
-```
+1. Go to **Admin** > **Tools** > **Logs**.
+2. Click on **Customize log levels** above the logs.
+
+ You can select from log-level presets for common troubleshooting tasks (for example, troubleshooting sync issues), or provide your own configuration as JSON. For example, here's an override configuration that increases logging for troubleshooting linked filters:
+
+ ```json
+ {
+ "metabase.parameters.chain-filter": "debug",
+ "metabase.parameters.chain-filter.dedupe-joins": "debug"
+ }
+ ```
The override from Admin settings will be temporary. You can select for how long the override should be in place (e.g., 60 minutes). When the override times out, the logging configuration will revert to the default logging configuration (or a custom configuration if you're using a [custom log file](#use-a-custom-log-configuration-file)).
diff --git a/docs/configuring-metabase/settings.md b/docs/configuring-metabase/settings.md
index d94f6c8be77..95236dd3aa4 100644
--- a/docs/configuring-metabase/settings.md
+++ b/docs/configuring-metabase/settings.md
@@ -6,10 +6,12 @@ redirect_from:
# General settings
-This section contains settings for your whole instance, like its URL, the reporting timezone, and toggles for disabling or enabling some of Metabase's optional features.
+_Admin > Settings > Feneral_
+This section contains settings for your whole instance, like its URL, the reporting timezone, and toggles for disabling or enabling some of Metabase's optional features.
You can configure these settings by clicking the **grid icon** in the upper right, then going to **Admin** > **Settings** > **General**.
+
## Site name
How you’d like to refer to this instance of Metabase.
@@ -18,13 +20,7 @@ How you’d like to refer to this instance of Metabase.
The site URL is the web address that people use to access your Metabase instance. Make sure to include `http://` or `https://` to make sure it’s reachable. This feature is only available for self-hosted Metabases. For customers on Metabase Cloud, check out [Custom domains](../cloud/custom-domain.md).
-## Custom homepage
-
-Admins can pick a dashboard to serve as the homepage. If people lack permissions to view the selected dashboard, Metabase will redirect them to the default homepage.
-
-If you've set a dashboard as your homepage, and want to revert to the default Metabase homepage, simply turn off the **Enabled** toggle to disable the Custom Homepage feature.
-
-## Redirect to HTTPS
+### Redirect to HTTPS
By default, Metabase is served over HTTP.
@@ -34,13 +30,19 @@ For example, say you enable HTTPS redirect for a Metabase instance at the site U
> Note: if you haven't set up HTTPS on your server, Metabase will not let you enable HTTPS redirect. Instead, you'll get a warning saying "It looks like HTTPS is not properly configured."
+## Custom homepage
+
+Admins can pick a dashboard to serve as the homepage. If people lack permissions to view the selected dashboard, Metabase will redirect them to the default homepage.
+
+To revert to the default Metabase homepage, simply toggle off Custom homepage.
+
## Email address for help requests
This email address will be displayed in various messages throughout Metabase when users encounter a scenario where they need assistance from an admin, such as a password reset request.
## Anonymous tracking
-This option turns determines whether or not you allow [anonymous data about your usage of Metabase](../installation-and-operation/information-collection.md) to be sent back to us to help us improve the product. [Your database’s data is never tracked or sent](https://www.metabase.com/security).
+On self-hosted Metabases, this option turns determines whether or not you allow [anonymous data about your usage of Metabase](../installation-and-operation/information-collection.md) to be sent back to us to help us improve the product. [Your database’s data is never tracked or sent](https://www.metabase.com/security).
## Friendly table and field names
diff --git a/docs/configuring-metabase/slack.md b/docs/configuring-metabase/slack.md
index 1a656f02fab..edf34dca5b6 100644
--- a/docs/configuring-metabase/slack.md
+++ b/docs/configuring-metabase/slack.md
@@ -6,7 +6,9 @@ redirect_from:
# Set up Slack
-If you want to have your [dashboard subscriptions](../dashboards/subscriptions.md) or [alerts](../questions/alerts.md) sent to Slack channels (or people on Slack), an admin must first integrate your Metabase with Slack.
+_Admin > Settings > Notification channels > Slack_
+
+If you want to have your [dashboard subscriptions](../dashboards/subscriptions.md) or [alerts](../questions/alerts.md) sent to Slack channels (or people on Slack), you need to first integrate your Metabase with Slack.
Both admins and people with [settings access](../permissions/application.md#settings-access) can set up Slack.
@@ -14,84 +16,88 @@ Both admins and people with [settings access](../permissions/application.md#sett
For Metabase to post to your Slack channels, you’ll need to create a Slack App and make it available to Metabase.
-From any Metabase page, go to **Admin** > **Settings** > **Notification channels** > **Slack**.
-
-Click on **Open Slack Apps**. Metabase will open a new browser tab and send you over to the Slack website to create the Slack app.
-
-On the Slack website, click **Create an App**.
-
-### Pick a workspace to develop your app
-
-Select the workspace you want to create your app.
-
-### The app manifest
+1. In Metabase, go to **Admin > Settings > Notification channels**.
+2. Click **Connect to Slack**.
+3. Click **Create a Slack App**. Metabase will open a new tab with the Slack website.
+4. On the Slack website, click **Create an App**.
+5. Pick a workspace to develop your app.
+6. You may get a warning that says **This app is created from a 3rd party manifest. Always verify URLs and permissions below.**
+
+ This warning is expected (Metabase is the third party here). You can click on **Edit configurations** to see the app manifest Metabase sent along in the URL. Here is the manifest in YAML format:
+
+ ```yml
+ _metadata:
+ major_version: 1
+ minor_version: 1
+ display_information:
+ name: Metabase
+ description: Bringing the power of Metabase to your Slack #channels!
+ background_color: "#509EE3"
+ features:
+ bot_user:
+ display_name: Metabase
+ oauth_config:
+ scopes:
+ bot:
+ - users:read
+ - channels:read
+ - channels:join
+ - files:write
+ - chat:write
+ - chat:write.customize
+ - chat:write.public
+ - groups:read
+ ```
+
+ The manifest just take cares of some settings for your app and helps speed things along.
+
+7. Click the **Next** button. Then hit **Create** to set up your Slack app.
-When you click on **Open Slack App**, Metabase will pass along the app manifest, which Slack will use to set up your app.
-
-You may get a warning that says:
-
-**This app is created from a 3rd party manifest** Always verify URLs and permissions below.
+## Install your app to your workspace
-This warning is expected (Metabase is the third party here). You can click on **Configure** to see the app manifest Metabase sent along in the URL. Here is the manifest in YAML format:
+1. On the Slack site for your newly created app, go to **Settings** > **Basic Information** tab
+2. Under **Install your app**, click on **Install to workspace**.
+3. On the next screen, click **Allow** to give Metabase access to your Slack workspace.
-```yml
-_metadata:
- major_version: 1
- minor_version: 1
-display_information:
- name: Metabase
- description: Bringing the power of Metabase to your Slack #channels!
- background_color: "#509EE3"
-features:
- bot_user:
- display_name: Metabase
-oauth_config:
- scopes:
- bot:
- - users:read
- - channels:read
- - channels:join
- - files:write
- - chat:write
- - chat:write.customize
- - chat:write.public
- - groups:read
-```
+## Configure your app in Metabase
-The manifest just take cares of some settings for your app and helps speed things along.
+Once you [created the app](#create-your-slack-app) and [installed it in your workspace](#install-your-app-to-your-workspace), you tell Metabase to use it by giving Metabase the OAuth token for the app.
-Click the **Next** button. Then hit **Create** to set up your Slack app.
+To obtain the OAuth token for the Slack aopp:
-## Install your app to your workspace
+1. Go to the Slack site page for your Slack app.
+2. On the Slack page for your app, go to **OAuth & Permissions** in the left sidebar.
+3. On the **OAuth & Permissions** page for your Slack app, copy the **Bot User OAuth Token**.
-On the Slack site for your newly created app, in the **Settings** > **Basic Information** tab, under **Install your app**, click on **Install to workspace**. On the next screen, click **Allow** to give Metabase access to your Slack workspace.
+To set up the app in Metabase:
-## The Bot User OAuth Token
+1. In Metabase, go to **Admin > Settings > Notification channels > Slack**. Click **Connect to Slack**.
+2. Paste the token into **Slack bot user OAuth token**.
+3. **Save changes** in Metabase.
-On the Slack site page for your Slack app, on the left in the **Features** section, click on **OAuth and Permissions** in the Slack Apps sidebar and then copy the **Bot User OAuth Token**. Return to the Slack settings page in your Metabase and paste this token in the Metabase field with the same name.
+ Metabase will automatically run a quick test to check that the API token is working properly. If something goes wrong, it'll give you an error message.
-## Save your changes in Metabase
+## Sending alerts and subscriptions to private Slack channels
-In Metabase, click on the **Save changes** button and that’s it! Metabase will automatically run a quick test to check that the API token is working properly. If something goes wrong, it'll give you an error message.
+In order to send [subscriptions](../dashboards/subscriptions.md) and [alerts](../questions/alerts.md) to private Slack channels, you must first add the Metabase app to the private channel.
-## Sending alerts and subscriptions to private Slack channels
+To add your app to a private Slack channel:
-In order to send subscriptions and alerts to private Slack channels, you must first add the Metabase app to the private channel.
+1. In Slack, go to the private channel and mention the Metabase app. For example, if you called your Slack app "Metabase", you'd just type `@Metabase`.
-In Slack, go to the private channel and mention the Metabase app. For example, if you called your Slack app "Metabase", you'd just type `@Metabase`. Slack will ask you if you want to invite your app to your channel, which you should.
+2. Slack will ask you if you want to invite your app to your channel, which you should.
-### Metabase not listing your private channel?
+Once you added the app to a private channel, you should see the channel in the list of channels when setting up a subscription or alerts within 10 mins (it can take a little time for Metabase to see all the channels the app has been invited to).
-It can take a little time for metabase to see all the channels the app has been invited to. New channels may not appear in listings for up to 10 minutes after inviting the app to the channel.
+In order for metabase to see private channels, the app must have the `groups:read` OAuth scope. Although this scope should be granted when setting up the app through Metabase, older installations might not have this scope.
-In order for metabase to see private channels, the app must have the `groups:read` oauth scope. Although this scope should be granted when setting up the app through metabase, older installations might not have this scope.
-If you think this might be the case [visit the app settings in slack](https://api.slack.com/apps/):
+To check or edit your OAuth settings:
-- Click on the metabase app in the app listing.
-- Click on **OAuth & Permissions** in the sidebar.
-- Under **Scopes** add the `groups:read` scope.
-- The app will the need to be reinstalled to the workspace
- by clicking the **Reinstall** button under **OAuth Tokens**.
+1. [Visit the app settings in slack](https://api.slack.com/apps/):
+2. Click on the Metabase app in the list of apps.
+3. Go to **OAuth & Permissions** in the sidebar.
+4. Under **Scopes**, add the `groups:read` scope if it's not added already.
+5. Reinstall the app by clicking the **Reinstall** button under **OAuth Tokens**.
## Further reading
diff --git a/docs/configuring-metabase/timezones.md b/docs/configuring-metabase/timezones.md
index e42bef65ba0..71cd0e5b4d1 100644
--- a/docs/configuring-metabase/timezones.md
+++ b/docs/configuring-metabase/timezones.md
@@ -39,7 +39,7 @@ You can make your database columns time zone aware by storing them as specific d
The exact data type will depend on your database. Some Metabase features only work with specific data types:
-- [Report timezone setting](../configuring-metabase/localization.md#report-timezone)
+- [Report timezone setting](../configuring-metabase/localization.md#set-default-instance-report-timezone)
- [`converttimezone` custom expression](../questions/query-builder/expressions/converttimezone.md)
## Common pitfalls
diff --git a/docs/configuring-metabase/webhooks.md b/docs/configuring-metabase/webhooks.md
index 5b90e87f911..c0381958e59 100644
--- a/docs/configuring-metabase/webhooks.md
+++ b/docs/configuring-metabase/webhooks.md
@@ -11,25 +11,27 @@ Only admins and people with settings access can send alerts to webhooks.
For now, webhooks are only available for [alerts](../questions/alerts.md); you can't select a webhook as the recipient of a [dashboard subscription](../dashboards/subscriptions.md).
-## Creating a webhook
+## Create a webhook
-Before you can send an alert to a webhook, an admin will need to create a webhook to target.
+_Admin > Settings > Notification channels_
-Admins and people with [settings access](../permissions/application.md#settings-access) can create a webhook by clicking the **grid icon** > **Admin** > **Notification channels**. In **Webhooks for alerts**, click **+ Add another**. Metabase will show you a short form to fill out:
+Before people can send alerts to a webhook, an admin or someone with [settings access](../permissions/application.md#settings-access) will need to create a webhook to target.
-- **Webhook URL**. Where you want Metabase to send the results of an alert. Must be a valid URL.
-- **Give it a name**. Name the webhook so that people can pick the right hook when setting up an alert on a question.
-- **Description**. Tell people what the hook is for.
-- **Authentication method**. See below.
+To create a webhook:
-## Webhook authentication method
+1. Click the **grid** icon in top right corner and select **Admin**.
+2. In the Admin console, go **Settings > Notification channels**.
+3. In **Webhooks for alerts**, click **Add a webhoor**.
+4. Metabase will show you a short form to fill out:
-You can specify an auth method for the webhook.
-
-- **None**: Anything goes.
-- **Basic**: Set a username and password.
-- **Bearer**: Include a [secret token](https://datatracker.ietf.org/doc/html/rfc6750).
-- **API key**: You can add the API key to the Header or as a Query param. Both approaches require a key and value (the API key itself).
+ - **Webhook URL**. Where you want Metabase to send the results of an alert. Must be a valid URL.
+ - **Give it a name**. Name the webhook so that people can pick the right hook when setting up an alert on a question.
+ - **Description**. Tell people what the hook is for.
+ - **Authentication method**:
+ - **None**: Anything goes.
+ - **Basic**: Set a username and password.
+ - **Bearer**: Include a [secret token](https://datatracker.ietf.org/doc/html/rfc6750).
+ - **API key**: You can add the API key to the Header or as a Query param. Both approaches require a key and value (the API key itself).
## Webhook payload
diff --git a/docs/dashboards/actions.md b/docs/dashboards/actions.md
index 0e45230712e..a71e8491ca6 100644
--- a/docs/dashboards/actions.md
+++ b/docs/dashboards/actions.md
@@ -4,51 +4,51 @@ title: Actions on dashboards
# Actions on dashboards
-![Dashboard with filter, action button, and detail card view](./images/dashboard-filter-action.png)
+You can add buttons to dashboards to perform [actions](../actions/start.md) like creating or updating records, and combine them with dashboard [filter](./filters.md).
-To put [actions](../actions/start.md) in action, you can combine them with a [model](../data-modeling/models.md) and a [filter](./filters.md) on a dashboard.
+![Dashboard with filter, action button, and detail card view](./images/dashboard-filter-action.png)
-## Adding an action to a dashboard
+## Create an action
-Visit a dashboard page and click on the **pencil** icon, then click on the **box with a mouse pointer** to add an action.
+To add an action button to a dashboard, you'll first need to create an action on a model. See [Model actions](../actions/introduction.md).
-Metabase will add an action button to the dashboard grid, and open a sidebar with the buttons settings.
+## Add an action button to a dashboard
-### Button text
+Once you [created an action](../actions/introduction.md), you can add a button to a dashboard to perform that action:
-A label explaining what the button does, e.g., "Ignition".
+1. Visit a dashboard page and click the **pencil** icon to start editing the dashboard.
+2. Click on the **box with a mouse pointer** to add an action.
-### Button variant
+ Metabase will add an action button to the dashboard grid, and open a sidebar with button settings:
-You can select from a variety of handsome buttons:
+ - **Button text**: A label explaining what the button does, e.g., "Add record".
+ - **Button variant**: How a button looks. You can select from a variety of handsome buttons:
-- Primary
-- Outline
-- Danger
-- Success
-- Borderless
+ ![Button types](./images/buttons.png)
-![Button types](./images/buttons.png)
+3. Pick an action to connect to the button.
+4. For every field in the action, select whether people should supply the value themselves, or whether the action should use the value from the dashboard filter. See [Connecting an action to a dashboard filter](#connect-an-action-to-a-dashboard-filter).
+5. Click **Done**, and **Save** the dashboard.
-## Connecting an action to a dashboard filter
+People viewing the dashboard will be able to click the button and perform your chosen action:
-For most actions, when people click on a button, they'll be prompted to input values in the fields defined by that action.
+![Button form](./images/button-form.png)
-Many types of actions rely on knowing the Entity ID for the model to determine which records to update or delete. To have people select the ID for the action, you'll need to:
+You can add as many buttons as you want, and wire them up to one or more filters.
-1. Click on the pencil icon to edit the dashboard.
-2. Add an action to the dashboard (if you haven't already).
-3. [Add a filter](./filters.md) to a dashboard, wire it up to any cards that you want to, and click **Done** in the bottom of the sidebar.
-4. Hover over the action button and click on the **gear** icon, and select **Change action**.
-5. Click on the field's dropdown to select where the action should get it's value. Here you can select "Ask the user" or have it automatically populated by a dashboard filter. In this case, we'll select our "ID" filter.
+## Connect an action to a dashboard filter
-![Wiring up an action button to a dashboard filter](./images/id-value.png)
+When people click the action button on a dashboard, they'll be prompted to input values in the fields defined by that action. Alternatively, you can pre-fill some action fields with the values selected for a dashboard filter. Passing filter values to action fields is useful when the dashboard filters by an ID, and you want the action button to update the record associated with that ID.
-If you also wire that filter up to a card with a model on the dashboard, you can filter for individual records in that model, view them in the model's card, and have the action buttons auto-populate the id.
+To connect an action field to a filter on a dashboard:
-![Button form](./images/button-form.png)
+1. On a dashboard with an action button, click the **pencil icon** edit the dashboard.
+2. [Add a filter](./filters.md) to a dashboard, connect the filter to one or more cards, and click **Done** in the bottom of the sidebar.
+3. [Add an action button to the dashboard](#add-an-action-button-to-a-dashboard) (if you haven't already).
+4. Hover over the action button and click on the **gear** icon, and select **Change action**.
+5. Click the field's dropdown to select where the action should get its value, and pick a filter to connect to (filters will be referenced in the dropdown by their name):
-You can add as many buttons as you want, and wire them up to one or more filters.
+ ![Wiring up an action button to a dashboard filter](./images/id-value.png)
## Actions are unavailable for public dashboards and dashboards in guest embeds
@@ -59,3 +59,4 @@ If you want people outside of your Metabase to use an action, you can create a [
## Further reading
- [Actions](../actions/start.md)
+- [Editable tables](../data-modeling/editable-tables.md)
diff --git a/docs/dashboards/filters.md b/docs/dashboards/filters.md
index 82fcd8fe2d4..2f3318f01ae 100644
--- a/docs/dashboards/filters.md
+++ b/docs/dashboards/filters.md
@@ -13,7 +13,7 @@ Instead of creating duplicate dashboards to show different cuts of the same data
## Filter and parameter widgets
-There are two basic types of widgets you can add. The type of filter or parameter widget you choose determines how the widget works, including which fields you can connect to the widget.
+There are two basic types of widgets you can add: filters or parameters. The type of filter or parameter widget you choose determines how the widget works, including which fields you can connect to the widget.
### Filter widgets
@@ -32,11 +32,32 @@ There are two basic types of widgets you can add. The type of filter or paramete
- [Time grouping](#time-grouping-parameter)
-## Adding a filter or parameter widget
+## Dashboard, header, and card widgets
+
+You can add widgets to the whole dashboard, to headers, or to individual dashboard cards.
+
+![Filter location](./images/filter-location.png)
+
+- **Dashboard-level widgets** can connect to cards on the entire dashboard, across all tabs.
+- **Header-level widgets** can only be connected to cards on the same tab.
+- **Card-level widgets** can only be connected to their individual cards.
+
+By default, prefer dashboard-level widgets.
+
+If, however, your dashboard grows larger, and it doesn't make sense to break the dashboard up into multiple dashboards, you can add widgets to headings and cards so people can filter in place as they scroll through sections. In these cases, you should scope the effects of a heading widget to the section immediately below.
+
+If you want tab-specific widgets, you could either:
+
+- Use a dashboard widget, but only connect the widget to cards on a specific tab. The dashboard widgets will only be visible when people select the tab.
+- Use a header widget.
+
+These are just rules of thumb to keep the user experience predictable. Do whatever works for your use case.
+
+## Add a filter or parameter to a dashboard
![Add a Filter](./images/add-filter.png)
-1. Click the **pencil icon** to enter dashboard editing mode.
+1. While viewing a dashboard, click the **pencil icon** to enter dashboard editing mode.
2. You can add a filter or parameter widget to:
- **The whole dashboard**. You'll need to connect these dashboard-level filters to individual cards. Metabase will only display dashboard-level widgets if they're connected to a card on the current tab.
@@ -47,25 +68,14 @@ There are two basic types of widgets you can add. The type of filter or paramete
3. Select a [filter type](#filter-and-parameter-widgets).
4. [Connect your filter or parameter widget to one or more dashboard cards](#connecting-a-filter-or-parameter-widget-to-dashboard-cards). Only dashboard-level widgets can be connected to cards on multiple tabs.
-5. [Configure your filter](#editing-a-filter).
+5. [Configure your filter](#configure-dashboard-filters-and-parameters).
6. **Save** your changes.
If the filter isn't connected to any of the cards on the current tab, Metabase won't display the filter.
-### When to add a widget to a heading or card
-
-These are just rules of thumb to keep the user experience predictable. Do whatever works for your use case.
-
-By default, you should add widgets to the dashboard itself.
-
-If, however, your dashboard grows larger, and it doesn't make sense to break the dashboard up into multiple dashboards, you can add widgets to headings and cards so people can filter in place as they scroll through sections. In these cases, you should scope the effects of a heading widget to the section immediately below. Filters on cards should generally only update the card itself.
+## Filter types
-If you want tab-specific widgets, you could either:
-
-- Add them to the dashboard itself, but only connect the widget to cards on a specific tab.
-- Use a heading filter.
-
-## Date picker filters
+### Date picker filters
When picking a Date picker filter, Metabase will prompt you to pick an operator:
@@ -78,34 +88,14 @@ When picking a Date picker filter, Metabase will prompt you to pick an operator:
Single Date and Date Range will provide a calendar widget, while the other options provide slightly different dropdown interfaces for picking values. To get a widget that's just like the date picker in the query builder, choose "All Options".
-### Issues with connecting to a date variable
+#### Issues with connecting to a date variable
-If you get a message like "A date variable in this card can only be connected to a time type with the Single date option," you can handle it in a couple of ways.
+If you get a message like "A date variable in this card can only be connected to a time type with the Single date option," it's probably because you're connecting your filter to a [basic variable](../questions/native-editor/basic-sql-parameters.md) (and not a field filter) in a native query. You can handle this scenario in a couple of ways:
- **If you want a date picker where people can select multiple dates**, you'll need to change the variable in your SQL code to a [field filter](../questions/native-editor/field-filters.md).
- **If you want the filter widget to just take a single date**, you'll need to change the dashboard filter widget's type to "Single date".
-## Time grouping parameter
-
-![Time grouping](./images/time-grouping.png)
-
-You can add a time grouping widget to a dashboard to change how charts are grouped by time. This widget won't filter the data; it'll change how Metabase aggregates the data. For example, you may want to look at the time series charts grouped by month by default, but give people the option to view the same results by other groupings: by week, by quarter, and so on.
-
-This widget doesn't filter data in the charts; the widget just changes the time granularity for any cards that have a datetime field connected to the widget.
-
-Grouping options include:
-
-- Minute (or minute of hour)
-- Hour (or hour of day)
-- Day (or day of week, month, or year)
-- Week (or week of year)
-- Month (or month of year)
-- Quarter (or quarter of year)
-- Year
-
-To connect a time grouping widget to a SQL question, you'll need to insert time grouping parameters in your code. See [time grouping parameters](../questions/native-editor/time-grouping-parameters.md).
-
-## Location filters
+### Location filters
There are four types of Location filters to choose from.
@@ -123,13 +113,13 @@ Additionally, you can select an operator for the location filter:
- **Starts with**. Match values that begin with the entered text.
- **Ends with**. Match values that end with the entered text.
-## ID filter
+### ID filter
The ID filter provides a simple input box where you can type the ID of a user, order, and so on.
You can give people the option to pick one value or multiple values.
-## Number filter
+### Number filter
You can choose from:
@@ -139,7 +129,7 @@ You can choose from:
- Greater than or equal to
- Less than or equal to
-## Text or category filter
+### Text or category filter
A flexible filter type that lets you create either a dropdown menu or an input box to filter on any text or category field in your cards. Options include:
@@ -156,10 +146,30 @@ You can also select how people should filter on this column:
- Search box
- Input box
-## Boolean filter
+### Boolean filter
A boolean filter allows people to filter data based on true/false values.
+## Time grouping parameter
+
+![Time grouping](./images/time-grouping.png)
+
+You can add a time grouping widget to a dashboard to change how charts are grouped by time. This widget won't filter the data; it'll change how Metabase aggregates the data. For example, you may want to look at the time series charts grouped by month by default, but give people the option to view the same results by other groupings: by week, by quarter, and so on.
+
+This widget doesn't filter data in the charts; the widget just changes the time granularity for any cards that have a datetime field connected to the widget.
+
+Grouping options include:
+
+- Minute (or minute of hour)
+- Hour (or hour of day)
+- Day (or day of week, month, or year)
+- Week (or week of year)
+- Month (or month of year)
+- Quarter (or quarter of year)
+- Year
+
+To connect a time grouping widget to a SQL question, you'll need to insert time grouping parameters in your code. See [time grouping parameters](../questions/native-editor/time-grouping-parameters.md).
+
## Connecting a filter or parameter widget to dashboard cards
For each widget that you add, you'll need to tell Metabase which column the filter should update for each card.
@@ -177,13 +187,7 @@ Which cards you can connect a filter or parameter widget to depends on:
For cards built in the query builder, _filters_ can be connected to fields at any stage of the query. _Time grouping parameters_ can only be connected to fields in the last stage of the query, and so to make use of time grouping parameters, your query should have a summary by a datetime field as the last stage. For example, if you have a query that's just computing `Count` of products by `Category` and `Created At`, you'll be able to connect the time grouping parameter to the `Created At` grouping, but if you modify the query to filter for results with `Count > 100`, you won't be able to connect time grouping parameter on a dashboard to that query because the last stage is now a filter.
-## Filtering dashboards with native/SQL questions
-
-To connect a dashboard filter widget to a card with a question created with the native editor, you'll need to [add a field filter or basic variable to your query](../questions/native-editor/sql-parameters.md).
-
-For parameters, check out [Time grouping parameters](../questions/native-editor/time-grouping-parameters.md).
-
-## Auto-connecting filters to cards
+### Auto-connecting filters to cards
If there are other cards that also have the field you select, Metabase will offer to automatically connect the filter to those cards too (including relevant cards on other tabs). If you later add a card with the selected field, Metabase will also try to connect that filter to the new card.
@@ -193,47 +197,78 @@ To undo this auto-connecting of cards, click the notification that pops up when
You can even wire up filters to text cards, but only if [the text card includes a variable](./introduction.md#including-variables-in-text-cards).
-## Requiring a filter or parameter
+## Filtering dashboards with native/SQL questions
-You can tell Metabase to require a filter so that people _must_ filter the dashboard by a certain column on a card. If you require a filter, you'll also need to supply a default value for that filter.
+To connect a dashboard filter widget to a card with a question created with the native editor, you'll need to [add a field filter or basic variable to your query](../questions/native-editor/sql-parameters.md).
-You might want to require a filter value if:
+If your native query uses a basic variable (and not a field filter), you'll only be able to use dashboard filter types that select a single value (so for example, you won't be able to use date range filters).
-- Your unfiltered dashboard contains questions that pull lots of data, as enforcing filtered data can prevent people from inadvertently querying tons of data and running up your data warehouse costs.
-- The questions on your dashboard don't make sense without a filter. For example, if you create a dashboard intended to view data relevant to a specific customer (as opposed to all customers), you can require a customer ID so that the dashboard only loads data for a particular customer.
+For parameters, check out [Time grouping parameters in SQL](../questions/native-editor/time-grouping-parameters.md).
-## Editing a filter
+## Configure dashboard filters and parameters
-To edit a dashboard filter's settings:
+To edit settings for a dashboard filter or parameter:
1. Click the **pencil** icon to enter dashboard editing mode.
-2. Click the filter you want to edit.
+2. Click the widget you want to edit.
+3. A widget editing sidebar will open on the right side
-From this filter editing view, you can wire up dashboard cards to the filter, or use the filter settings sidebar to:
+ From this editing view, you can wire up dashboard cards to the filter, or use the filter settings sidebar to:
-- [Rename filter](#rename-filter)
-- [Set filter input type](#set-filter-input-type)
-- [Set a default filter value](#set-a-default-filter-value)
-- [Remove a filter](#remove-a-filter)
-- [Reorder filters](#reorder-filters)
-- [Make a multi-select filter](#make-a-multi-select-filter)
-- [Change a filter's selectable values](#change-a-filters-selectable-values)
+ - [Rename a dashboard widget](#rename-a-dashboard-widget)
+ - [Change widget type](#change-filter-or-parameter-type)
+ - [Change filter operator](#change-filter-operator)
+ - [Set filter input type](#set-filter-input-type)
+ - [Make a multi-select filter](#make-a-multi-select-filter)
+ - [Change a filter's selectable values](#change-a-filters-selectable-values)
+ - [Set a default filter value](#set-a-default-filter-value)
+ - [Make a filter required](#make-a-filter-or-parameter-required)
+ - [Move a filter](#move-a-filter-or-parameter)
+ - [Remove a filter](#remove-a-filter-or-parameter)
-### Rename filter
+### Rename a dashboard widget
1. In dashboard edit mode, click the filter you want to edit.
-2. Change the label text.
+2. In the filter editing sidebar, change the **Label** text.
Renaming the filter only affects the filter's display; the label has no effect on which columns Metabase filters.
+### Change filter or parameter type
+
+You can change the [type](#filter-types) or an existing filter (for example, from a Date filter to a Text filter). Any incompatible columns connected to the widget will be disconnected.
+
+To change the widget type:
+
+1. When viewing a dashboard, click the **pencil** icon to **Edit the dashboard**.
+2. Click on the filter or parameter you want to edit. A widget editing sidebar should pop up on the right side.
+3. In the sidebar, change the type of filter or parameter. Changing the widget type disconnects the widget from all cards. You'll need to reconnect to the relevant columns on each card for the new type. If you've changed the widget type by mistake and want to restore the widget and its connections to cards, you can exit dashboard edit mode without saving your changes.
+
+### Change filter operator
+
+For some [filter types](#filter-types), you can configure the filter operator - meaning, how Metabase should use the value that a person passed in the filter. For example, for a Number filter, you can configure whether Metabase should filter for values exactly equal to the value passed in the filter, greater than the value, or less than the value.
+
+To change the operator for a dashboard filter:
+
+1. When viewing a dashboard, click the **pencil** icon to **Edit the dashboard**.
+2. Click on the filter you want to edit. A widget editing sidebar should pop up on the right side.
+3. In **Filter operator**, pick the filter operator. The options will depend on the filter type. Some filter types (for example, ID) don't have operator selection.
+
### Set filter input type
+You can set a widget to display options as a dropdown menu, search box, or input box.
+
+[Metadata settings](../data-modeling/metadata-editing.md#filtering) for the filtered column, including [variable settings in native queries](../questions/native-editor/filter-widgets.md#dropdown-menu-and-search), can also affect the filter's appearance.
+
+For example, if the column you're connecting a filter to is configured in the [metadata settings](../data-modeling/metadata-editing.md#filtering) to display a search box instead of a dropdown, that metadata setting will take precedence.
+
+To configure filter input type:
+
1. In dashboard edit mode, click the filter you want to edit.
2. From the filter settings sidebar, set **How should people filter on this column?**:
-- [Dropdown list](#dropdown-list)
-- [Search box](#search-box)
-- [Input box](#plain-input-box)
+ - [Dropdown list](#dropdown-list)
+ - [Search box](#search-box)
+ - [Input box](#plain-input-box)
#### Dropdown list
@@ -256,24 +291,6 @@ An input box that lets people enter plain text (no suggestion list).
Useful for looking up partial matches (such as the ["contains" filter](#text-or-category-filter)) in columns that contain free text, such as comments or descriptions. The input box is the default filter widget for columns with more than 100 unique values.
-### Set a default filter value
-
-1. In dashboard edit mode, click the filter you want to edit.
-2. From the sidebar, choose a value from the **Default value** input field.
-
-For example, you might want to set a default filter value like "Active," so that when people load your dashboard, they only see data for "Active" records (not "Inactive," "Canceled," and so on).
-
-### Remove a filter
-
-1. In dashboard edit mode, click the filter you want to edit.
-2. From the sidebar, click **Remove**.
-
-If you accidentally remove a filter, just click **Cancel** in the top-right to exit dashboard edit mode without saving your changes.
-
-### Reorder filters
-
-In dashboard edit mode, click the grabber handle (six dots) on the left side of a filter widget, then drag the widget to a different position.
-
### Make a multi-select filter
1. In dashboard edit mode, click the filter you want to edit.
@@ -285,15 +302,65 @@ A multi-select filter with the widget type [Dropdown list](#dropdown-list) or [S
1. In dashboard edit mode, click the filter you want to edit.
2. From the sidebar, find **How should users filter on this column?**.
-3. Select "Dropdown list".\*
+3. Select "Dropdown list". If you don't see "Dropdown list" as an option, go to [Filter widgets: Dropdown list](#dropdown-list) for more info.
4. Click **Edit** (to the right of "Dropdown list") to specify where the values should come from:
+
- From connected fields
- From another model or question
- Custom list
-![Selectable values](./images/selectable-values.png)
+ ![Selectable values](./images/selectable-values.png)
+
+### Set a default filter value
+
+You might want to set a default filter value, like "Active," so that when people load your dashboard, they only see data for "Active" records (not "Inactive," "Canceled," and so on).
+
+1. When viewing a dashboard, click the **pencil** icon to **Edit the dashboard**.
+2. Click on the filter you want to make required. A filter sidebar should pop up on the right side.
+3. In the sidebar, scroll down and choose a value from the **Default value** input field.
+
+### Make a filter or parameter required
+
+You can tell Metabase to require a filter so that people _must_ filter the dashboard by a certain column on a card. If you require a filter, you'll also need to supply a default value for that filter.
+
+You might want to require a filter value if:
+
+- Your unfiltered dashboard contains questions that pull lots of data. Enforcing filtered data can prevent people from inadvertently querying tons of data and running up your data warehouse costs.
+- The questions on your dashboard don't make sense without a filter. For example, if you create a dashboard intended to view data relevant to a specific customer (as opposed to all customers), you can require a customer ID so that the dashboard only loads data for a particular customer.
+
+To require a value for a dashboard filter:
+
+1. When viewing a dashboard, click the **pencil** icon to **Edit the dashboard**.
+2. Click on the filter you want to make required. A filter sidebar should pop up on the right side.
+3. In the filter settings sidebar, scroll to the toggle **Always require a value**.
+4. Specify the default value for the filter.
+
+### Move a filter or parameter
+
+Widgets can be displayed and applied on dashboard, header, or card level, see [Dashboard, header, and card widgets](#dashboard-header-and-card-widgets). If you want to change the level of the filter - for example, move a dashboard filter into a card filter, or a header filter into a dashboard filter - you'll need to move it in the filter settings (you can't drag filters to a different level).
+
+To move a filter:
+
+1. In dashboard edit mode, click the filter or parameter you want to edit.
+2. From the sidebar, click **Move filter**.
+3. Select a card or header to move the widget to. Select "Top of the page" to make the widget into a dashboard-wide filter or parameter.
+4. Make sure that the widget is connected to the right columns.
+
+### Remove a filter or parameter
+
+1. In dashboard edit mode, click the filter you want to edit.
+2. From the sidebar, click **Remove**.
+
+If you accidentally remove a filter, just click **Cancel** in the top-right to exit dashboard edit mode without saving your changes.
+
+## Reorder filters
+
+To reorder dashboard-wide filters:
+
+1. While viewing a dashboard, click the **pencil** icon to enter edit mode.
+2. In dashboard edit mode, click the grabber handle (six dots) on the right side of a filter widget, then drag the widget to a different position.
-\* If you don't see "Dropdown list" as an option, go to [Filter widgets: Dropdown list](#dropdown-list) for more info.
+ You can't drag a dashboard level filter to a header or a card. To move a dashboard-level filter to a header or a card, see [Move filter](#move-a-filter-or-parameter).
## Linking filters
diff --git a/docs/dashboards/images/autorefresh.png b/docs/dashboards/images/autorefresh.png
index 94609cbf0dd..40a5ad6623f 100644
Binary files a/docs/dashboards/images/autorefresh.png and b/docs/dashboards/images/autorefresh.png differ
diff --git a/docs/dashboards/images/dashboard-filter-action.png b/docs/dashboards/images/dashboard-filter-action.png
index 3147da6c90c..bd831fc94a1 100644
Binary files a/docs/dashboards/images/dashboard-filter-action.png and b/docs/dashboards/images/dashboard-filter-action.png differ
diff --git a/docs/dashboards/images/dashboard-with-link-cards.png b/docs/dashboards/images/dashboard-with-link-cards.png
index 72068249582..a0bb1ff8f02 100644
Binary files a/docs/dashboards/images/dashboard-with-link-cards.png and b/docs/dashboards/images/dashboard-with-link-cards.png differ
diff --git a/docs/dashboards/images/email-options.png b/docs/dashboards/images/email-options.png
index 3c1075bed27..2aefca2fd11 100644
Binary files a/docs/dashboards/images/email-options.png and b/docs/dashboards/images/email-options.png differ
diff --git a/docs/dashboards/images/email-or-slack.png b/docs/dashboards/images/email-or-slack.png
index 468112f5a18..dc1e43bca21 100644
Binary files a/docs/dashboards/images/email-or-slack.png and b/docs/dashboards/images/email-or-slack.png differ
diff --git a/docs/dashboards/images/filter-location.png b/docs/dashboards/images/filter-location.png
new file mode 100644
index 00000000000..8e4822647d6
Binary files /dev/null and b/docs/dashboards/images/filter-location.png differ
diff --git a/docs/dashboards/images/interactive-dashboard.png b/docs/dashboards/images/interactive-dashboard.png
index 2f0cd35fc88..6c22ec398bf 100644
Binary files a/docs/dashboards/images/interactive-dashboard.png and b/docs/dashboards/images/interactive-dashboard.png differ
diff --git a/docs/dashboards/images/select-subscriptions.png b/docs/dashboards/images/select-subscriptions.png
new file mode 100644
index 00000000000..d2acb40e780
Binary files /dev/null and b/docs/dashboards/images/select-subscriptions.png differ
diff --git a/docs/dashboards/images/share-icon.png b/docs/dashboards/images/share-icon.png
index f1fbc51d199..984a6d72942 100644
Binary files a/docs/dashboards/images/share-icon.png and b/docs/dashboards/images/share-icon.png differ
diff --git a/docs/dashboards/images/text-card-button.png b/docs/dashboards/images/text-card-button.png
index d30572e0418..b0328479c11 100644
Binary files a/docs/dashboards/images/text-card-button.png and b/docs/dashboards/images/text-card-button.png differ
diff --git a/docs/dashboards/introduction.md b/docs/dashboards/introduction.md
index 7d07a55728d..a2db05a6aec 100644
--- a/docs/dashboards/introduction.md
+++ b/docs/dashboards/introduction.md
@@ -23,12 +23,24 @@ You can add [filter widgets to dashboards](./filters.md) that filter data identi
You can make as many dashboards as you want. Go nuts.
+## Example dashboard
+
+Every new Metabase comes with an example dashboard, **E-commerce insights**, in the **Examples** collection (though your admin can turn off or delete the examples). The example dashboard is yours to explore and play with.
+
## How to create a dashboard
-In the top right of the screen, click the **+ New** > **Dashboard**. Give your new dashboard a name and a description, choose which [collections](../exploration-and-organization/collections.md) the dashboard should go in, then click **Create**, and Metabase will take you to your shiny new dashboard.
+{% include youtube.html id='W-i9E5_Wjmw' %}
+
+1. In the top right of the screen, click the **+ New** > **Dashboard**.
+2. Give your new dashboard a name and a description.
+3. Choose which [collections](../exploration-and-organization/collections.md) the dashboard should go in.
+4. Click **Create**, and Metabase will take you to your shiny new dashboard.
+5. Next, you'll need to add some questions (charts) to the dashboard, see [Adding or saving questions to the dashboard](#adding-or-saving-questions-to-a-dashboard).
## Adding or saving questions to a dashboard
+To get some charts on a dashboard, you'll need to [create questions](../questions/introduction.md) (Metabase word for chart or query) and then add them, to the dashboard.
+
You can add questions that are saved to collections, or save questions directly to a dashboard.
### From a dashboard
@@ -98,11 +110,15 @@ To see how to wire up a filter to a card, see [dashboard filters](./filters.md).
## Link cards
+Link cards are specialized cards that let you search and link to other items in your Metabase. You can also use them for external links. Useful for pointing people to other resources relevant to your dashboard.
+
![Dashboards with link cards](./images/dashboard-with-link-cards.png)
-Link cards are specialized cards that let you search and link to other items in your Metabase. You can also use them for external links. Useful for pointing people to other resources relevant to your dashboard.
+To add a link card to a dashboard:
-To add a link card to a dashboard, click the **pencil** icon to enter dashboard editing mode, then click on the **link** icon. Click on the input field in the link card to search your Metabase for an item to link to, or paste an external link.
+1. When viewing a dashboard, click the **pencil** icon to enter dashboard editing mode;
+2. Click the **link** (paper clip) icon to add a link card.
+3. On the link card, click the input field to search your Metabase for an item to link to, or paste an external link.
Link cards support variables so you can use dashboard filters to update values in the link card's URL. For example, you could include a variable in a URL using double braces, like so:
@@ -313,16 +329,15 @@ Public links can be viewed by anyone, even if they don't have access to Metabase
## Exporting results from a dashboard
-See [Exporting results](../questions/exporting-results.md).
+You can export the entire dashboard as PDF, or export results of individual questions on the dashboard. See [Exporting results](../questions/exporting-results.md).
## Configuring a dashboard through its URL
-You can amend the URL of a dashboard to automatically enter fullscreen, enable night mode, or auto-refresh the dashboard. Customizing the dashboard's URL allows you to configure the dashboard - even when you do not have any input access to the device where the dashboard will be displayed, like scripted screens, for example.
+You can amend the URL of a dashboard to automatically enter fullscreen or auto-refresh the dashboard. Customizing the dashboard's URL allows you to configure the dashboard - even when you do not have any input access to the device where the dashboard will be displayed, like scripted screens, for example.
To configure a dashboard using its URL, you can add the following optional keywords:
- `fullscreen`
-- `night`
- `refresh`
Here's an example URL:
@@ -331,7 +346,7 @@ Here's an example URL:
https://metabase.mydomain.com/dash/2#refresh=60&fullscreen&night
```
-The part that says `refresh=60` sets the dashboard to automatically refresh every 60 seconds, `fullscreen` sets it to fullscreen mode, and `night` sets it to night mode (night mode only works when using fullscreen). Use an ampersand, `&`, in between keywords, and make sure there's a hash, `#`, after the dashboard's ID number.
+The part that says `refresh=60` sets the dashboard to automatically refresh every 60 seconds, `fullscreen` sets it to fullscreen mode. Use an ampersand, `&`, in between keywords, and make sure there's a hash, `#`, after the dashboard's ID number.
There is one important limitation with the `fullscreen` option: for security reasons, many browsers require user interaction to initiate fullscreen. In those browsers, using the `fullscreen` option will enable the fullscreen UI in Metabase, but it won't expand the browser content to fill the screen. To ensure the dashboard occupies the entire screen, either activate fullscreen by clicking the button in the UI, or use the `fullscreen` URL option and launch the browser in fullscreen or kiosk mode.
diff --git a/docs/dashboards/subscriptions.md b/docs/dashboards/subscriptions.md
index ae84789e13c..a04dd1d638e 100644
--- a/docs/dashboards/subscriptions.md
+++ b/docs/dashboards/subscriptions.md
@@ -1,8 +1,8 @@
---
title: Dashboard subscriptions
redirect_from:
-- /docs/latest/users-guide/dashboard-subscriptions
-- /docs/latest/enterprise-guide/dashboards-subscriptions
+ - /docs/latest/users-guide/dashboard-subscriptions
+ - /docs/latest/enterprise-guide/dashboards-subscriptions
---
# Dashboard subscriptions
@@ -15,52 +15,71 @@ If your Metabase has email or Slack set up, all you need to do is create a dashb
To enable dashboard subscriptions, your administrators will need to have set up email or Slack for your Metabase. See [Setting up email](../configuring-metabase/email.md) or [Setting up Slack](../configuring-metabase/slack.md).
-## Setting up a dashboard subscription
+## Set up a dashboard subscription
-To set up a subscription to a dashboard, click on the **Sharing** icon and select **Subscriptions**. Metabase will slide out a sidebar on the right, with an option to set up a subscription via email or Slack:
+To set up a subscription to a dashboard,
-![Set up a dashboard subscription with email or slack](./images/email-or-slack.png)
+1. Click on the **three dots** icon Select **Subscriptions**.
-Let's say we want to email a dashboard. We'll click on the **Email it** option in the sidebar, and Metabase will give us some options:
+ ![Select subscriptions from menu](./images/select-subscriptions.png)
-![Dashboard subscription email options](./images/email-options.png)
+2. Metabase will slide out a sidebar on the right, with an option to set up a subscription via email or Slack.
-## Email subscription options
+3. Configure [subscription recipients](#subscription-recipients) and [frequency](#frequency-and-timing). Optionally, you can configure filter and attachment settings.
-For emails, we can:
+ ![Dashboard subscription email options](./images/email-options.png)
-### Add subscribers
+### Subscription recipients
-Add email addresses to register subscribers. On Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise), admins can limit email recipients to [approved domains for notifications](../configuring-metabase/email.md#approved-domains-for-notifications) and [configure which recipients Metabase suggests](../configuring-metabase/email.md#suggest-recipients-on-dashboard-subscriptions-and-alerts).
+#### Email
-### Determine frequency and timing
+You can sent email subscriptions both to people who have Metabase accounts (by typing their names) and to people outside Metabase (by typing their email).
-Tell Metabase how often it should send the dashboard:
+On Metabase [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise), admins can limit email recipients to [approved domains for notifications](../configuring-metabase/email.md#approved-domains-for-notifications) and [configure which recipients Metabase suggests](../configuring-metabase/email.md#suggest-recipients-on-dashboard-subscriptions-and-alerts).
+
+#### Slack
+
+For Slack subscriptions, you can set up a subscription for a channel (like #general), or for a single person via their Slack username (not their display name).
+
+You can also send subscriptions to private channels, but that requires additional configuration, see [Sending alerts and subscriptions to private Slack channels](../configuring-metabase/slack.md#sending-alerts-and-subscriptions-to-private-slack-channels).
+
+
+If you rename the subscribed channel in Slack, you'll need to update the subscription to point to the new Slack channel name.
+
+### Frequency and timing
+
+You can tell Metabase how often it should send the dashboard:
- Hourly
- Daily
- Weekly
- Monthly
-And what time of day to send the dashboard.
-
-### Send email now
+You'll need to specify what time of day to send the dashboard, and, for weekly and monthly subscription, the day when to send the subscription.
-A button that sends an email to all subscribers each time you touch it.
+### Test subscription
-### Don't send if there aren't results
+You can click **Send email/Slack now** in subscription settings to send a test email or Slack message (without waiting for regular schedule). This will send a subscriptions immediately to all subscribers or Slack channels.
-If there are no results, you can tell Metabase to skip sending the email.
+We recommend first creating a subscription with a test email/channel, then using **Send email/Slack now** to test it, and once you are satisfied with the subscription, replacing the test email/channel with real recipients and saving the subscription.
### Set filter values for when this gets sent
{% include plans-blockquote.html feature="Dashboard subscription filter customization" %}
-Here you can set filters to apply when Metabase sends the subscription.
+You can set filters to apply when Metabase sends the subscription to send "views" of the dashboard to different people. See [Customize filter values for each dashboard subscription](#customize-filter-values-for-each-dashboard-subscription).
+
+### Don't send if there aren't results
+
+If the questions on the dashboard return no results, you can tell Metabase to skip sending the email.
+
+This is helpful for dashboards that are displaying time-limited results (for example, "Survey responses over the last week"), or dashboards that display rare events (like "Latest outage analysis").
+
+## Email attachments
-## Attach results
+When configuring an email subscription, you can tell Metabase if it should attach results to the email as a file, in addition to displaying the table in the email body.
-When configuring a subscription, you can tell Metabase if it should attach results to the email as a file, in addition to displaying the table in the email body.
+Currently, you can only send attachments with question results. You can't sent the whole dashboard as a PDF attachment.
If you've added filters to your dashboard and set default values for those filters, Metabase will apply those default values to your subscriptions, filtering the results of all questions that are connected to those filters when the subscriptions are sent. To learn more, check out [dashboard filters](./filters.md).
@@ -85,22 +104,6 @@ The attached files will include up to 1 048 575 rows by default (Excel's row lim
You can toggle on "Send only attachments (no charts)" if you want to receive just the .csv or .xlsx files without the charts. Remember to select the results you want to attach in "Questions to attach" above the toggle.
-## Slack subscription options
-
-For Slack subscriptions, you can set up a subscription for a channel (like #general), or for a single person via their Slack username.
-
-> Note that Slack username can be different from Slack display name.
-
-![slack subscription options](./images/slack-subscription-options.png)
-
-> If you rename the subscribed channel in Slack, you'll need to update the subscription to point to the new Slack channel name.
-
-You can specify how often Metabase sends a Slack message (hourly, daily, weekly, or monthly), and whether to send a message if the dashboard fails to return results.
-
-### Sending subscriptions to private channels
-
-See [Sending alerts and subscriptions to private Slack channels](../configuring-metabase/slack.md#sending-alerts-and-subscriptions-to-private-slack-channels).
-
## Adding multiple subscriptions
You can add multiple subscriptions to a single dashboard. To add a subscription, click on the **+** icon in the dashboard subscription panel.
@@ -119,7 +122,7 @@ You can view a list of all alerts and dashboard subscriptions that people have s
{% include plans-blockquote.html feature="Dashboard subscription filter customization" %}
-You can customize which filter values to apply to each dashboard subscription. That way you can send different groups of people an email (or Slack message) the contents of the dashboard with different filters applied. You only need to maintain one dashboard, which you can use to send results relevant to each subscriber.
+You can customize which filter values to apply to each dashboard subscription. That way you can send an email (or Slack message) with the dashboard results to different groups of people, with different dashboard filters applied for each group. You only need to maintain one dashboard, which you can use to send results relevant to each subscriber. For example, send a dashboard filtered for "Marketing" department and "This week" date weekly to a marketing lead, and send the dashboard filtered for all departments and "This quarter" to the CEO.
### Setting filter values
diff --git a/docs/data-modeling/editable-tables.md b/docs/data-modeling/editable-tables.md
index ca8094175b4..b7608ef6f4c 100644
--- a/docs/data-modeling/editable-tables.md
+++ b/docs/data-modeling/editable-tables.md
@@ -5,11 +5,11 @@ summary: Admins can create, update, and delete data in tables right in Metabase.
# Editable tables
-{% include plans-blockquote.html feature="Editable table data" %}
+{% include plans-blockquote.html feature="Editable tables" %}
-Admins can enable editable table data in Metabase.
+Admins can enable editable tables in Metabase, which will allow admins to edit data in tables directly from Metabase.
-![Edit table](./images/edit-table.png)
+![Add option](./images/add-option.png)
## Databases that support editable tables
@@ -20,6 +20,7 @@ Currently, editable tables are available for the following databases:
## Setting up editable tables
+_Admin > Databases > Editable tables_
To set up table editing, admins can:
@@ -33,11 +34,16 @@ For this to work, Metabase's connection to your database must support writing ba
## Update or delete records in a table
+_Browse Databases > Edit table_
+
To update or delete records in a table:
1. Open the left sidebar.
2. In the Data section, click **Databases**.
3. Hover over the table you want to edit and click the **Pencil** icon.
+
+ ![Edit table](./images/edit-table.png)
+
4. Edit rows in the table just like you would in a spreadsheet.
Depending on the data in the column, Metabase may show a list of values to choose from. If you need to add an option to that list, simply type out the option and add it (you may need to refresh the browser for the new option to show up in the list).
@@ -69,7 +75,7 @@ If you try to delete a row that has foreign key references from other tables, yo
Metabase offers two ways to modify data in your database: **editable table data** and [actions](../actions/introduction.md).
-### When to use editable table data
+### When to use editable tables
Use editable table data to:
diff --git a/docs/data-modeling/json-unfolding.md b/docs/data-modeling/json-unfolding.md
index a4bc4f05166..8d29ef265d7 100644
--- a/docs/data-modeling/json-unfolding.md
+++ b/docs/data-modeling/json-unfolding.md
@@ -5,10 +5,6 @@ summary: Learn how to unfold JSON columns into separate fields that you can filt
# Working with JSON
-## Filtering JSON
-
-In the [query builder](../questions/query-builder/editor.md), Metabase can't parse JSON in columns, so you can only filter by "Is empty" or "Not empty".
-
## JSON unfolding
With [some databases](#databases-that-support-json-unfolding), Metabase can unfold JSON columns into their component fields, which you can then filter on using the query builder.
@@ -29,8 +25,21 @@ This unfolding allows you to filter for values found in the original JSON object
Metabase will prefix the unfolded column names with the name of the original column that contained the JSON. You can change the column names in **Admin** > [Table metadata](metadata-editing.md), or by creating a [model](./models.md) and editing the column metadata.
+## Databases that support JSON unfolding
+
+- [BigQuery](../databases/connections/postgresql.md): automatically enabled, applies to `STRUCT` types only.
+
+ If your data is stored in the [STRUCT data type](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#struct_type) in BigQuery, you can query the table's nested fields. This is enabled by default. However, Metabase won't unfold JSON stored in BigQuery as the `JSON` type. This is because in BigQuery, nested fields are _part of the table definition itself_, so when Metabase syncs with your BigQuery database, it'll be able to get metadata about any of your tables, including tables with nested fields. Querying nested fields, however, doesn't extend to arrays (REPEATED (STRUCT)) in BigQuery.
+
+- [Druid (JDBC)](../databases/connections/druid.md)
+- [MongoDB](../databases/connections/mysql.md): automatically enabled for all nested fields.
+- [MySQL](../databases/connections/mysql.md)
+- [PostgreSQL](../databases/connections/postgresql.md)
+
## Toggling JSON unfolding for a database
+_Admin > Databases > Advanced options > Allow unfolding of JSON column_
+
If you notice a hit to performance from this JSON unfolding, we recommend turning it off.
To turn off JSON unfolding for a database:
@@ -47,6 +56,8 @@ To turn off JSON unfolding for a database:
## Toggling JSON unfolding for a specific column
+_Admin > Table metadata > Unfold JSON_
+
If performance degrades, or you'd rather keep the JSON contained in the original column, you can turn off unfolding for individual fields in their settings.
1. Click the **grid** icon in the upper right.
@@ -64,14 +75,6 @@ If performance degrades, or you'd rather keep the JSON contained in the original
For example, if you upload a CSV with JSON in it, you might need to update the data/type in the database. Note that you can't edit the data type via Metabase; you can only change its field type. So even if the field type in Metabase is `Field containing JSON`, if the data/type isn't `JSON`, Metabase won't give you the option to unfold the column. You'll need to change the column type in the database itself.
-## Databases that support JSON unfolding
-
-- [BigQuery](../databases/connections/postgresql.md): automatically enabled, applies to `STRUCT` types only.
-
- If your data is stored in the [STRUCT data type](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#struct_type) in BigQuery, you can query the table's nested fields. This is enabled by default. However, Metabase won't unfold JSON stored in BigQuery as the `JSON` type. This is because in BigQuery, nested fields are _part of the table definition itself_, so when Metabase syncs with your BigQuery database, it'll be able to get metadata about any of your tables, including tables with nested fields. Querying nested fields, however, doesn't extend to arrays (REPEATED (STRUCT)) in BigQuery.
-
-- [Druid (JDBC)](../databases/connections/druid.md)
-- [MongoDB](../databases/connections/mysql.md): automatically enabled for all nested fields.
-- [MySQL](../databases/connections/mysql.md)
-- [PostgreSQL](../databases/connections/postgresql.md)
+## Filtering JSON
+In the [query builder](../questions/query-builder/editor.md), Metabase can't parse JSON in columns, so you can only filter by "Is empty" or "Not empty".
diff --git a/docs/data-modeling/metadata-editing.md b/docs/data-modeling/metadata-editing.md
index a396ed34dd6..ee861e828b2 100644
--- a/docs/data-modeling/metadata-editing.md
+++ b/docs/data-modeling/metadata-editing.md
@@ -1,17 +1,19 @@
---
-title: "Table metadata admin settings"
+title: "Table metadata editing"
redirect_from:
- /docs/latest/administration-guide/03-metadata-editing
---
-# Table metadata admin settings
+# Table metadata editing
-_Admin > Table metadata_
+> Prefer using [Data Studio > Data structure](../data-studio/data-structure.md) for metadata editing. The page _Admin > Table Metadata_ will be removed in future versions of Metabase.
-![Table metadata settings](./images/table-metadata-settings.png)
+_Admin > Table metadata_
Metabase lets you add and edit metadata for your tables and columns.
+![Table metadata settings](./images/table-metadata-settings.png)
+
The **Table metadata settings only affect the way Metabase displays the data. None of the settings change the data in your database.**
Admins can grant access to these metadata settings to other groups. See [table metadata permissions](../permissions/data.md#manage-table-metadata-permissions).
diff --git a/docs/data-modeling/metrics.md b/docs/data-modeling/metrics.md
index f0aefbba52a..4ef4bb009ee 100644
--- a/docs/data-modeling/metrics.md
+++ b/docs/data-modeling/metrics.md
@@ -13,17 +13,7 @@ Metrics are like pre-defined calculations: create your aggregations once, save t
For example, you may want to create a metric that calculates revenue, so people can refer to revenue in their own questions. That way you standardize how revenue is calculated (so you don't end up with five different calculations for the revenue).
-## Using metrics
-
-You can:
-
-- Save metrics to [collections](../exploration-and-organization/collections.md).
-- Add metrics to [dashboards](../dashboards/introduction.md).
-- View metrics in the [database browser](../exploration-and-organization/exploration.md#browse-your-databases).
-- Pick metrics as aggregation columns in the Summarize block when creating questions, modify them or combine.
-- [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans include the ability to [mark metrics as verified](../exploration-and-organization/content-verification.md).
-
-### Metrics in the query builder
+## Metrics in the query builder
When asking questions in the query builder, you can find metrics that your team created in the summarization section under **Common metrics**. You can pick multiple metrics and they will be calculated independently and joined automatically along the chosen dimensions.
@@ -35,6 +25,16 @@ You can also pick a metric as a data source when creating a new question. If the
You can use custom expressions to combine multiple metrics, or perform calculations on top of metrics.
+## Using metrics
+
+You can:
+
+- When creating questions in the query builder, you can pick metrics as aggregation columns in the Summarize block. You can modify metrics, or combine them.
+- Save metrics to [collections](../exploration-and-organization/collections.md), including the [Library](../data-studio/library.md).
+- Add metrics to [dashboards](../dashboards/introduction.md).
+- View metrics in the [database browser](../exploration-and-organization/exploration.md#browse-your-databases).
+- [Pro](https://www.metabase.com/product/pro) and [Enterprise](https://www.metabase.com/product/enterprise) plans include the ability to [mark metrics as verified](../exploration-and-organization/content-verification.md).
+
## Creating a metric
To create a metric, bring up the command palette with cmd/ctrl + k. That’s cmd + k for Macs, or ctrl + k for Windows PCs. Search for New metric.
@@ -86,9 +86,13 @@ By "editing" a metric, we mean [editing the metric's query definition](#editing-
These collection permissions also interact with the group's [data permissions](../permissions/data.md), which define whether the group can view or query the metric's source data.
+## Metrics in the Library
+
+By adding metrics to your Library, the query builder will display the metrics more prominently in menus. See [Library metrics](../data-studio/library.md#metrics)
+
## Verifying a metric
-See [content verification](../exploration-and-organization/content-verification.md).
+See [content verification](../exploration-and-organization/content-verification.md). Prefer using [Library metrics](../data-studio/library.md#metrics) instead of content verification.
## Further reading
diff --git a/docs/data-modeling/model-persistence.md b/docs/data-modeling/model-persistence.md
index 23b22730ee7..0a7878d855e 100644
--- a/docs/data-modeling/model-persistence.md
+++ b/docs/data-modeling/model-persistence.md
@@ -28,7 +28,7 @@ To persist models for faster loading, you'll need to turn on model persistence f
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)
+3. [individual models](#turn-on-model-persistence-for-individual-models)
### Turn on model persistence for your Metabase
@@ -36,7 +36,7 @@ To turn on model persistence for your Metabase, go to **Admin** > **Performance*
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/)).
+The cron scheduler uses the [default instance report Timezone](../configuring-metabase/localization.md#set-default-instance-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.
@@ -54,6 +54,8 @@ Once you've turned on model persistence for your Metabase, you'll need to set it
4. Ensure that the credentials Metabase uses to connect to your data warehouse can manage and write to that schema.
+By default, new models on the database will _not_ b persisted. You need to [Turn on model persistence for individual models](#turn-on-model-persistence-for-individual-models).
+
## Turn on model persistence for individual models
{% include plans-blockquote.html feature="Individual model persistence" %}
diff --git a/docs/data-modeling/models.md b/docs/data-modeling/models.md
index 87e1ab9fa51..495b6401109 100644
--- a/docs/data-modeling/models.md
+++ b/docs/data-modeling/models.md
@@ -6,7 +6,9 @@ redirect_from:
# Models
-Models are a fundamental building block in Metabase. Models curate data from another table or tables from the same database to anticipate the kinds of questions people will ask of the data. You can think of them as derived tables, or a special kind of saved question meant to be used as the starting point for new questions. You can base a model on a SQL or query builder question, which means you can include custom, calculated columns in your model.
+> Prefer [Transforms](../data-studio/transforms/transforms-overview.md) instead of models. Models remain supported for now, but will be deprecated in future versions of Metabase.
+
+Models curate data from another table or tables from the same database to anticipate the kinds of questions people will ask of the data. You can think of them as derived tables, or a special kind of saved question meant to be used as the starting point for new questions. You can base a model on a SQL or query builder question, which means you can include custom, calculated columns in your model.
Models:
diff --git a/docs/data-modeling/segments.md b/docs/data-modeling/segments.md
index d728eabfad3..0b405443f31 100644
--- a/docs/data-modeling/segments.md
+++ b/docs/data-modeling/segments.md
@@ -4,6 +4,8 @@ title: "Segments"
# Segments
+> Prefer [Data Studio](../data-studio/data-structure.md#segments) for managing segments.
+
Metabase allows admins to create segments so people can quickly and easily reference them in the query builder.
To manage segments:
diff --git a/docs/databases/connecting.md b/docs/databases/connecting.md
index b1c86bec419..71def5e8844 100644
--- a/docs/databases/connecting.md
+++ b/docs/databases/connecting.md
@@ -14,11 +14,14 @@ Connect Metabase to your data sources.
## Adding a database connection
-To add a database connection, click the **grid** icon in the top right, and navigate to **Admin** > **Databases** > **Add a database**.
+To add a database connection:
-Fill out the fields for that database, and click **Save changes** at the bottom.
+1. Click the **grid** icon in the top right.
+2. Select **Admin**.
+3. In Admin settings, navigate **Databases** > **Add a database**.
+4. Fill out the fields for that database, and click **Save changes** at the bottom.
-The connection settings differ database to database. For the list of connection settings available for your database, click on the link to your database below.
+ The connection settings differ database to database. For the list of connection settings available for your database, click the link to your database below.
## Connecting to supported databases
diff --git a/docs/exploration-and-organization/collections.md b/docs/exploration-and-organization/collections.md
index 0b1e354fed4..21a0ba19781 100644
--- a/docs/exploration-and-organization/collections.md
+++ b/docs/exploration-and-organization/collections.md
@@ -38,6 +38,16 @@ Pairing Official badges with [verified items](./content-verification.md) can hel
To add an Official badge to a collection, an admin can visit the collection and click on the three-dot menu (**...**) and select **Make collection official**. Admins can also remove an Official badge in the same menu. Admins can also mark a collection as Official or not when they first create the collection.
+### Library
+
+{% include plans-blockquote.html feature="Library" %}
+
+![Library](./images/library.png)
+
+The Library is a special collection that helps you create a source of truth for analytics by providing a centrally managed set of curated content. Use the Library to separate authoritative, reusable components from ad-hoc analyses.
+
+See [Library](../data-studio/library.md).
+
## Collection permissions
[Administrators can give you different kinds of access](../permissions/collections.md) to each collection:
diff --git a/docs/exploration-and-organization/content-verification.md b/docs/exploration-and-organization/content-verification.md
index fa62c6e6191..e2de410e8d8 100644
--- a/docs/exploration-and-organization/content-verification.md
+++ b/docs/exploration-and-organization/content-verification.md
@@ -52,3 +52,4 @@ Dashboard verification status has no affect on its questions. Questions must be
## Further reading
- [Official collections](./collections.md#official-collections)
+- [Library](../data-studio/library.md)
diff --git a/docs/exploration-and-organization/data-model-reference.md b/docs/exploration-and-organization/data-model-reference.md
index 06399e43a21..63d99e4a3f0 100644
--- a/docs/exploration-and-organization/data-model-reference.md
+++ b/docs/exploration-and-organization/data-model-reference.md
@@ -26,9 +26,11 @@ You can open the data reference from:
You can also visit `https://[your metabase here]/reference`.
+Admins and [Data Analysts](../people-and-groups/managing.md#data-analysts) can get a more comfortable view of data reference in [Data Studio](../data-studio/overview.md).
+
## Databases
-The data reference is a collection of pages organized by database, then schemas in that database (if you have several schemas), and finally tables in that database - the same structure you use to [pick data](../questions/query-builder/editor.md#picking-data). The data reference section is a great place to find information about the [data types](https://www.metabase.com/learn/grow-your-data-skills/data-fundamentals/data-types-overview) of columns in your data.
+The data reference is a collection of pages organized by database, then schemas in that database (if you have several schemas), and finally tables in that database - the same structure you use to [pick data](../questions/query-builder/editor.md#pick-data). The data reference section is a great place to find information about the [data types](https://www.metabase.com/learn/grow-your-data-skills/data-fundamentals/data-types-overview) of columns in your data.
### Database details
diff --git a/docs/exploration-and-organization/delete-and-restore.md b/docs/exploration-and-organization/delete-and-restore.md
index e41bfce601d..f71d383d7ca 100644
--- a/docs/exploration-and-organization/delete-and-restore.md
+++ b/docs/exploration-and-organization/delete-and-restore.md
@@ -128,11 +128,15 @@ You won't see archived Events and Timelines in Trash. To see archived events and
## Deleting and restoring snippets
-Snippets can be archived and unarchived. See [Archiving snippets](../questions/native-editor/snippets.md#archive-snippets). You won't see archived snippets in Trash.
+Snippets can be archived and unarchived. See [Archiving snippets](../questions/native-editor/snippets.md#archive-snippets). You won't see archived snippets in Trash. Snippets can't be permanently deleted.
## Deleting segments
-Segments can be retired. See [Retiring Segments](../data-modeling/segments.md#editing-and-retiring-segments). You won't see retired Segments in Trash.
+Segments can be retired. See [Retiring Segments](../data-modeling/segments.md#editing-and-retiring-segments). Retiring segments is permanent.
+
+## Deleting measures
+
+See [Delete measures](../data-studio/data-structure.md#delete-a-measure). Deleting measures is permanent.
## Deleting subscriptions and alerts
diff --git a/docs/exploration-and-organization/events-and-timelines.md b/docs/exploration-and-organization/events-and-timelines.md
index 41fba9b1250..98002dd62d3 100644
--- a/docs/exploration-and-organization/events-and-timelines.md
+++ b/docs/exploration-and-organization/events-and-timelines.md
@@ -47,6 +47,8 @@ You'll see an icon along the x-axis that plots the event. A vertical line will e
![An event on a chart](./images/example-event.png)
+You can't add a timeline with events to the [Library](../data-studio/library.md).
+
## Adding events when viewing a question
If your question is a time series, you can click on the **Calendar** in the bottom right of the question, and Metabase will open the timeline sidebar. Metabase will list any timelines and their events that fall in the range of your time series. You can:
diff --git a/docs/exploration-and-organization/history.md b/docs/exploration-and-organization/history.md
index 244d185d0f0..5a4ee73eb43 100644
--- a/docs/exploration-and-organization/history.md
+++ b/docs/exploration-and-organization/history.md
@@ -4,20 +4,46 @@ title: History
# History
-For questions, dashboards, and models, Metabase keeps a version history for the previous fifteen versions of that item. You can view changes, and revert to previous versions.
+Metabase keeps a version history for the previous fifteen versions for an entity. You can view changes, and revert to previous versions.
-## Viewing tracked changes
+On Metabase Pro and Enterprise plans, you can also version control most entities in Metabase, see [Remote Sync](../installation-and-operation/remote-sync.md).
-1. Go to your question, dashboard, or model.
+## History for questions, dashboards, metrics, and models
+
+### Viewing tracked changes
+
+1. Go to your question, dashboard, metric, or model.
2. Click the info icon.
3. Click on the **History** tab.
4. The History tab will display the item's history of up to 15 versions.
Metabase will keep track of a version each time you save, move, revert, [move to Trash](./delete-and-restore.md), or [verify](./content-verification.md) an item.
-## Reverting to previous versions
+### Reverting to previous versions
1. Go to your question, dashboard, or model.
2. Click the info icon (an **i** in a circle).
3. A sidebar will appear with up to fifteen previous versions.
4. Click on the **back arrow** beside a version to revert your item to that point in time.
+
+## History for transforms
+
+### Viewing tracked changes
+
+1. Go to your transform in [Data studio](../data-studio/transforms/transforms-overview.md).
+2. Click the **three dots** icon and select **History**
+3. The History tab will display the item's history of up to 15 versions.
+
+Any change to the transform's query or script will be recorded as "changed source".
+
+### Reverting to previous versions
+
+1. Go to your transform in [Data studio > Transforms](../data-studio/transforms/transforms-overview.md).
+2. Click the **three dots** icon and select **History**.
+3. Click the **back arrow** beside a version to revert your item to that point in time.
+
+## History for segments and measures
+
+1. Go to the table source for the segment or metrics in [Data studio > Data Structure](../data-studio/data-structure.md).
+2. Pick the segment or measure in the right sidebar.
+3. On the segment or measure's page, go to **Revision history** tab.
diff --git a/docs/exploration-and-organization/images/library.png b/docs/exploration-and-organization/images/library.png
new file mode 100644
index 00000000000..03e57728f3c
Binary files /dev/null and b/docs/exploration-and-organization/images/library.png differ
diff --git a/docs/exploration-and-organization/uploads.md b/docs/exploration-and-organization/uploads.md
index 2024c8c48c1..d89fe8332ed 100644
--- a/docs/exploration-and-organization/uploads.md
+++ b/docs/exploration-and-organization/uploads.md
@@ -6,7 +6,7 @@ title: Uploading data
If an admin has [set up uploads](../databases/uploads.md), you can upload CSV data by clicking on the **Upload** icon in the top right of the collection page.
-![Upload CSV data](../databases/images/upload-icon.png).
+![Upload CSV data](../databases/images/upload-icon.png)
## Create, append, or replace models with uploads
diff --git a/docs/installation-and-operation/serialization.md b/docs/installation-and-operation/serialization.md
index 41979e08a0f..ab3f5c36036 100644
--- a/docs/installation-and-operation/serialization.md
+++ b/docs/installation-and-operation/serialization.md
@@ -58,6 +58,7 @@ Metabase will only export the following entities:
- Snippets
- Data model and table metadata
- Segments
+- Measures
- Public sharing settings for questions and dashboards
- [General Metabase settings](#general-metabase-settings-that-are-exported)
- Events and timelines
@@ -632,14 +633,14 @@ tar -xvf metabase_data.tgz
1. Send a `curl` request to export data:
- ```sh
- curl \
- -H 'x-api-key: YOUR_API_KEY' \
- -X POST 'https://your-metabase-url/api/ee/serialization/export' \
- -o metabase_data.tgz
- ```
+ ```sh
+ curl \
+ -H 'x-api-key: YOUR_API_KEY' \
+ -X POST 'https://your-metabase-url/api/ee/serialization/export' \
+ -o metabase_data.tgz
+ ```
- substituting `YOUR_API_KEY` with your API key and `your-metabase-url` with the URL of your Metabase instance.
+ substituting `YOUR_API_KEY` with your API key and `your-metabase-url` with the URL of your Metabase instance.
> We use `POST`, not `GET`, for the `/export` endpoint.
@@ -675,10 +676,10 @@ tar -xvf metabase_data.tgz
-o -
```
- substituting `YOUR_API_KEY` with your API key and `your-metabase-url` with your Metabase instance URL.
- The `-o -` option will output logs in the terminal.
+ substituting `YOUR_API_KEY` with your API key and `your-metabase-url` with your Metabase instance URL.
+ The `-o -` option will output logs in the terminal.
- > If you import Metabase data into the same Metabase as you exported it from, you will overwrite your existing questions, dashboards, etc. See [How import works](#how-import-works).
+ > If you import Metabase data into the same Metabase as you exported it from, you will overwrite your existing questions, dashboards, etc. See [How import works](#how-import-works).
## Other uses of serialization
diff --git a/docs/people-and-groups/images/user-provisioning.png b/docs/people-and-groups/images/user-provisioning.png
index 7b32e3fb262..32a2795bb8a 100644
Binary files a/docs/people-and-groups/images/user-provisioning.png and b/docs/people-and-groups/images/user-provisioning.png differ
diff --git a/docs/people-and-groups/user-provisioning.md b/docs/people-and-groups/user-provisioning.md
index 19f92efd435..0f33e31be5c 100644
--- a/docs/people-and-groups/user-provisioning.md
+++ b/docs/people-and-groups/user-provisioning.md
@@ -13,17 +13,18 @@ Metabase supports user provisioning via the System for Cross-domain Identity Man
> For now, Metabase officially supports SCIM for [Okta](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm?cshid=ext_Apps_App_Integration_Wizard-scim) and [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal). Other SCIM providers may work, but we haven't tested them. If you're having issues with another identity provider, please [reach out to us](https://www.metabase.com/help-premium).
-## Setting up user provisioning
+## Set up user provisioning via SCIM
![Setting up user provisioning with SCIM in Metabase](./images/user-provisioning.png)
-To set up user provisioning. Click the **grid** icon in the upper right and navigate to **Admin** > **Settings**> **Authentication**.
+To set up user provisioning:
-Click on the **User provisioning** tab.
+1. Click the **grid** icon in the upper right and navigate to **Admin** > **Settings**> **Authentication**.
-## User provisioning via SCIM
+2. Click the **User provisioning** tab.
+3. Toggle on user provisioning.
-To set up user provisioning with SCIM, hit the toggle to enable it. Metabase will tell you the SCIM endpoint URL and SCIM token to share with your identity provider.
+Metabase will tell you the SCIM endpoint URL and SCIM token to share with your identity provider.
> SAML user provisioning is always disabled when SCIM is enabled.
diff --git a/docs/permissions/collections.md b/docs/permissions/collections.md
index 6ccbeb4b026..3933af4ea2c 100644
--- a/docs/permissions/collections.md
+++ b/docs/permissions/collections.md
@@ -104,6 +104,14 @@ Administrators can see and edit the contents of every user's personal collection
A personal collection works just like any other collection except that its permissions are fixed and cannot be changed. If a sub-collection within a personal collection is moved to a different collection, the sub-collection will inherit the permissions of its new parent collection.
+### Library collection
+
+See [Data Studio > Library](../data-studio/library.md)
+
+### External collections
+
+See [Tenants > External collections](../embedding/tenants.md#collection-types)
+
## Further reading
- [Working with collection permissions][collection-permissions].
diff --git a/docs/permissions/notifications.md b/docs/permissions/notifications.md
index e02c4c5bc5c..c37aeb32eca 100644
--- a/docs/permissions/notifications.md
+++ b/docs/permissions/notifications.md
@@ -5,7 +5,7 @@ summary: Learn who can create and edit alerts and dashboard subscriptions, and w
# Notification permissions
-Notifications in Metabase include [alerts](../questions/alerts.md) and [dashboard subscriptions](../dashboards/subscriptions.md#setting-up-a-dashboard-subscription).
+Notifications in Metabase include [alerts](../questions/alerts.md) and [dashboard subscriptions](../dashboards/subscriptions.md).
## Who can edit dashboard subscriptions and alerts
@@ -19,7 +19,7 @@ What you can do with alerts and dashboard subscriptions depends on whether you'r
Everyone's in the All Users group. Which means that everyone can:
-- Create [alerts](../questions/alerts.md) and [dashboard subscriptions](../dashboards/subscriptions.md#setting-up-a-dashboard-subscription).
+- Create [alerts](../questions/alerts.md) and [dashboard subscriptions](../dashboards/subscriptions.md).
- Add new recipients to dashboard subscriptions and alerts that they created.
- Unsubscribe from any alert or subscription in their [Account settings](../people-and-groups/account-settings.md).
diff --git a/docs/questions/images/filter.png b/docs/questions/images/filter.png
new file mode 100644
index 00000000000..c5eedd1103c
Binary files /dev/null and b/docs/questions/images/filter.png differ
diff --git a/docs/questions/images/get-alerts-about-this.png b/docs/questions/images/get-alerts-about-this.png
index 20276067689..7dd10411ab5 100644
Binary files a/docs/questions/images/get-alerts-about-this.png and b/docs/questions/images/get-alerts-about-this.png differ
diff --git a/docs/questions/images/join.png b/docs/questions/images/join.png
new file mode 100644
index 00000000000..32204283e5e
Binary files /dev/null and b/docs/questions/images/join.png differ
diff --git a/docs/questions/images/library-data-picker.png b/docs/questions/images/library-data-picker.png
new file mode 100644
index 00000000000..f7a6a7fccf0
Binary files /dev/null and b/docs/questions/images/library-data-picker.png differ
diff --git a/docs/questions/images/preview-table.png b/docs/questions/images/preview-table.png
index 432bf88ebb4..9a883facc96 100644
Binary files a/docs/questions/images/preview-table.png and b/docs/questions/images/preview-table.png differ
diff --git a/docs/questions/images/summarize.png b/docs/questions/images/summarize.png
new file mode 100644
index 00000000000..ce34db175b4
Binary files /dev/null and b/docs/questions/images/summarize.png differ
diff --git a/docs/questions/introduction.md b/docs/questions/introduction.md
index 9a1f388e44c..e34880b4047 100644
--- a/docs/questions/introduction.md
+++ b/docs/questions/introduction.md
@@ -13,34 +13,17 @@ Questions in Metabase are queries, their results, and their visualization. Quest
## Creating a new question
-You can create a new question from scratch, or build off of an existing question. To create a question from scratch, you can click on **+ New** and select how you want to query your data: either with the graphical query builder, or the SQL/native editor:
+You can create a new question from scratch, or build off of an existing question. To create a question from scratch click on **+ New** and select how you want to query your data:
-You can also use [Metabot](../ai/metabot.md) to create questions using natural language. Just ask Metabot what you want to know about your data, and it can generate charts and queries for you.
+- **+ New > Question** to create a question using the graphicalcquery builder. See [Query builder](../questions/query-builder/editor.md).
+ ![Query builder editor](./images/editor.png)
-### Query builder
+- **+ New >SQl/Native query** to create a question using the native/SQL query editor. See [Native editor](../questions/native-editor/writing-sql.md).
-![Query builder editor](./images/editor.png)
+ ![Native editor](./images/native-editor.png)
-Selecting **Question** will take you to the [editor in the graphical query builder](./query-builder/editor.md).
-
-### Native editor
-
-![Native editor](./images/native-editor.png)
-
-Selecting **SQL/native code** will open the [native code editor](./native-editor/writing-sql.md).
-
-Even if you know SQL, you should still check out the [graphical query builder](./query-builder/editor.md), as you can use it to build [interactive charts](https://www.metabase.com/learn/metabase-basics/querying-and-dashboards/questions/drill-through).
-
-### From an existing question
-
-You can also build a new question from an existing question. You won't overwrite the existing question, so feel free to play around. You can use either the [query builder](./query-builder/editor.md) or the [native code editor](./native-editor/referencing-saved-questions-in-queries.md).
-
-Some kinds of saved questions, however, can't be used as source data:
-
-- Druid questions
-- Mongo questions
-- Questions that use `Cumulative Sum` or `Cumulative Count` aggregations
-- Questions that have columns that are named the same or similar thing, like `Count` and `Count 2`
+ Even if you know SQL, you should still check out the [graphical query builder](./query-builder/editor.md), as you can use it to build [interactive charts](https://www.metabase.com/learn/metabase-basics/querying-and-dashboards/questions/drill-through).
+ You can also use [Metabot](../ai/metabot.md) to create questions using natural language. Just ask Metabot what you want to know about your data, and it can generate charts and queries for you.
## Saving questions
diff --git a/docs/questions/query-builder/editor.md b/docs/questions/query-builder/editor.md
index 9fa243987ed..a6835685bbc 100644
--- a/docs/questions/query-builder/editor.md
+++ b/docs/questions/query-builder/editor.md
@@ -7,112 +7,99 @@ redirect_from:
# The query builder
-Metabase includes a graphical query builder that lets you build interactive charts.
+Metabase includes a graphical query builder that lets you build interactive charts by building a query step by step from building blocks like filters and summaries.
-With the query builder you can:
+![Metabase query builder](../images/notebook-editor.png)
+
+## Create a new question with the query builder
-- [Pick data](#picking-data)
-- [Join tables](#joining-data)
+From the **+ New** dropdown, select **Question**. Metabase will give you a graphical interface to build your query step-by-step:
+
+- [Pick data](#pick-data)
+- [Join tables](#join-data)
- [Create custom columns](#custom-columns)
- [Filter data](./filters.md)
- [Summarize and group data](./summarizing-and-grouping.md)
- [Limit results](#setting-a-row-limit)
+- [Visualize results as a chart](#visualizing-your-data)
-When viewing a chart, you can also click through questions to explore the data in greater detail.
-
-![Drill-through menu](../images/drill-through-menu.png)
-
-The drill-through menu will present different options depending on what you click on. You can then optionally save any exploration as a new question. Full drill-through menu is only available for questions built using the query builder. Questions built with the SQL/native editor will have only have [limited drill-through actions](../native-editor/writing-sql.md#drill-though-in-sql-questions). For more on how drill-through works, check out [Creating interactive charts](https://www.metabase.com/learn/metabase-basics/querying-and-dashboards/questions/drill-through).
+## Preview results
-## Creating a new question with the query builder
+To the right of each step in the query builder is a **Preview** button (looks like a Play button - a triangle pointing to the right) that shows you the first 10 rows of the results of your question up to that step.
-From the **+ New** dropdown, select **Question**, then pick your starting data:
-
-You can start a question from:
-
-- **A model**. A [model](../../data-modeling/models.md) is a special kind of saved question meant to be used as a good starting point for questions. Sometimes these are called derived tables, as they usually pull together data from multiple raw tables.
-- **A metric**. [Metrics](../../data-modeling/metrics.md) are pre-defined calculations. If you pick a metric as a starting point for a question, Metabase will create a question with the same data source as the selected metric, and apply the metric. You'll be able to add more joins, filter, and summaries.
-- **Tables**. You'll need to specify the database and the table in that database as the starting point for your question.
-- A **saved question**. You can use the results of any question as the starting point for a new question.
-
-Note that there are some kinds of saved questions that can't be used as source data:
+![Previewing results](../images/preview-table.png)
-- Druid questions
-- Mongo questions
-- Questions that use `Cumulative Sum` or `Cumulative Count` aggregations
-- Questions that have columns that are named the same or similar thing, like `Count` and `Count 2`
+## Pick data
-## The editor
+To start building a question with the query builder, you need to select the data you want to work with. You can pick pick a a table from a database, a[model](../../data-modeling/models.md), a [metric](../../data-modeling/metrics.md), or another saved question. You can search by typing, or browse your databases and collections.
-Once you select your data, Metabase will take you to the query builder's editor. Say you selected **Tables** > **Sample database** > **Orders**, then you'll see something like this:
+![data picker](../images/data-picker.png)
-![Metabase query builder](../images/notebook-editor.png)
+If your Metabase has the [Library collection](../../data-studio/library.md), then by default you'll only see the Data (tables) and Metrics from the library. To query other data sources, select "Browse all".
-This is the query builder's editor. It has three default steps.
+![library data picker](../images/library-data-picker.png)
-- [Picking data](#picking-data)
-- [Filtering](./filters.md)
-- [Summarizing and grouping by](./summarizing-and-grouping.md)
+Once you select the data source, you can preview the data, or view the data in a new browser tab by Cmd/Ctrl+Clicking on the data source's name.
-You can also add steps for [joining data](./join.md), [custom columns](#custom-columns), and [sorting results](#sorting-results), and [limiting results](#setting-a-row-limit).
+To choose which columns to include in your query, click on the arrow next to the data source. If you uncheck a column, you'll still be able to use the column while building a query (for example, in filters) but Metabase won't display the column in results.
-To the right of each completed step is a **Preview** button (looks like a Play button - a triangle pointing to the right) that shows you the first 10 rows of the results of your question up to that step.
+You can [hide columns](../visualizations/table.md#rearranging-adding-and-hiding-columns) from the table views.
-![Previewing results](../images/preview-table.png)
+> **Hiding columns should _not_ be used to secure sensitive information**. Hiding columns in table visualization settings only affects the visibility of the columns _in the visualization_, not in the query results. Even people with only "view data" permissions to the question will be able to change the visualization settings and unhide columns. To exclude a column from the results of a specific query, uncheck the column in the "Data" block of the query builder.
-## Picking data
+## Join data
-The data section is where you select the data you want to work with. Here you'll pick a [model](../../data-modeling/models.md), a [metric](../../data-modeling/metrics.md), a table from a database, or a saved question. You can search by typing, or browse your databases and collections.
+![Join](../images/join.png)
-![data picker](../images/data-picker.png)
+You can also select data from multiple tables from the same database by joining the tables, see [Joins](./join.md).
-You can see the data source in a new browser tab by Cmd/Ctrl+Clicking on the data source's name in the query builder.
+## Custom columns
-To choose which columns to include in your query, click on the arrow next to the data source. If you uncheck a column, you'll still be able to use the column while building a query (for example, in filters) but Metabase won't display the column in results.
+![Custom column](../images/custom-column.png)
-You can [hide columns](../visualizations/table.md#rearranging-adding-and-hiding-columns) from the table views.
+Custom columns are helpful when you need to create a new column based on a calculation, such as subtracting the value of one column from another, or extracting a portion of an existing text column. Custom columns that you add aren't permanently added to the underlying database table; the columns will only be present in the given question.
-> **Hiding columns should _not_ be used to secure sensitive information**. Hiding columns in table visualization settings only affects the visibility of the columns _in the visualization_, not in the query results. Even people with only "view data" permissions to the question will be able to change the visualization settings and unhide columns. To exclude a column from the results of a specific query, uncheck the column in the "Data" block of the query builder.
+You can use the following math operators in your formulas: `+`, `–`, `*` (multiplication), and `/` (division), along with a whole host of spreadsheet-like functions. You can also use parentheses to clarify the order of operations.
-## Joining data
+You can add custom columns after the [Pick data](#pick-data) step or after [Summarize](#summarize-and-group-data) step.
-You can also select multiple tables from the same database by [joining them](./join.md).
+See [Custom expressions](../query-builder/expressions.md).
-## Filtering data
+## Filter data
-See [filters](./filters.md).
+![Filter](../images/filter.png)
-## Visualizing your data
+You can add filters to restrict the data you retrieve. For example, you can tell Metabase to only retrieve data for `Widgets` over `Last 3 weeks`. See [filtering data](./filters.md).
-Check out [visualizing results](../visualizations/visualizing-results.md).
+## Summarize and group data
-## Column heading drill-through
+![Summary](../images/summarize.png)
-When viewing a [table](../visualizations/table.md), clicking on the heading of a column gives you different options, depending on the columns data type. See [table](../visualizations/table.md#column-heading-options-for-filtering-and-summarizing).
+Once you pick the data to query and hhe filters to apply, you can choose to summarize your data - for example, compute the count of rows or average of a column. You can also break out and group summaries by dimensions.
-## Custom expressions
+See [Summarizing and grouping](./summarizing-and-grouping.md).
-Custom expressions allow you to use spreadsheet-like functions and simple arithmetic within or between aggregation functions.
+Metabase comes with several built-in summaries, but you can also use custom expressions to write spreadsheet-like functions and simple arithmetic within or between aggregation functions.
For example, you could do `Average(sqrt[FieldX]) + Sum([FieldY])` or `Max(floor([FieldX] - [FieldY]))`, where `FieldX` and `FieldY` are fields in the currently selected table. [Learn more about writing expressions](./expressions.md).
-## Custom columns
+## Sort results
-![Custom column](../images/custom-column.png)
+![Sorting](../images/sort-step.png)
-Custom columns are helpful when you need to create a new column based on a calculation, such as subtracting the value of one column from another, or extracting a portion of an existing text column. Custom columns that you add aren't permanently added to the underlying database table; the columns will only be present in the given question.
+The sorting step lets you pick one or more columns to sort your results by. For each column you pick, you can also choose whether to sort ascending or descending; just click the arrow to change from ascending (up arrow) to descending (down arrow).
-You can use the following math operators in your formulas: `+`, `–`, `*` (multiplication), and `/` (division), along with a whole host of spreadsheet-like functions. You can also use parentheses to clarify the order of operations. See [list of expressions](../query-builder/expressions-list.md).
+If you're using cumulative aggregation functions in you **Summarize** block, the sort order might affect how the aggregation is computed (as opposed to just how the results are displayed ). See [Cumulative functions](../query-builder/expressions/cumulative.md).
-## Sorting results
+## Setting a row limit
-![Sorting](../images/sort-step.png)
+The row limit step lets you cap how many rows you want from the previous results. When used in conjunction with sorting, limits can let you do things like create a top-10 list, by first sorting by one of the columns in your result, then adding a row limit of 10.
-The sorting step lets you pick one or more columns to sort your results by. For each column you pick, you can also choose whether to sort ascending or descending; just click the arrow to change from ascending (up arrow) to descending (down arrow).
+Unlike other steps, the row limit step can only be added at the end of your question, so if you limit your results to 10 rows, Metabase will _first_ do all the actions in previous steps (filters, summaries, etc), and only _then_ limit the display (as opposed to just starting with 10 rows to begin with)
-## Setting a row limit
+If you do want to add more steps to limited results, you can always save the limited results as a question, then start a _new_ question based on those results.
-The row limit step lets you cap how many rows you want from the previous results. When used in conjunction with sorting, limits can let you do things like create a top-10 list, by first sorting by one of the columns in your result, then adding a row limit of 10. Unlike other steps, the row limit step can only be added at the end of your question. If you do want to add more steps to limited results, you can always save the limited results as a question, then start a _new_ question based on those results.
+Note that if you pick row limit over 2,000 for unaggregated queries or 10,000 for aggregated queries, Metabase will still only display 2,000 or 10,000 rows in the table visualization. This is to avoid overloading your browser. See [Table visualization](../visualizations/table.md).
## Viewing the native query that powers your question
@@ -130,3 +117,21 @@ You can also convert the question to a [native editor question](../native-editor
2. Click **Convert the question to SQL** option in the bottom right below the SQL code.
Conversion is a one-way street: you can't convert a SQL question back into a query builder question.
+
+## Visualizing your data
+
+To view results, click **Visualize** to create a chart. Metabase will automatically pick the best visualization for your data, but you can change and customize it.
+
+Check out [visualizing results](../visualizations/visualizing-results.md).
+
+### Drill-through
+
+When viewing a chart, you can also click through questions to explore the data in greater detail.
+
+![Drill-through menu](../images/drill-through-menu.png)
+
+The drill-through menu will present different options depending on what you click on. You can then optionally save any exploration as a new question. The full drill-through menu is only available for questions built using the query builder. Questions built with the SQL/native editor have [limited drill-through actions](../native-editor/writing-sql.md#drill-though-in-sql-questions). For more on how drill-through works, check out [Creating interactive charts](https://www.metabase.com/learn/metabase-basics/querying-and-dashboards/questions/drill-through).
+
+### Column heading drill-through
+
+When viewing a [table](../visualizations/table.md), clicking on the heading of a column gives you different options, depending on the columns data type. See [table](../visualizations/table.md#column-heading-options-for-filtering-and-summarizing).
diff --git a/docs/questions/query-builder/expressions-list.md b/docs/questions/query-builder/expressions-list.md
index 40705e4fdc6..c7fe28ba4b8 100644
--- a/docs/questions/query-builder/expressions-list.md
+++ b/docs/questions/query-builder/expressions-list.md
@@ -879,7 +879,7 @@ Related: [dayName](#dayname), [quarterName](#quartername).
### [now](./expressions/now.md)
-Returns the current date and time using your Metabase [report timezone](../../configuring-metabase/localization.md#report-timezone).
+Returns the current date and time using your Metabase [instance default report timezone](../../configuring-metabase/localization.md#set-default-instance-report-timezone).
Syntax: `now()`
diff --git a/docs/questions/query-builder/expressions/now.md b/docs/questions/query-builder/expressions/now.md
index 9e452ff9063..815aeeced11 100644
--- a/docs/questions/query-builder/expressions/now.md
+++ b/docs/questions/query-builder/expressions/now.md
@@ -4,7 +4,7 @@ title: Now
# Now
-`now` returns the current datetime using your Metabase [report timezone](../../../configuring-metabase/localization.md#report-timezone).
+`now` returns the current datetime using your Metabase [report timezone](../../../configuring-metabase/localization.md#set-default-instance-report-timezone).
## Creating conditional logic using the current date or time
@@ -58,7 +58,7 @@ For more info about the way these data types behave in Metabase, see [Timezones]
## Limitations
-`now` might not be _now_ (in your local time) if you don't live in the same timezone as your Metabase [report time zone](../../../configuring-metabase/localization.md#report-timezone).
+`now` might not be _now_ (in your local time) if you don't live in the same timezone as your Metabase [report time zone](../../../configuring-metabase/localization.md#set-default-instance-report-timezone).
If you need to compare `now` to a column in a different time zone, use [convertTimezone](./converttimezone.md) to shift both columns into the same time zone. For example:
@@ -78,7 +78,7 @@ Different ways to do the same thing, because while you'd love to use custom expr
When you run a question using the [query builder](https://www.metabase.com/glossary/query-builder), Metabase will convert your query builder settings (filters, summaries, etc.) into a SQL query, and run that query against your database to get your results.
-By default, `now` uses your Metabase's [report time zone](../../../configuring-metabase/localization.md#report-timezone). If your admin hasn't set a report time zone, `now` will use your database's time zone.
+By default, `now` uses your Metabase's [report time zone](../../../configuring-metabase/localization.md#set-default-instance-report-timezone). If your admin hasn't set a report time zone, `now` will use your database's time zone.
Say you're using a Postgres database. If your Metabase report time zone is set to EST, you'll get `now` in EST:
diff --git a/docs/questions/query-builder/summarizing-and-grouping.md b/docs/questions/query-builder/summarizing-and-grouping.md
index a17c9787131..8ac5d831ea7 100644
--- a/docs/questions/query-builder/summarizing-and-grouping.md
+++ b/docs/questions/query-builder/summarizing-and-grouping.md
@@ -30,7 +30,7 @@ And a lot of the time, you'll then **group** that metric by:
Adding a summarize step lets you choose how to aggregate the data from the previous step. You can pick one or more metrics, and optionally group those metrics by one or more dimensions (columns). When picking your metrics you can choose from basic functions like `sum`, `average`, and `count`; or you can pick a common metric defined by an admin; or you can create a [custom expression](./expressions.md) by writing a formula.
-Common metrics include:
+Basic metrics include:
- **Count of rows:** the total of number of rows in the table, after any filters have been applied. If you're looking at your `Orders` table and want to know how many orders were placed with a price greater than \$40, you’d filter by “Price greater than 40,” and then select `Count of rows`, because you want Metabase to count how many orders matched your filter.
- **Sum of …:** the sum of all the values in a specific column.
@@ -48,7 +48,7 @@ If you summarize and add a grouping you can then summarize _again_. You can also
You can also add metrics and groupings on the results page in a sidebar: the top of the sidebar where you pick the number ("metric") you want to see, and the part below is where you pick how to group that number (or how to "break it out").
-If your admins have created any named [metrics](../../data-modeling/metrics.md) that are specific to your company or organization, they will be in this dropdown under the **Common Metrics** section. These might be things like your company’s official way of calculating revenue.
+If your admins have created any named [metrics](../../data-modeling/metrics.md) or [measures](../../data-studio/data-structure.md#measures) that are specific to your company or organization, they will be in this dropdown under the **Metrics** or **Measures** section. These might be things like your company’s official way of calculating revenue.
By default, Metabase will limit the number of aggregated rows displayed to 10,000 rows. You can change this limit with the environment variable [`MB_AGGREGATED_QUERY_ROW_LIMIT`](../../configuring-metabase/environment-variables.md#mb_aggregated_query_row_limit).
diff --git a/docs/troubleshooting-guide/timezones.md b/docs/troubleshooting-guide/timezones.md
index c96c5b3068c..760853bebeb 100644
--- a/docs/troubleshooting-guide/timezones.md
+++ b/docs/troubleshooting-guide/timezones.md
@@ -44,7 +44,7 @@ Once you think you have identified a problem, drill down to understand exactly w
**Steps to take:**
-1. Check the [report timezone setting](../configuring-metabase/localization.md#report-timezone) from **Admin** > **Settings** > **Localization**.
+1. Check the [report timezone setting](../configuring-metabase/localization.md#set-default-instance-report-timezone) from **Admin** > **Settings** > **Localization**.
2. If you're using a database that doesn't support the report timezone setting, ensure that Metabase's time zone matches that of the database. Metabase's time zone is the Java Virtual Machine's time zone, typically set via a `-Duser.timezone<..>` parameter or the `JAVA_TIMEZONE` environment variable; exactly how it is set will depend on how you launch Metabase. Note that Metabase's time zone doesn't impact any databases that use a Report Time Zone.
## Are SQL queries not respecting the Reporting Time Zone setting?