add caching doc and fix a typo

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.
 

src/metabase/public_settings.clj

@@ -62,7 +62,7 @@
   :default false)
 
 (defsetting query-caching-max-kb
-  "The maximum size of the cache per card, in kilobytes:"
+  "The maximum size of the cache, per saved question, in kilobytes:"
   ;; (This size is a measurement of the length of *uncompressed* serialized result *rows*. The actual size of
   ;; the results as stored will vary somewhat, since this measurement doesn't include metadata returned with the
   ;; results, and doesn't consider whether the results are compressed, as the `:db` backend does.)