diff --git a/docs/administration-guide/01-managing-databases.md b/docs/administration-guide/01-managing-databases.md
index 3013073e57687dd15e025f18dce87c50593c26dd..8641131b9c570fc7033f70fcd00a71b9f20c19d4 100644
--- a/docs/administration-guide/01-managing-databases.md
+++ b/docs/administration-guide/01-managing-databases.md
@@ -1,64 +1,63 @@
+## Managing databases
-## Managing Databases
If you already connected your database during the installation, you’ve probably covered a lot of this territory. But if you need to add another database or manage the settings of one you already have connected, just click the settings icon in the top right of Metabase and select **Admin**.
Cool, now you’re in the administration section of Metabase. Next, select **Databases** from the menu bar at the top of the screen to see your databases.
-### Adding a Database Connection
+### Adding a database connection
Now you’ll see a list of your databases. To connect another database to Metabase, click **Add database**. Metabase currently supports the following types of databases:
-* Amazon Redshift
-* [Google BigQuery](databases/bigquery.md)
-* H2
-* [MongoDB (version 3.4 or higher)](databases/mongodb.md)
-* MySQL (version 4.1 or higher, as well as MariaDB)
-* Postgres
-* SQLite
-* SQL Server
-* Druid
-* [Oracle](databases/oracle.md)
-* [Vertica](databases/vertica.md)
-* Presto
-* Google Analytics
-* SparkSQL
-* Snowflake
+- Amazon Redshift
+- [Google BigQuery](databases/bigquery.md)
+- H2
+- [MongoDB (version 3.4 or higher)](databases/mongodb.md)
+- MySQL (version 4.1 or higher, as well as MariaDB)
+- Postgres
+- SQLite
+- SQL Server
+- Druid
+- [Oracle](databases/oracle.md)
+- [Vertica](databases/vertica.md)
+- Presto
+- Google Analytics
+- SparkSQL
+- Snowflake
To add a database, you'll need its connection information.
-#### <a name="heroku-databases"></a>Getting connection information for Databases on Heroku:
+#### <a name="heroku-databases"></a>Getting connection information for databases on Heroku:
1. Go to [https://postgres.heroku.com/databases](https://postgres.heroku.com/databases).
2. Click on the database you want to connect to Metabase.
3. Write down the following information based on your database:
- * Hostname
- * Port
- * Username
- * Database Name
- * Password
+ - Hostname
+ - Port
+ - Username
+ - Database Name
+ - Password
-#### <a name="rds-databases"></a>Getting connection information for Databases on Amazon's RDS:
+#### <a name="rds-databases"></a>Getting connection information for databases on Amazon's RDS:
1. Go to your AWS Management Console.
- * Need help finding that? Visit [https://**My_AWS_Account_ID**.signin.aws.amazon.com/console](https://**My_AWS_Account_ID**.signin.aws.amazon.com/console). Be sure to insert your own AWS Account ID, though!
-2. Under "Database" services, click "RDS".
-3. Then click "Instances".
-4. Select the database you want to connect to Metabase.
-5. Write down the following information based on your database:
- * Hostname - This is listed as the "Endpoint" parameter
- * Port - Find the port parameter under "Security and Network"
- * Username - Find this under "Configuration Details"
- * Database Name - Find this under "Configuration Details"
- * Password - Ask your database administrator for the password.
-
+ - Need help finding that? Visit [https://**My_AWS_Account_ID**.signin.aws.amazon.com/console](https://**My_AWS_Account_ID**.signin.aws.amazon.com/console). Be sure to insert your own AWS Account ID, though!
+2. Under "Database" services, click "RDS".
+3. Then click "Instances".
+4. Select the database you want to connect to Metabase.
+5. Write down the following information based on your database:
+ - Hostname - This is listed as the "Endpoint" parameter
+ - Port - Find the port parameter under "Security and Network"
+ - Username - Find this under "Configuration Details"
+ - Database Name - Find this under "Configuration Details"
+ - Password - Ask your database administrator for the password.
### Secure Socket Layer (SSL)
Metabase automatically tries to connect to databases with and without SSL. If it is possible to connect to your database with a SSL connection, Metabase will make that the default setting for your database. You can always change this setting later if you prefer to connect without this layer of security, but we highly recommend keeping SSL turned on to keep your data secure.
-### Database Sync and Analysis
+### Database sync and analysis
By default, Metabase performs a lightweight hourly sync of your database, and a nightly deeper analysis of the fields in your tables to power some of Metabase's features, like filter widgets.
@@ -70,7 +69,7 @@ Save your changes, and you'll see a new tab at the top of the form called "Sched
#### Database syncing
-Metabase maintains its own information about the various tables and fields in each database that is added to aid in querying. By default, Metabase performs this lightweight sync hourly to look for changes to the database such as new tables or fields. Metabase does *not* copy any data from your database. It only maintains lists of the tables and columns.
+Metabase maintains its own information about the various tables and fields in each database that is added to aid in querying. By default, Metabase performs this lightweight sync hourly to look for changes to the database such as new tables or fields. Metabase does _not_ copy any data from your database. It only maintains lists of the tables and columns.
Syncing can be set to hourly, or daily at a specific time. Syncing can't be turned off completely, otherwise Metabase wouldn't work.
@@ -78,6 +77,10 @@ If you'd like to sync your database manually at any time, click on it from the D
+#### Query auto-running settings
+
+By default, Metabase will auto-run queries when you use the Summarize and Filter buttons when viewing a table or chart. If your users are exploring data that is stored in a slow database, you may want to turn the auto-run off to avoid re-running the query every time your users change an option in the Summarize view. Turning this off presents the users with the option to re-run the query when they choose to.
+
#### Scanning for field values
When Metabase first connects to your database, it takes a look at the metadata of the fields in your tables and automatically assigns them a field type. Metabase also takes a sample of each table to look for URLs, JSON, encoded strings, etc. If a field is classified wrong, you can always manually edit it from the **Metadata** tab in the Admin Panel.
@@ -88,7 +91,7 @@ By default, Metabase also performs a more intensive daily sampling of each field
- **Regularly, on a schedule** lets you choose to scan daily, weekly, or monthly, and also lets you choose what time of day, or which day of the month to scan. This is the best option if you have a relatively small database, or if the distinct values in your tables change often.
- **Only when adding a new filter widget** is a great option if you have a relatively large database, but you still want to enable dashboard and SQL/native query filters. With this option enabled, Metabase will only scan and cache the values of the field or fields that are required whenever a new filter is added to a dashboard or SQL/native question. For example, if you were to add a dashboard category filter, mapped to one field called `Customer ID` and another one called `ID`, only those two fields would be scanned at the moment the filter is saved.
-- **Never, I'll do this manually if I need to** is an option for databases that are either prohibitively large, or which never really have new values added. If you want to trigger a manual re-scan, click the button in top-right of the database's page that says "Re-scan field values now."
+- **Never, I'll do this manually if I need to** is an option for databases that are either prohibitively large, or which never really have new values added. If you want to trigger a manual re-scan, click the button in the top-right of the database's page that says "Re-scan field values now."
If for some reason you need to flush out the cached field values for your database, click the button that says "Discard saved field values" in the top-right of the database's page.
@@ -102,7 +105,7 @@ On either the table settings or field settings page, you'll see these options:
-### Deleting Databases
+### Deleting databases
To delete a database from Metabase, click on **Remove this database** from the database detail screen.
@@ -114,60 +117,61 @@ You can also delete a database from the database list: hover over the row with t
**Caution: Deleting a database is irreversible! All saved questions and dashboard cards based on the database will be deleted as well!**
-### SSH Tunneling In Metabase
+### SSH tunneling in Metabase
+
---
+
Metabase has the ability to connect to some databases by first establishing a connection to a server in between Metabase and a data warehouse, then connect to the data warehouse using that connection as a bridge. This makes connecting to some data warehouses possible in situations that would otherwise prevent the use of Metabase.
+#### When to use this feature
-#### When To Use This Feature
There are two basic cases for using an SSH tunnel rather than connecting directly:
-* A direct connection is impossible
-* A direct connection is forbidden due to a security policy
+- A direct connection is impossible
+- A direct connection is forbidden due to a security policy
Sometimes when a data warehouse is inside an enterprise environment, direct connections are blocked by security devices such as firewalls and intrusion prevention systems. To work around this many enterprises offer a VPN, a bastion host, or both. VPNs are the more convenient and reliable option though bastion hosts are used frequently, especially with cloud providers such as Amazon Web Services where VPC (Virtual Private Clouds) don't allow direct connections. Bastion hosts offer the option to first connect to a computer on the edge of the protected network, then from that computer establish a second connection to the data warehouse on the internal network and essentially patch these two connestions together. Using the SSH tunneling feature, Metabase is able to automate this process in many cases. If a VPN is available that should be used in preference to SSH tunneling.
-#### How To Use This Feature
+#### How to use this feature
When connecting though a bastion host:
-* Answer yes to the "Use an SSH-tunnel for database connections" parameter
-* Enter the hostname for the data warehouse as it is seen from inside the network in the `Host` parameter.
-* Enter the data warehouse port as seen from inside the network into the `Port` parameter.
-* Enter the external name of the bastion host as seen from the outside of the network (or wherever you are) into the `SSH tunnel host` parameter.
-* Enter the ssh port as seen from outside the network into the `SSH tunnel port` parameter. This is usually 22, regardless of which data warehouse you are connecting to.
-* Enter the username and password you use to login to the bastion host into the `SSH tunnel username` and `SSH tunnel password` parameters.
+- Answer yes to the "Use an SSH-tunnel for database connections" parameter
+- Enter the hostname for the data warehouse as it is seen from inside the network in the `Host` parameter.
+- Enter the data warehouse port as seen from inside the network into the `Port` parameter.
+- Enter the external name of the bastion host as seen from the outside of the network (or wherever you are) into the `SSH tunnel host` parameter.
+- Enter the ssh port as seen from outside the network into the `SSH tunnel port` parameter. This is usually 22, regardless of which data warehouse you are connecting to.
+- Enter the username and password you use to login to the bastion host into the `SSH tunnel username` and `SSH tunnel password` parameters.
If you are unable to connect test your ssh credentials by connecting to the SSH server/Bastion Host using ssh directly:
ssh <SSH tunnel username>@<SSH tunnel host> -p <SSH tunnel port>
-
Another common case where direct connections are not possible is when connecting to a data warehouse that is only accessible locally and does not allow remote connections. In this case you will be opening an SSH connection to the data warehouse, then from there connecting back to the same computer.
-* Answer yes to the "Use an SSH-tunnel for database connections" parameter
-* Enter `localhost` in the `Host` parameter. This is the name the server
-* Enter the same value in the `Port` parameter that you would use if you where sitting directly at the data warehouse host system.
-* Enter the extenal name of the data warehouse, as seen from the outside of the network (or wherever you are) into the `SSH tunnel host` parameter.
-* Enter the ssh port as seen from outside the network into the `SSH tunnel port` parameter. This is usually 22, regardless of which data warehouse you are connecting to.
-* Enter the username and password you use to login to the bastion host into the `SSH tunnel username` and `SSH tunnel password` parameters.
+- Answer yes to the "Use an SSH-tunnel for database connections" parameter
+- Enter `localhost` in the `Host` parameter. This is the name the server
+- Enter the same value in the `Port` parameter that you would use if you where sitting directly at the data warehouse host system.
+- Enter the extenal name of the data warehouse, as seen from the outside of the network (or wherever you are) into the `SSH tunnel host` parameter.
+- Enter the ssh port as seen from outside the network into the `SSH tunnel port` parameter. This is usually 22, regardless of which data warehouse you are connecting to.
+- Enter the username and password you use to login to the bastion host into the `SSH tunnel username` and `SSH tunnel password` parameters.
If you have problems connecting verify the ssh host port and password by connecting manually using ssh or PuTTY on older windows systems.
-#### Disadvantages to Indirect Connections
+#### Disadvantages to indirect connections
While using an ssh tunnel makes it possible to use a data warehouse that is otherwise not accessible it is almost always preferable to use a direct connection when possible:
There are several inherent limitations to connecting through a tunnel:
-* If the enclosing SSH connection is closed because you put your computer to sleep or change networks, all established connections will be closed as well. This can cause delays resuming connections after suspending your laptop
-* It's almost always slower. The connection has to go through an additional computer.
-* Opening new connections takes longer. SSH connections are slower to establish then direct connections.
-* Multiple operations over the same SSH tunnel can block each other. This can increase latency in some cases.
-* The number of connections through a bastion host is often limited by organizational policy.
-* Some organizations have IT security policies forbidding using SSH tunnels to bypass security perimeters.
+- If the enclosing SSH connection is closed because you put your computer to sleep or change networks, all established connections will be closed as well. This can cause delays resuming connections after suspending your laptop
+- It's almost always slower. The connection has to go through an additional computer.
+- Opening new connections takes longer. SSH connections are slower to establish then direct connections.
+- Multiple operations over the same SSH tunnel can block each other. This can increase latency in some cases.
+- The number of connections through a bastion host is often limited by organizational policy.
+- Some organizations have IT security policies forbidding using SSH tunnels to bypass security perimeters.
-#### What if The Built in SSH Tunnels Don't Fit My Needs?
+#### What if the built-in SSH tunnels don't fit my needs?
This feature exists as a convenient wrapper around SSH and automates the common cases of connecting through a tunnel. It also makes connecting possible from systems that don't have or allow shell access. Metabase uses a built in SSH client that does not depend on the installed system's ssh client. This allows connecting from systems where it's not possible to run SSH manually, it also means that Metabase cannot take advantage of authentication services provided by the system such as Windows Domain Authentication or Kerberos Authentication.
@@ -177,8 +181,8 @@ If you need to connect using a method not enabled by Metabase, you can often acc
This allows you to use the full array of features included in ssh. If you find yourself doing this often, please let us know so we can see about making your process more convenient through Metabase.
-
---
## Next: enabling features that send email
+
Metabase can send emails for certain features, like email invites, but first you need to [set up an email account](02-setting-up-email.md).
diff --git a/docs/administration-guide/images/Metric.png b/docs/administration-guide/images/Metric.png
index a818a90eb1e75fe2f0c06740b6bfa3e9485fe05d..1a80344c959f7605faa9794515e1ae62fe0c2b0f 100644
Binary files a/docs/administration-guide/images/Metric.png and b/docs/administration-guide/images/Metric.png differ
diff --git a/docs/administration-guide/images/ProfileDropdown.png b/docs/administration-guide/images/ProfileDropdown.png
index 0ee4f72d9c5c5e43ab6660cf3dcf174af0d9dc7b..188eadbf2c6ceab89929d701a3bd94be4fdd44f4 100644
Binary files a/docs/administration-guide/images/ProfileDropdown.png and b/docs/administration-guide/images/ProfileDropdown.png differ
diff --git a/docs/administration-guide/images/Segment.png b/docs/administration-guide/images/Segment.png
index 8b9d30b85847dec786fba89ffeb7dd7e3ccd6621..8862e7b4927d4aa19af2046d626b3f1589b65154 100644
Binary files a/docs/administration-guide/images/Segment.png and b/docs/administration-guide/images/Segment.png differ
diff --git a/docs/administration-guide/images/change-access.png b/docs/administration-guide/images/change-access.png
index 744f5495dc31649090bcd80c70f6dd1376a8a8b8..567ec76a5af575af07d0d8088da893628708a3bb 100644
Binary files a/docs/administration-guide/images/change-access.png and b/docs/administration-guide/images/change-access.png differ
diff --git a/docs/administration-guide/images/groups.png b/docs/administration-guide/images/groups.png
index ac3fdb5a6889d120bacb281f1412e640685cdab6..7e56da3d97d3f29d7c96f50cbbb6f2ac0eecbc6c 100644
Binary files a/docs/administration-guide/images/groups.png and b/docs/administration-guide/images/groups.png differ
diff --git a/docs/administration-guide/images/gsg/blank-guide.png b/docs/administration-guide/images/gsg/blank-guide.png
deleted file mode 100644
index 1b3f6430a56c4115c12ad2a1f0f5fe9601ba1c84..0000000000000000000000000000000000000000
Binary files a/docs/administration-guide/images/gsg/blank-guide.png and /dev/null differ
diff --git a/docs/administration-guide/images/gsg/finished-guide.png b/docs/administration-guide/images/gsg/finished-guide.png
deleted file mode 100644
index c548fd7d8424e925f8df60b817fcc7a5b4bc68d0..0000000000000000000000000000000000000000
Binary files a/docs/administration-guide/images/gsg/finished-guide.png and /dev/null differ
diff --git a/docs/administration-guide/images/gsg/pick-items.png b/docs/administration-guide/images/gsg/pick-items.png
deleted file mode 100644
index ef30b26271f288db6f341aee807caaf71593af27..0000000000000000000000000000000000000000
Binary files a/docs/administration-guide/images/gsg/pick-items.png and /dev/null differ
diff --git a/docs/administration-guide/images/gsg/sections.png b/docs/administration-guide/images/gsg/sections.png
deleted file mode 100644
index 96cfdc0d3e66254fba25d5fc0bda8105357c2a4f..0000000000000000000000000000000000000000
Binary files a/docs/administration-guide/images/gsg/sections.png and /dev/null differ
diff --git a/docs/administration-guide/images/permissions.png b/docs/administration-guide/images/permissions.png
index 11e5f3016b143c1ba14996c8877bf77ed91d9229..05087de1b66882fa879e2abd0ff6481a329e8896 100644
Binary files a/docs/administration-guide/images/permissions.png and b/docs/administration-guide/images/permissions.png differ
diff --git a/docs/administration-guide/images/table-permissions.png b/docs/administration-guide/images/table-permissions.png
index f3ae7bc9f26f7ed46cdd7fb3237b027c91752ea2..00fc7876ed46b305553c49979ffdbb190926b3a5 100644
Binary files a/docs/administration-guide/images/table-permissions.png and b/docs/administration-guide/images/table-permissions.png differ
diff --git a/docs/enterprise-guide/images/sandboxing/advanced-example-1-filtering-question.png b/docs/enterprise-guide/images/sandboxing/advanced-example-1-filtering-question.png
index 708108abcf2dbace908c94c547fb9a5af23bfc5d..b162363ea18b0d4dbac2497da2a5bc64542a8425 100644
Binary files a/docs/enterprise-guide/images/sandboxing/advanced-example-1-filtering-question.png and b/docs/enterprise-guide/images/sandboxing/advanced-example-1-filtering-question.png differ
diff --git a/docs/enterprise-guide/images/sandboxing/advanced-example-1-people-table.png b/docs/enterprise-guide/images/sandboxing/advanced-example-1-people-table.png
index e9a4c6dcbcc1ab457b91eea64074f9baab323cc8..6b76eee1dd8de28c5f0e791a43a1038607c65536 100644
Binary files a/docs/enterprise-guide/images/sandboxing/advanced-example-1-people-table.png and b/docs/enterprise-guide/images/sandboxing/advanced-example-1-people-table.png differ
diff --git a/docs/enterprise-guide/images/sandboxing/advanced-example-1-results.png b/docs/enterprise-guide/images/sandboxing/advanced-example-1-results.png
index a30269f8d0f5ed942608f096ab6f0d64db82bdf9..b1acb477700e75016632619d4ac89d8438884eef 100644
Binary files a/docs/enterprise-guide/images/sandboxing/advanced-example-1-results.png and b/docs/enterprise-guide/images/sandboxing/advanced-example-1-results.png differ
diff --git a/docs/enterprise-guide/images/sandboxing/advanced-example-2-filtering-question.png b/docs/enterprise-guide/images/sandboxing/advanced-example-2-filtering-question.png
index b7eed672a76350f86b684728f70cc928d51060bb..d95f22534cd1a2b2f68161d5f1414c6753158f85 100644
Binary files a/docs/enterprise-guide/images/sandboxing/advanced-example-2-filtering-question.png and b/docs/enterprise-guide/images/sandboxing/advanced-example-2-filtering-question.png differ
diff --git a/docs/enterprise-guide/images/sandboxing/advanced-example-2-orders-table.png b/docs/enterprise-guide/images/sandboxing/advanced-example-2-orders-table.png
index 34b20e2e57c90abd383abad90b440674a76aa956..2d9c11f825a17222e34d1a0df6cbcf3f901ea8fd 100644
Binary files a/docs/enterprise-guide/images/sandboxing/advanced-example-2-orders-table.png and b/docs/enterprise-guide/images/sandboxing/advanced-example-2-orders-table.png differ
diff --git a/docs/enterprise-guide/images/sandboxing/advanced-example-2-results.png b/docs/enterprise-guide/images/sandboxing/advanced-example-2-results.png
index 765e380ab49cd2f56acd1195d059e9eda2a9b843..66630cc173506cdb394df5658b7559e82e9d78e2 100644
Binary files a/docs/enterprise-guide/images/sandboxing/advanced-example-2-results.png and b/docs/enterprise-guide/images/sandboxing/advanced-example-2-results.png differ
diff --git a/docs/enterprise-guide/images/sandboxing/filtered-pie-chart.png b/docs/enterprise-guide/images/sandboxing/filtered-pie-chart.png
index 3de98721c37cf8e51a201a5f31e0f35e21023b18..0b8ccb307fcabdd7efa43aba2e92802e4607cbf9 100644
Binary files a/docs/enterprise-guide/images/sandboxing/filtered-pie-chart.png and b/docs/enterprise-guide/images/sandboxing/filtered-pie-chart.png differ
diff --git a/docs/enterprise-guide/images/sandboxing/filtered-table.png b/docs/enterprise-guide/images/sandboxing/filtered-table.png
index 3c6aa417640898fe039e3622ecef117e1a017d92..bc2a70f313653e9f1a9f42ba03c9ef2ca2053f0d 100644
Binary files a/docs/enterprise-guide/images/sandboxing/filtered-table.png and b/docs/enterprise-guide/images/sandboxing/filtered-table.png differ
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 607c9af86d64ea9939d4373cf5b71e623f36bb00..67a8bca5ffb0a399bdd248a66ea75fa7be7d9a95 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,112 +1,110 @@
-
# Getting Started with Metabase
Metabase is a simple and powerful analytics tool which lets anyone learn and make decisions from their company's data. No technical knowledge required! We hope you love it.
## Logging in
+
The way you log in to Metabase will depend on how you or your admin set it up, so if you don’t know where to go, just ask the person who sent you your Metabase invite.
## The homepage
-Go ahead and log in to Metabase and the first thing you'll see is the activity feed. Right now there’s not much there, but it’ll soon get full as you and your teammates do things in Metabase.
-
+
+
+Fresh out of the box, Metabase will show you a few things on the home page:
+
+- Some [automatic explorations](./users-guide/14-x-rays.md) of your tables that you can look at and save as a dashboard if you like any of them.
+- An area where things you or your teammates create will show up, along with a link to see all the dashboards, questions, and pulses you have.
+- A list of the databases you've connected to Metabase.
+
+
## Asking a new question
But, enough about that — let’s get to asking questions. For the next few examples, we'll be using the **Sample Dataset** that comes with Metabase.
-Go ahead and click **New Question** at the top of the screen. Now we’re on the new question page. The bar that you see going across the page is what you’ll use to ask your questions. The “Select a table†dropdown should already be open, showing you a list of your database(s) and the tables within them.
+Go ahead and click **Ask a question** at the top of the screen. There are several ways you can ask a question in Metabase, but we'll click on the Simple Question option for now. You'll then need to pick the table that you have a question about. Click the database that the table is in, then pick the table from the list. Once you do, you'll see the table's contents.
-
+
## Our first question
-We’re going to ask a question about the Orders table in the Sample Dataset database, so we’ll click on **Orders** in the dropdown. The Orders table has a bunch of fake data in it about product orders for a made up company. If you just want to see everything that’s in this table, you can click **Run query** and see all the raw data.
+The Orders table has a bunch of fake data in it about product orders for a made up company. Let's start with a simple question about these orders: how many orders have been placed with a subtotal (before tax) greater than \$40? More precisely, this question translates to: "How many records (or rows) are in the table 'Orders' with a value greater than 40 in the Subtotal column?â€
-
-
-Let's start with a simple question: how many orders have been placed with a subtotal (before tax) greater than $40? More precisely, this question translates to, "How many records (or rows) are in the table 'Orders' with a value greater than 40 in the Subtotal column?â€
-
-To find out, we want to *filter* the data by **the field we’re interested in**, which is **Subtotal**. Since each row in this table represents one order, counting how many rows there are after we’ve filtered them will give us the answer we want.
+To find out, we want to _filter_ the data by **the field we’re interested in**, which is **Subtotal**. Since each row in this table represents one order, counting how many rows there are after we’ve filtered them will give us the answer we want.
-So, after we select Subtotal from the Filter dropdown we’ll get some options for the filter, and we’ll choose **Greater than**, type the number 40 in the box, and click Add Filter.
+So, we click the Filter button to open up the filtering sidebar, then select Subtotal as the column to filter on, and we’ll get some options for the filter. We’ll choose **Greater than**, type the number 40 in the box, and click Add Filter.
-Next we need to tell Metabase what we want to see. Under the View dropdown, we’ll select **Count**, because, like we said, we want to count the total number of rows that match our filter. If we left the View set to Raw Data, that would just show us a list of all the rows, which doesn’t answer our question.
+Next we need to tell Metabase what number we want to see. When we ask things like "how many," "what's the total," "what's the average," etc., we need to **summarize** our data. So we'll click the Summarize button to open the sidebar where we can pick how we want to summarize this data. The "Count of rows" metric is selected by default which is great since we want to count the total number of rows that match our filter.
### And our first answer!
-Okay, cool — we’re ready to ask our question, so let’s click the **Run query** button!
+Okay, cool — we’re ready to ask our question, so let’s click **Done**!
-So it looks like there were 12,284 orders, each with a subtotal greater than $40. Ka-ching! Another way of saying this is that there were 12,284 *records* in the table that met the parameters we set.
-
+So it looks like there were 16,309 orders, each with a subtotal greater than \$40. Nice. Another way of saying this is that there were 16,309 _records_ in the table that met the parameters we set.
+
+
### Tweaking our question
-Okay, so that’s pretty useful, but it would be even *more* useful if we could know on *which days* our customers placed these big orders. That’s not hard to do at all.
+Okay, so that’s pretty useful, but it would be even _more_ useful if we could know in _which months_ our customers placed these big orders. That’s not hard to do at all.
-Back in the question builder box, next to **Count** in the View area, we’ll click on **Add a grouping.** This shows us a dropdown of columns that we can use to group our results by. the one we want is **Created At**, because this will now give us a separate total count of orders over $40 by the days the orders were placed (or “createdâ€). So we’ll select **Created At** and click **Run query** again.
+If we open up the Summarize sidebar again, below where we picked our metric, there's a list of all the columns that we can use as **groupings**. The one we want is **Created At**, because this will now give us a separate total count of orders over \$40 for each month the orders were placed in (or “created atâ€). So we’ll select **Created At**, and Metabase immediately shows us a line chart of the orders over time.
-This time our result looks different: instead of one big number, now we’re looking at a table that shows us how many orders over $40 there were each day. Neat, but this isn’t really a great way of visualizing this information.
+If we want to quickly check the results in tabular fashion, we can click the little toggle at the bottom center of the page to toggle from our chart to the data and back again.
-
+
### Changing the visualization
-Luckily enough, Metabase can present the answers to your questions in a variety of ways. To change the visualization, just select one of the options from the **Visualization** dropdown menu, which is in the top-left of the screen, above the table. Let’s choose **Area**.
+Metabase can present the answers to your questions in a variety of ways. To change the visualization, just select one of the options from the **Visualization** sidebar. Click the Visualization button in the bottom-left to open it. Let’s choose the **Area** chart option.
-Sweet! Looks like business is booming — up and to the right is always good. If you want, try playing around with other visualization options in from the dropdown.
+Sweet! Looks like business is booming — up and to the right is always good.
-You’ll notice that some formats aren’t the best way to show an answer to a question. If Metabase think that's the case with a specific answer and visualization, the choice will appear faded in the visualization dropdown menu. For example, it wouldn't make sense to show the total number of orders over $40 as a single bar graph, or as a map.
-
-If you want, you can try playing around with your question, like changing the number 40 to a different number. Whenever you make any changes to the question, the blue "Run query" button will reappear. Click it to ask your new question and get your new answer.
-
-
+You’ll notice that some visualizations aren’t the best way to show an answer to a question. If Metabase think that's the case with a specific answer and visualization combination, that visualization choice will appear faded in the sidebar. For example, it wouldn't make sense to show the total number of orders over \$40 as a single bar graph, or as a map.
+If you want, you can try playing around with your question, like changing the number 40 to a different number. To do that, just click on the filter badge below the page title.
## Sharing answers with others
+
You can use Metabase all on your own, but it becomes even more useful when you start sharing your answers with other people on your team or in your organization. The first step is saving some of your questions.
### Saving questions
-Sometimes you’ll find yourself asking certain questions again and again, whether it’s running regular reports, looking up something about an important segment of users, or just answering the same question for other people in your company. To keep from repeating the same set of steps each time you want to ask the same question, you can save your questions to use later.
+Sometimes you’ll find yourself asking certain questions again and again, whether it’s running regular reports, looking up something about an important segment of users, or just answering the same question for other people in your company. To keep from repeating the same set of steps each time you want to ask the same question, you can save your questions to use later.
To do this, click on the **SAVE** button in the top-right of the question builder screen.
-Metabase will take a stab at giving your question a meaningful name, but you can (and should) use your own naming convention that’ll help you and others find your questions later on, after amnesia has sunk in.
+Metabase will take a stab at giving your question a meaningful name, but you can (and should) use your own naming convention that’ll help you and others find your questions later on, after amnesia has sunk in. You can also pick which folder, or "Collection," to save your question in.
-Once you’ve saved your question, you can either go back to the home page, add your saved question to a dashboard, or keep asking questions. Let’s click **Add to a dashboard** and give that a try.
+Once you’ve saved your question, Metabase will ask if you want to add it to a new or existing dashboard. Let’s click **Create new dashboard** and give that a try. You’ll see a dialog that prompts you to create a new one and give it a name and description. Name it anything you’d like. We’ll call ours “My First Dashboard.â€
-
+
### Creating a dashboard
-Unless you went off and did your own thing, you shouldn’t have any dashboards yet, so you’ll see a dialog that prompts you to create a new one and give it a name and description. Name it anything you’d like. We’ll call ours “My First Dashboard.â€
+Dashboards are great when you have a set of answers that you want to view together. Your saved questions will be displayed as cards on the dashboard, which you can resize and move around to your heart’s content.
-
-
-Dashboards are great when you have a set of questions and answers that you want to view together. Your saved questions will be displayed as cards on the dashboard, which you can resize and move around to your heart’s content.
+So, after you click the button to create your dashboard, you should see your chart as a little card.
-So, after you click the button to create your dashboard, you should see your fancy saved question as a little card. Ain’t he cute?
+
-
-
-If you’re feeling up to it, you can click the edit button in the top-right of the screen (the one that looks like a pencil), and that’ll let you move and resize your saved question so you can get it looking just how you want it. Just click **Save** in the top-right when you’re done. We’ll make ours a bit wider to let those data points breathe.
+You can move and resize your chart so you can get it looking just how you want it. Just click **Save** in the top-right when you’re done. We’ll make ours a bit wider to let those data points breathe.
@@ -114,11 +112,8 @@ If you’re feeling up to it, you can click the edit button in the top-right of
One other thing: once you’ve asked a question or saved a dashboard, the URL in your browser will link directly to that question or dashboard. That means you can copy and paste that URL into an email or chat and let other people see what you’ve found. This will only work if Metabase is installed on a shared server, and will require creating Metabase accounts for the people you want to share with.
-
-
---
## That’s it!
-You’ve done really well. You now have a dashboard with your question that you can share! At this point you know enough to be dangerous.
-Want to learn more? Is your thirst for knowledge insatiable? Check out our [Users Guide](users-guide/start.md) for more in-depth explanations of the ins and outs of Metabase.
+We hope this was helpful. Want to learn more? Is your thirst for knowledge insatiable? Check out our [Users Guide](users-guide/start.md) for more in-depth explanations of the ins and outs of Metabase.
diff --git a/docs/images/ActivityFeed.png b/docs/images/ActivityFeed.png
deleted file mode 100644
index 528a25789f3c6ed63644c4c2a11a6bdd9c6efcab..0000000000000000000000000000000000000000
Binary files a/docs/images/ActivityFeed.png and /dev/null differ
diff --git a/docs/images/AddFilter.png b/docs/images/AddFilter.png
index 13d0b8de5a76ddc66be62731ae9d77b812c7834d..553bf1212eb99acf852e07c5f683c9546f55a58f 100644
Binary files a/docs/images/AddFilter.png and b/docs/images/AddFilter.png differ
diff --git a/docs/images/AddQuerytoDashboard.png b/docs/images/AddQuerytoDashboard.png
deleted file mode 100644
index 88ef95f8a335d0be44abf28daedceeb46fbf4e07..0000000000000000000000000000000000000000
Binary files a/docs/images/AddQuerytoDashboard.png and /dev/null differ
diff --git a/docs/images/AddQuestiontoDashboard.png b/docs/images/AddQuestiontoDashboard.png
deleted file mode 100644
index 61548bc207f480847cac99a63dc489f986fc393c..0000000000000000000000000000000000000000
Binary files a/docs/images/AddQuestiontoDashboard.png and /dev/null differ
diff --git a/docs/images/AreaChart.png b/docs/images/AreaChart.png
index c405ebbcee5a0325bee6290c3f77920171614834..606f37fd79918a8daffb731b8a2bcca4a8ab2617 100644
Binary files a/docs/images/AreaChart.png and b/docs/images/AreaChart.png differ
diff --git a/docs/images/CardSaved.png b/docs/images/CardSaved.png
deleted file mode 100644
index cedd76c07a7f090e25a84b50425c105e72971484..0000000000000000000000000000000000000000
Binary files a/docs/images/CardSaved.png and /dev/null differ
diff --git a/docs/images/Count.png b/docs/images/Count.png
index c8f9ded9c7f0f814eee91d755d1467d8f9303e84..7aaf914eeff6a2c6d79176798ffb99029ff56201 100644
Binary files a/docs/images/Count.png and b/docs/images/Count.png differ
diff --git a/docs/images/CountAnswer.png b/docs/images/CountAnswer.png
index ea453dd694480bc60622067b5e7af78cebdc96b0..d3aaf942ab1bbf802a072e64c825d815802a6083 100644
Binary files a/docs/images/CountAnswer.png and b/docs/images/CountAnswer.png differ
diff --git a/docs/images/CountByDay.png b/docs/images/CountByDay.png
deleted file mode 100644
index 8c21fb6e91838624f323fb7a03cac93ebb2a0fed..0000000000000000000000000000000000000000
Binary files a/docs/images/CountByDay.png and /dev/null differ
diff --git a/docs/images/CountByMonthTable.png b/docs/images/CountByMonthTable.png
new file mode 100644
index 0000000000000000000000000000000000000000..925114fb09a12895017fbe5ba0e9ce2ea8930d29
Binary files /dev/null and b/docs/images/CountByMonthTable.png differ
diff --git a/docs/images/CreateDashboard.png b/docs/images/CreateDashboard.png
index 35b3f8463a4f76ca416518e8a50ffb7378828667..cff7e7291d8fe93c0809227a0f68b3b04557bc88 100644
Binary files a/docs/images/CreateDashboard.png and b/docs/images/CreateDashboard.png differ
diff --git a/docs/images/CreatedAt.png b/docs/images/CreatedAt.png
index 4fd74cc75561b3ad7f9251bd87dc7d59a4d4ff8b..4997742ed2fbce43da7fe5e49f92aa48b48a94c0 100644
Binary files a/docs/images/CreatedAt.png and b/docs/images/CreatedAt.png differ
diff --git a/docs/images/DashboardCreatedSuccessfully.png b/docs/images/DashboardCreatedSuccessfully.png
deleted file mode 100644
index c98e7402b8e40cd575276b00e27319de4e795067..0000000000000000000000000000000000000000
Binary files a/docs/images/DashboardCreatedSuccessfully.png and /dev/null differ
diff --git a/docs/images/DashboardView.png b/docs/images/DashboardView.png
deleted file mode 100644
index d39f0023f9baa85353718a3875afc6b67e09a52d..0000000000000000000000000000000000000000
Binary files a/docs/images/DashboardView.png and /dev/null differ
diff --git a/docs/images/DataModelHelp1.png b/docs/images/DataModelHelp1.png
deleted file mode 100644
index 5653d06106464866eda81d5a6a788c2de1ba74a1..0000000000000000000000000000000000000000
Binary files a/docs/images/DataModelHelp1.png and /dev/null differ
diff --git a/docs/images/DataModelHelp2.png b/docs/images/DataModelHelp2.png
deleted file mode 100644
index c86df3dd2f1f516fb0a5692bb9335e08f207312b..0000000000000000000000000000000000000000
Binary files a/docs/images/DataModelHelp2.png and /dev/null differ
diff --git a/docs/images/DataModelHelp3.png b/docs/images/DataModelHelp3.png
deleted file mode 100644
index 916a8487cf85f71b0ae934c3f9bbd1d98d2a612e..0000000000000000000000000000000000000000
Binary files a/docs/images/DataModelHelp3.png and /dev/null differ
diff --git a/docs/images/DatabaseAdmin.png b/docs/images/DatabaseAdmin.png
deleted file mode 100644
index 7045cdafdf63abc3ff502f1d8a766447c5d9effb..0000000000000000000000000000000000000000
Binary files a/docs/images/DatabaseAdmin.png and /dev/null differ
diff --git a/docs/images/DatabaseConnected.png b/docs/images/DatabaseConnected.png
deleted file mode 100644
index acd4beb70d2ef1299235cf81e5be64cd1a8d05a3..0000000000000000000000000000000000000000
Binary files a/docs/images/DatabaseConnected.png and /dev/null differ
diff --git a/docs/images/DatabaseView.png b/docs/images/DatabaseView.png
deleted file mode 100644
index 17bec5a4d4e6b8ebce1661b074e4ae7cc9009194..0000000000000000000000000000000000000000
Binary files a/docs/images/DatabaseView.png and /dev/null differ
diff --git a/docs/images/DeleteDashboard.png b/docs/images/DeleteDashboard.png
deleted file mode 100644
index dd6183a531f879c6605cd8b7d5491c4d8b967dc8..0000000000000000000000000000000000000000
Binary files a/docs/images/DeleteDashboard.png and /dev/null differ
diff --git a/docs/images/EditDashboardCard.png b/docs/images/EditDashboardCard.png
deleted file mode 100644
index cfa3fbbbf0c187599d4b193c49503f257bf3fefe..0000000000000000000000000000000000000000
Binary files a/docs/images/EditDashboardCard.png and /dev/null differ
diff --git a/docs/images/EmptyHomepage.png b/docs/images/EmptyHomepage.png
new file mode 100644
index 0000000000000000000000000000000000000000..2e8268f72c56b86e54a4e43bcd365b4db41b21bb
Binary files /dev/null and b/docs/images/EmptyHomepage.png differ
diff --git a/docs/images/GroupingFeature.png b/docs/images/GroupingFeature.png
deleted file mode 100644
index 6ba3aa7862b77395f2b11472baecb3f20e9d0849..0000000000000000000000000000000000000000
Binary files a/docs/images/GroupingFeature.png and /dev/null differ
diff --git a/docs/images/MetabaseQuestion1.png b/docs/images/MetabaseQuestion1.png
deleted file mode 100644
index 4ab647d93ac017b0c9669b13d412feb53d1dc9e7..0000000000000000000000000000000000000000
Binary files a/docs/images/MetabaseQuestion1.png and /dev/null differ
diff --git a/docs/images/MetabaseQuestion1Answer.png b/docs/images/MetabaseQuestion1Answer.png
deleted file mode 100644
index 811b30f52a4fcf2b2d4bcc7fc4963d3e87a70ced..0000000000000000000000000000000000000000
Binary files a/docs/images/MetabaseQuestion1Answer.png and /dev/null differ
diff --git a/docs/images/NewDashboard.png b/docs/images/NewDashboard.png
new file mode 100644
index 0000000000000000000000000000000000000000..46d9a12707fc7bedc9c6ae2be5d0a9dacd7dd46f
Binary files /dev/null and b/docs/images/NewDashboard.png differ
diff --git a/docs/images/Orders.png b/docs/images/Orders.png
deleted file mode 100644
index dbcdf0a6ac89d5e5994e088ddc9432df3d65e3fe..0000000000000000000000000000000000000000
Binary files a/docs/images/Orders.png and /dev/null differ
diff --git a/docs/images/OrdersTable.png b/docs/images/OrdersTable.png
new file mode 100644
index 0000000000000000000000000000000000000000..2886ecb83fd88f841f90582556bc5888c8f84337
Binary files /dev/null and b/docs/images/OrdersTable.png differ
diff --git a/docs/images/ResizedChart.png b/docs/images/ResizedChart.png
index e4e78eb731afe85e120b99b7faa4dd995fdaf21c..6bd98b1748fb8a7571daf018b1aece44f4a2f1bb 100644
Binary files a/docs/images/ResizedChart.png and b/docs/images/ResizedChart.png differ
diff --git a/docs/images/SaveButton.png b/docs/images/SaveButton.png
index 19ed6570cf3d8c709c105bd0285cf12203da85dc..c265eeac15dc2f5a129c3cf8474f702573fef87b 100644
Binary files a/docs/images/SaveButton.png and b/docs/images/SaveButton.png differ
diff --git a/docs/images/SaveCardDialog.png b/docs/images/SaveCardDialog.png
deleted file mode 100644
index 91b0238a313c81830b670798b43139f002d7f729..0000000000000000000000000000000000000000
Binary files a/docs/images/SaveCardDialog.png and /dev/null differ
diff --git a/docs/images/SaveQuestionButton.png b/docs/images/SaveQuestionButton.png
deleted file mode 100644
index 3caabf0604c72a349aef77eeb7e3739b6c458021..0000000000000000000000000000000000000000
Binary files a/docs/images/SaveQuestionButton.png and /dev/null differ
diff --git a/docs/images/SaveQuestionDialog.png b/docs/images/SaveQuestionDialog.png
index e993964c319135bfa1711e000963a9fe1b45868a..09c892561214d0ce73952c975378826c596dca2a 100644
Binary files a/docs/images/SaveQuestionDialog.png and b/docs/images/SaveQuestionDialog.png differ
diff --git a/docs/images/SavedDashboard Copy.png b/docs/images/SavedDashboard Copy.png
deleted file mode 100644
index efcf501f23d2f3a70d5e03464d03889068fa2834..0000000000000000000000000000000000000000
Binary files a/docs/images/SavedDashboard Copy.png and /dev/null differ
diff --git a/docs/images/SavedDashboard.png b/docs/images/SavedDashboard.png
deleted file mode 100644
index ff6fde923b05db4b5952a99c543ebfecd4d621e9..0000000000000000000000000000000000000000
Binary files a/docs/images/SavedDashboard.png and /dev/null differ
diff --git a/docs/images/SavedQuestion.png b/docs/images/SavedQuestion.png
index 45dfb3dde67e1c249abcc24444cc7d0e3df3b8d1..a1bb261eef92326d846065481edb2fb609390437 100644
Binary files a/docs/images/SavedQuestion.png and b/docs/images/SavedQuestion.png differ
diff --git a/docs/images/ShareableURL.png b/docs/images/ShareableURL.png
deleted file mode 100644
index 19ed6570cf3d8c709c105bd0285cf12203da85dc..0000000000000000000000000000000000000000
Binary files a/docs/images/ShareableURL.png and /dev/null differ
diff --git a/docs/images/Subtotal.png b/docs/images/Subtotal.png
index 768f4ce36f07df4edf256ce4ce1b673314ba5d2a..11278329e2e2034786d1539f53adee8b3cc22743 100644
Binary files a/docs/images/Subtotal.png and b/docs/images/Subtotal.png differ
diff --git a/docs/images/TableInterface.png b/docs/images/TableInterface.png
deleted file mode 100644
index a3658ccc0f75a3bb95b56c1aa520dbf3d9159e90..0000000000000000000000000000000000000000
Binary files a/docs/images/TableInterface.png and /dev/null differ
diff --git a/docs/images/VisualizationMenu.png b/docs/images/VisualizationMenu.png
index bc7b5fefbda1c983aeb83efefbcb40bbf75477a7..47444bdbfc2b1fae05bafa08fa771ab790c89646 100644
Binary files a/docs/images/VisualizationMenu.png and b/docs/images/VisualizationMenu.png differ
diff --git a/docs/users-guide/01-what-is-metabase.md b/docs/users-guide/01-what-is-metabase.md
index 1ed4cc455ccc0e06349abd3771c3ab02793a716c..f5bc64ddeca338fee28c1243841ea8ac63c0d65d 100644
--- a/docs/users-guide/01-what-is-metabase.md
+++ b/docs/users-guide/01-what-is-metabase.md
@@ -10,16 +10,17 @@ So, you've [gotten Metabase up and running](../operations-guide/start.md) and [c
### The home page
-
+
Fresh out of the box, Metabase will show you a few things on the home page:
-* Some [automatic explorations](14-x-rays.md) of your tables that you can look at and save as a dashboard if you like any of them.
-* An area where things you or your teammates create will show up, along with a link to see all the dashboards, questions, and pulses you have.
-* A list of the databases you've connected to Metabase.
+
+- Some [automatic explorations](14-x-rays.md) of your tables that you can look at and save as a dashboard if you like any of them.
+- An area where things you or your teammates create will show up, along with a link to see all the dashboards, questions, and pulses you have.
+- A list of the databases you've connected to Metabase.
-Once you've created some [dashboards](07-dashboards.md), any of them that you pin will show up on the homepage for all of your teammates, so that when they log in to Metabase they'll know right where to go.
+Once you've created some [dashboards](07-dashboards.md), any of them that you pin in the main "Our analytics" collection will show up on the homepage for all of your teammates, so that when they log in to Metabase they'll know right where to go.
### Browse your data
@@ -33,7 +34,7 @@ As you and your team create dashboards and collections, they'll start to show up
### Ask a question or write a query
-Click the `Ask a question button` in the top-right of Metabase to start a new custom exploration of one of your tables, or to write a new SQL or native query if you want to really dig in.
+Click the `Ask a question` button in the top-right of Metabase to start a new simple exploration of one of your tables, ask a more detailed custom question using the notebook editor, or write a new SQL query if you want to really dig in.
### Make a new dashboard or pulse
@@ -47,7 +48,7 @@ To make a dashboard or pulse, click the plus (+) icon in the top-right of the ma
-The search bar that's always present at the top of the screen lets you search through your dashboards, collections, saved questions, and pulses in an instant. Just type part of the title of the thing you're looking for and hit enter.
+The search bar that's always present at the top of the screen lets you search through your tables, dashboards, collections, saved questions, metrics, segments, and pulses in an instant. Just type part of the title of the thing you're looking for and hit enter. You can activate the search bar from anywhere by pressing the `/` key.
## A primer on databases
diff --git a/docs/users-guide/02-database-basics.md b/docs/users-guide/02-database-basics.md
index 958cbc152bea916fe41ad8d0c879c63a7a7fe0fc..104a609e7c1f820b44edbfc3288ffd831950b87e 100644
--- a/docs/users-guide/02-database-basics.md
+++ b/docs/users-guide/02-database-basics.md
@@ -1,8 +1,10 @@
-### A Short Overview of Databases
+## A Short Overview of Databases
+
Before you jump into working with Metabase, it's helpful to know a few key database terms.
#### Tables
-Fundamentally, databases are *collections of tables*. Tables contain one or more *columns* and one or more *rows*. A row is made up of *cells*, and each cell has a *value* that corresponds to the column it falls under.
+
+Fundamentally, databases are _collections of tables_. Tables contain one or more _columns_ and one or more _rows_. A row is made up of _cells_, and each cell has a _value_ that corresponds to the column it falls under.
Here's an example of a table:
@@ -14,64 +16,64 @@ Here's an example of a table:
Here, the columns are `Name` and `Age`. The first row contains two cells, one with `John` and one with `25`, corresponding to the Name and Age columns, respectively.
#### Columns
-All the cells in a column contain the same type of information. For example, in the sample table above, the `Name` column contains names in each cell, while the `Age` column lists ages.
-Columns are also sometimes interchangeably referred to as *fields*. Each field has a type that describes what kind of data is stored in the field.
+All the cells in a column contain the same type of information. For example, in the sample table above, the `Name` column contains names in each cell, while the `Age` column lists ages.
+Columns are also sometimes interchangeably referred to as _fields_. Each field has a type that describes what kind of data is stored in the field.
**Examples of types:**
-* **String Types** (TEXT, CHAR, VCHAR, etc.) - In the world of technology, snippets of text are referred to as “strings.†(You’ve probably heard of a “string of text†before.) These fields store things like names, addresses, or anything else that is text.
+- **String Types** (TEXT, CHAR, VCHAR, etc.) - In the world of technology, snippets of text are referred to as “strings.†(You’ve probably heard of a “string of text†before.) These fields store things like names, addresses, or anything else that is text.
-* **Numerical Types** (Integer, Float, DoubleFloat, Decimal, etc.) - These fields store numbers. Integers are whole numbers; Floats and Decimals are ways to store numbers with decimals in them. Numerical types store things like ages, bank account balances, costs, latitudes, and longitudes.
+- **Numerical Types** (Integer, Float, DoubleFloat, Decimal, etc.) - These fields store numbers. Integers are whole numbers; Floats and Decimals are ways to store numbers with decimals in them. Numerical types store things like ages, bank account balances, costs, latitudes, and longitudes.
-* **Time Types** (Timestamp, etc.) - These fields are a special number format used to store dates and times (or both), called “timestamps.†Sometimes databases store an integer timestamp which is either seconds or milliseconds, such as `00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970`. This convention allows for compact storage of timestamps.
+- **Time Types** (Timestamp, etc.) - These fields are a special number format used to store dates and times (or both), called “timestamps.†Sometimes databases store an integer timestamp which is either seconds or milliseconds, such as `00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970`. This convention allows for compact storage of timestamps.
-* **IDs** (also called **primary keys**) - This field in a table uniquely identifies each row. For example, imagine a car reservation app where you can book a car in advance. The ID of the reservation could be the reservation number, and no two reservations would share the same reservation number, allowing each reservation to be uniquely identified by its reservation number.
+- **IDs** (also called **primary keys**) - This field in a table uniquely identifies each row. For example, imagine a car reservation app where you can book a car in advance. The ID of the reservation could be the reservation number, and no two reservations would share the same reservation number, allowing each reservation to be uniquely identified by its reservation number.
**Example**
-*Reservations Table*
-
-| Reservation ID | Name | Age |
-| -------------- | ----- | ---- |
-| 11 | John | 25 |
-| 12 | Jenny | 31 |
+_Reservations Table_
-In the above table, the `Reservation ID` field is the ID (primary key). The `Name` field is a string type and the `Age` field is a numerical type (specifically an Integer).
+| Reservation ID | Name | Age |
+| -------------- | ----- | --- |
+| 11 | John | 25 |
+| 12 | Jenny | 31 |
+In the above table, the `Reservation ID` field is the ID (primary key). The `Name` field is a string type and the `Age` field is a numerical type (specifically an Integer).
#### Relationships
+
Tables can contain references to other tables, which establishes a relationship between them.
-For example, in our hypothetical car booking app’s database, we could have two tables: one for reservations (let's call it **Reservations**) and one for customers, (we'll call this one **Customers**).
+For example, in our hypothetical car booking app’s database, we could have two tables: one for reservations (let's call it **Reservations**) and one for customers, (we'll call this one **Customers**).
-To connect the reservation data to the corresponding customer data, you can use a *foreign key*. A foreign key is a special kind of field in a table that references the same column in a different table. Almost always, the field that the foreign key points to is the *ID* or *primary key* in the other table.
+To connect the reservation data to the corresponding customer data, you can use a _foreign key_. A foreign key is a special kind of field in a table that references the same column in a different table. Almost always, the field that the foreign key points to is the _ID_ or _primary key_ in the other table.
For example, in our hypothetical car booking app, we could connect each reservation in the Reservations table to the corresponding customer that made the reservation by having the `Customer` column of the reservation contain the same value as the `ID` column of the customer who made the reservation.
**Reservations**
-| Customer | Date | Car |
-| ---- | --- | --- |
-| 11 | 12/20/2015 | Toyota Camry |
-| 12 | 1/2/2016 | Range Rover |
-
+| Customer | Date | Car |
+| -------- | ---------- | ------------ |
+| 11 | 12/20/2015 | Toyota Camry |
+| 12 | 1/2/2016 | Range Rover |
**Customers**
-| ID | Name| Age |
-| ---- | --- | --- |
-| 11| John | 25 |
-| 12| Jenny | 31 |
+| ID | Name | Age |
+| --- | ----- | --- |
+| 11 | John | 25 |
+| 12 | Jenny | 31 |
If we wanted to analyze our hypothetical app's database with Metabase, we could ask a question, like:
What's the average age of all customers who made reservations in February of 2015?
-To do this, we’d open up the Reservation table, add a filter to only look at reservations between February 1 and February 28, 2015, select Average for the View. For the Field, now we put our foreign key to use and select Age from the *Customers* table that our Reservations table references — each reservation will now have a corresponding customer age, matched up by the customer ID.
+To do this, we’d open up the Reservation table, add a filter to only look at reservations between February 1 and February 28, 2015, and select `Average of…`. To select the average of Age specifically, we now put our foreign key to use and select Age from the _Customers_ table that our Reservations table references.
---
## Next: Asking questions
+
Now that we have a shared vocabulary and a basic understanding of databases, let's learn more about [exploring in Metabase](03-basic-exploration.md)
diff --git a/docs/users-guide/03-basic-exploration.md b/docs/users-guide/03-basic-exploration.md
index abbf589474ea01a34345e518b997a96c2775d0fa..c5c200222cd754d3323ade41fb045f24bff2c8f7 100644
--- a/docs/users-guide/03-basic-exploration.md
+++ b/docs/users-guide/03-basic-exploration.md
@@ -1,63 +1,59 @@
-### Exploring in Metabase
+## Exploring in Metabase
#### See what your teammates have made
+
As long as you're not the very first user in your team's Metabase, the easiest way to start exploring your data is by looking at dashboards, charts, and lists that your teammates have already created. The best place to start is by checking out any dashboards that might be pinned on your home page or in the collections you have access to.
#### Browse your data
-Alternatively, you can dive right in to exploring the data in Metabase by clicking on one of the databases at the bottom of the home page, and then clicking on a table to see it. You can also click on the bolt icon on any table to see an automatic exploration of its data. Give it a try!
+
+Alternatively, you can dive right in to exploring the data in Metabase by clicking on one of the databases at the bottom of the home page or clicking the "Browse data" button in the top nav bar, and then selecting a database and clicking on one of its tables to see it. You can also click on the bolt icon on any table to see an automatic exploration of its data. Give it a try!
#### Exploring collections
+
Collections in Metabase are a lot like folders. They're where all your team's dashboards and charts are kept. To explore a collection just click on one in the "Our analytics" section of the home page, or click on `Browse all items` to see everything.
-If your teammates are cool, they'll have pinned some important dashboards or questions within your collections; if so, those important or useful items will show up nice and large at the top of a collection. Collections also have a list of any other items that are saved within them, as well as a list of other collections that are saved inside the current one.
+If your teammates are cool, they'll have pinned some important dashboards or questions within your collections; if so, those important or useful items will show up nice and large at the top of a collection. Any dashboards that are pinned in the top-level, "Our Analytics" collection will also show up on the Metabase homepage.
+
+Collections also have a list of any other items that are saved within them, as well as a list of other collections that are saved inside the current one.
#### Exploring dashboards
-Dashboards are simply collections of charts and numbers that you want to be able to refer back to regularly. You can learn more about dashboards [here](07-dashboards.md).
+
+Dashboards are simply collections of charts and numbers that you want to be able to refer back to regularly. [Learn more about dashboards](07-dashboards.md).
If you click on a part of a chart, such as a bar in a bar chart, or a dot on a line chart, you'll see a menu with actions you can take to dive deeper into that result, to branch off from it in a different direction, or to [x-ray](14-x-rays.md) it to see an automatic exploration of the thing you clicked on.
In this example of pie orders by type over time, clicking on a dot on this line chart gives us the ability to:
+
- **Zoom in** — i.e., see just the banana cream pie orders in June 2017 over time
- **View these Orders** — which lets us see a list of banana cream pie orders in June 2017
- **Break out by a category** — this lets us do things like see the banana cream pie orders in June 2017 broken out by the status of the customer (e.g., `new` or `VIP`, etc.) or other different aspects of the order. Different charts will have different break out options, such as Location and Time.
**Note that charts created with SQL don't currently have these action options.**
-Other charts as well as table cells will often also allow you to go to a filtered view of that chart or table. You can click on one of the inequality symbols to see that chart where, for example, the value of the Subtotal column is less than $100, or where the Purchased-at timestamp is greater than (i.e., after) April 1, 2017.
+Other charts as well as table cells will often also allow you to go to a filtered view of that chart or table. For example, You can click on one of the inequality symbols to see that chart where the value of the Subtotal column is less than \$100, or where the Purchased-at timestamp is greater than (i.e., after) April 1, 2017.
Lastly, clicking on the ID of an item in a table gives you the option to go to a detail view for that single record. (E.g., you can click on a customer's ID to see the profile view for that one customer.)
#### Exploring saved questions
-In Metabase parlance, every chart or number on a dashboard is called a "question." Clicking on the title of a question on a dashboard will take you to a detail view of that question. You'll also end up at this detail view if you use one of the actions mentioned above.
-
-When you're looking at the detail view of a question, you can use all the same actions mentioned above. You can also click on the headings of tables to see more options, like viewing the sum of the values in a column, or finding the minimum or maximum value in it.
-
+In Metabase parlance, every chart on a dashboard is called a "question." Clicking on the title of a question on a dashboard will take you to a detail view of that question. You'll also end up at this detail view if you use one of the actions mentioned above.
-Additionally, the question detail page has an Explore button in the bottom-right of the screen with options that change depending on the kind of question you're looking at. (Note that the Explore button disappears if your cursor stops moving.)
+When you're looking at the detail view of a question, you can use all the same actions mentioned above. You can also click on the headings of tables to see more options, like summing the values of a column, or filtering based on that column.
-
+One of our personal favorite ways to explore is with the Distribution option. This will show you how many rows there are in a given table, grouped by column you clicked on. So if you have a Users table, if you click on an Age column and select Distribution, you'll see a bar chart with the count of users you have in each age bracket.
-Here's a list of all the actions:
-* **Table actions**
- - `X-ray this` will show you an automatic exploration and summary of the data in this table. [Learn more about x-rays](14-x-rays.md)
- - `Count of rows by time` lets you see how many rows there were in this table over time.
- - `Summarize this segment` gives you options of various summarization functions (sum, average, maximum, etc.) you can use on this table to arrive at a number.
-* **Chart and pivot table actions**
- - `Break outs` will be listed depending on the question, and include the option to break out by a category, location, or time. For example, if you're looking at the count of total orders over time, you might be able to further break that out by customer gender, if that information is present.
- - `View this as a table` does what it says. Every chart has a table behind it that is providing the data for the chart, and this action lets you see that table.
- - `View the underlying records` shows you the un-summarized list of records underlying the chart or number you're currently viewing.
- - `X-ray this question` will show you an automatic [x-ray]((14-x-rays.md)) exploration of this question's results.
+
---
## Next: Asking custom questions
+
So what do you do if you can't find an existing dashboard or question that's exactly what you're looking for? Let's learn about [asking our own new questions](04-asking-questions.md)
diff --git a/docs/users-guide/04-asking-questions.md b/docs/users-guide/04-asking-questions.md
index b7e9413788f2afd46c4a392c35e995c409488fd5..b23c27688f6502e244686e9bb197bf6a014a12a0 100644
--- a/docs/users-guide/04-asking-questions.md
+++ b/docs/users-guide/04-asking-questions.md
@@ -1,227 +1,118 @@
+## Asking questions in Metabase
-## Asking custom questions
----
-Metabase's two core concepts are questions and their corresponding answers. Everything else is based around questions and answers. To ask Metabase a question, click the New Question button at the top of the screen.
+Metabase's two core concepts are questions and their corresponding answers. Everything else is based around questions and answers. To ask a question in Metabase, click the Ask a Question button at the top of the screen.
### Ways to start a new question
-If an administrator has [defined some metrics](../administration-guide/07-segments-and-metrics.md), when you click on the `Ask a question` button in the top bar you'll see a screen like this one:
-
-
-
-You can start your new question:
-- from an existing metric
-- from scratch with the Question Builder interface
-- using the SQL / native query editor
-
-Asking a new question about a **metric** is often a great place to start.
-
-#### Asking a new question about a metric
-
-A **metric** is a numeric measurement of something your company wants to track, like revenue, the total number of users, or the number of events that have occurred. So if you have a question like, "how many users have we had in the last 30 days?", then you could start by finding a metric like "Total Users" from your company's list of metrics, and then filtering it down to the time period you care about. Clicking on the metric option will show you a list of your company's metrics:
-
-
-
- Clicking on a metric will show you that number. From there, you can click directly on the number to break it out in interesting ways — like by day, by state, by customer, etc.:
-
-
-
-You can also use the Action Menu in the bottom-right of the screen to choose a break out, or to see the table data that the metric uses:
-
-
-
-#### Asking a new question about a table
-
-Another quick way to start a new question is by clicking on one of your connected databases at the bottom of the homepage, and picking a table that you have a question about. You'll immediately see the table and the graphical question builder so that you can keep exploring.
-
-
-
-When viewing a table you can also click on the headings of columns to see options for ways to explore more, like clicking on the Age column of your Users table to see how many Users you have per age group (that's called a "distribution"):
-
-
-
-You can also use the Action Menu when viewing a table to see any metrics in it, or to summarize the table.
-
-
-
-#### Asking a new custom question
-
-If you have a question that isn't covered by an existing question, you can create a new custom question using the Question Builder interface by clicking "Custom." Or, if you're an advanced user, you can click "SQL" to go straight to the SQL/native query editor.
-
-
-### Using the Question Builder interface
-
-Metabase has a simple graphical question builder that looks like this:
-
-
-
-The question builder is made up of four distinct sections, from left to right:
-- **Data**, where you pick the source data you want to ask a question about
-- **Filters**, where you can optionally add one or more filters to narrow down your source data
-- **View**, where you choose what you want to see — raw table data, a basic metric, or a "common" metric that an administrator has defined
-- **Groupings**, where you can group or break out your metric by time, location, or other categories
-
-#### Source data
----
-All of the data in databases are in tables. Typically, tables will be named for the thing that each row in the table contains. For example, in a Customers table, each row in the table would represent a single customer. This means that when you’re thinking about how to phrase your question, you’ll need to decide what your question is about, and which table has that information in it.
-
-The first dropdown menu in the question builder is where you’ll choose the database and table you want.
+
-##### Using saved questions as source data
+When you click the Ask a Question button, you'll see that there are three ways to ask a specific question in Metabase:
-If you've [saved some questions](06-sharing-answers.html), in the Data menu you'll see the option to use one of your saved questions as source data. What this means in practice is that you can do things like use complex SQL queries to create new tables that can be used in a question just like any other table in your database.
+1. The simple question mode, which lets you filter, summarize, and visualize data.
+2. [The custom question mode](custom-questions.md), which gives you a powerful notebook-style editor to create more complex questions that require joins, multiple stages of filtering and aggregating, or custom columns.
+3. [The SQL/native query editor](writing-sql.md).
-You can use most saved questions as source data, provided you have [permission](../administration-guide/05-setting-permissions.html) to view that question. You can even use questions that were saved as a chart rather than a table.
+This page will cover the simple mode.
-**Note:** there are some kinds of saved questions that can't be used as source data:
-- Druid questions
-- Google Analytics 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`
-
-#### Filters
----
-Filtering your data lets you exclude information that you don’t want. You can filter by any field in the table you're working with, or by any tables that are connected through a foreign key. Filters narrow down the source data to an interesting subset, like "active users" or "bookings after June 15th, 2015."
+### Asking a simple question
-Different fields will have different filter options based on what kind of data type they are. There are four universal filter options, or “operators,†that can be applied to any field. These operators are:
+After you select the Simple Question option, you'll need to pick some data that you have a question about. Just pick one of the databases that's connected to Metabase, and you'll see a list of all the tables inside of it. Pick the one that you have a question about; it could be a Users table, or maybe it's something like Events, Orders, or Downloads.
-* *is a value,* e.g., "Status is 'closed'"
-* *is not a value,* e.g., "Status is not 'closed'"
-* *is null*, i.e., the cell in the field is empty
-* *is not null*, i.e., the cell in the field isn’t empty
+To ask a question about a table of data, we usually do some **filtering** and/or **summarizing**.
-Some fields have a limited number of possible operators. Metabase will pick up on this and limit the choices in the filter selection to only valid values. Some fields (e.g., a number field like Price) will have many possible operators.
+#### Filtering
-Fields that are comparable, like numbers or dates, can also be filtered using the following operators:
+Filtering just means narrowing things down based on certain criteria. You're probably already familiar with filtering when looking for something online, like when shopping. Maybe you only want to see olive-colored pants, or books where the author's last name is "Steinbeck," or pictures of people wearing olive-colored pants reading John Steinbeck.
-* *Less than* a value you enter
-* *Greater than* a value you enter
-* *Between* two values you enter
+You can do the same kind of thing with data in Metabase. Just click the Filter button in the top-right of the screen to open the filter sidebar. You'll see a list of all of the columns in this table, as well as columns from tables that are related to the one you're looking at. Depending on the column you pick, you'll see slightly different options for your filter.
-##### Filtering by dates
+Broadly speaking, there are three types of columns, each with their own set of filtering options:
-If filtering by dates, a date picker will appear to allow you to select dates easily, and will default to the previous 30 days.
+1. **Numerics columns** let you add filters to only include rows in your table where this number is between two specific values, or is greater or less than a specific value, or is exactly equal to something.
+2. With **text or category columns**, you can specify that you only want to include data where this column is or isn't a specific option, or you can exclude rows that don't have a value for this column.
+3. **Date** columns give you a calendar or input box so that you can select specific time ranges, or choose all days before or after a certain date.
-Click on the first dropdown to change the kind of date filter you're using. The rest of the popup menu will change depending on this first selection.
-
-One important thing to understand when filtering by time or dates like this is the difference between specific and relative dates:
+One important thing to understand when filtering on a date column is the difference between specific and relative dates:
**Specific dates** are things like November 1, 2010, or June 3 – July 12, 2017; they always refer to the same date(s).
-**Relative dates** are things like "the past 30 days," or "the current week;" as time passes, the dates these refer to change. Relative dates are a useful way to set up a filter on a question so that it stays up to date by showing you for example how many users visited your website in the last 7 days.
+**Relative dates** are things like "the past 30 days," or "the current week;" as time passes, the dates these refer to _change_. Relative dates are a useful way to set up a filter on a question so that it stays up-to-date by showing you for example how many users visited your website in the last 7 days.
-##### Using segments
-If your Metabase administrators have created special named filters for the table you're viewing they’ll appear at the top of the filter dropdown in purple text with a star next to them. These are called "segments," and they're shortcuts to filters that are commonly used in your organization. They might be called things like “Active Users,†or “Most Popular Products.â€
+##### Filtering by a segment
-#### Selecting answer output in the View section
----
-The next section of the question builder is where you select what you want the output of your answer to be, under the View dropdown. You’re basically telling Metabase, “I want to view…†Metabase can output the answer to your question in four different ways:
+If your Metabase administrators have created special named filters for the table you're viewing, they’ll appear at the top of the filter dropdown in purple text with a star next to them. These are called "segments," and they're shortcuts to a combination of filters that are commonly used in your organization. They might be called things like “Active Users,†or “Most Popular Products.â€
-##### 1. Raw data
-Raw Data is just a table with the answer listed in rows. It's useful when you want to see the actual data you're working with, rather than a sum or average, etc., or when you're exploring a small table with a limited number of records.
+Once you're happy with your filter, click Done, and your data will be updated with your filter applied. If you want to edit your filter, just click the little purple token at the top of the screen. If you click on the X, you'll remove your filter. You can add as many filters as you need.
-When you filter your data to see groups of interesting users, orders, etc., Raw Data will show you an output of each individual record that matches your question's criteria.
+
-##### 2. Basic metrics
+#### Summarizing
-What's a *metric*? It's a number that is derived from your source table and takes into consideration any filters you asked Metabase to apply to your question. So when you select one of these metrics, your answer will come back in the form of a number. You can add additional metrics to your question using the `+` icon next to your selected metric.
+When we have a question like "how many people downloaded our app each day this week?" or "what's the average age of customers who visit each of our stores on the weekend?", we're asking for a **summary** of the data. A summary is usually made up of two parts: one or more _numbers_ we care about (called a "metric" in data-speak), and how we want to see that number _grouped_ or _broken out_. So in our first example:
-The different basic metrics are:
+- the metric is "how many people downloaded our app"
+- we want that metric to be grouped by "each day"
+- and "this week" is a filter
-* **Count of rows:** The total of number of rows in the answer. Each row corresponds to a separate record. If you want to know how many orders in the Orders table were placed with a price greater than $40, you’d filter by “Price greater than 40,†and then select Count, because you want Metabase to count how many orders matched your filter.
-* **Sum of …:** Sum of all the values in a column. This is really easy to get mixed up with Count — just remember that Count counts each *row*, but Sum adds up all the values in a single field. You’d use Sum to get your total revenue dollar amount, for example.
-* **Average of …:** Average of all the values in a column.
-* **Number of distinct values of…:** Number of unique values in all the cells of a single column. This would be useful to find out things like how many different *types* of products were sold last month (not how many were sold in total).
-* **Cumulative sum of…:** This gives you a running total of a specific column. This will look exactly the same as Sum unless you break out your answer by day, week, month, etc. (See the next section about breaking out metrics.) An example would be total revenue over time.
-* **Cumulative count of rows:** This gives you a running total of the number of rows in the table over time. Just like `Cumulative sum of…`, this will look exactly the same as `Count of rows` unless you break out your answer a time field.
-* **Standard deviation of …:** A number which expresses how much the values of a column vary, plus or minus, from the average of that column.
-* **Minimum of …:** The minimum value present in the selected field.
-* **Maximum of …:** The maximum value present in the selected field.
+There are two very common ways you'll tend to summarize your data:
-##### 3. Common metrics
+- Counting the number of rows in your table
+- Getting the sum or average of a numeric column
-If your admins have created any named metrics 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.
+And a lot of the time, you'll then **group** that number by:
-##### 4. Custom expressions
-Custom expressions allow you to do simple arithmetic within or between aggregation functions. For example, you could do `Average(FieldX) + Sum(FieldY)` or `Max(FieldX - FieldY)`, where `FieldX` and `FieldY` are fields in the currently selected table. You can either use your cursor to select suggested functions and fields, or simply start typing and use the autocomplete. If you are a Metabase administrator, you can now also use custom aggregation expressions when creating defined common metrics in the Admin Panel.
+- Time
+- Place
+- Some other category like operating system, gender, state, etc.
-Currently, you can use any of the basic aggregation functions listed in #2 above in your custom expression, and these basic mathematical operators: `+`, `-`, `*` (multiply), `/` (divide). You can also use parentheses to clarify the order of operations.
+To do this in Metabase, click the Summarize button in the top-right of the screen, and the summary sidebar will open up.
-#### Breaking out metrics: adding a grouping
----
-Metrics are great by themselves if the answer you’re looking for is just a simple, single number. But often you'll want to know more detailed information than that. For example, the sum of all invoiced amounts is a metric. It's natural to want to look at this metric across time or another grouping, such as whether the invoices are paid or not.
-
-You can do this by adding a **Grouping** to your question. You can break out your answer by any date or time in your table, or by any category field. These groupings are called *dimensions*.
-
-If you apply a *single dimension* to your question, you get a table where the leftmost column is the dimension and the rightmost column is the value of the metric for that dimension's value. You can visualize this in several ways, like a line or bar graph, with the value as the y-axis, and the dimension as the x-axis.
+
-*Two dimension* breakouts are equivalent to a pivot table in Excel, and are one of the workhorses of the business intelligence world. For example, we might want to know how many orders we had per state per month. If we want to try this with the Sample Dataset, we’d open the Orders table, skip the filters, then choose "Count or rows," and then add groupings by User:State and Created At: Month. The result is a table where the first row and column have the month and state information, and where the rest of the cells are the number of orders. (If you don't want your table to be pivoted, you can turn this option off by clicking the gear icon near the top-left of your table.)
-
-If you add more dimensions, you will add columns to the left of the metric.
-
-### Additional Options
----
-Click on the three dots on the far right hand side of the question builder bar to open up these additional settings:
+##### Picking metrics
-
+The sidebar has two main parts: the top is where you pick the number ("metric") you want to see, and the part below it is where you pick how to group that number (or how to "break it out").
-* Sort by a column: either by clicking on the column header or by selecting the column in the advanced section.
-* Limit your results to 1, 10, 25, 100, or more rows.
-* Create a custom field using math
+By default the "count of rows" metric will be selected, since it's super common, but you can change it to something else by clicking on it. You can also select more than one metric to view: just click the "add a metric" button. You can remove any selected metric by clicking on the X icon. The different basic metrics are:
-#### Creating a custom field
-A custom field is helpful if you need to create a new field based on a calculation, such as subtracting the value of one field from another.
+- **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.
+- **Average of …:** the average of all the values in a single column.
+- **Number of distinct values of…:** the number of unique values in all the cells of a single column. This is useful when trying to find out things like how many different _types_ of products were sold last month (not how many were sold in total).
+- **Cumulative sum of…:** This gives you a running total for a specific column. In order for this metric to be useful you'll need to group it by a date column to see it across time.
+- **Cumulative count of rows:** This gives you a running total of the number of rows in the table over time. Just like `Cumulative sum of…`, you'll need to group this by a date column in order for it to be useful.
+- **Standard deviation of …:** A number which expresses how much the values of a column vary, plus or minus, from the average value of that column.
+- **Minimum of …:** The minimum value present in the selected field.
+- **Maximum of …:** The maximum value present in the selected field.
-
+If your admins have created any named metrics 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.
-Say we had a table of baseball games, each row representing a single game, and we wanted to figure out how many more runs the home team scored than the away team (the “run differentialâ€). If we have one field with the home team’s score, and another field with the away team’s score, we could type a formula like this:
+##### Picking a grouping for your metrics
-
+Depending on the grouping column you select, Metabase will show you what it thinks is the best default visualization or chart for this summary. So if you select a date column, you'll see a line chart like this:
-The words in the quotes are the names of the fields in our table. If you start typing in this box, Metabase will show you fields in the current table that match what you’ve typed, and you can select from this list to autocomplete the field name.
+
-Right now, you can only use the following math operators in your formulas: `+`, `–`, `*` (multiplication), and `/` (division). You can also use parentheses to clarify the order of operations.
+When you click on a different grouping column than the one you currently have selected, the grouping will switch to use that column instead. But if you want to _add_ an additional grouping, just click the plus (+) icon on the right side of the column. To remove a grouping, click on the X icon.
-Once you’ve written your formula and given your new field a name, select `Raw Data` for your view, and click the `Get Answer` button to see your new field appended to your current table. It’ll be on the far right of the table. **Note that this new field is NOT permanently added to this table.** It will only be kept if you save a question that uses it.
+
-Here’s our result:
+Some grouping columns will give you the option of choosing how big or small to make the groupings. So for example, if you've picked a Date column to group by, you can click on the words `by month` to change the grouping to day, week, hour, quarter, year, etc. If you're grouping by a numeric column, like age, Metabase will automatically "bin" the results, so you'll see your metric grouped in age brackets, like 0–10, 11–20, 21–30, etc. Just like with dates, you can click on the current binning option to change it to a specific number of bins. It's not currently possible to choose your own ranges for bins, though.
-
+
-Now we can use this new field just like any other field, meaning we can use it to filter our question, add a grouping with it, or find out things like the average of this field. You can add multiple custom fields, and they’ll all show up at the top of drop downs within the question builder:
+Once you're done setting your metrics and groupings, click Done to close the Summarize sidebar and see your results in all their glory.
-
+If you want to jump ahead and learn about [how to change the visualization](05-visualizing-results.md) of your results, by all means, feel free.
+### Viewing an individual record's details
-### Digging into individual records
----
Click on a record's ID number (or primary key) to see more information about a given user, order, venue, etc. You can see all fields related to that one record and all connected tables that are hidden in the table view for the sake of readability. Press the right or left arrow keys, or click on the arrows to the right or left of the screen to page through the other records in the current list.
-## Asking more advanced questions in the SQL/native query editor
----
-If you ever need to ask questions that can't be expressed using the question builder, you can use **SQL** instead.
-
-### What's SQL?
-
-SQL (pronounced "sequel") stands for Structured Query Language, and is a widely used standard for getting data from databases. To learn more about it, check out this [SQL Tutorial](http://www.w3schools.com/sql/default.asp).
-
-Even if you don't understand SQL or how to use it, it's worthwhile to understand how to use it inside Metabase because sometimes other people will share SQL-based questions that might be useful to you.
-
-### Using SQL
-You can switch a card from question builder mode to SQL mode by clicking on the "**>_**" button in the upper right hand corner.
-
-
-
-You can write SQL (or your database's native querying language) directly into the text box that appears.
-
-
-
-To try it out, type the command `select sum(subtotal), created_at from orders group by created_at`. Don't worry if you don't understand this just yet. Click **Run query** and note the table that comes back is the same as if you had asked for the sum of Subtotal in the Orders table, grouped by Created At.
-
-Questions asked using SQL can be saved, downloaded, or added to a dashboard just like questions asked using the question builder.
+
---
-## Next: Creating charts
-Once you have an answer to your question, you can now learn more about [visualizing answers](05-visualizing-results.md).
+## Next: creating custom questions
+
+If you have a question that's a bit more involved or specific, you can use the powerful notebook editor to craft a [custom question](custom-questions.md).
diff --git a/docs/users-guide/05-visualizing-results.md b/docs/users-guide/05-visualizing-results.md
index 90981da144b440435b61792108e842e2827f9b29..c5157375cf3a2087f29ca493c5795f9b5de55c14 100644
--- a/docs/users-guide/05-visualizing-results.md
+++ b/docs/users-guide/05-visualizing-results.md
@@ -1,56 +1,60 @@
## Visualizing results
----
+
While tables are useful for looking up information or finding specific numbers, it's usually easier to see trends and make sense of data overall using charts.
In Metabase, an answer to a question can be visualized in a number of ways:
-* [Number](#numbers)
-* [Smart number](#smart-numbers)
-* [Progress bar](#progress-bars)
-* [Gauge](#gauges)
-* [Table](#tables)
-* [Line chart](#line-bar-and-area-charts)
-* [Bar chart](#line-bar-and-area-charts)
-* [Line + bar chart](#line-plus-bar-charts)
-* [Row chart](#row-charts)
-* [Area chart](#line-bar-and-area-charts)
-* [Scatterplot or bubble chart](#scatterplots-and-bubble-charts)
-* [Pie/donut chart](#pie-or-donut-charts)
-* [Funnel](#funnel)
-* [Map](#maps)
+- [Number](#numbers)
+- [Trend](#smart-numbers)
+- [Progress bar](#progress-bars)
+- [Gauge](#gauges)
+- [Table](#tables)
+- [Line chart](#line-bar-and-area-charts)
+- [Bar chart](#line-bar-and-area-charts)
+- [Line + bar chart](#line-plus-bar-charts)
+- [Row chart](#row-charts)
+- [Area chart](#line-bar-and-area-charts)
+- [Scatterplot or bubble chart](#scatterplots-and-bubble-charts)
+- [Pie/donut chart](#pie-or-donut-charts)
+- [Funnel](#funnel)
+- [Map](#maps)
-To change how the answer to your question is displayed, click on the Visualization dropdown menu beneath the question builder bar.
+To change how the answer to your question is displayed, click on the Visualization button in the bottom-right of the screen to open the visualization selection sidebar.
-
+
-If a particular visualization doesn’t really make sense for your answer, the format option will appear grayed-out in the dropdown menu. You can still select a grayed-out option, though you might need to click on the chart options gear icon to make your selection work with your data.
+If a particular visualization doesn’t really make sense for your answer, that option will appear grayed-out in the sidebar. You can still select a grayed-out option, though you might need to open the chart options to make your selection work with your data.
Once a question is answered, you can save or download the answer, or add it to a dashboard or Pulse.
### Visualization types and options
-Each visualization type has its own advanced options you can tweak. Just click the gear icon next to the visualization selector. Here's an overview of what you can do:
+Each visualization type has its own advanced options you can tweak. Just click the Settings button next to the Visualization button to see all your options. The options panel also automatically opens up whenever you pick a new visualization type. Here's an overview of what you can do:
#### Numbers
-This option is for displaying a single number, nice and big. The options for numbers include adding character prefixes or suffixes to it (so you can do things like put a currency symbol in front or a percent at the end), setting the number of decimal places you want to include, and multiplying your result by a number (like if you want to multiply a decimal by 100 to make it look like a percent).
+
+This option is for displaying a single number, nice and big. The options for numbers include adding character prefixes or suffixes to it (so you can do things like put a currency symbol in front or a percent at the end), setting the number of decimal places you want to include, and multiplying your result by a number (like if you want to multiply a decimal by 100 to make it look like a percent). If you want to _divide_ by a number, then just multiply it by a decimal (e.g, if your result is `100`, but you want it to display as `1`, simply multiply it by 0.01).
-#### Smart numbers
-The Smart Number visualization is great for displaying how a single number has changed over time. To use this visualization, you'll need to have a single number grouped by a Time field, like the Count of Orders by Created At. The Smart Number will show you the value of the number during the most recent period, and below that you'll see how much the number has increased or decreased compared to its value in the period before that. The period is determined by your group-by field: if you're grouping by Day, the Smart Number will show you the most recent day compared to the day before that.
+#### Trends
+
+The Trend visualization is great for displaying how a single number has changed over time. To use this visualization, you'll need to have a single number grouped by a Time field, like the Count of Orders by Created At. The Trend will show you the value of the number during the most recent period, and below that you'll see how much the number has increased or decreased compared to its value in the period before that. The period is determined by your group-by field: if you're grouping by Day, the Trend will show you the most recent day compared to the day before that.
-By default, Smart Numbers will display increases as green (i.e. "good") and decreases as red ("bad"). If your number is something where an increase is bad and a decrease is good (such as Bounce Rate, or Costs), you can reverse this behavior in the visualization settings:
+By default, Trends will display increases as green (i.e. "good") and decreases as red ("bad"). If your number is something where an increase is bad and a decrease is good (such as Bounce Rate, or Costs), you can reverse this behavior in the visualization settings:
#### Progress bars
-Progress bars are for comparing a single number to a goal value that you set. Open up the chart options for your progress bar to choose a value for your goal, and Metabase will show you how far away your question's current result is from the goal.
+
+Progress bars are for comparing a single number to a goal value that you set. Open up the settings for your progress bar to choose a value for your goal, and Metabase will show you how far away your question's current result is from the goal.
#### Gauges
+
Ah, gauges: you either love 'em or you hate 'em. …Or you feel "meh" about them, I guess. Whatever the case, gauges allow you to show a single number and where its value falls within a set of colored ranges that you can specify. By default, when you choose the Gauge visualization, Metabase will create red, yellow, and green ranges for you.
@@ -60,19 +64,19 @@ Open up the visualization settings to define your own ranges, choose colors for
#### Tables
+
The Table option is good for looking at tabular data (duh), or for lists of things like users or orders. The visualization options for tables allow you to add, hide, or rearrange fields in the table you're looking at, as well as modify their formatting.
##### Rearranging, adding, and removing columns
-Open up the visualization options for a table and you'll see the Columns tab, which displays all the columns currently being shown in the table. Below that you'll see a list of more columns from linked tables that you can add to the current table view.
+Open up the settings for your table and you'll see the Columns tab, which displays all the columns currently being shown in the table. Below that you'll see a list of more columns from linked tables, if any, that you can add to the current table view.
To hide a column, click the X icon on it; that'll send it down to the "More columns" area in case you want to bring it back. To add a linked column, just click the + icon on it, which will bring it to the "Visible columns" section. Click and drag any of the columns listed there to rearrange the order in which they appear. Another super easy way to rearrange columns without having to open up the visualization settings is to simply click and drag on a column's heading to move it where you'd like it to go.
**Note:** changing these options doesn't change the actual table itself; it just creates a custom view of it that you can save as a "question" in Metabase and refer back to later, share with others, or add to a dashboard.
-
##### Column formatting options
To format the display of any column in a table, click on the column heading and choose the `Formatting` option (you can also get there by clicking on the gear on any column when in the `Columns` tab of the visualization settings).
@@ -82,26 +86,30 @@ To format the display of any column in a table, click on the column heading and
The options you see will be different depending on the type of column you're viewing:
**Dates**
-* `Date style` gives you a bunch of different choices for how to display the date.
-* `Abbreviate names of days and months`, when turned on, will turn things like `January` to `Jan`, and `Monday` to `Mon`.
-* `Show the time` lets you decide whether or not to display the time, and if so, how. You can include hours and minutes, and additionally seconds and milliseconds.
+
+- `Date style` gives you a bunch of different choices for how to display the date.
+- `Abbreviate names of days and months`, when turned on, will turn things like `January` to `Jan`, and `Monday` to `Mon`.
+- `Show the time` lets you decide whether or not to display the time, and if so, how. You can include hours and minutes, and additionally seconds and milliseconds.
**Numbers**
-* `Show a mini bar chart` will display a small horizontal bar next to each number in this column to show its size relative to the other values in the column.
-* `Style` lets you choose to display the number as a plain number, a percent, in scientific notation, or as a currency.
-* `Separator style` gives you various options for how commas and periods are used to separate the number.
-* `Minimum number of decimal places` forces the number to be displayed with exactly this many decimal places.
-* `Multiply by a number` multiplies each number in this column by whatever you type here. Just don't type an emoji here; it almost always causes a temporal vortex to manifest.
-* `Add a prefix/suffix` lets you put a symbol, word, or whatever before or after each cell's value.
+
+- `Show a mini bar chart` will display a small horizontal bar next to each number in this column to show its size relative to the other values in the column.
+- `Style` lets you choose to display the number as a plain number, a percent, in scientific notation, or as a currency.
+- `Separator style` gives you various options for how commas and periods are used to separate the number.
+- `Minimum number of decimal places` forces the number to be displayed with exactly this many decimal places.
+- `Multiply by a number` multiplies each number in this column by whatever you type here. Just don't type an emoji here; it almost always causes a temporal vortex to manifest.
+- `Add a prefix/suffix` lets you put a symbol, word, or whatever before or after each cell's value.
**Currency**
Currency columns have all the same options as numbers, plus the following:
-* `Unit of Currency` lets you change the unit of currency from whatever the system default is.
-* `Currency label style` allows you to switch between displaying the currency label as a symbol, a code like (USD), or the full name of the currency.
-* `Where to display the unit of currency` lets you toggle between showing the currency label in the column heading or in every cell in the column.
+
+- `Unit of Currency` lets you change the unit of currency from whatever the system default is.
+- `Currency label style` allows you to switch between displaying the currency label as a symbol, a code like (USD), or the full name of the currency.
+- `Where to display the unit of currency` lets you toggle between showing the currency label in the column heading or in every cell in the column.
##### Formatting data in charts
-While we're talking about formatting, we thought you should also know that you can access formatting options for the columns used in a chart. Just open the visualization options, select the `Data` tab:
+
+While we're talking about formatting, we thought you should also know that you can access formatting options for the columns used in a chart. Just open the visualization settings and select the `Data` tab:
@@ -110,6 +118,7 @@ Then click on the gear icon next to the column that you want to format. Dates, n
##### Conditional table formatting
+
Sometimes is helpful to highlight certain rows or columns in your tables when they meet a specific condition. You can set up conditional formatting rules by going to the visualization settings while looking at any table, then clicking on the `Formatting` tab.
@@ -122,11 +131,13 @@ When you add a new rule, you'll first need to pick which column(s) should be aff
You can set as many rules on a table as you want. If two or more rules disagree with each other, the rule that's on the top of your list of rules will win. You can click and drag your rules to reorder them, and click on a rule to edit it.
##### Pivoted tables
+
If your table is a result that contains one numeric column and two grouping columns, Metabase will also automatically "pivot" your table, like in the example below. What this does is it takes one of your columns and rotates it 90 degrees ("pivots" it) so that each of its values becomes a column heading. If you open up the visualization settings by clicking the gear icon, you can choose which column to pivot in case Metabase got it wrong; or you can also turn the pivoting behavior off entirely.
#### Line, bar, and area charts
+
Line charts are best for displaying the trend of a number over time, especially when you have lots of x-axis values. Bar charts are great for displaying a number grouped by a category (e.g., the number of users you have by country), and they can also be useful for showing a number over time if you have a smaller number of x-axis values (like orders per month this year).
@@ -136,7 +147,7 @@ Area charts are useful when comparing the proportions of two metrics over time.
**Trend lines**
-Another useful option for line, area, bar, and scatter charts is trend lines. If you have a question where you're grouping by a time field, open up the visualization options by clicking the gear icon, and turn the `Show trend line` toggle on to display a trend line. Metabase will choose the best type of line to fit to the trend of your series. This will even work if you have multiple numbers selected in the View section of your question. It won't work, however, if you have any groupings beyond the one time field.
+Another useful option for line, area, bar, and scatter charts is trend lines. If you have a question where you're grouping by a time field, open up the visualization settings and turn the `Show trend line` toggle on to display a trend line. Metabase will choose the best type of line to fit to the trend of your series. This will even work if you have multiple metrics selected in your summary. But it won't work if you have any groupings beyond the one time field.
@@ -150,15 +161,16 @@ Metabase will pick one of your series to display as a line, and another to displ
-To use a Line + Bar chart, you'll either need to have two or more numbers selected in the View section of your question, with one or two grouping columns, like this…
+To use a Line + Bar chart, you'll either need to have two or more metrics selected in the Summarize By section of your question, with one or two grouping columns, like this…
-…or you'll need a question with a single item in the View section, with two grouping columns, like this:
+…or you'll need a question with a single metric and with two grouping columns, like this:
#### Row charts
+
If you're trying to group a number by a column that has a lot of possible values, like a Vendor or Product Title field, try visualizing it as a row chart. Metabase will show you the bars in descending order of size, with a final bar at the bottom for items that didn't fit.
@@ -169,29 +181,31 @@ If you have a bar chart like Count of Users by Age, where the x-axis is a number
-By default, Metabase will automatically choose a good way to bin your results. But you can change how many bins your result has, or turn the binning off entirely, by clicking on the number field you're grouping by, then clicking on the area to the right of the field name:
+By default, Metabase will automatically choose a good way to bin your results. But you can change how many bins your result has, or turn the binning off entirely, by clicking on the area to the right of the column you're grouping by:
-
+
##### Options for line, bar, and area charts
These three charting types have very similar options, which are broken up into the following:
-* **Data** — choose the fields you want to plot on your x and y axes. This is mostly useful if your table or result set contains more than two columns, like if you're trying to graph fields from an unaggregated table. You can also add additional metrics to your chart by clicking the `Add another series` link below the y-axis dropdown, or break your current metric out by an additional dimension by clicking the `Add a series breakout` link below the x-axis dropdown (note that you can't add an additional series breakout if you have more than one metric/series).
-* **Display** — here's where you can make some cosmetic changes, like setting colors, and stacking bar or area charts. With line and area charts, you can also change the line style (line, curve, or step). You can also set a goal line for your chart, display a trend line, or configure how your chart deals with x-axis points that have missing y-axis values.
-* **Axes** — this is where you can hide axis markers or change their ranges, and turn split axes on or off. You can also configure the way your axes are scaled, if you're into that kind of thing.
-* **Labels** — if you want to hide axis labels or customize them, here's where to go.
+- **Data** — choose the fields you want to plot on your x and y axes. This is mostly useful if your table or result set contains more than two columns, like if you're trying to graph fields from an unaggregated table. You can also add additional metrics to your chart by clicking the `Add another series` link below the y-axis dropdown, or break your current metric out by an additional dimension by clicking the `Add a series breakout` link below the x-axis dropdown (note that you can't add an additional series breakout if you have more than one metric/series).
+- **Display** — here's where you can make some cosmetic changes, like setting colors, and stacking bar or area charts. With line and area charts, you can also change the line style (line, curve, or step). You can also set a goal line for your chart, display a trend line, or configure how your chart deals with x-axis points that have missing y-axis values.
+- **Axes** — this is where you can hide axis markers or change their ranges, and turn split axes on or off. You can also configure the way your axes are scaled, if you're into that kind of thing.
+- **Labels** — if you want to hide axis labels or customize them, here's where to go.
#### Scatterplots and bubble charts
+
Scatterplots are useful for visualizing the correlation between two variables, like comparing the age of your users vs. how many dollars they've spent on your products. To use a scatterplot, you'll need to ask a question that results in two numeric columns, like `Count of Orders grouped by Customer Age`. Alternatively, you can use a raw data table and select the two numeric fields you want to use in the chart options.
-If you have a third numeric field, you can also create a bubble chart. Select the Scatter visualization, then open up the chart options and select a field in the `bubble size` dropdown. This field will be used to determine the size of each bubble on your chart. For example, you could use a field that contains the total dollar amount for each x-y pair — i.e., larger bubbles for larger total dollar amounts spent on orders.
+If you have a third numeric field, you can also create a bubble chart. Select the Scatter visualization, then open up the chart settings and select a field in the `bubble size` dropdown. This field will be used to determine the size of each bubble on your chart. For example, you could use a field that contains the total dollar amount for each x-y pair — i.e., larger bubbles for larger total dollar amounts spent on orders.
Scatterplots and bubble charts also have similar chart options as line, bar, and area charts, including the option to display trend or goal lines.
#### Pie or donut charts
+
A pie or donut chart can be used when breaking out a metric by a single dimension, especially when the number of possible breakouts is small, like users by gender. If you have more than a few breakouts, like users per country, it's usually better to use a bar chart so that your users can more easily compare the relative sizes of each bar.
The options for pie charts let you choose which field to use as your measurement, and which one to use for the dimension (i.e., the pie slices). You can also customize the color of each piece slice, the pie chart's legend, whether or not to show each slice's percent of the whole in the legend, and the minimum size a slice needs to be in order for it to be displayed.
@@ -199,6 +213,7 @@ The options for pie charts let you choose which field to use as your measurement
#### Funnel
+
Funnels are commonly used in e-commerce or sales to visualize how many customers are present within each step of a checkout flow or sales cycle. At their most general, funnels show you values broken out by steps, and the percent decrease between each successive step. To create a funnel in Metabase, you'll need to have a table with at least two columns: one column that contains the metric you're interested in, and another that contains the funnel's steps.
For example, I might have an Opportunities table, and I could create a question that gives me the number of sales leads broken out by a field that contains stages such as `Prospecting`, `Qualification`, `Proposal`, `Negotiation`, and `Closed`. In this example, the percentages shown along the x-axis tell you what percent of the total starting opportunities are still present at each subsequent step; so 18.89% of our total opportunities have made it all the way to being closed deals. The number below each percent is the actual value of the count at that step — in our example, the actual number of opportunities that are currently at each step. Together, these numbers help you figure out where you're losing your customers or users.
@@ -206,14 +221,15 @@ For example, I might have an Opportunities table, and I could create a question
#### Maps
+
When you select the Map visualization setting, Metabase will automatically try and pick the best kind of map to use based on the table or result set you're currently looking at. Here are the maps that Metabase uses:
-* **United States Map** — Creating a map of the United States from your data requires your results to contain a column that contains states. This lets you do things like visualize the count of your users broken out by state, with darker states representing more users.
-* **Country Map** — To visualize your results in the format of a map of the world broken out by country, your result must contain a field with countries. (E.g., count of users by country.)
+- **United States Map** — Creating a map of the United States from your data requires your results to contain a column that contains names of states or two-letter state codes. This lets you do things like visualize the count of your users broken out by state, with darker states representing more users.
+- **World Map** — To visualize your results in the format of a map of the world broken out by country, your result must contain a column with two-letter country codes. (E.g., count of users by country.)
-* **Pin Map** — If your table contains a latitude and longitude field, Metabase will try to display it as a pin map of the world. This will put one pin on the map for each row in your table, based on the latitude and longitude fields. You can try this with the Sample Dataset that's included in Metabase: start a new question and select the People table, use `raw data` for your view, and choose the Map option for your visualization. you'll see a map of the world, with each dot representing the latitude and longitude coordinates of a single person from the People table.
+- **Pin Map** — If your table contains a latitude and longitude field, Metabase will try to display it as a pin map of the world. This will put one pin on the map for each row in your table, based on the latitude and longitude fields. You can try this with the Sample Dataset that's included in Metabase: start a new question and select the People table, use `raw data` for your view, and choose the Map option for your visualization. you'll see a map of the world, with each dot representing the latitude and longitude coordinates of a single person from the People table.
@@ -224,4 +240,5 @@ Metabase also allows administrators to add custom region maps via GeoJSON files
---
## Next: Sharing and organizing questions
+
Now let's learn about [sharing and organizing your saved questions](06-sharing-answers.md).
diff --git a/docs/users-guide/06-sharing-answers.md b/docs/users-guide/06-sharing-answers.md
index c293c56f5bbf3234049a969903a518b6fbe9609b..640c5ac66f91cd816ffaeba2b67710ada584a3ef 100644
--- a/docs/users-guide/06-sharing-answers.md
+++ b/docs/users-guide/06-sharing-answers.md
@@ -1,8 +1,7 @@
-
## Sharing and organizing your questions and answers
----
### How to save a question
+
Whenever you’ve arrived at an answer that you want to save for later, click the **SAVE** button in the top right of the screen. This will also save the visualization option you’ve chosen for your answer.
@@ -12,16 +11,19 @@ A pop-up box will appear, prompting you to give your question a name and descrip
Now, whenever you want to refer to your question again you can find it by searching for it in the search bar at the top of Metabase, or by navigating to the collection where you saved it. To edit your question, go to it and click the pencil icon in the top-right.
### Sharing questions with public links
+
If your Metabase administrator has enabled [public sharing](../administration-guide/12-public-links.md) on a saved question or dashboard, you can go to that question or dashboard and click on the sharing icon to find its public links. Public links can be viewed by anyone, even if they don't have access to Metabase. You can also use the public embedding code to embed your question or dashboard in a simple web page or blog post.
### Organizing and finding your saved questions
+
After your team has been using Metabase for a while, you’ll probably end up with lots of saved questions. Metabase has several ways to help you organize things and find what you’re looking for.
#### Collections
+
Collections are the main way to organize questions, as well as dashboards and pulses. [Administrators can give you different kinds of access](../administration-guide/06-collections.md) to each collection:
- **View access:** you can see the collection and its contents, but you can't modify anything or put anything new into the collection.
@@ -29,6 +31,7 @@ Collections are the main way to organize questions, as well as dashboards and pu
- **No access:** you can't see the collection or its contents. If you have access to a dashboard, but it contains questions that are saved in a collection you don't have access to, those questions will show a permissions notification instead of the chart or table.
#### Your personal collection
+
In addition to the collections you and your teammates have made, you'll also always have your own personal collection that only you and administrators can see. To find it, click on the "browse all items" button on the homepage and click on "my personal collection" in the list of collections.
You can use your personal collection as a scratch space to put experiments and explorations that you don't think would be particularly interesting to the rest of your team, or as a work-in-progress space where you can work on things and then move them to a shared place once they're ready.
@@ -48,20 +51,23 @@ Any dashboards that are pinned in the main "Our analytics" collection will also
Type into the search box that's at the top of Metabase and hit enter to search through all the dashboards, questions, collections, and pulses your team has.
#### Moving
+
To move a question, dashboard, or pulse into a collection, or from one collection to another, just click and drag it onto the collection where you want it to go. You can also click on the `…` menu to the right of the question and pick the Move action. If you're trying to move several things at once, click on the items' icons to select them, then click the Move action that pops up at the bottom of the screen.
-Note that you have to have Curate permission for the collection that you're moving a question into *and* the collection you're moving the question out of.
+Note that you have to have Curate permission for the collection that you're moving a question into _and_ the collection you're moving the question out of.
#### Archiving
+
Sometimes questions outlive their usefulness and need to be sent to Question Heaven. To archive a question or dashboard, just click on the `…` menu that appears on the far right when you hover over a question and pick the Archive action. You'll only see that option if you have "curate" permission for the current collection. You can also archive multiple items at once, the same way as you move multiple items. Note that archiving a question removes it from all dashboards or Pulses where it appears, so be careful!
-You can also archive *collections* as long as you have curate permissions for the collection you're trying to archive, the collection *it's* inside of, as well as any and all collections inside of *it*. Archiving a collection archives all of its contents as well.
+You can also archive _collections_ as long as you have curate permissions for the collection you're trying to archive, the collection _it's_ inside of, as well as any and all collections inside of _it_. Archiving a collection archives all of its contents as well.
If you have second thoughts and want to bring an archived item back, you can see all your archived questions from the archive; click the menu icon in the top-right of any collection page to get to the archive. To unarchive a question, hover over it and click the unarchive icon that appears on the far right.
---
## Next: creating dashboards
+
Next, we'll learn about [creating dashboards and adding questions to them](07-dashboards.md).
diff --git a/docs/users-guide/09-multi-series-charting.md b/docs/users-guide/09-multi-series-charting.md
index 174839b81ee6258b310bded3fe89dfa1aff7cafa..785a52f5171ac562d510953dc2126be8d15af7ae 100644
--- a/docs/users-guide/09-multi-series-charting.md
+++ b/docs/users-guide/09-multi-series-charting.md
@@ -1,6 +1,6 @@
## Charts with multiple series
-Data in isolation is rarely all that useful. One of the best ways to add context and clarity when communicating with data is to show data side-by-side with other data. Here are just a few examples of data that is better together than apart.
+Data in isolation is rarely all that useful. One of the best ways to add context and clarity when communicating with data is to show data side-by-side with other data. Here are just a few examples of data that is better together than apart.
- Your company’s revenue vs. its costs over time.
- Average order price this month and user signups for that month.
@@ -18,6 +18,7 @@ e.g. Let me see revenue over time and cost over time together.
e.g. The count of users by region over time.
### Combining two existing saved questions
+
If you already have two or more saved questions you’d like to compare, and they share a dimension, they can be combined on any dashboard. Here’s how:
1. Add a question with a dimension like time or a category to a dashboard. In practice, these will usually be line charts or bar charts.
@@ -41,27 +42,29 @@ Once you have your chart looking how you’d like, hit done and your changes wil
#### A quick note about SQL based questions.
+
Metabase has less information about SQL based questions, so we cannot guarantee if they can be added reliably. You'll see a little warning sign next to SQL questions to indicate this and when you try adding them just be aware it may not work.
-### Combining Number charts
+### Combining Number charts
+
If you need to compare single numbers and get a sense of how they differ, Metabase also lets you turn multiple Number charts into a bar chart. To do this, follow the same process outlined above. While editing a dashboard, click “edit data†on the Number chart of your choice and then select the other saved question(s) you’d like to see represented on the bar chart. (At Metabase, we use this to create simple funnel visualizations.)
### Creating a multi-series visualization in the query builder.
-If you’re creating a new question in the query builder, you can also view the result as a multi-series visualization. To do this you’ll need to add two dimensions to your question and use an aggregation that isn’t just “raw data.â€
-As an example, we might want to see which service is referring the most people to our product this month.
+If you’re creating a new question you can also view the result as a multi-series visualization. To do this you’ll need to summarize and add two groupings to your question.
-(In the sample dataset that ships with Metabase this would involve using the Source and Created At dimensions of the “People†table.)
+As an example, we might want to see which website or service is referring the most people to our website. (In the sample dataset that ships with Metabase this would involve using the `Source` and `Created At` columns of the `People` table.)
-To do this we’d select “Count of rows†and then add “Source and “Created At.†Then, we’d add a filter to limit the results to just this month. You can learn more about how to work with the query builder in the “Asking questions†section of the user guide.
+To do this we’d click the Summarize button, and then add `Source` and `Created At` as groupings (the `count of rows` metric that we want is already selected by default). [Learn more about asking questions](04-asking-questions.md).
-If we switch the resulting table to a line or bar chart we can now see a multi-series visualization of how each referrer has performed for us this month.
+Metabase will automatically display a multi-series line chart visualization of how each referrer has performed for us.
-It’s worth noting that at this time you won’t be able to add another saved question to multi-series visualizations made in this fashion. Metabase can only visualize up to 10 values of a dimension at once, so you may need to filter the values if you're selecting a field that contains a lot of values like "State."
+It’s worth noting that at this time you won’t be able to add another saved question to multi-series visualizations made in this fashion. Metabase can only visualize up to 20 values of a dimension at once, so you may need to filter the values if you're selecting a field that contains a lot of values like "State."
### Other multiple series tips
+
- When displaying multiple series it’s important to keep legibility in mind. Combining many series can sometimes decrease the communication value of the data.
### To recap:
diff --git a/docs/users-guide/10-pulses.md b/docs/users-guide/10-pulses.md
index 36612bed79117555c9224f029ba04b015a6fd331..9691bd906ef30ec1ff22789bdd6553680e733f98 100644
--- a/docs/users-guide/10-pulses.md
+++ b/docs/users-guide/10-pulses.md
@@ -1,15 +1,17 @@
-
## Sharing updates with pulses
+
The Pulses feature in Metabase gives you the ability to automatically send regular updates to your teammates to help everyone keep track of changes to the metrics that matter to you most. You can deliver a pulse via email or [Slack](https://slack.com/), on the schedule of your choice.
To create a new pulse, click the plus (+) button in the top-right of Metabase and select `New pulse`.
### Name it
+
First, choose a name for your pulse. This will show up in the email subject line and the Slack message title, so choose something that will let people know what kind of updates the pulse will contain, like “Daily Marketing Update,†or “Users Metrics.†Next, choose which collection it should be saved in so that it's easy to find in the future.
### Pick your data
+
Before you can create a pulse, you’ll need to have some [saved questions](06-sharing-answers.md). Click the dropdown to see a list of all your saved questions. You can type in the dropdown to help filter and find the question you’re looking for.
@@ -23,6 +25,7 @@ Now you can include tables in your pulses as well. They'll be capped to 10 colum
#### Attaching a .csv or .xls with results
+
You can also optionally include the results of a saved question in an emailed pulse as a .csv or .xls file attachment. Just click the paperclip icon on an included saved question to add the attachment. Click the paperclip again to remove the attachment.
@@ -36,13 +39,15 @@ Your attachments will be included in your emailed pulse just like a regular emai
#### Limitations
+
Currently, there are a few restrictions on what kinds of saved questions you can put into a pulse:
-* Raw data questions are capped to 10 columns and 20 rows. For emailed pulses, the rest of the results will be included automatically as a file attachment, with a limit of 2,000 rows.
-* Pivot tables will be cropped to a maximum of three columns and 10 rows.
-* Bar charts (and pie charts which get turned into bar charts) will be cropped to one column for the labels, one column for the values, and 10 total rows.
+- Raw data questions are capped to 10 columns and 20 rows. For emailed pulses, the rest of the results will be included automatically as a file attachment, with a limit of 2,000 rows.
+- Pivot tables will be cropped to a maximum of three columns and 10 rows.
+- Bar charts (and pie charts which get turned into bar charts) will be cropped to one column for the labels, one column for the values, and 10 total rows.
### Choose how and when to deliver your data
+
Each pulse you create can be delivered by email, Slack, or both. You can also set a different delivery schedule for email versus Slack. To deliver by email, just type in the Metabase user names, or email addresses you want to send the pulse to, separated by commas. Then, choose to either send it daily, weekly, or monthly, and the time at which you want it to be sent.
@@ -52,6 +57,7 @@ To send via Slack, you’ll need to choose which channel you want to post the pu
Once you’re done, just click `Create pulse` and you’ll see your new pulse in the collection where you chose to save it
### Editing or archiving a pulse
+
If you ever need to make changes to a pulse, just navigate to the collection where it's saved and click on it, or search for it in the big search bar at the top of Metabase.
If a pulse has outlived its usefulness you can archive it by clicking on the Archive button at the bottom of the pulse's detail page. Just remember: if you archive a pulse, no one will receive it anymore. You can unarchive a pulse just like you can with questions and dashboards by navigating to the archive from the top-right button while viewing any collection and clicking on the View Archive menu option, then clicking on the `Unarchive this` button on the far right next to the pulse.
diff --git a/docs/users-guide/12-data-model-reference.md b/docs/users-guide/12-data-model-reference.md
index a142c49ddeb5fea1161bba837d215668dee3eba8..e2a94667ef848c94a643f323b645c217e105e07f 100644
--- a/docs/users-guide/12-data-model-reference.md
+++ b/docs/users-guide/12-data-model-reference.md
@@ -1,25 +1,23 @@
-
## Data Model Reference
----
-Sometimes, as you’re looking at all the various tables and data in your database, you’ll probably have questions about what all the data means. That’s where the *data model reference* comes in handy. You can get to the data model reference from the question builder screen by clicking on the **Book** icon in the top right corner of the screen.
-
+Sometimes when you're writing a SQL query, you might forget the exact names of different tables or columns, or which table contains what. That’s where the _data reference_ comes in handy. You can open the data reference panel from the SQL editor by clicking on the book icon in the top right corner of the editor when it's open.
-After clicking the icon, the **Data Reference** sidebar will open. It lists all the databases you have access to and the tables inside them.
+
-
+This panel lists all the databases you have access to and the tables and columns inside of them.
-Click on the table you would like to explore further to see a description of it and a list of all the fields it contains. Each table or field will only contain a description if your admin wrote something there.
+
-
+Click on the table you would like to explore further to see a description of it and a list of all the columns it has. Each table or column will only contain a description if your admin wrote something in the Data Model section of the Admin Panel.
-If you click on a field you’re interested in, you’ll see a description of the field's contents as well as some suggestions for questions you could view about that field.
+If you click on a column you’re interested in, you’ll see a description of its contents, as well as a list of sample values for columns that don't have a huge number of distinct values.
-
+
-In addition to looking at a table's fields, you can also look at its connections if your table includes any. Connections show up here if there’s a field in the table you’re looking at that’s included in another table. Click on **Connections** (located next to **Field** button) to view the connected tables.
+In addition to looking at a table's column, you can also look at its connections if your table includes any. Connections show up here if there’s a column in the table you’re looking at that’s included in another table (i.e., a foreign key relationship). Click on **Connections** (located next to the **Fields** button) to view the connected tables.
---
## Next: powering up your SQL questions with variables
+
Find out [how to use variables in your native SQL queries](13-sql-parameters.md) to create powerful filter widgets and more.
diff --git a/docs/users-guide/13-sql-parameters.md b/docs/users-guide/13-sql-parameters.md
index 0bf03996ec3114e6cf892fadc6747505c18505b9..ba99ea45d03d2c64fe87694c03596ad7a54877e5 100644
--- a/docs/users-guide/13-sql-parameters.md
+++ b/docs/users-guide/13-sql-parameters.md
@@ -1,6 +1,5 @@
-
## SQL Parameters
----
+
Metabase has the flexible ability to allow variables in native (SQL) queries. This lets you dynamically replace values in your queries using filter widgets or through the query's URL.
@@ -10,6 +9,7 @@ Options and settings for your variables will appear in the `Variables` side pane
### Defining Variables
+
Typing `{% raw %}{{variable_name}}{% endraw %}` in your native query creates a variable called `variable_name`. Variables can be given types in the side panel, which changes their behavior. All variable types other than `field filter` will cause a filter widget to be placed on this question corresponding to the chosen variable type. When a value is selected via a filter widget, that value replaces the corresponding variable in the SQL template, wherever it appears. If you have multiple filter widgets, you can click and drag on any of them to move and reorder them.
This example defines a variable called `cat`, allowing you to dynamically change the `WHERE` clause in this query:
@@ -21,6 +21,7 @@ WHERE category = {% raw %}{{cat}}{% endraw %}
```
#### The Field Filter variable type
+
Setting a variable to the `field filter` type allows you to map it to a field in any table in the current database, and lets you display a dropdown filter widget filled with the values of the field you connected it to. Field filter variables also allow you to connect your SQL question to a dashboard filter if you put it in a dashboard.
A field filter variable inserts SQL similar to that generated by the GUI query builder when adding filters on existing columns. This is useful because it lets you do things like insert dynamic date range filters into your native query. When adding a field filter, you should link that variable to a specific column. Field filter variables should be used inside of a `WHERE` clause.
@@ -36,7 +37,9 @@ WHERE {% raw %}{{created_at}}{% endraw %}
```
##### Creating SQL question filters using field filter variables
+
First, insert a variable tag in your SQL, like `{% raw %}{{my_var}}{% endraw %}`. Then, in the side panel, select the `Field Filter` variable type, and choose which field to map your variable to. In order to display a filter widget, you'll have to choose a field whose Type in the Data Model section of the Admin Panel is one of the following:
+
- Category
- City
- Entity Key
@@ -52,6 +55,7 @@ The field can also be a datetime one (which can be left as `No special type` in
You'll then see a dropdown labeled `Widget`, which will let you choose the kind of filter widget you want on your question, which is especially useful for datetime fields (you can select `None` if you don't want a widget at all). **Note:** If you're not seeing the option to display a filter widget, make sure the mapped field is set to one of the above types, and then try manually syncing your database from the Databases section of the Admin Panel to force Metabase to scan and cache the field's values.
Filter widgets **can't** be displayed if the variable is mapped to a field marked as:
+
- Avatar Image URL
- Description
- Email
@@ -64,12 +68,15 @@ Filter widgets **can't** be displayed if the variable is mapped to a field marke
- URL
##### Setting a default value
+
If you input a default value for your field filter, this value will be selected in the filter whenever you come back to this question. If you clear out the filter, though, no value will be passed (i.e., not even the default value). The default value has no effect on the behavior of your SQL question when viewed in a dashboard.
###### Default value in the query
+
You can also define default value directly in your query, useful for complex default value.
Current date example:
+
```
SELECT p.*
FROM products p
@@ -77,12 +84,14 @@ WHERE p.createdAt = [[ {% raw %}{{dateOfCreation}}{% endraw %} #]]CURRENT_DATE()
```
##### Connecting a SQL question to a dashboard filter
+
In order for a saved SQL question to be usable with a dashboard filter, it must contain at least one field filter. The kind of dashboard filter that can be used with the SQL question depends on the field that you map to the question's field filter(s). For example, if you have a field filter called `{% raw %}{{var}}{% endraw %}` and you map it to a State field, you can map a Location dashboard filter to your SQL question. In this example, you'd create a new dashboard or go to an existing one, click the Edit button, and the SQL question that contains your State field filter, add a new dashboard filter or edit an existing Location filter, then click the dropdown on the SQL question card to see the State field filter. [Learn more about dashboard filters here](08-dashboard-filters.md).
### Optional Clauses
-To make an optional clause in your native query, type `[[brackets around a {% raw %}{{variable}}{% endraw %}]]`. If `variable` is given a value, then the entire clause is placed into the template. If not, then the entire clause is ignored.
+
+To make an optional clause in your native query, type `[[brackets around a {% raw %}{{variable}}{% endraw %}]]`. If `variable` is given a value, then the entire clause is placed into the template. If not, then the entire clause is ignored.
In this example, if no value is given to `cat` from its filter widget or URL, then the query will just select all the rows from the `products` table. But if `cat` does have a value, like `Widget`, then the query will only grab the products with a category type of `Widget`:
@@ -119,4 +128,5 @@ WHERE True
---
## Next: automated x-ray explorations
+
Learn about how to easily and quickly see automatic explorations of your data with Metabase's powerful [x-ray feature](14-x-rays.md).
diff --git a/docs/users-guide/14-x-rays.md b/docs/users-guide/14-x-rays.md
index e16a201b0b24ddb0518dc3af09f32d8275f99b3e..10bf7b7a68dd057789d0ceb07073f5645d0f8e6d 100644
--- a/docs/users-guide/14-x-rays.md
+++ b/docs/users-guide/14-x-rays.md
@@ -1,5 +1,5 @@
## X-rays
----
+
X-rays are a fast and easy way to get automatic insights and explorations of your data.
### Viewing x-rays by clicking on charts or tables
@@ -19,34 +19,18 @@ If you're already looking at an x-ray of a table or a segment, Metabase will als
-
### Table x-rays
Another great way to get to know your data is by x-raying your tables. From the home page, scroll to the bottom of the screen, click on one of your connected databases, and then click the bolt icon on a table to view an x-ray of it.
-### X-raying question results
-
-You can also see an x-ray of the results of a saved or unsaved question by clicking the blue compass button in the bottom-right of the question screen and selecting the x-ray action. This will show you an x-ray of the numbers and fields in your question's results.
+## X-rays in the data browser and data reference
-
+You can also view an x-ray by browsing to a table and clicking on the lightning bolt icon. Click on the `Browse Data` button in the top navigation, select a database, and hover over a table to see the icon.
-## X-rays in the Data Reference
-
-You can also view an x-ray by navigating to a table, field, metric, or segment in the [Data Reference](./12-data-model-reference.md). Just click the x-ray link in the lefthand sidebar.
+From the Browse Data page, you can also click on `Learn about our data` to view the Data Reference section. From here you can navigate through databases, tables, columns, metrics, or segments, and you can click on the x-ray link in the left sidebar to see an x-ray of the item you're currently viewing.
-### Browsing through x-rays
-
-One fun and interesting thing you can do once you're looking at an x-ray is to click and browse through the list of suggested next x-rays that show up in the righthand column.
-
-Depending on the x-ray you're currently viewing, you'll see suggestions that will let you:
-
-- compare the table or segment you're currently x-raying to another segment
-- "zoom out" and view an x-ray of the table the current x-ray is based on
-- "zoom in" to see a more detailed x-ray about a field or dimension of the current x-ray
-- go to an x-ray of a related item, like a metric based on the current table, or a different table that's related to the current one
-
### Exploring newly added datasets
If you're an administrator, when you first connect a database to Metabase, Metabot will offer to show you some automated explorations of your newly-connected data.
@@ -55,10 +39,19 @@ If you're an administrator, when you first connect a database to Metabase, Metab
Click on one of these to see an x-ray.
-
+
You can see more suggested x-rays over on the right-hand side of the screen. Browsing through x-rays like this is a pretty fun way of getting a quick overview of your data.
+### Browsing through suggested x-rays
+
+Depending on the x-ray you're currently viewing, you'll see suggestions that will let you:
+
+- compare the table or segment you're currently x-raying to another segment
+- "zoom out" and view an x-ray of the table the current x-ray is based on
+- "zoom in" to see a more detailed x-ray about a field or dimension of the current x-ray
+- go to an x-ray of a related item, like a metric based on the current table, or a different table that's related to the current one
+
### Saving x-rays
If you come across an x-ray that's particularly interesting, you can save it as a dashboard by clicking the green Save button. Metabase will create a new dashboard and put it and all of its charts in a new collection, and will save this new collection wherever you choose.
@@ -67,14 +60,12 @@ If you come across an x-ray that's particularly interesting, you can save it as
If for some reason x-rays aren't a good fit for your team or your data, administrators can turn them off completely in the general settings area of the Admin Panel.
-### Where did the old x-rays go?
-
-We're reworking the way we do things like time series growth analysis, which was present in past versions of x-rays. In the meantime, we've removed those previous x-rays, and will bring those features back in a more elegant and streamlined way in a future version of Metabase.
-
### Need help?
+
If you still have questions about x-rays or comparisons, you can head over to our [discussion forum](https://discourse.metabase.com/). See you there!
---
## Next: setting up alerts
+
Learn how to get notified when one of your questions meets or goal or has results with [alerts](15-alerts.md).
diff --git a/docs/users-guide/15-alerts.md b/docs/users-guide/15-alerts.md
index c9a897e20edd9d4c5a088f3e291ce5e9f01d7c89..e0856ef1c23436933f9823d76a61eabb25fc558b 100644
--- a/docs/users-guide/15-alerts.md
+++ b/docs/users-guide/15-alerts.md
@@ -1,12 +1,15 @@
-
## Getting alerts about questions
+
Whether you're keeping track of revenue, users, or negative reviews, there are often times when you want to be alerted about something. Metabase has a few different kinds of alerts you can set up, and you can choose to be notified via email or Slack.
### Getting alerts
+
To start using alerts, someone on your team who's an administrator will need to make sure that [email integration](../administration-guide/02-setting-up-email.md) is set up first.
### Types of alerts
+
There are three kinds of things you can get alerted about in Metabase:
+
1. When a time series crosses a goal line.
2. When a progress bar reaches or goes below its goal.
3. When any other kind of question returns a result.
@@ -14,44 +17,49 @@ There are three kinds of things you can get alerted about in Metabase:
We'll go through these one by one.
### Goal line alerts
+
This kind of alert is useful when you're doing things like tracking daily active users and you want to know when you reach a certain number of them, or when you're tracking orders per week and you want to know whenever that number ever goes below a certain threshold.
To start, you'll need a line, area, or bar chart displaying a number over time. (If you need help with that, check out the page on [asking questions](04-asking-questions.md).)
-Now we need to set up a goal line. To do that, open up the visualization settings by clicking the gear icon next to the dropdown where you chose your chart type. Then click on the Display tab, and turn on the "Show goal" setting. Choose a value for your goal and click Done.
+Now we need to set up a goal line. To do that, open up the visualization settings by clicking the Settings button in the bottom-left. Then click on the Display tab, and turn on the "Show goal" setting. Choose a value for your goal and click Done.
-Save your question, then click on the menu button in the top right of the screen and click on "Get alerts about this."
+Save your question, then click on the bell icon in the bottom-right of the screen.
This is where you'll get to choose a few things:
+
- Whether you want to be alerted when the time series goes above the goal line or when it goes below it.
- Whether you only wanted to be alerted every time this happens or only the first time.
- How often you want Metabase to check to see if the goal line has been crossed.
-Click Done, and your alert will be all set up! You'll get an email confirmation, too. If you need to edit or unsubscribe from the alert you set up, just open up that same menu. It'll say "Alerts are on," so just click that, and you'll see the Edit and Unsubscribe buttons. This is also where you'll see alerts about this question that administrators might have added you to.
+Click Done, and your alert will be all set up! You'll get an email confirmation, too. If you need to edit or unsubscribe from the alert you set up, just click that same icon. You'll see the Edit and Unsubscribe buttons. This is also where you'll see alerts about this question that administrators might have added you to.
### Progress bar alerts
-Setting up this kind of alert is really similar to setting up a goal line alert. First, create a question that returns a single number as its result, then choose the Progress Bar chart type from the Visualization menu. Click the gear to select a goal value, click Done, then save your question.
-Next, open up the menu in the top-right, click "Get alerts about this," and you'll see that same screen of options for when you want to get alerts about this progress bar.
+Setting up this kind of alert is really similar to setting up a goal line alert. First, create a question that returns a single number as its result, then choose the Progress Bar chart type from the Visualization menu. Open the settings menu to select a goal value, click Done, then save your question.
+
+Next, click the bell icon in the bottom-right and you'll see that same screen of options for when you want to get alerts about this progress bar.
### Results alerts
-Lastly, you can get an alert when one of your saved questions returns any result. This kind of alert is the most useful if you have a question that doesn't *usually* return any results, but you just want to know when it *does*. For example, you might have a table called `Reviews`, and you want to know any time a customer leaves a bad review, which you consider to be anything below three stars. To set up an alert for this situation, you'd go and create a raw data question (i.e., a question that returns a list of reviews), and add a filter to only include results with one or two stars.
+
+Lastly, you can get an alert when one of your saved questions returns any result. This kind of alert is the most useful if you have a question that doesn't _usually_ return any results, but you just want to know when it _does_. For example, you might have a table called `Reviews`, and you want to know any time a customer leaves a bad review, which you consider to be anything below three stars. To set up an alert for this situation, you'd go and create a raw data question (i.e., a question that returns a list of reviews), and add a filter to only include results with one or two stars.
-You probably don't want to be alerted about all the bad reviews you've *ever* gotten, but just recent ones, you'd probably also add a filter to only include results from yesterday or today, depending on how often you want to check for these bad reviews. At this point, when you check the results of this question, it probably won't return any results, which is a good thing.
+You probably don't want to be alerted about all the bad reviews you've _ever_ gotten, but just recent ones. So you can add a filter to only include results from yesterday or today, depending on how often you want to check for these bad reviews. At this point, when you check the results of this question, it probably won't return any results, which is a good thing.
-Save the question, the click on "get alerts about this" from the menu in the top-right of the screen, and select how often you want Metabase to check this question for results. That's it!
+Save the question, the click on the bell icon in the bottom-right of the screen, and select how often you want Metabase to check this question for results. That's it!
### Adding additional recipients to your alerts
+
If you're an administrator of your Metabase instance, you'll be able to see and edit every alert on all saved questions. You'll also see some additional options to add recipients to alerts, which look like this:
@@ -61,7 +69,9 @@ Just like with [Pulses](10-pulses.md), you can add any Metabase user, email addr
Here's more information about [setting up email integration](../administration-guide/02-setting-up-email.md) and [setting up Slack integration](../administration-guide/09-setting-up-slack.md).
### Stopping alerts
+
There are a few ways alerts can be stopped:
+
- Regular users can unsubscribe from any alert that they're a recipient of.
- Admins can edit any alert and delete it entirely. This can't be undone, so be careful!
- If a saved question that has an alert on it gets edited in such a way that the alert doesn't make sense anymore, the alert will get deleted. For example, if a saved question with a goal line alert on it gets edited, and the goal line is removed entirely, that alert will get deleted.
diff --git a/docs/users-guide/custom-questions.md b/docs/users-guide/custom-questions.md
new file mode 100644
index 0000000000000000000000000000000000000000..50f77869af03fc6503c685642ca00026ec8ce4f5
--- /dev/null
+++ b/docs/users-guide/custom-questions.md
@@ -0,0 +1,124 @@
+## Creating custom questions with the notebook editor
+
+If you have a question that's a bit more involved than a [simple question](04-asking-questions.md), you can create a custom question using the notebook editor. You can get there by clicking the Ask a Question button in the top nav bar and selecting Custom Question. If you started from a Simple question or a saved question, you can get back to the custom question notebook editor by clicking the icon in the top-right of the screen.
+
+### The parts of the notebook
+
+
+
+The notebook is made up of a sequence of individual steps. Under each step you'll see buttons to add more steps after the current one. To the right of each step is a preview button that shows you the first 10 rows of the results of your question up to that step.
+
+
+
+#### Picking your starting data
+
+This first step is required, and is where you pick the data that you want to base your question on. In most cases you'll pick one of the tables in your database, but you can also choose a previously saved question's result as the starting point for your new question. What this means in practice is that you can do things like use complex SQL queries to create new tables that can be used as starting data in a question just like any other table in your database.
+
+You can use most saved questions as source data, provided you have [permission](../administration-guide/05-setting-permissions.html) to view that question. You can even use questions that were saved as a chart rather than a table.
+
+There are some kinds of saved questions that can't be used as source data:
+
+- Druid questions
+- Google Analytics 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`
+
+#### Filtering
+
+
+
+When you add a filter step, you can select one or more columns to filter on. Depending on the type of column you pick, you'll get different options, like a calendar for date columns. [Learn more about filtering](04-asking-questions.md).
+
+You can add subsequent filter steps after every Summarize step. This lets you do things like summarize by the count of rows per month, and then add a filter on the `count` column to only include rows where the count is greater than 100. (This is basically like a SQL `HAVING` clause.)
+
+#### Summarizing
+
+
+
+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 columns. When picking your metrics you can choose from basic functions like sum, average, and count; or you can pick a common metric that an admin has defined; or you can create a custom expression by writing a formula.
+
+If you summarize and add a grouping you can then summarize _again_. You can also add steps to filter and/or join in between. For example, your first summarization step could be to get the count of orders per month, and you could then add a second summarization step to get the average monthly order total by selecting the `Average of…` your `count` column.
+
+
+
+**Custom expressions**
+
+Custom expressions allow you to do simple arithmetic within or between aggregation functions. For example, you could do `Average(FieldX) + Sum(FieldY)` or `Max(FieldX - FieldY)`, where `FieldX` and `FieldY` are fields in the currently selected table. You can either use your cursor to select suggested functions and fields, or simply start typing and use the autocomplete. If you are a Metabase administrator, you can now also use custom aggregation expressions when creating defined common metrics in the Admin Panel.
+
+Currently, you can any of the basic aggregation functions (the same ones that appear in the pick-the-metric-you-want-to-see dropdown), and these basic mathematical operators: `+`, `-`, `*` (multiply), `/` (divide). You can also use parentheses to specify the order of operations.
+
+#### Creating custom columns
+
+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.
+
+
+
+Say we had a table of baseball games, each row representing a single game, and we wanted to figure out how many more runs the home team scored than the away team (the “run differentialâ€). If we have one field with the home team’s score, and another field with the away team’s score, we could type a formula like this:
+
+
+
+The words in the quotes are the names of the fields in our table. If you start typing in this box, Metabase will show you fields in the current table that match what you’ve typed, and you can select from this list to autocomplete the field name.
+
+Right now, you can only use the following math operators in your formulas: `+`, `–`, `*` (multiplication), and `/` (division). You can also use parentheses to clarify the order of operations.
+
+Once you’ve written your formula and given your new column a name, select `Raw Data` for your view, and click the `Get Answer` button to see your new field appended to your current table. It’ll be on the far right of the table.
+
+**Note that this new column is NOT permanently added to this table.** It will only be kept if you save a question that uses it.
+
+Here’s our result:
+
+
+
+Now we can use this new column just like any other one, meaning we can use it to filter our question, add a grouping with it, or find out things like the average of it. You can add multiple custom fields, and they’ll all show up at the top of drop downs within the question builder:
+
+
+
+#### Sorting results
+
+
+
+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).
+
+#### Setting a row limit
+
+The row limit step lets you limit how many rows you want from the previous results. When used in conjunction with sorting, this 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.
+
+#### Joining data
+
+
+
+The join step allows you to combine your current data with another table, or even with a saved question.
+
+Currently you can't use joins if your starting data is from a Google Analytics or MongoDB database.
+
+After you click on the Join Data button to add a join step, you'll need to pick the data that you want to join. **Note:** You can only pick tables and saved questions that are from the same database as your starting data.
+
+
+
+Next, you'll need to pick the columns you want to join on. This means you pick a column from the first table, and a column from the second table, and the join will stitch rows together where the value from the first column is equal to the value in the second column. A very common example is to join on an ID column in each table, so if you happened to pick a table to join on where there is a foreign key relationship between the tables, Metabase will automatically pick those corresponding ID columns for you. At the end of your join step, there's a `Columns` button you can click to choose which columns you want to include from the joined data.
+
+By default, Metabase will do a left outer join, but you can click on the Venn diagram icon to change this to a different type of join. The options you'll see will differ based on the type of database you're using. Here are what the basic types of joins each do:
+
+- **Left outer join:** select all records from Table A, along with records from Table B that meet the join condition, if any.
+- **Right outer join:** select all records from Table B, along with records from Table B that meet the join condition, if any.
+- **Inner join:** only select the records from Table A and B where the join condition is met.
+- **Full outer join:** select all records from both tables, whether or not the join condition is met. This is not available for MySQL or H2, and is only available for some database types, like Spark SQL, SQL Server, and SQLite.
+
+**A left outer join example:** If Table A is Orders and Table B is Customers, and assuming you do a join where the `customer_id` column in Orders is equal to the `ID` column in Customers, when you do a left outer join your results will be a full list of all your orders, and each order row will also display the columns of the customer who placed that order. Since a single customer can place many orders, a given customer's information might be repeated many times for different order rows. If there isn't a corresponding customer for a given order, the order's information will be shown, but the customer columns will just be blank for that row.
+
+##### Multiple stages of joins
+
+In many cases you might have tables A, B, and C, where A and B have a connection, and B and C have a connection, but A and C don't. If you want to join A to B to C, all you have to do is add multiple join steps. Click on Join Data, join table A to table B, then click the Join Data step below that completed join block to add a second join step, and join the results of your last join to table C.
+
+
+
+### Viewing the SQL that powers your question
+
+Under the hood, all Metabase questions are SQL (gasp!). If you're curious to see the SQL that will get run when you ask your question, you can click the little console icon in the top-right of the notebook editor. In the modal that opens up, you'll also be given the option to start a new query in the SQL editor, using this generated SQL as a starting point. It's a nice little shortcut to have Metabase write some boilerplate SQL for you, but then allows you to tweak and customize the query.
+
+---
+
+## Next: writing SQL
+
+If you have a question that's even too much for the notebook, you can always fire up the trusty old [SQL editor](writing-sql.md).
diff --git a/docs/users-guide/images/Bookicon.png b/docs/users-guide/images/Bookicon.png
index 863d5ca70037ff3fcd9281ff227dfe856d012a22..95cb16f3d8bfd8e1aeddeab52e89cb200b412c53 100644
Binary files a/docs/users-guide/images/Bookicon.png and b/docs/users-guide/images/Bookicon.png differ
diff --git a/docs/users-guide/images/DataReference.png b/docs/users-guide/images/DataReference.png
index 61979f878eafea4d6e31ce846b4408fc2f2df85e..6e9ee2e00085474007ba07f88ca574b646e8cf1d 100644
Binary files a/docs/users-guide/images/DataReference.png and b/docs/users-guide/images/DataReference.png differ
diff --git a/docs/users-guide/images/DataReferenceTab.png b/docs/users-guide/images/DataReferenceTab.png
deleted file mode 100644
index f0f1836b314897ee0d06c580a7935ab2507e8732..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/DataReferenceTab.png and /dev/null differ
diff --git a/docs/users-guide/images/MultiSeriesQueryBuilder.png b/docs/users-guide/images/MultiSeriesQueryBuilder.png
index f786b6fcbb1537fbdb159df90fec98507276f326..dc45297e86bea6ff4c037bd9cb82ca0fb6aef531 100644
Binary files a/docs/users-guide/images/MultiSeriesQueryBuilder.png and b/docs/users-guide/images/MultiSeriesQueryBuilder.png differ
diff --git a/docs/users-guide/images/QueryInterfaceBar.png b/docs/users-guide/images/QueryInterfaceBar.png
deleted file mode 100644
index afa8c57be3eb2ba5528fc510874e866df9b5a17c..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/QueryInterfaceBar.png and /dev/null differ
diff --git a/docs/users-guide/images/SQL-filter-widget.png b/docs/users-guide/images/SQL-filter-widget.png
new file mode 100644
index 0000000000000000000000000000000000000000..da337b7deaeffef218e90272d59cf2125ba22bf9
Binary files /dev/null and b/docs/users-guide/images/SQL-filter-widget.png differ
diff --git a/docs/users-guide/images/SQLInterface.png b/docs/users-guide/images/SQLInterface.png
index 27dae4c39ae973e43a33ba68c02f88dc389afd44..f399193731be3e908edaae873e13798bf3eb828a 100644
Binary files a/docs/users-guide/images/SQLInterface.png and b/docs/users-guide/images/SQLInterface.png differ
diff --git a/docs/users-guide/images/SaveButton.png b/docs/users-guide/images/SaveButton.png
index 1dd0ec501411e9db30407f98318eb2471844d15c..c265eeac15dc2f5a129c3cf8474f702573fef87b 100644
Binary files a/docs/users-guide/images/SaveButton.png and b/docs/users-guide/images/SaveButton.png differ
diff --git a/docs/users-guide/images/VisualizeChoices.png b/docs/users-guide/images/VisualizeChoices.png
index 1a28437171e3868af1a9cb1e17a730a21ee1845f..71a7cfb1ebcfb5b82032e36416246bd1fcec23ab 100644
Binary files a/docs/users-guide/images/VisualizeChoices.png and b/docs/users-guide/images/VisualizeChoices.png differ
diff --git a/docs/users-guide/images/alerts/bad-reviews.png b/docs/users-guide/images/alerts/bad-reviews.png
index c3fa0c784f72e990f4f3e92179bdc2edb82d515b..8750b031a496600cc2ac2eab8c3077093310cc0c 100644
Binary files a/docs/users-guide/images/alerts/bad-reviews.png and b/docs/users-guide/images/alerts/bad-reviews.png differ
diff --git a/docs/users-guide/images/alerts/edit-menu.png b/docs/users-guide/images/alerts/edit-menu.png
index f9d5c9a3bd7060cca4a552fcd6e55e7c40105487..e796a7adc5949e6b92e37a375443da4455121ab5 100644
Binary files a/docs/users-guide/images/alerts/edit-menu.png and b/docs/users-guide/images/alerts/edit-menu.png differ
diff --git a/docs/users-guide/images/alerts/get-alerts-about-this.png b/docs/users-guide/images/alerts/get-alerts-about-this.png
index fa4e722a21476f6e04d011ea8d58c2ef1157ccea..e936322d8fd81500bdaf1514d35c8dd06a886792 100644
Binary files a/docs/users-guide/images/alerts/get-alerts-about-this.png and b/docs/users-guide/images/alerts/get-alerts-about-this.png differ
diff --git a/docs/users-guide/images/alerts/no-results.png b/docs/users-guide/images/alerts/no-results.png
index 15a34e4c206841bd9c483469f7cf832c795e30d9..404768fb6cfeaef4dbe73c7df1dd8a8cbf583063 100644
Binary files a/docs/users-guide/images/alerts/no-results.png and b/docs/users-guide/images/alerts/no-results.png differ
diff --git a/docs/users-guide/images/binning.png b/docs/users-guide/images/binning.png
deleted file mode 100644
index 3fa91a8336268e048635d90161373aeb22eace90..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/binning.png and /dev/null differ
diff --git a/docs/users-guide/images/browse-data.png b/docs/users-guide/images/browse-data.png
index 423205c7fdfdf7482782c08070552760dba6cf99..56b34099f724befa22259add56f01049db95c393 100644
Binary files a/docs/users-guide/images/browse-data.png and b/docs/users-guide/images/browse-data.png differ
diff --git a/docs/users-guide/images/collection-detail.png b/docs/users-guide/images/collection-detail.png
index 5dd7fe9277762c16d3f42b6ee64c0a576450f582..3b2c41f60cf9b5af2f67c36c9a346751b44a7505 100644
Binary files a/docs/users-guide/images/collection-detail.png and b/docs/users-guide/images/collection-detail.png differ
diff --git a/docs/users-guide/images/create-menu.png b/docs/users-guide/images/create-menu.png
index 6c93c4798b0f53282f34354ade51eb0725cbfbf3..f3f67795d40f51365847cf34dd08d899ba7cb7e3 100644
Binary files a/docs/users-guide/images/create-menu.png and b/docs/users-guide/images/create-menu.png differ
diff --git a/docs/users-guide/images/custom-fields/context-menu.png b/docs/users-guide/images/custom-fields/context-menu.png
deleted file mode 100644
index d1c9d91a472fcaf03fb89583a5848c1f6bb581ae..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/custom-fields/context-menu.png and /dev/null differ
diff --git a/docs/users-guide/images/dashboards/DashboardEdit.png b/docs/users-guide/images/dashboards/DashboardEdit.png
index 1c1601cac0c38f9553a6d1458d9fdc981b1bdb3a..a7d26f4041ca48b219114da9686e28863fab7cc4 100644
Binary files a/docs/users-guide/images/dashboards/DashboardEdit.png and b/docs/users-guide/images/dashboards/DashboardEdit.png differ
diff --git a/docs/users-guide/images/data-reference-column-detail.png b/docs/users-guide/images/data-reference-column-detail.png
new file mode 100644
index 0000000000000000000000000000000000000000..4b037508592edbc7d7f84dd54c37d092e96c11e5
Binary files /dev/null and b/docs/users-guide/images/data-reference-column-detail.png differ
diff --git a/docs/users-guide/images/drill-through/actions.png b/docs/users-guide/images/drill-through/actions.png
deleted file mode 100644
index feb04e38be96d9fcf4fb663ad149387a3141143e..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/drill-through/actions.png and /dev/null differ
diff --git a/docs/users-guide/images/drill-through/heading-actions.png b/docs/users-guide/images/drill-through/heading-actions.png
index f0817602da13e5ad8e1a943294764e3be0096e75..c23777f5cc491046c9ed74c7221bd060533e574f 100644
Binary files a/docs/users-guide/images/drill-through/heading-actions.png and b/docs/users-guide/images/drill-through/heading-actions.png differ
diff --git a/docs/users-guide/images/drill-through/inequality-filters.png b/docs/users-guide/images/drill-through/inequality-filters.png
index 6fffc3db838c85d299a0abba0e644adfe29b9c01..3b89f7ec8d77b9d126039268770ca27b35c8a511 100644
Binary files a/docs/users-guide/images/drill-through/inequality-filters.png and b/docs/users-guide/images/drill-through/inequality-filters.png differ
diff --git a/docs/users-guide/images/histogram.png b/docs/users-guide/images/histogram.png
index 4657f24ec8a72a0e5a99e0d5a7fd89a7fd2ce95d..2244968c1ebd9c0f3cef7e1ad409084cf7392b09 100644
Binary files a/docs/users-guide/images/histogram.png and b/docs/users-guide/images/histogram.png differ
diff --git a/docs/users-guide/images/homepage-x-rays.png b/docs/users-guide/images/homepage-x-rays.png
deleted file mode 100644
index 800eaef33e9b77693affa25877e33d35f008c85e..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/homepage-x-rays.png and /dev/null differ
diff --git a/docs/users-guide/images/insights.png b/docs/users-guide/images/insights.png
deleted file mode 100644
index a7dd4dc24ed3715334f44b013281912d555c58f9..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/insights.png and /dev/null differ
diff --git a/docs/users-guide/images/metabase-homepage.png b/docs/users-guide/images/metabase-homepage.png
index 2618c7204ea86349ba48d167b5c10eb83595caa2..2830583a246a678203320471a63e99272f4b5d70 100644
Binary files a/docs/users-guide/images/metabase-homepage.png and b/docs/users-guide/images/metabase-homepage.png differ
diff --git a/docs/users-guide/images/metric-action-menu.png b/docs/users-guide/images/metric-action-menu.png
deleted file mode 100644
index c84407afa661081cdc4fe3cd7a8f4657b6a4d921..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/metric-action-menu.png and /dev/null differ
diff --git a/docs/users-guide/images/metric-drill-through.png b/docs/users-guide/images/metric-drill-through.png
deleted file mode 100644
index 9415a5f9c927fe2a972617a5156b56d20011337f..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/metric-drill-through.png and /dev/null differ
diff --git a/docs/users-guide/images/new-question-all-options.png b/docs/users-guide/images/new-question-all-options.png
deleted file mode 100644
index fa0a3c9c794e8cbb2d635e0555476f2f4735fe13..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/new-question-all-options.png and /dev/null differ
diff --git a/docs/users-guide/images/new-question.png b/docs/users-guide/images/new-question.png
new file mode 100644
index 0000000000000000000000000000000000000000..1fd770f133f31328bc579b856e414938404cfbb3
Binary files /dev/null and b/docs/users-guide/images/new-question.png differ
diff --git a/docs/users-guide/images/notebook/filter-badge.png b/docs/users-guide/images/notebook/filter-badge.png
new file mode 100644
index 0000000000000000000000000000000000000000..e0869f941790fe4a4461702003937c85e130fb87
Binary files /dev/null and b/docs/users-guide/images/notebook/filter-badge.png differ
diff --git a/docs/users-guide/images/notebook/filter-step.png b/docs/users-guide/images/notebook/filter-step.png
new file mode 100644
index 0000000000000000000000000000000000000000..d004e9937f111c0ec99a165b45e9c0a9f75fe914
Binary files /dev/null and b/docs/users-guide/images/notebook/filter-step.png differ
diff --git a/docs/users-guide/images/notebook/histogram-bins.png b/docs/users-guide/images/notebook/histogram-bins.png
new file mode 100644
index 0000000000000000000000000000000000000000..0645334f729c9fd81667b3d57f6ad2698a50e1b0
Binary files /dev/null and b/docs/users-guide/images/notebook/histogram-bins.png differ
diff --git a/docs/users-guide/images/notebook/join-a-b-c.png b/docs/users-guide/images/notebook/join-a-b-c.png
new file mode 100644
index 0000000000000000000000000000000000000000..fb8016018636f16734e3f906669f090aa3fc6107
Binary files /dev/null and b/docs/users-guide/images/notebook/join-a-b-c.png differ
diff --git a/docs/users-guide/images/notebook/join-pick-data.png b/docs/users-guide/images/notebook/join-pick-data.png
new file mode 100644
index 0000000000000000000000000000000000000000..1e73921211762c27a24ba87f1fee468250df6e13
Binary files /dev/null and b/docs/users-guide/images/notebook/join-pick-data.png differ
diff --git a/docs/users-guide/images/notebook/join-step.png b/docs/users-guide/images/notebook/join-step.png
new file mode 100644
index 0000000000000000000000000000000000000000..a17035a62a2029184125899f7095d55e71394b44
Binary files /dev/null and b/docs/users-guide/images/notebook/join-step.png differ
diff --git a/docs/users-guide/images/notebook/multiple-summarize-steps.png b/docs/users-guide/images/notebook/multiple-summarize-steps.png
new file mode 100644
index 0000000000000000000000000000000000000000..65be7ac77f38a66ba1a46bdddda1c7cb564d14b7
Binary files /dev/null and b/docs/users-guide/images/notebook/multiple-summarize-steps.png differ
diff --git a/docs/users-guide/images/notebook/notebook-ui.png b/docs/users-guide/images/notebook/notebook-ui.png
new file mode 100644
index 0000000000000000000000000000000000000000..1489868993b86c7328f10b8420a3ecb74714a235
Binary files /dev/null and b/docs/users-guide/images/notebook/notebook-ui.png differ
diff --git a/docs/users-guide/images/notebook/preview-table.png b/docs/users-guide/images/notebook/preview-table.png
new file mode 100644
index 0000000000000000000000000000000000000000..99f6f9f6242e34a83126f750c759ee48961993d6
Binary files /dev/null and b/docs/users-guide/images/notebook/preview-table.png differ
diff --git a/docs/users-guide/images/notebook/record-details.png b/docs/users-guide/images/notebook/record-details.png
new file mode 100644
index 0000000000000000000000000000000000000000..0e52f75e36223bd8067d71240f261b1913b2c8a4
Binary files /dev/null and b/docs/users-guide/images/notebook/record-details.png differ
diff --git a/docs/users-guide/images/notebook/sort-step.png b/docs/users-guide/images/notebook/sort-step.png
new file mode 100644
index 0000000000000000000000000000000000000000..0220354fd7d03bd51dfc19cda2d6558c143a8f35
Binary files /dev/null and b/docs/users-guide/images/notebook/sort-step.png differ
diff --git a/docs/users-guide/images/notebook/summarize-sidebar.png b/docs/users-guide/images/notebook/summarize-sidebar.png
new file mode 100644
index 0000000000000000000000000000000000000000..025ff2f6b097f2d6bdf4d8b5d246ea6f537ffe03
Binary files /dev/null and b/docs/users-guide/images/notebook/summarize-sidebar.png differ
diff --git a/docs/users-guide/images/notebook/summarize-step.png b/docs/users-guide/images/notebook/summarize-step.png
new file mode 100644
index 0000000000000000000000000000000000000000..0bfe4127276e67d8383ce5f38b888d71ab5b1cd1
Binary files /dev/null and b/docs/users-guide/images/notebook/summarize-step.png differ
diff --git a/docs/users-guide/images/notebook/summarize-timeseries-breakout.png b/docs/users-guide/images/notebook/summarize-timeseries-breakout.png
new file mode 100644
index 0000000000000000000000000000000000000000..41fc886c1a9733c0c5f5009323a2037058afcd40
Binary files /dev/null and b/docs/users-guide/images/notebook/summarize-timeseries-breakout.png differ
diff --git a/docs/users-guide/images/notebook/summarize-timeseries.png b/docs/users-guide/images/notebook/summarize-timeseries.png
new file mode 100644
index 0000000000000000000000000000000000000000..84d4bfa5cdff8a8e765866210111a4dde13d2505
Binary files /dev/null and b/docs/users-guide/images/notebook/summarize-timeseries.png differ
diff --git a/docs/users-guide/images/our-analytics-page.png b/docs/users-guide/images/our-analytics-page.png
index ccd13915992b2baee6d16bd8c33a0f474c715ab5..d63f525a9558569d8fcac2ed919f5a099812a216 100644
Binary files a/docs/users-guide/images/our-analytics-page.png and b/docs/users-guide/images/our-analytics-page.png differ
diff --git a/docs/users-guide/images/search-results.png b/docs/users-guide/images/search-results.png
index 1ecc3053cf328fa26aed14314af2933960a9924c..32c330d250df403b4cda5e9f5ceddc274322436d 100644
Binary files a/docs/users-guide/images/search-results.png and b/docs/users-guide/images/search-results.png differ
diff --git a/docs/users-guide/images/segment-actions.png b/docs/users-guide/images/segment-actions.png
deleted file mode 100644
index 7491a7859d5da9b6a345896be0a32a1eb55ee8a9..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/segment-actions.png and /dev/null differ
diff --git a/docs/users-guide/images/share-icon.png b/docs/users-guide/images/share-icon.png
index 90f5cbc424c020beca12748e0403f6b1a03b7155..f90ba58fb0086979cde3464d4e950674c0bcbb9a 100644
Binary files a/docs/users-guide/images/share-icon.png and b/docs/users-guide/images/share-icon.png differ
diff --git a/docs/users-guide/images/visualizations/add-fields.png b/docs/users-guide/images/visualizations/add-fields.png
index 988927d832addb29b497cf05d24fb19f4160f60f..a9c26857e46587ab844f3dcd12685c273073da10 100644
Binary files a/docs/users-guide/images/visualizations/add-fields.png and b/docs/users-guide/images/visualizations/add-fields.png differ
diff --git a/docs/users-guide/images/visualizations/chart-formatting-options.png b/docs/users-guide/images/visualizations/chart-formatting-options.png
index 0c4f8c6f8d7bbc823bb88d2086678ffdf3cb070c..0d007e2d45136de301316a3cea81611be304814d 100644
Binary files a/docs/users-guide/images/visualizations/chart-formatting-options.png and b/docs/users-guide/images/visualizations/chart-formatting-options.png differ
diff --git a/docs/users-guide/images/visualizations/chart-formatting.png b/docs/users-guide/images/visualizations/chart-formatting.png
index 23e465f5b0c30207a627c013baef4b83678bc23a..5ed4a26d80a4fa64c94769c3c1cf7b73b990db9a 100644
Binary files a/docs/users-guide/images/visualizations/chart-formatting.png and b/docs/users-guide/images/visualizations/chart-formatting.png differ
diff --git a/docs/users-guide/images/visualizations/column-header-formatting.png b/docs/users-guide/images/visualizations/column-header-formatting.png
index be896806e4e49a6c228ab6547c377160ade5e9f7..b033597a71fe7f1dab30eb4d1536c6066ea721bb 100644
Binary files a/docs/users-guide/images/visualizations/column-header-formatting.png and b/docs/users-guide/images/visualizations/column-header-formatting.png differ
diff --git a/docs/users-guide/images/visualizations/combo-chart-data-1.png b/docs/users-guide/images/visualizations/combo-chart-data-1.png
index 008d259edb3463894ccc0cc206e0ae7bec454e38..5b80f1ce3a950ccb01ebcab5b375d37f25e99dd4 100644
Binary files a/docs/users-guide/images/visualizations/combo-chart-data-1.png and b/docs/users-guide/images/visualizations/combo-chart-data-1.png differ
diff --git a/docs/users-guide/images/visualizations/combo-chart-data-2.png b/docs/users-guide/images/visualizations/combo-chart-data-2.png
index 1f926ee4378b9665bc0cc044d8bc5fc2eb91cf60..6e245f3522d67ebb338ad9d0d042bcf1f80fb460 100644
Binary files a/docs/users-guide/images/visualizations/combo-chart-data-2.png and b/docs/users-guide/images/visualizations/combo-chart-data-2.png differ
diff --git a/docs/users-guide/images/visualizations/combo-chart-settings.png b/docs/users-guide/images/visualizations/combo-chart-settings.png
index 29e76994c1610bc12d4a37f9f5ccb579112143ff..48654ca78751d6de5f956dd41217bf05a41880f8 100644
Binary files a/docs/users-guide/images/visualizations/combo-chart-settings.png and b/docs/users-guide/images/visualizations/combo-chart-settings.png differ
diff --git a/docs/users-guide/images/visualizations/combo-chart.png b/docs/users-guide/images/visualizations/combo-chart.png
index 4fa379cef1081b614cfbc6e854e283103a66fd98..386ec2a1234e0a246abd60ce0742560a5e792d85 100644
Binary files a/docs/users-guide/images/visualizations/combo-chart.png and b/docs/users-guide/images/visualizations/combo-chart.png differ
diff --git a/docs/users-guide/images/visualizations/conditional-formatting.png b/docs/users-guide/images/visualizations/conditional-formatting.png
index 5d60851d3df313450237e8c51ceab98082715a9b..40873aa0a08782444a47d09512600d354b7b0643 100644
Binary files a/docs/users-guide/images/visualizations/conditional-formatting.png and b/docs/users-guide/images/visualizations/conditional-formatting.png differ
diff --git a/docs/users-guide/images/visualizations/donut.png b/docs/users-guide/images/visualizations/donut.png
index 1414e0e883030ca400e8f99e47518f55ab1e3cd9..612167080c6e1f93bbc1a6e0408931428b505a8b 100644
Binary files a/docs/users-guide/images/visualizations/donut.png and b/docs/users-guide/images/visualizations/donut.png differ
diff --git a/docs/users-guide/images/visualizations/gauge-settings.png b/docs/users-guide/images/visualizations/gauge-settings.png
index fee18c7d33071c3bd3ae4aa9f6e981c13dc76d71..d461270dfd9659d2e25792d2872cc3d659e330c9 100644
Binary files a/docs/users-guide/images/visualizations/gauge-settings.png and b/docs/users-guide/images/visualizations/gauge-settings.png differ
diff --git a/docs/users-guide/images/visualizations/gauge.png b/docs/users-guide/images/visualizations/gauge.png
index 85f7b07deadaebad767b378d521be687886e983c..b20aaab754eaff7f1423ef74db9cddca917f7145 100644
Binary files a/docs/users-guide/images/visualizations/gauge.png and b/docs/users-guide/images/visualizations/gauge.png differ
diff --git a/docs/users-guide/images/visualizations/number.png b/docs/users-guide/images/visualizations/number.png
index 8c47b599c651c73013d1de00b0055abcddfa7743..417766f8e323716fae289646f4df664e8461166a 100644
Binary files a/docs/users-guide/images/visualizations/number.png and b/docs/users-guide/images/visualizations/number.png differ
diff --git a/docs/users-guide/images/visualizations/pin-map.png b/docs/users-guide/images/visualizations/pin-map.png
index dd9e91a8b920c0d6a92efa32447158593ffe6cfa..5ef31e3715923a4b74df6f54323b125f80c5b0a8 100644
Binary files a/docs/users-guide/images/visualizations/pin-map.png and b/docs/users-guide/images/visualizations/pin-map.png differ
diff --git a/docs/users-guide/images/visualizations/pivot.png b/docs/users-guide/images/visualizations/pivot.png
index 5cfdf14f6ff0a61b53e6ecb1a25a08ca36d3a7aa..e0f04b24e2d80f602600d1dfa937b38709845041 100644
Binary files a/docs/users-guide/images/visualizations/pivot.png and b/docs/users-guide/images/visualizations/pivot.png differ
diff --git a/docs/users-guide/images/visualizations/progress.png b/docs/users-guide/images/visualizations/progress.png
index 9814e3356e6517e688c86cc12bfc1b972cb295dd..ea5ec42bb65dddbfd633d0636afdf886238f206b 100644
Binary files a/docs/users-guide/images/visualizations/progress.png and b/docs/users-guide/images/visualizations/progress.png differ
diff --git a/docs/users-guide/images/visualizations/row.png b/docs/users-guide/images/visualizations/row.png
index 28b451b60f9c9b557de03848f1273ad4ef7b1b3a..07d03715ef75479d9b179848e4594d51dc80e86e 100644
Binary files a/docs/users-guide/images/visualizations/row.png and b/docs/users-guide/images/visualizations/row.png differ
diff --git a/docs/users-guide/images/visualizations/smart-number.png b/docs/users-guide/images/visualizations/smart-number.png
index 34932e818e70b44f43fa53a34faa6d08b37ffbf9..939e09f7c444881db863f8bd6e000426a6d7e1de 100644
Binary files a/docs/users-guide/images/visualizations/smart-number.png and b/docs/users-guide/images/visualizations/smart-number.png differ
diff --git a/docs/users-guide/images/visualizations/smart-scalar-settings.png b/docs/users-guide/images/visualizations/smart-scalar-settings.png
index 0b33f973d049503fd540860c809c6334f21d8ca2..7dfffaa45ec706f95f0fe9ca0efa7e031cdb3feb 100644
Binary files a/docs/users-guide/images/visualizations/smart-scalar-settings.png and b/docs/users-guide/images/visualizations/smart-scalar-settings.png differ
diff --git a/docs/users-guide/images/visualizations/trend-lines.png b/docs/users-guide/images/visualizations/trend-lines.png
index 15bcf87248f4124d6033d65caa9cb7ecb53a0cc0..f7007296d9375e9b8e7ae8f78819dc4b203cb317 100644
Binary files a/docs/users-guide/images/visualizations/trend-lines.png and b/docs/users-guide/images/visualizations/trend-lines.png differ
diff --git a/docs/users-guide/images/x-rays/example.png b/docs/users-guide/images/x-rays/example.png
deleted file mode 100644
index 4dde0fe6a443cca9744faaa4777b138ece1035ea..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/x-rays/example.png and /dev/null differ
diff --git a/docs/users-guide/images/x-rays/x-ray-action.png b/docs/users-guide/images/x-rays/x-ray-action.png
deleted file mode 100644
index 3dce83a3e075a23f124892cdb4e07e154fc8ad87..0000000000000000000000000000000000000000
Binary files a/docs/users-guide/images/x-rays/x-ray-action.png and /dev/null differ
diff --git a/docs/users-guide/images/x-rays/x-rays-browse.png b/docs/users-guide/images/x-rays/x-rays-browse.png
new file mode 100644
index 0000000000000000000000000000000000000000..fbd31dc76ac73c25e6120b988bfdf51d18ee7579
Binary files /dev/null and b/docs/users-guide/images/x-rays/x-rays-browse.png differ
diff --git a/docs/users-guide/start.md b/docs/users-guide/start.md
index a737d161e266d50f99fc8df314992a373fa82df5..3e6e1cedf9f52ec004f61dc0bdff8c69ab91e643 100644
--- a/docs/users-guide/start.md
+++ b/docs/users-guide/start.md
@@ -1,21 +1,32 @@
# User Guide
-**This guide will teach you:**
-
-* [An overview of Metabase](01-what-is-metabase.md)
-* [The basics of database terminology](02-database-basics.md)
-* [Basic exploration in Metabase](03-basic-exploration.md)
-* [Asking questions in Metabase](04-asking-questions.md)
-* [How to visualize the answers to questions](05-visualizing-results.md)
-* [Sharing and organizing your saved questions](06-sharing-answers.md)
-* [Creating dashboards](07-dashboards.md)
-* [Adding filters to dashboards](08-dashboard-filters.md)
-* [Creating charts with multiple series](09-multi-series-charting.md)
-* [Using Pulses for daily emails](10-pulses.md)
-* [Get answers in Slack with Metabot](11-metabot.md)
-* [Some helpful tips on building your data model](12-data-model-reference.md)
-* [Creating SQL Templates](13-sql-parameters.md)
-* [Viewing X-ray reports](14-x-rays.md)
-* [Getting alerts](15-alerts.md)
+**Some basics**
+
+- [An overview of Metabase](01-what-is-metabase.md)
+- [The basics of databases](02-database-basics.md)
+
+**Exploring and asking questions**
+
+- [Basic exploration in Metabase](03-basic-exploration.md)
+- [Asking questions in Metabase](04-asking-questions.md)
+- [Using the notebook editor to ask custom questions](custom-questions.md)
+- [Using the SQL editor](writing-sql.md)
+- [How to visualize the answers to questions](05-visualizing-results.md)
+
+**Sharing results**
+
+- [Sharing and organizing your saved questions](06-sharing-answers.md)
+- [Creating dashboards](07-dashboards.md)
+- [Adding filters to dashboards](08-dashboard-filters.md)
+- [Creating dashboard charts with multiple series](09-multi-series-charting.md)
+- [Using Pulses for daily emails](10-pulses.md)
+- [Get answers in Slack with Metabot](11-metabot.md)
+
+**More**
+
+- [Referencing your data model while writing SQL](12-data-model-reference.md)
+- [Creating SQL Templates](13-sql-parameters.md)
+- [Getting automatic insights with X-rays](14-x-rays.md)
+- [Setting and getting alerts](15-alerts.md)
Let's get started with an overview of [What Metabase does](01-what-is-metabase.md).
diff --git a/docs/users-guide/writing-sql.md b/docs/users-guide/writing-sql.md
new file mode 100644
index 0000000000000000000000000000000000000000..a016cc61263b3b60569c2e644af7f98b70454aef
--- /dev/null
+++ b/docs/users-guide/writing-sql.md
@@ -0,0 +1,37 @@
+## Asking more advanced questions in the SQL/native query editor
+
+If you ever need to ask questions that can't be expressed using the question builder, you can use **SQL** instead.
+
+### What's SQL?
+
+SQL (pronounced "sequel") stands for Structured Query Language, and is a widely used standard for getting data from databases. We won't try to teach you all about SQL in this guide, but to learn more about it, check out this [SQL Tutorial](http://www.w3schools.com/sql/default.asp).
+
+Even if you don't understand SQL or how to use it, it's worthwhile to understand how works inside Metabase because sometimes other people will share SQL-based questions that might be useful to you.
+
+### Starting a new SQL query
+
+If you have the [permissions](../administration-guide/05-setting-permissions.md) to use the SQL editor, when you click the Ask a Question button you'll see an option to start a new SQL query. There's also a shortcut to the editor in the top nav bar; it's the little console icon.
+
+You can write SQL (or your database's native querying language) directly into the editor that appears.
+
+
+
+To try it out, type the command `select sum(subtotal), created_at from orders group by created_at`. Don't worry if you don't understand this just yet. Click the blue run button and note the table that comes back is the same as if you had asked for the sum of Subtotal in the Orders table, grouped by Created At.
+
+**Tip!** You can run your SQL query by pressing `ctrl` + `enter` on Windows, or `command` + `return` on a Mac. You can also run only a specific section of a query by selecting the part you'd like to run and pressing `ctrl` + `alt` + `enter` on Windows, or `command` + `option` + `return` on a Mac.
+
+Questions asked using SQL can be saved, downloaded, or added to a dashboard just like questions asked using the question builder.
+
+### Using SQL filters
+
+If you or someone else wrote a SQL query that includes [variables](13-sql-parameters.md), your question might have filter widgets at the top of the screen. These let you modify and filter the SQL query before it's run, changing the results you might get.
+
+
+
+Writing SQL queries that use variables or parameters can be very powerful, but it's also a bit more advanced, so that topic has its own page if you'd like to [learn more](13-sql-parameters.md).
+
+---
+
+## Next: Creating charts
+
+Now that you have an answer to your question, you can now learn more about [visualizing answers](05-visualizing-results.md).