Merge pull request #5072 from metabase/release-0.24.0

Merge release-0.24.0 to master

bin/osx-release

@@ -187,8 +187,10 @@ sub create_dmg_from_source_dir {
            '-fs', 'HFS+',
            '-fsargs', '-c c=64,a=16,e=16',
            '-format', 'UDRW',
-           '-size', '256MB',          # it looks like this can be whatever size we want; compression slims it down
+           '-size', '512MB',          # has to be big enough to hold everything uncompressed, but doesn't matter if there's extra space -- compression slims it down
            $dmg_filename) == 0 or die $!;
+
+    announce "$dmg_filename created.";
 }
 
 # Mount the disk image, return the device name

bin/version

 #!/usr/bin/env bash
 
-VERSION="v0.24.0-snapshot"
+VERSION="v0.25.0-snapshot"
 
 # dynamically pull more interesting stuff from latest git commit
 HASH=$(git show-ref --head --hash=7 head)            # first 7 letters of hash should be enough; that's what GitHub uses

docs/administration-guide/13-embedding.md

@@ -4,9 +4,9 @@ Metabase includes a powerful application embedding feature that allows you to em
 ### Key Concepts
 
 #### Applications
-An important distinction to keep in mind is the difference between Metabase and the embedding application. The charts and dashboards you will be embedding live in the Metabase application, and will be embedded in your application (i.e. the embedding application). 
+An important distinction to keep in mind is the difference between Metabase and the embedding application. The charts and dashboards you will be embedding live in the Metabase application, and will be embedded in your application (i.e. the embedding application).
 
-#### Parameters 
+#### Parameters
 Some dashboards and questions have the ability to accept parameters. In dashboards, these are synonymous with dashboard filters. For example, if you have a dashboard with a filter on Publisher ID, this can be specified as a parameter when embedding, so that you could insert the dashboard filtered down to a specific Publisher ID.
 
 SQL based questions with template variables can also accept parameters for each variable. So for a query like
@@ -18,21 +18,21 @@ WHERE product_id = {{productID}}
 you could specify a specific productID when embedding the question.
 
 #### Signed parameters
-In general, when embedding a chart or dashboard, the server of your embedding application will need to sign a request for that resource. 
+In general, when embedding a chart or dashboard, the server of your embedding application will need to sign a request for that resource.
 
-If you choose to sign a specific parameter value, that means the user can't modify that, nor is a filter widget displayed for that parameter. For example, if the "Publisher ID" is assigned a value and the request signed, that means the front-end client that renders that dashboard on behalf of a given logged-in user can only see information for that publisher ID. 
+If you choose to sign a specific parameter value, that means the user can't modify that, nor is a filter widget displayed for that parameter. For example, if the "Publisher ID" is assigned a value and the request signed, that means the front-end client that renders that dashboard on behalf of a given logged-in user can only see information for that publisher ID.
 
 ### Enabling embedding
-To enable embedding, go to the Admin Panel and under Settings, go to the "Embedding in other applications" tab. From there, click "Enable." Here you will see a secret signing key you can use later to sign requests. If you ever need to invalidate that key and generate a new one, just click on "Regenerate Key". 
+To enable embedding, go to the Admin Panel and under Settings, go to the "Embedding in other applications" tab. From there, click "Enable." Here you will see a secret signing key you can use later to sign requests. If you ever need to invalidate that key and generate a new one, just click on "Regenerate Key".
 ![Enabling Embedding](images/embedding/01-enabling.png)
 
-You can also see all questions and dashboards that have been marked as "Embeddable" here, as well as revoke any questions or dashboards that should no longer be embeddable in other applications. 
+You can also see all questions and dashboards that have been marked as "Embeddable" here, as well as revoke any questions or dashboards that should no longer be embeddable in other applications.
 
 Once you've enabled the embedding feature on your Metabase instance, you should then go to the individual questions and dashboards you wish to embed to set them up for embedding.
 
 ### Embedding Charts and Dashboards
 
-To mark a given question or dashboard, click on the sharing icon 
+To mark a given question or dashboard, click on the sharing icon
 
 ![Share icon](images/embedding/02-share-icon.png)
 
@@ -40,11 +40,11 @@ Then select "Embed this question in an application"
 
 ![Enable sharing for a question](images/embedding/03-enable-question.png)
 
-Here you will see a preview of the question or dashboard as it will appear in your application, as well as a panel that shows you the code you will need to insert in your application. 
+Here you will see a preview of the question or dashboard as it will appear in your application, as well as a panel that shows you the code you will need to insert in your application.
 
 ![Preview](images/embedding/04-preview.png)
 
-Importantly, you will need to hit "Publish" when you first set up a  chart or dashboard for embedding and each time you change your embedding settings. Also, any changes you make to the resource might require you to update the code in your own application to the latest code sample in the "Code Pane". 
+Importantly, you will need to hit "Publish" when you first set up a  chart or dashboard for embedding and each time you change your embedding settings. Also, any changes you make to the resource might require you to update the code in your own application to the latest code sample in the "Code Pane".
 
 ![Code samples for embedding](images/embedding/05-code.png)
 
@@ -52,7 +52,7 @@ We provide code samples for common front end template languages as well as some
 
 
 ### Embedding Charts and Dashboards with locked parameters
-If you wish to have a parameter locked down to prevent your embedding application's end users from seeing other users' data, you can mark parameters as "Locked."Once a parameter is marked as Locked, it is not displayed as a filter widget, and must be set by the embedding application's server code. 
+If you wish to have a parameter locked down to prevent your embedding application's end users from seeing other users' data, you can mark parameters as "Locked."Once a parameter is marked as Locked, it is not displayed as a filter widget, and must be set by the embedding application's server code.
 
 ![Locked parameters](images/embedding/06-locked.png)
 
@@ -65,6 +65,3 @@ Dashboards are a fixed aspect ratio, so if you'd like to ensure they're automati
 
 ### Reference applications
 To see concrete examples of how to embed Metabase in applications under a number of common frameworks, check out our [reference implementations](https://github.com/metabase/embedding-reference-apps) on Github.
-
-## That’s it!
-If you still have questions, or want to share Metabase tips and tricks, head over to our [discussion board](http://discourse.metabase.com/). See you there!

docs/administration-guide/14-caching.md

+## Caching query results in Metabase
+Metabase now gives you the ability to automatically cache the results of queries that take a long time to run.
+
+### Enabling caching
+To start caching your queries, head to the Settings section of the Admin Panel, and click on the `Caching` tab at the bottom of the side navigation. Then turn the caching toggle to `Enabled`.
+
+![Caching](images/caching.png)
+
+End-users will see a timestamp on cached questions in the top right of the question detail page showing the time when that question was last updated (i.e., the time when the current result was cached). Clicking on the `Refresh` button on a question page will manually rerun the query and override the cached result with the new result.
+
+### Caching settings
+In Metabase, rather than setting cache settings manually on a per-query basis, we give you two parameters to set to automatically cache the results of long queries: the minimum average query duration, and the cache TTL multiplier.
+
+#### Minimum query duration
+Your Metabase instance keeps track of the average query execution times of your queries, and it will cache the results of all saved questions with an average query execution time longer than the number you put in this box (in seconds).
+
+#### Cache Time-to-live (TTL)
+Instead of setting an absolute number of minutes or seconds for a cached result to persist, Metabase lets you put in a multiplier to determine the cache's TTL. Each query's cache TTL is computed by multiplying its average execution time by the number you put in this box. So if you put in `10`, a query that takes 5 seconds on average to execute will have its cache last for 50 seconds; and a query that takes 10 minutes will have a cached result lasting 100 minutes. This way, each query's cache is proportional to its execution time.
+
+#### Max cache entry size
+Lastly, you can set the maximum size of each question's cache in kilobytes, to prevent them from taking up too much space on your server.

docs/administration-guide/start.md

@@ -17,6 +17,7 @@ Are you in charge of managing Metabase for your organization? Then you're in the
 * [Creating a Getting Started Guide for your team](11-getting-started-guide.md)
 * [Sharing dashboards and questions with public links](12-public-links.md)
 * [Embedding Metabase in other Applications](13-embedding.md)
+* [Caching query results](14-caching.md)
 
 First things first, you'll need to install Metabase. If you haven’t done that yet, our [Installation Guide](../operations-guide/start.md#installing-and-running-metabase) will help you through the process.
 

docs/operations-guide/running-the-metabase-jar-file.md

 # Running the Metabase Jar File
 
-To run the Metabase jar file you need to have Java installed on your system.  Currently Metabase requires Java 6 or higher and will work on either the OpenJDK or Oracle JDK.  Note that the Metabase team prefers to stick with open source solutions where possible, so we use the OpenJDK for our Metabase instances.
+To run the Metabase jar file you need to have Java installed on your system.  Currently Metabase requires Java 7 or higher and will work on either the OpenJDK or Oracle JDK.  Note that the Metabase team prefers to stick with open source solutions where possible, so we use the OpenJDK for our Metabase instances.
 
 ### Download Metabase
 
@@ -15,11 +15,11 @@ Before you can launch the application you must verify that you have Java install
 
 You should see output such as:
 
-    java version "1.60_65"
-    Java (TM) SE Runtime Environment (build 1.6.0_65-b14-466.1-11M4716)
-    Java HotSpot (TM) 64-Bit Server VM (build 20.65-b04-466.1, mixed mode)
+    java version "1.8.0_31"
+    Java(TM) SE Runtime Environment (build 1.8.0_31-b13)
+    Java HotSpot(TM) 64-Bit Server VM (build 25.31-b07, mixed mode)
 
-If you did not see the output above and instead saw either an error or your Java version is less than 1.6, then you need to install the Java Runtime.
+If you did not see the output above and instead saw either an error or your Java version is less than 1.7, then you need to install the Java Runtime.
 
 [OpenJDK Downloads](http://openjdk.java.net/install/)  
 [Oracle's Java Downloads](http://www.oracle.com/technetwork/java/javase/downloads/index.html)

docs/users-guide/02-database-basics.md

@@ -74,4 +74,4 @@ To do this, we’d open up the Reservation table, add a filter to only look at r
 ---
 
 ## Next: Asking questions
-Now that we have a shared vocabulary and a basic understanding of databases, let's learn more about [asking questions](03-asking-questions.md)
+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)

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.
+
+#### 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))
+
+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, or to branch off from it in a different direction.
+
+![Drill through](images/drill-through/drill-through.png)
+
+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.
+
+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.
+
+![Inequality filters](images/drill-through/inequality-filters.png)
+
+Lastly, clicking on the ID of an item in 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.)
+
+**Note that charts created with SQL don't currently have these action options.**
+
+#### Exploring saved questions
+In Metabase parlance, every chart on 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. You can also browse all the questions your teammates have saved by clicking the `Questions` link in the main navigation.
+
+When you're viewing 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.
+
+![Heading actions](images/drill-through/heading-actions.png)
+
+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.)
+
+![Action menu](images/drill-through/actions.png)
+
+Here's a list of all the actions:
+* Table actions
+  - `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.
+
+---
+
+## Next: Asking new 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)

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

@@ -159,4 +159,4 @@ Questions asked using SQL can be saved, downloaded, or added to a dashboard just
 ---
 
 ## Next: Creating charts
-Once you have an answer to your question, you can now learn more about [visualizing answers](04-visualizing-results.md).
+Once you have an answer to your question, you can now learn more about [visualizing answers](05-visualizing-results.md).

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

@@ -100,4 +100,4 @@ Metabase now also allows administrators to add custom region maps via GeoJSON fi
 ---
 
 ## Next: Sharing and organizing questions
-Now let's learn about [sharing and organizing your saved questions](05-sharing-answers.md).
+Now let's learn about [sharing and organizing your saved questions](06-sharing-answers.md).

docs/users-guide/05-sharing-answers.md → docs/users-guide/06-sharing-answers.md

@@ -51,4 +51,4 @@ Clicking on the icon to the left of questions let's you select several at once s
 ---
 
 ## Next: creating dashboards
-Next, we'll learn about [creating dashboards and adding questions to them](06-dashboards.md).
+Next, we'll learn about [creating dashboards and adding questions to them](07-dashboards.md).

docs/users-guide/06-dashboards.md → docs/users-guide/07-dashboards.md

@@ -10,7 +10,7 @@ Have a few key performance indicators that you want to be able to easily check?
 You can make as many dashboards as you want. Go nuts.
 
 ### How to create a dashboard
-Once you have a question saved, you can create a dashboard. Click the **Dashboards** dropdown at the top of the screen, then **Create a new dashboard**. Give your new dashboard a name and a description, then click **Create**, and you’ll be taken to your shiny new dashboard. You can always get to your dashboards from the dropdown at the very top of the screen.
+Once you have a question saved, you can create a dashboard. Click the **Dashboards** link at the top of the screen, then click the plus icon in the top-right to create a new dashboard. Give your new dashboard a name and a description, then click **Create**, and you’ll be taken to your shiny new dashboard.
 
 ![Create Dashboard](images/dashboards/DashboardCreate.png)
 
@@ -34,11 +34,17 @@ Once you're in edit mode you'll see a grid appear. You can move and resize the c
 
 Questions in your dashboard will automatically update their display based on the size you choose to make sure your data looks great at any size.
 
+### Archiving a dashboard
+Archiving a dashboard does not archive the individual saved questions on it — it just archives the dashboard. To archive a dashboard while viewing it, click the pencil icon to enter edit mode, then click the Archive button.
 
-### Deleting a dashboard
-Deleting a dashboard does not delete the individual saved questions on it — it just deletes the dashboard. Remember — dashboards are shared by everyone on your team, so think twice before you delete something that someone else might be using!
+You can view all of your archived dashboards by clicking the box icon in the top-right of the Dashboards page. Archived dashboards in this list can be unarchived by clicking the icon of the box with the upward arrow next to that dashboard.
 
-To delete a dashboard, click the pencil-looking **Edit** icon in the top right of the dashboard, then click **Delete**.
+(Note: as of Metabase v0.24, dashboards can no longer be permanently deleted; only archived.)
+
+### Finding dashboards
+After a while, your team might have a lot of dashboards. To make it a little easier to find dashboards that you look at often, you can mark a dashboard as a favorite by clicking the star icon on it from the dashboards list. You can use the filter dropdown in the top of the list to view only your favorite dashboards, or only the ones that you created yourself.
+
+![Filter list](images/dashboards/FilterDashboards.png)
 
 ### Fullscreen dashboards
 
@@ -90,4 +96,4 @@ Some tips:
 ---
 
 ## Next: Adding dashboard filters
-Make your dashboards more flexible and powerful by [adding dashboard filters](07-dashboard-filters.md).
+Make your dashboards more flexible and powerful by [adding dashboard filters](08-dashboard-filters.md).

docs/users-guide/07-dashboard-filters.md → docs/users-guide/08-dashboard-filters.md

@@ -74,4 +74,4 @@ Here are a few tips to get the most out of dashboard filters:
 ---
 
 ## Next: Charts with multiple series
-We'll learn how to [create charts with multiple lines, bars, and more](08-multi-series-charting.md) next.
+We'll learn how to [create charts with multiple lines, bars, and more](09-multi-series-charting.md) next.

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

@@ -78,4 +78,4 @@ Go forth and start letting your data get to know each other.
 
 ## Next: Getting reports with Pulses
 
-Pulses let you send out a group of saved questions on a schedule via email or Slack. [Get started with Pulses](09-pulses.md).
+Pulses let you send out a group of saved questions on a schedule via email or Slack. [Get started with Pulses](10-pulses.md).

docs/users-guide/09-pulses.md → docs/users-guide/10-pulses.md

@@ -50,4 +50,4 @@ If you want to delete a pulse, you can find that option at the bottom of the edi
 
 ## Next: Connecting Metabase to Slack with Metabot 🤖
 
-If your team uses Slack to communicate, you can [use Metabot](10-metabot.md) to display your saved questions directly within Slack whenever you want.
+If your team uses Slack to communicate, you can [use Metabot](11-metabot.md) to display your saved questions directly within Slack whenever you want.

docs/users-guide/10-metabot.md → docs/users-guide/11-metabot.md

@@ -48,4 +48,4 @@ If you don’t have a sense of which questions you want to view in  Slack, you c
 
 ## Next:
 
-Sometimes you’ll need help understanding what data is available to you and what it means. Metabase provides a way for your administrators and data experts to build a [data model reference](11-data-model-reference.md) to help you make sense of your data.
+Sometimes you’ll need help understanding what data is available to you and what it means. Metabase provides a way for your administrators and data experts to build a [data model reference](12-data-model-reference.md) to help you make sense of your data.