Merge branch 'master' into docs-fixes [ci skip]

docs/users-guide/09-multi-series-charting.md

@@ -7,73 +7,88 @@ Data in isolation is rarely all that useful. One of the best ways to add context
 - New users per day vs. returning users per day.
 - Orders per day from a few different product lines.
 
-### In Metabase there are two main ways to get data side-by-side.
+### Displaying data side by side
 
-1. Combining two existing saved questions that share a common dimension (like time) on a dashboard
+There are two main ways to visualize data side by side:
 
-e.g. Let me see revenue over time and cost over time together.
+1. [**Ask a question that involves multiple dimensions**](#ask-a-question-that-involves-multiple-dimensions) with the Simple or Custom query builders (or in SQL, if you’re fancy). Example: the count of users by region over time.
 
-2. Asking a question that involves multiple dimensions in the query builder (or in SQL if you’re fancy).
+2. [**Combine two saved questions**](#combining-two-saved-questions) that share a common dimension (like time) on a dashboard. For example, you could look at revenue over time and costs over time together.
 
-e.g. The count of users by region over time.
+### Ask a question that involves multiple dimensions 
 
-### Combining two existing saved questions
+If you’re creating a new question, you can view the results as a multi-series visualization by summarizing your data and grouping it into two groups.
 
-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:
+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, you would group by the `Source` and `Created At` columns of the **People** table.
+
+To create the multi-series chart, select the **People** table, click on the **Summarize** button in the upper right, then add `Source` and `Created At` as groupings (the `count of rows` metric that we want is selected by default). Be sure to click the plus button to the right of your selection, so Metabase knows to add the grouping; otherwise, Metabase will switch to that grouping. [Learn more about asking questions](04-asking-questions.md).
+
+Metabase will automatically display a multi-series line chart visualization of how each referrer has performed for us.
+
+![multi-series in the query builder](images/multi-series-charts/multi-series_query_builder.png)
+
+You can also create a multi-series chart by composing a custom question in the notebook editor. All you need to do is summarize your data (e.g., count the rows) and group that data into multiple groups (e.g. `Created At` by month and Product Category).
 
-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.
+![Composing a multi-series question in the notebook editor](images/multi-series-charts/notebook_editor_multi-series.png)
 
-2. While in edit mode on the dashboard, hovering on the card will show a “Edit data” button. Click this button to start adding series that you want to compare to the first series..
+Note: you won’t be able to add another saved question to multi-series visualizations made in this fashion. Metabase can visualize up to 100 distinct values of a dimension at once, so if you're selecting a field that contains a lot of values, you might need to filter the values.
 
-![multiseriestrigger](images/MultiSeriesTrigger.png)
 
-3. In the Edit Data modal you’ll see the original question, and on the right you’ll see a list of compatible questions you can choose from. Check the box next to any questions you’d like to see side-by-side with the original, and Metabase will add it to the same chart.
+### Combining two saved questions
 
-![multiseriesmodal1](images/MultiSeriesModal1.png)
+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 category to a dashboard. In practice, these will usually be line charts or bar charts.
+
+2. While in edit mode on the dashboard, hovering over a card will display some editing options in the upper right of the question, including an option to **add a line**, as well as a **gear** icon. Click on the add a line option (the **+** with a line and the word "Add" next to it). 
 
-The X and Y axis will automatically update if necessary and Metabase will create a legend using the existing card titles to help you understand which question maps to which series on the chart. Repeat this process as many times as you need.
+![add multi-series](images/multi-series-charts/add_series.png)
 
-To remove a series either uncheck the box, or click the x next to the title in the legend above the chart.
+3. In the Edit Data modal, you’ll see the original question on the left, with a list of compatible questions you can choose from on the right. Search question(s) to add, and check the box next to each question you’d like to see alongside with the original. Metabase will add the question(s) to the same chart.
 
-![multiseriesmodal2](images/MultiSeriesModal2.png)
+![multi-series edit modal](images/multi-series-charts/edit_modal.png)
 
-Once you have your chart looking how you’d like, hit done and your changes will be shown on the card in the dashboard. Depending on how dense your data is, at this point you might want to consider enlarging your chart to make sure the data is legible.
+If necessary, the X and Y axes will automatically update. Metabase will create a legend using the existing card titles to help you understand which question maps to which series on the chart. Repeat this process as many times as you need.
 
-![multiseriefinished](images/MultiSeriesFinished.png)
+![Edit modal with multi-series](images/multi-series-charts/edit_modal_multi-series.png)
 
-#### A quick note about SQL based questions.
+To remove a series, simply uncheck its box.
 
-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.
+Once you have your chart looking how you’d like, hit done. Metabase will show your changes on the card in the dashboard. Depending on how dense your data is, at this point you might want to consider enlarging your chart to make sure the data is legible.
+
+> **SQL questions may not work**. Metabase has less information about SQL-based questions, so we cannot guarantee they can be added reliably. You'll see a little warning sign next to SQL questions to indicate this uncertainty, so be aware that adding these kinds of questions may not work.
 
 ### 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.)
+If you need to compare single numbers to get a sense of how they differ, Metabase can turn multiple number charts into a bar chart. 
 
-### Creating a multi-series visualization in the query builder.
+As above, while editing a dashboard, hover over a number chart of your choice, and click on the icon with the **+** and bar chart icon to add a saved question. 
 
-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.
+![Add bar chart](images/multi-series-charts/add_bar_chart.png)
 
-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.)
+Use the search bar to find other saved question(s) that you’d like to see represented on the bar chart, and click the checkbox to add them to your chart. In this case, we added **Widget orders** to compare them to **Gadget orders**.
 
-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).
+![From numbers to bar chart](images/multi-series-charts/numbers_to_bar_chart.png)
 
-Metabase will automatically display a multi-series line chart visualization of how each referrer has performed for us.
+### Multi-series charts, values, and legibility
+
+When displaying multiple series, it’s important to keep legibility in mind. Combining many series can sometimes decrease the communication value of the data.
 
-![multiseriesquerybuilder](images/MultiSeriesQueryBuilder.png)
+Metabase allows you to add values to multi-series charts, but go easy on this feature, especially on charts with lots of data points. Adding values to multiple series, each with many data points, can make charts more difficult to read.
 
-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."
+From the **Visualization -> Display** options, you can toggle the option: **Show values on data points**. Metabase will do its best to fit as many values as can fit nicely. You can also force Metabase to (begrudgingly) show values for all data points, by setting the **Values to show** to **All**. 
 
-### Other multiple series tips
+![add values to multi-series chart](images/multi-series-charts/add_values.gif)
 
-- When displaying multiple series it’s important to keep legibility in mind. Combining many series can sometimes decrease the communication value of the data.
+You can also toggle values for each individual series. If you have three series, for example, you can show values on one, two, or all three series. In the **Display** tab, click on the down arrow to the right of a series to expand its details, and toggle **Show values for this series** to show or hide its values. You can also toggle values for the whole chart, then selectively hide values for individual series until you have your chart looking just right.
 
-### To recap:
+Additionally, there is an option to configure the formatting of the values: 
 
-- Existing saved questions can be combined and displayed on dashboards when editing the dashboard.
-- Scalars can be combined to create bar charts and simple funnels
-- You can produce a multi-series visualization in the query builder by adding two dimensions to your query.
+- **Auto**. Metabase selects the appropriate style for you
+- **Compact**. Metabase abbreviates values, e.g., 1,000 becomes 1K.
+- **Full**. Values are displayed in their natural beauty.
 
-Go forth and start letting your data get to know each other.
+Now go forth and start letting your data get to know each other.
 
 ---
 

docs/users-guide/custom-questions.md

@@ -86,12 +86,14 @@ After you click on the Join Data button to add a join step, you'll need to pick
 
 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:
+By default, Metabase will do a left outer join, but you can click on the Venn diagram icon to select a different type of join. Not all databases support all types of joins, so Metabase will only display the options supported by the database you're using.
+
+Here are the basic types of joins:
 
 - **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.
+- **Right outer join:** select all records from Table B, along with records from Table A 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.
+- **Full outer join:** select all records from both tables, whether or not the join condition is met.
 
 **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.
 

docs/users-guide/expressions.md

@@ -94,21 +94,18 @@ This would return rows where `Created At` is between January 1, 2020 and March 3
 
 Certain database types don't support some of the above functions:
 
-MySQL and SQL Server
+**BigQuery**: `abs`, `ceil`, `floor`, `median`, `percentile` and `round`
 
-- median
-- percentile
+**H2**: `median`, `percentile` and `regexextract`
 
-SQLite
+**MySQL**: `median`, `percentile` and `regexextract`
 
-- log
-- median
-- percentile
-- power
-- standardDeviation
-- sqrt
-- variance
+**SQL Server**: `median`, `percentile` and `regexextract`
 
-Additionally, **Vertica**, **BigQuery**, and **Presto** only provide _approximate_ results for median and percentile.
+**SQLite**: `log`, `median`, `percentile`, `power`, `regexextract`, `standardDeviation`, `sqrt` and `variance`
+
+**Vertica**: `median` and `percentile`
+
+Additionally, **Presto** only provides _approximate_ results for `median` and `percentile`.
 
 If you're using or maintaining a third-party database driver, please [refer to the wiki](https://github.com/metabase/metabase/wiki/What's-new-in-0.35.0-for-Metabase-driver-authors) to see how your driver might be impacted.