Merge pull request #5864 from metabase/0.26-docs

Docs for 0.26 features

docs/administration-guide/01-managing-databases.md

@@ -57,26 +57,39 @@ To add a database, you'll need its connection information.
 
 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 Analysis
+### Database Sync and Analysis
 
-When Metabase connects to your database, it tries to decipher the field types in your tables based on each field's name. Metabase also takes a sample of each table to look for URL's, json, encoded strings, etc. If a field is classified wrong, you can always manually edit it from the **Metadata** tab in the Admin Panel.
+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.
 
-### Metadata Syncing
+If you'd like to change these default settings, find and click on your database in the Databases section of the Admin Panel, and turn on the toggle at the bottom of the form that says "This is a large database, so let me choose when Metabase syncs and scans." (This is an option that used to be called "Enable in-depth analysis.")
 
-Metabase maintains it's own information about the various tables and fields in each Database that is added to aid in querying.  This information is generally updated once each night to look for changes to the database such as new tables, but if you'd like to sync your database manually at any time:
+![Large database toggle](images/large-db-toggle.png)
 
-NOTE: Metabase does NOT copy any data from your database, it only maintains lists of the tables and columns.
+Save your changes, and you'll see a new tab at the top of the form called "Scheduling." Click on that, and you'll see options to change when and how often Metabase syncs and scans.
 
-1. Go to the Admin Panel.
+#### Database syncing
 
-2. Select **Databases** from the navigation menu.
-![adminbar](images/AdminBar.png)
+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.
 
-3. Click on the database you would like to sync.
-![databaselist](images/DatabaseList.png)
+Syncing can be set to hourly, or daily at a specific time. Syncing can't be turned off completely, otherwise Metabase wouldn't work.
 
-4. Click on the **Sync** button on the right of the screen.
-![databaseconnection](images/DatabaseConnection.png)
+If you'd like to sync your database manually at any time, click on it from the Databases list in the admin panel and click on the Sync button on the right side of the screen:
+
+![Database connection](images/DatabaseConnection.png)
+
+#### 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.
+
+By default, Metabase also performs a more intensive daily sampling of each field's values and caches the distinct values in order to make checkbox and select filters work in dashboards and SQL/native questions. This process can slow down large databases, so if you have a particularly large database, you can turn on the option to choose when Metabase scans, and select one of three scan options in the Scheduling tab:
+
+![Scanning options](images/scanning-options.png)
+
+- **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."
+
+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.
 
 ### Deleting Databases
 
@@ -88,7 +101,7 @@ You can also delete a database from the database list: hover over the row with t
 
 ![deletedatabasebutton](images/DatabaseDeleteButton.png)
 
-**Caution: Deleting a database is irreversible!  All saved questions and dashboard cards based on the database will be deleted as well!**
+**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
 ---

docs/users-guide/03-basic-exploration.md

 ### Exploring in Metabase
-As long as you're not the very first user in your team's Metabase, the easiest way to get started is by exploring charts and dashboards that your teammates have already created.
+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.
 
 #### Exploring dashboards
 Click on the `Dashboards` nav item to see all the dashboards your teammates have created. 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))

docs/users-guide/04-asking-questions.md

 
 ## Asking 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 to go to the question builder. (Note: to [create a new SQL query](04-asking-questions.html#using-sql), click the console icon in the top right of the new question screen.)
+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.
+
+### Ways to start a new question
+
+If an administrator has [defined some metrics or segments](../administration-guide/07-segments-and-metrics.md), when you click on the New Question button, you'll see a screen like this one:
+
+![New question options](images/new-question-all-options.png)
+
+You can start your new question:
+- from an existing metric
+- from an existing segment
+- from scratch with the Question Builder interface
+- or using the SQL / native query editor
+
+Asking a new question about a **metric** or a **segment** 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:
+
+![List of metrics](images/metrics-list.png)
+
+ 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.:
+
+![Metric drill through](images/metric-drill-through.png)
+
+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:
+
+![Metric action menu](images/metric-action-menu.png)
+
+#### Asking a new question about a segment
+
+A **segment** is any kind of list or table of things that your company cares about: returning users, orders that used a certain promo code, or sales leads that need to be followed up with are all examples of possible segments.
+
+Selecting the Segment option from the new question menu will show you a list of your company's segments. When you click on one, you'll see a list, like this one:
+
+![Californians segment](images/segment-californians.png)
+
+When viewing a segment or a table, you can click on the headings of columns to see options for ways to explore more, like seeing the distribution of the values a column has, or the number of distinct values:
+
+![Table heading actions](images/table-heading-actions.png)
+
+You can also use the Action Menu when viewing a segment or table to see any metrics that are related, or to summarize the table.
+
+![Table action menu](images/segment-actions.png)
+
+#### Asking a new custom question
+
+If your team hasn't set up any metrics or segments, or if you have a question that isn't covered by an existing question or segment, you can create a 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:
 
 ![queryinterfacebar](images/QueryInterfaceBar.png)
 
-Questions are made up of a number of parts: source data, filters, and answer output.
+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 saved metric
+- **Groupings**, where you can group or break out your metric by time, location, or other categories
 
-### Source data
+#### 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
+##### Using saved questions as source data
 
 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.
 
 You can use any saved question 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.
 
-### Filters
+#### 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."  
 
@@ -38,7 +95,7 @@ Fields that are comparable, like numbers or dates, can also be filtered using th
 * *Greater than* a value you enter
 * *Between* two values you enter
 
-#### Filtering by dates
+##### Filtering by dates
 
 If filtering by dates, a date picker will appear to allow you to select dates easily. You have two main options for picking your date: relative or specific.
 
@@ -52,19 +109,19 @@ In practice, if you select **Past 30 days** from the Relative Date calendar pick
 
 Now the relative date will be referencing the past 30 days from *today*, *not* from the day you saved the question. This is a really useful way of creating and saving questions that stay up-to-date: you can always know what your total sales were in the past 7 days, for example.
 
-#### Using segments
+##### Using segments
 If your Metabase admins have created special named filters, called segments, 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 shortcuts to sets of filters that are commonly used in your organization. They might be something like “Active Users,” or “Most Popular Products.”
 
-### Answer output
+#### Selecting answer output in the View section
 ---
-The last 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 the…” Metabase can output the answer to your question in four different ways:
+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:
 
-#### 1. Raw Data
+##### 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.  
 
 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
+##### 2. Basic metrics
 
 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.
 
@@ -80,28 +137,26 @@ The different basic metrics are:
 * **Minimum of …:** The minimum value present in the selected field.
 * **Maximum of …:** The maximum value present in the selected field.
 
-#### 3. Common Metrics
+##### 3. Common metrics
 
 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.
 
-#### 4. Custom Expressions
+##### 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.
 
 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.
 
-### Breaking Out Metrics: Add a group
+#### 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.
+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 **Group** element to your question. You can break out your answer by any date or time in your table, as well as any category field. These groupings are called *dimensions*.
+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 the how many orders we had per state, and also per month. If we want to try this with the Sample Dataset, we’d open the Orders table, skip the filters, then choose Count, 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.
+*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 dimension.
+If you add more dimensions, you will add columns to the left of the metric.
 
 ### Additional Options
 ---
@@ -137,11 +192,11 @@ Now we can use this new field just like any other field, meaning we can use it t
 ![Field in dropdown](images/custom-fields/field-in-dropdown.png)
 
 
-### Digging into Individual Records
+### Digging into individual records
 ---
-Click on a record's primary key (or ID) to see more information about a given person, 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.
+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 SQL
+## 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.
 
@@ -152,11 +207,11 @@ SQL (pronounced "sequel") stands for Structured Query Language, and is a widely
 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. (Note: you’ll only see this button on new question pages or on saved questions that were written in SQL. Otherwise, you’ll see the SAVE button there instead.)
+You can switch a card from question builder mode to SQL mode by clicking on the "**>_**" button in the upper right hand corner.
 
 ![sqlbutton](images/SQLButton.png)
 
-You can write SQL directly into the text box that appears.
+You can write SQL (or your database's native querying language) directly into the text box that appears.
 
 ![sqlinterface](images/SQLInterface.png)
 

docs/users-guide/05-visualizing-results.md

@@ -51,6 +51,18 @@ Area charts are useful when comparing the the proportions between two metrics ov
 
 ![Stacked area chart](images/visualizations/area.png)
 
+##### Histograms
+
+If you have a bar chart like Count of Users by Age, where the x-axis is a number, you'll get a special kind of chart called a **histogram**, where each bar represents a range of values (called a "bin"). Note that Metabase will automatically bin your results any time you use a number as a grouping, even if you aren't viewing a bar chart. Questions that use latitude and longitude will also get binned automatically.
+
+![Histogram](images/histogram.png)
+
+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 in the Question Builder, then clicking on the area to the right of the field name:
+
+![Binning options](images/binning.png)
+
+##### 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 metric fields 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).

docs/users-guide/14-x-rays.md

+## X-rays and Comparisons
+---
+X-rays and comparisons are two powerful new features in Metabase that allow you to get deeper statistical reports about your segments, fields, and time series.
+
+### Time series x-rays
+
+To view an x-ray report for a time series, open up a saved time series question (any kind of chart or table with a metric broken out by time), click on the Action Menu in the bottom-right of the screen, and select "X-ray this question:"
+
+![Time series x-ray action](images/x-ray-action-time-series.png)
+
+You'll get an in-depth analysis of your time series question, including growth rates, the distribution of values, and seasonality:
+
+![Time series x-ray](images/x-ray-time-series.png)
+
+### Segment, table, and field x-rays
+To view an x-ray for a segment, table, or field, first go to the Data Reference, then navigate to the thing you want to x-ray, then select the x-ray option in the lefthand menu:
+
+![X-rays in data reference](images/x-ray-data-reference.png)
+
+If you have a saved Raw Data question that uses one or more segments as filters, you can also x-ray one of those segments from the Action Menu in the bottom-right of the screen when viewing that question:
+
+![X-ray action](images/x-ray-action.png)
+
+An x-ray report for a segment called "Californians" looks like this, displaying a summary of the distribution of values for each field in the segment, and the maximal and minimal values if applicable:
+
+![X-ray](images/x-ray.png)
+
+Clicking on the summary for any field will take you to the detailed x-ray report for that single field.
+
+### Changing the fidelity of an x-ray
+
+X-rays can be a somewhat costly or slow operation for your database to run, so by default Metabase only does a quick sampling of the segment or field you're x-raying. You can increase the fidelity in the top-right of the x-ray page:
+
+![X-ray fidelity](images/x-ray-fidelity.png)
+
+### Comparing a segment
+
+Segments are a subset of a larger table or list, so one thing you can do when viewing an x-ray of a segment is compare it to its "parent" table. For example, if I have a segment called "Californians," which is a subset of the "People" table, I can click on the button that says "Compare to all People" to see a comparison report:
+
+![Compare](images/x-ray-compare-button.png)
+
+The comparison report shows how many rows there are in the segment versus the parent table, and also gives you a breakdown of how the fields in the segment differ from that of the parent table:
+
+![Comparison report](images/x-ray-comparison.png)
+
+An example for where this can be especially useful is a scenario where you've defined many different segments for your users or customers, like "Repeat Customers," "Users between 18 and 35," or "Female customers in Kalamazoo who dislike cheese." You can open up the x-ray for any of these segments, and then compare them to the larger Users or Customers table to see if there are any interesting patterns or differences.