Merge pull request #2500 from metabase/0.17.0-docs

0.17.0 docs

docs/operations-guide/running-metabase-on-docker.md

@@ -44,6 +44,15 @@ In this scenario all you need to do is make sure you launch Metabase with the co
 Keep in mind that Metabase will be connecting from within your docker container, so make sure that either you're using a fully qualified hostname or that you've set a proper entry in your container's `/etc/hosts file`.
 
 
+### Setting the JVM Timezone
+
+It's best to set your JVM timezone to match the timezone you'd like all your reports to come in.  You can do this by simply specifying the `JVM_TIMEZONE` environment variable which is picked up by the Metabase launch script.  For example:
+
+    docker run -d -p 3000:3000 \
+      -e "JVM_TIMEZONE=US/Pacific" \
+      --name metabase metabase/metabase
+
+
 ### Additional custom settings
 
 While running Metabase on docker you can use any of the custom settings from [Customizing the Metabase Jetty Webserver](./start.md#customizing-the-metabase-jetty-webserver) by setting environment variables on your docker run command.

docs/operations-guide/running-metabase-on-elastic-beanstalk.md

@@ -3,6 +3,7 @@
 > [Upgrading to new versions of Metabase](#deploying-new-versions-of-metabase)  
 > [Retaining Metabase logs on S3](#retaining-metabase-logs)  
 > [Running Metabase over HTTPS](#running-metabase-over-https)  
+> [Setting the Java timezone](#setting-the-jvm-timezone)  
 > [Using Papertrail for logging](#running-metabase-with-papertrail-on-aws)  
 > [Protecting invalid hostname access](#protecting-against-invalid-hostname-access)
 
@@ -16,7 +17,7 @@ The Metabase team runs a number of production installations on AWS using Elastic
 
 Metabase provides an Elastic Beanstalk pre-configured launch url to help new installations getting started.  If you are starting fresh we recommend you follow this link to begin creating the Elastic Beanstalk deployment with a few choices pre-filled.
 
-[Launch Metabase on Elastic Beanstalk](http://downloads.metabase.com/v0.16.1/launch-aws-eb.html)
+[Launch Metabase on Elastic Beanstalk](http://downloads.metabase.com/v0.17.0/launch-aws-eb.html)
 
 The rest of this guide will follow each phase of the Elastic Beanstalk setup step-by-step.
 
@@ -53,7 +54,7 @@ When your environment type settings look like the above then go ahead and click
 
 The application version describes the exact binary you wish to deploy to your Elastic Beanstalk application.  Metabase provides a pre-built AWS Elastic Beanstalk application version which can be linked to directly.  Simply enter the following url in the `S3 URL` textbox:
 
-https://s3.amazonaws.com/downloads.metabase.com/v0.16.1/metabase-aws-eb.zip
+https://s3.amazonaws.com/downloads.metabase.com/v0.17.0/metabase-aws-eb.zip
 
 Leave all the settings under Deployment Limits on their defaults.  These settings won't impact Metabase.
 
@@ -186,7 +187,7 @@ Here's each step:
 1. Go to Elastic Beanstalk and select your `Metabase` application
 * Click on `Application Versions` on the left nav (you can also choose `Application Versions` from the dropdown at the top of the page)
 * Download the latest Metabase Elastic Beanstalk deployment file
-  * https://s3.amazonaws.com/downloads.metabase.com/v0.16.1/metabase-aws-eb.zip
+  * https://s3.amazonaws.com/downloads.metabase.com/v0.17.0/metabase-aws-eb.zip
 * Upload a new Application Version
 	* Click the `Upload` button on the upper right side of the listing
 		* Give the new version a name, ideally including the Metabase version number (e.g. v0.13.0)
@@ -263,6 +264,18 @@ Once your application is working properly over HTTPS we recommend setting an add
 * Scroll to the bottom of the page and click `Apply` in the lower right, then wait for your application to update.
 
 
+
+# Setting the JVM Timezone
+
+It's best to set your JVM timezone to match the timezone you'd like all your reports to come in.  You can do this by adding the `JAVA_TIMEZONE` environment variable.
+
+1. Click on `Configuration` on the left hand sidebar
+* Scroll down to `Software Configuration` under the _Web Tier_ section and click the gear icon to edit those settings.
+* Under `Environment Properties` add the following
+   * `JAVA_TIMEZONE` with a value such as `US/Pacific`
+* Scroll to the bottom of the page and click `Apply` in the lower right, then wait for your application to update.
+
+
 # Using Papertrail for logging on AWS
 
 This provides a simple way to use the Papertrail logging service for collecting the logs for you Metabase instance in an easy to read location.

docs/operations-guide/running-metabase-on-heroku.md

 # Running Metabase on Heroku
 
-Metabase is currently offering beta support for Heroku deployments and planning to improve support for Heroku going forward.  Metabase will deploy and run fine on Heroku but there are a few limitations.
+Heroku is a great place to evaluate Metabase and take it for a quick spin with just a click of a button and a couple minutes of waiting time.  If you decide to keep your Metabase running long term we recommend some upgrades as noted below to avoid limitations of the Heroku free tier.
 
 
 ### Launching Metabase
@@ -14,10 +14,19 @@ If you've got a Heroku account then all there is to do is follow this one-click
 This will launch a Heroku deployment using a github repository that Metabase maintains.
 
 
-### Known Issues
+### Upgrading beyond the `Free` tier
+
+Heroku is very kind and offers a free tier to be used for very small/non-critical workloads which is great if you just want to evaluate Metabase and see what it looks like.  If you like what you see and decide to use Metabase as an ongoing part of your analytics workflow we recommend these upgrades which are quite affordable and will allow you to fully utilize all of Metabase's capabilities without running into annoying limitations.
+
+1. Upgrade your dyno to the `Hobby` tier or one of the professional `Standard` 1x/2x dynos.  The most important reason for this is that your dyno will never sleep and that allows Metabase to run all of its background work such as sending Pulses, syncing metadata, etc, in a reliable fashion.
+
+2. Upgrade your Postgres database to the `Basic` package or for more peace of mind go for the `Standard 0` package.  The primary reason for this upgrade is to get more than the minimum number of database rows offered in the free tier (10k), which we've had some users exhaust within a week.  You'll also get better overall performance along with backups, which we think is worth it.
+
+
+### Known Limitations
 
  * Heroku’s 30 second timeouts on all web requests can cause a few issues if you happen to have longer running database queries.  Most people don’t run into this but be aware that it’s possible.
- * If you don’t access the application for a while Heroku will sleep your Metabase environment.  This prevents things like Pulses and Metabase background tasks from running when scheduled and at times makes the app appear to be slow when really it's just Heroku reloading your app.
+ * When using the `free` tier, if you don’t access the application for a while Heroku will sleep your Metabase environment.  This prevents things like Pulses and Metabase background tasks from running when scheduled and at times makes the app appear to be slow when really it's just Heroku reloading your app.  You can resolve this by upgrading to the `hobby` tier or higher.
 
 Now that you’ve installed Metabase, it’s time to [set it up and connect it to your database](../setting-up-metabase.md).
 

docs/operations-guide/start.md

@@ -7,8 +7,8 @@
 > [Running database migrations manually](#running-metabase-database-migrations-manually)  
 > [Backing up Metabase Application Data](#backing-up-metabase-application-data)  
 > [Customizing the Metabase Jetty Webserver](#customizing-the-metabase-jetty-webserver)  
-> [Changing password complexity](#changing-metabase-password-complexity)
-
+> [Changing password complexity](#changing-metabase-password-complexity)  
+> [Handling Timezones](#handling-timezones-in-metabase)
 
 # Installing and Running Metabase
 
@@ -231,3 +231,26 @@ The settings above can be used independently, so it's fine to use only one or th
 * `weak` = no character constraints
 * `normal` = at least 1 digit
 * `strong` = minimum 8 characters w/ 2 lowercase, 2 uppercase, 1 digit, and 1 special character
+
+
+# Handling timezones in Metabase
+
+Metabase does its best to ensure proper and accurate reporting in whatever timezone you desire, but timezones are a complicated beast so it's important to abide by some recommendations listed below to ensure your reports come out as intended.
+
+The following places where timezones are set can all impact the data you see:
+
+* `Database` - includes global database timezone settings, specific column type settings, and even individual data values.
+* `OS & JVM` - on whatever system is running Metabase the timezone settings of the Operating System as well as the Java Virtual Machine can impact your reports.
+* `Metabase` - inside Metabase the reporting timezone setting (if set) will influence how your data is reported.
+
+To ensure proper reporting it's important that timezones be set consistently in all places.  Metabase recommends the following settings:
+
+* Make sure all of your database columns are properly setup to include timezone awareness.
+* Unless you have a special need it's best to set your database reporting timezone to UTC and store all of your date/time related values in UTC.
+* Configure your JVM to use the same timezone you want to use for reporting, which ideally should also match the timezone of your database.
+* Set the Metabase `Report Timezone` to match the timezone you want to see your reports in, again, this should match the rest of the timezone settings you've made.
+
+
+Common Pitfalls:
+1. Your database is using date/time columns without any timezone information.  Typically when this happens your database will assume all the data is from whatever timezone the database is configured in or possible just default to UTC (check your database vendor to be sure).
+2. Your JVM timezone is not the same as your Metabase `Report Timezone` choice.  This is a very common issue and can be corrected by launching java with the `-Duser.timezone=<timezone>` option properly set to match your Metabase report timezone.

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

@@ -89,8 +89,35 @@ If you add more dimensions, you will add columns to the left of the dimension.
 ---
 Click on the three dots on the far right hand side of the question builder bar to open up these additional settings:
 
-* Limit your results to 1, 10, 25, 100, or more rows.
+![Context Menu](images/custom-fields/context-menu.png)
+
 * 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
+
+#### 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.
+
+![Custom fields](images/custom-fields/blank-formula.png)
+
+Say we had a table of individual baseball games, 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:
+
+![Formula](images/custom-fields/filled-formula.png)
+
+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 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:
+
+![New field](images/custom-fields/query-result.png)
+
+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:
+
+![Field in dropdown](images/custom-fields/field-in-dropdown.png)
+
 
 ### Digging into Individual Records
 ---

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

@@ -8,7 +8,38 @@ Whenever you’ve arrived at an answer that you want to save for later, click th
 
 A pop-up box will appear, you to give your question a name and a description. We suggest phrasing the names for your questions in the form of a question, such as, “How many customers did we have last month?” After saving your question, you'll be asked if you want to add it to a dashboard.
 
-Now, whenever you want to refer to your question again, you can find it in the saved questions list by clicking on the Questions link from the main navigation. To edit your question, go to it and click the pencil icon in the top-right.
+Now, whenever you want to refer to your question again, you can find it in the saved questions list by clicking on the **Questions** link from the main navigation. To edit your question, go to it and click the pencil icon in the top-right.
+
+### 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. The Questions page has several tools that’ll help you organize things and find what you’re looking for.
+
+![Questions](images/saved-questions.png)
+
+#### Shortcuts
+In the top left, you’ll find shortcuts to your favorite questions (mark a question as a favorite by clicking on the star icon that appears on the far right when you hover over it), questions you’ve recently viewed, questions that you’ve saved personally, and popular questions that are used the most by your team.
+
+#### Search
+You can search for a question by typing keywords into the **Search for a question** area.
+
+#### Labels
+One great way to organize your questions is to label them. Create and organize your team’s labels by clicking on the **Labels** heading in the left menu on the Questions page. To create a label, just choose a color (or emoji!) for it, give it a name, and click **Create Label**. You can edit or delete a label by hovering of a label and clicking the **Edit** or **X** icon. You can create labels that pertain to different teams, projects, products, reports, dashboards, or whatever you want!
+
+You can assign as many labels as you want to your questions. Just hover over a question in your list and click the label icon, then pick the label(s) you want to apply to the question.
+
+![Actions](images/question-actions.png)
+
+If you have several questions that you want to give the same label to, just click the checkbox on the left side of each question’s title when you hover over it to select your questions, then click the Labels dropdown at the top of the page.
+
+![Checkbox](images/question-checkbox.png)
+
+Once you’ve created a label, it’ll appear in the list on the left side of the screen. Clicking on a label, either in the list of labels or on an individual question, will show you all the questions that have that label.
+
+#### Archiving
+Sometimes questions outlive their usefulness and need to be sent to Question Heaven. To archive a question, just click on the box icon that appears on the far right when you hover over a question. You can also archive multiple questions the same way you apply labels to multiple questions.
+
+If you have second thoughts and want to bring an archived question back, you can see all your archived questions from the **Archive** link at the bottom of the left menu. To unarchive a question, hover over it and click the box icon that appears on the far right.
 
 ## Dashboards
 ---