diff --git a/docs/administration-guide/01-managing-databases.md b/docs/administration-guide/01-managing-databases.md
index 3df9809ee53cc0eb884d0e0fbd99950057f382af..a304360d4e934598167c9851769325d4f8447f06 100644
--- a/docs/administration-guide/01-managing-databases.md
+++ b/docs/administration-guide/01-managing-databases.md
@@ -14,7 +14,7 @@ Now you’ll see a list of your databases. To connect another database to Metaba
- [Google BigQuery](databases/bigquery.md)
- H2
- [MongoDB (version 3.4 or higher)](databases/mongodb.md)
-- [MySQL (version 4.1 or higher, as well as MariaDB)](databases/mysql.md)
+- [MySQL (version 5.5.3 or higher, as well as MariaDB)](databases/mysql.md)
- Postgres
- SQLite
- SQL Server
diff --git a/docs/administration-guide/05-setting-permissions.md b/docs/administration-guide/05-setting-permissions.md
index a692398d439fdd83dd8fd43538e58b6f6bb1ebaf..ecadf7f4f96dbaff78606f389d5ecb7bf5950b4c 100644
--- a/docs/administration-guide/05-setting-permissions.md
+++ b/docs/administration-guide/05-setting-permissions.md
@@ -22,10 +22,11 @@ You’ll notice that you already have two default groups: Administrators and All
You’ll also see that you’re a member of the **Administrators** group — that’s why you were able to go to the Admin Panel in the first place. So, to make someone an admin of Metabase you just need to add them to this group. Metabase admins can log into the Admin Panel and make changes there, and they always have unrestricted access to all data that you have in your Metabase instance. So be careful who you add to the Administrator group!
-The **All Users** group is another special one. Every Metabase user is always a member of this group, though they can also be a member of as many other groups as you want. We recommend using the All Users group as a way to set default access levels for new Metabase users. If you have [Google single sign-on](10-single-sign-on.md) enabled, new users who join that way will be automatically added to the All Users group.
+The **All Users** group is another special one. Every Metabase user is always a member of this group, though they can also be a member of as many other groups as you want. We recommend using the All Users group as a way to set default access levels for new Metabase users. If you have [Google single sign-on](10-single-sign-on.md) enabled, new users who join that way will be automatically added to the All Users group.
#### An important note on the All Users group
-As we mentioned above, a user is given the *most permissive* setting she has for a given database/schema/table across *all* groups she is in. Because of that, it is important that your All Users group should never have *greater* access for an item than a group for which you're trying to restrict access — otherwise the more permissive setting will win out. This goes for both data access as well as [collection permission](06-collections.md) settings.
+
+As we mentioned above, a user is given the _most permissive_ setting she has for a given database/schema/table across _all_ groups she is in. Because of that, it is important that your All Users group should never have _greater_ access for an item than a group for which you're trying to restrict access — otherwise the more permissive setting will win out. This goes for both data access as well as [collection permission](06-collections.md) settings.
If you’ve set up the [Slack integration](09-setting-up-slack.md) and enabled [Metabot](../users-guide/11-metabot.md), you’ll also see a special **Metabot** group, which will allow you to restrict which questions your users will be able to access in Slack via Metabot.
@@ -73,12 +74,14 @@ Lastly, data access levels for tables are almost exactly the same as well:
- **Unrestricted access:** can ask questions about this table and see saved questions and dashboard cards using this table.
- **No access:** can’t ask questions about this table or see saved questions or dashboard cards using this table.
-*Note: you’ll notice that tables don’t have the option for limited access. In the future, column-level permissions will be added to Metabase, and setting limited access on a table will allow you to choose which columns the group should have access to.*
+_Note: you’ll notice that tables don’t have the option for limited access. In the future, column-level permissions will be added to Metabase, and setting limited access on a table will allow you to choose which columns the group should have access to._
### A note about Pulses
+
Pulses act a bit differently with regard to permissions. When a user creates a new Pulse, they will only have the option to include saved questions that they have permission to view. Note, however, that they are not prevented from emailing that Pulse to anyone, or posting that Pulse to a Slack channel (if you have Slack integration set up), regardless of the recipients’ permissions. Unlike dashboards, where individual cards are blocked based on a user’s permissions, a Pulse will always render all of its cards.
---
-## Next: custom segments and metrics
+## Next: collections
+
Metabase lets you create and set permissions on collections of dashboards and questions. [Learn how](06-collections.md).
diff --git a/docs/enterprise-guide/audit.md b/docs/enterprise-guide/audit.md
index 3fa31f47441a986c6a1ed325235f29d6f6e341cb..88a6f1934a379206fbb3a4e49bb9bbd506defe93 100644
--- a/docs/enterprise-guide/audit.md
+++ b/docs/enterprise-guide/audit.md
@@ -14,31 +14,31 @@ The Team Members panel has a view of other options for viewing your team's usage
The Audit Log tab will display, in chronological order, each query, who viewed it, and when. Note that if the user did not save their query, its name will be listed as `Ad-hoc`. Each query name can be clicked to view more details about your users' interactions with it, including a full revision history. You will also be able to view the query in Metabase. Note that this link will always show the latest version of the query - use the revision history to see changes over time.
-
#### Drilling In
Throughout the People section, names can be clicked to access the profile of a specific user’s activity. This profile includes:
-* Dashboard views
-* Query views
-* Downloads
+- Dashboard views
+- Query views
+- Downloads
### Data
-The Data section focuses on your databases, schemas and tables, and is divided into corresponding sections. Look here if you're trying to uncover queries and schemas that need optimization. Each section provides visualizations around the use and speed of querying against your databases, schemas or tables. You will also be able to view lists of stats about all of your databases, schemas and tables.
+The Data section focuses on your databases, schemas and tables, and is divided into corresponding sections. Look here if you're trying to uncover queries and schemas that need optimization. Each section provides visualizations around the use and speed of querying against your databases, schemas or tables. You will also be able to view lists of stats about all of your databases, schemas and tables.
### Items
+
The Items section focuses on questions, dashboards and downloads, and is divided into corresponding sections. Use these pages to gain a better understanding of what your users are interacting with.
#### Questions
-The Questions section will show you your most popular queries, as well as your slowest queries. If queries you think are important aren't appearing on your most popular queries list, you may want to make sure your team is focusing on the right things.
+The Questions section will show you your most popular queries, as well as your slowest queries. If queries you think are important aren't appearing on your most popular queries list, you may want to make sure your team is focusing on the right things.
-If important queries are appearing on the list of slowest queries, you will want to look at optimizing them. One option is to adjust your [caching settings](../../14-caching.html), but there are plenty of other options as well. To help you determine if your optimization efforts are heading in the right direction, use the `Query views and speed per day` visualization at the bottom of the page.
+If important queries are appearing on the list of slowest queries, you will want to look at optimizing them. One option is to adjust your [caching settings](../administration-guide/14-caching.md), but there are plenty of other options as well. To help you determine if your optimization efforts are heading in the right direction, use the `Query views and speed per day` visualization at the bottom of the page.
@@ -48,9 +48,9 @@ A list of all of your questions is available as well, and you can see various da
You can also click on any question to drill into a more detailed profile showing:
-* View activity
-* Revision History
-* A full audit log of who viewed the question, and when
+- View activity
+- Revision History
+- A full audit log of who viewed the question, and when
#### Dashboards
diff --git a/docs/faq/general/how-do-i-ask-for-help.md b/docs/faq/general/how-do-i-ask-for-help.md
index 6cb0dc8ea9d143cd1c967a7b92ed9231c1cc7d2d..8a5dc4ef4aa4b29cf77d576690664c92cb9a431b 100644
--- a/docs/faq/general/how-do-i-ask-for-help.md
+++ b/docs/faq/general/how-do-i-ask-for-help.md
@@ -1,5 +1,5 @@
# How do I ask for help?
-The best place to start when asking for help are our [Troubleshooting guides](../../troubleshooting-guide/index.html). We’ve compiled a list of common problems that users experience, along with common symptoms and error messages to help you self-diagnose and resolve your issues.
+The best place to start when asking for help are our [Troubleshooting guides](../../troubleshooting-guide/index.md). We’ve compiled a list of common problems that users experience, along with common symptoms and error messages to help you self-diagnose and resolve your issues.
-As hard as we’ve tried to make the documentation as complete as possible, we know that you might need additional help or have a general question about Metabase not answered here. The best way to get help in these cases is to post on our [Discourse](https://discourse.metabase.com/) and harness the power of our community to get your question answered.
\ No newline at end of file
+As hard as we’ve tried to make the documentation as complete as possible, we know that you might need additional help or have a general question about Metabase not answered here. The best way to get help in these cases is to post on our [Discourse](https://discourse.metabase.com/) and harness the power of our community to get your question answered.
diff --git a/docs/faq/setup/how-do-i-integrate-with-sso.md b/docs/faq/setup/how-do-i-integrate-with-sso.md
index afea7746bbc44d5adb63bd1118aaf1a8fd2b8963..3892a584329d3744a8906bf39e2f16246e5b52b8 100644
--- a/docs/faq/setup/how-do-i-integrate-with-sso.md
+++ b/docs/faq/setup/how-do-i-integrate-with-sso.md
@@ -1,3 +1,3 @@
# How do I integrate Metabase and our single-sign on (SSO) option?
-The open-source edition of Metabase allows you to [integrate with LDAP or Google sign-in](../../administration-guide/10-single-sign-on.md). If you’re using a [SAML](../../enterprise-guide/authenticating-with-saml.md) or [JWT](../..enterprise-guide/authenticating-with-jwt.html) SSO solution, you will need the [Enterprise Edition](https://metabase.com/enterprise/).
\ No newline at end of file
+The open-source edition of Metabase allows you to [integrate with LDAP or Google sign-in](../../administration-guide/10-single-sign-on.md). If you’re using a [SAML](../../enterprise-guide/authenticating-with-saml.md) or [JWT](../../enterprise-guide/authenticating-with-jwt.md) SSO solution, you will need the [Enterprise Edition](https://www.metabase.com/enterprise/).
diff --git a/docs/faq/setup/what-is-h2.md b/docs/faq/setup/what-is-h2.md
index 0d0ba0267c10631bb4601f1e6f77e492328f8033..9979d16967096c400c0c6f23d9d055a7e0f5e2d2 100644
--- a/docs/faq/setup/what-is-h2.md
+++ b/docs/faq/setup/what-is-h2.md
@@ -1,3 +1,3 @@
# What's H2?
-H2 is the underlying application database that’s packaged with Metabase. H2 is a lightweight, in-memory database: perfect for getting spun up quickly, not so perfect for long-term usage. We recommend that you [migrate away from H2](../../operations-guide/start.html#migrating-from-using-the-h2-database-to-mysql-or-postgres) for production instances of Metabase.
\ No newline at end of file
+H2 is the underlying application database that’s packaged with Metabase. H2 is a lightweight, in-memory database: perfect for getting spun up quickly, not so perfect for long-term usage. We recommend that you [migrate away from H2](../../operations-guide/migrating-from-h2.md) for production instances of Metabase.
diff --git a/docs/faq/setup/when-should-i-migrate-h2.md b/docs/faq/setup/when-should-i-migrate-h2.md
index 82c4f33aaa65f8d80ad4ea01b1cbc963ebda3615..e7461ea93370d1b2eaa94bf575f7ca8e9dc0344b 100644
--- a/docs/faq/setup/when-should-i-migrate-h2.md
+++ b/docs/faq/setup/when-should-i-migrate-h2.md
@@ -1,3 +1,3 @@
# When should I migrate H2 to mySQL or Postgres?
-As soon as you’re planning on using Metabase for anything other than testing. H2 is fairly easily corruptible, so it’s better to be safe than sorry when running Metabase in production. The migration is fairly simple, and [full instructions](../../operations-guide/start.html#migrating-from-using-the-h2-database-to-mysql-or-postgres) are available.
\ No newline at end of file
+As soon as you’re planning on using Metabase for anything other than testing. H2 is fairly easily corruptible, so it’s better to be safe than sorry when running Metabase in production. The migration is fairly simple, and [full instructions](../../operations-guide/migrating-from-h2.md) are available.
diff --git a/docs/faq/using-metabase/how-do-i-ask-questions.md b/docs/faq/using-metabase/how-do-i-ask-questions.md
index 87bfb69bdde2dbaa1d6b23209fc2fed162f9d9f0..714875cd22cad0031667f65aeb6044b97ba36416 100644
--- a/docs/faq/using-metabase/how-do-i-ask-questions.md
+++ b/docs/faq/using-metabase/how-do-i-ask-questions.md
@@ -1,3 +1,3 @@
# How do I ask questions about my organization's data?
-Metabase provides a variety of ways to ask questions about your organization’s data, from using our GUI interface to construct a question, to writing a SQL query from scratch. Read all about how to ask questions [here](../../users-guide/04-asking-questions.md).
\ No newline at end of file
+Metabase provides a variety of ways to ask questions about your organization’s data, from using our GUI interface to construct a question, to writing a SQL query from scratch. Read all about how to ask questions [here](../../users-guide/04-asking-questions.md).
diff --git a/docs/faq/using-metabase/how-do-i-reset-my-password.md b/docs/faq/using-metabase/how-do-i-reset-my-password.md
index f6d37258b0fec1aa0f503563f66bc031e2b30cc2..ab7c1e5a13ab7db6630a6df5c0b24fe7cc6f0ec7 100644
--- a/docs/faq/using-metabase/how-do-i-reset-my-password.md
+++ b/docs/faq/using-metabase/how-do-i-reset-my-password.md
@@ -1,3 +1,3 @@
# How do I reset my password?
-If you're having trouble logging in due to a forgotten password, click the `I seem to have forgotten my password` button in the lower right of the log-in screen. If your Metabase administrator has already [configured your email settings](02-setting-up-email.md), you will be able to generate a Reset Password email. If email has not been configured, you will need to contact them to perform a password reset.
\ No newline at end of file
+If you're having trouble logging in due to a forgotten password, click the `I seem to have forgotten my password` button in the lower right of the log-in screen. If your Metabase administrator has already [configured your email settings](../../administration-guide/02-setting-up-email.md), you will be able to generate a Reset Password email. If email has not been configured, you will need to contact them to perform a password reset.
diff --git a/docs/information-collection.md b/docs/information-collection.md
index 26e2c9c219af447d43ea5b10e72cca2e8e415ca5..ccaca558a5884b31cdbf3b0426dbf7ff05260faa 100644
--- a/docs/information-collection.md
+++ b/docs/information-collection.md
@@ -2,7 +2,7 @@
Metabase uses Google Analytics to collect anonymous usage information from the installed servers that enable this feature. Below are the events we have instrumented, as well as the information we collect about the user performing the action and the instance being used.
-We also will phone home some anonymized metrics from the metabase application server on a nightly basis. Note that we don't collect any usernames, any emails, the server IP, database details of any kind or any personally identifiable information in this process.
+We also will phone home some anonymized metrics from the metabase application server on a nightly basis. Note that we don't collect any usernames, any emails, the server IP, database details of any kind or any personally identifiable information in this process.
While this list of anonymous information we collect might seem long, it’s useful to compare this to other alternatives. With a typical SaaS platform, not only will this information be collected, but it will also be accompanied by information about your data, how often it is accessed, the specific queries that you use, specific numbers of records all tied to your company and current plan.
@@ -12,74 +12,72 @@ In the list below, we spell out exactly why we collect each bit of information.
If you prefer not to provide us with this anonymous usage data, please go to your instance’s admin section and toggle off the option for `Anonymous Tracking`.
-
### Example questions we want to answer:
-* Is our query interface working?
- * Are users stopping halfway through a question?
- * Are users using filters?
- * Are users using groupings?
- * How often are users using bare rows vs other aggregation options?
- * are people clicking on column headings to sort or manually adding a sort clause?
-* How often are users writing SQL instead of using the query interface?
- * are these queries written by a select group of analysts or is the entire company sql literate?
-* Are people using dashboards as a starting point for queries?
-* how many clicks are there on dashboard cards?
-* How many of these clicks result in modified queries that are executed?
-* How often are questions saved?
-* How often are saved questions added to dashboards?
+- Is our query interface working?
+ - Are users stopping halfway through a question?
+ - Are users using filters?
+ - Are users using groupings?
+ - How often are users using bare rows vs other aggregation options?
+ - are people clicking on column headings to sort or manually adding a sort clause?
+- How often are users writing SQL instead of using the query interface?
+ - are these queries written by a select group of analysts or is the entire company sql literate?
+- Are people using dashboards as a starting point for queries?
+- how many clicks are there on dashboard cards?
+- How many of these clicks result in modified queries that are executed?
+- How often are questions saved?
+- How often are saved questions added to dashboards?
### What we will do with the answers to these questions:
-* Prioritize improvements in the query interface vs the SQL interface.
-* Optimize the product for the usage patterns our users are using the product for
-* Stay on top of browser incompatibilities
-* Optimize our dashboards for either passive consumption or as a starting point for further exploration depending on how they are being used
-While we will closely follow reported issues and feature requests, we aim to make as many of our users happy and provide them with improvements in features that matter to them. Allowing us to collect information about your instance gives your users a vote in future improvements in a direct way.
+- Prioritize improvements in the query interface vs the SQL interface.
+- Optimize the product for the usage patterns our users are using the product for
+- Stay on top of browser incompatibilities
+- Optimize our dashboards for either passive consumption or as a starting point for further exploration depending on how they are being used
+While we will closely follow reported issues and feature requests, we aim to make as many of our users happy and provide them with improvements in features that matter to them. Allowing us to collect information about your instance gives your users a vote in future improvements in a direct way.
# The data we collect:
-NOTE: we never capture any specific details in any of our tracking methodology such as user details, table names, field names, etc. collected data is limited to the types of actions users are taking with the product.
-
+NOTE: we never capture any specific details in any of our tracking methodology such as user details, table names, field names, etc. collected data is limited to the types of actions users are taking with the product.
### Google Analytics Events
-| Category | Action | Why we collect this |
-|----------|--------|---------------------|
-| Links and Page Views | General website tracking of what pages are most used | This provides better understanding of what parts of the application are liked and used by customers so we know what's popular and potentially what needs more improvement. |
-| Dashboards | When the dashboard dropdown is used, when dashboards are created and updated, what types of edits occur such as adding/removing cards and repositioning. | We use this information to understand how dashboards are being used and what types of activities users most commonly do on their dashboards. |
-| Pulses | When pulses are created and updated, what types of pulses are created, and how many cards typically go in a pulse. | This is used to have a sense for how teams are structuring their push based communication. When and where is information most often sent and how much information allows Metabase to continue improving features around push based data interactions. |
-| Query Builder | When questions are saved and viewed along with what types of choices are made such as chart types and query clauses used. | Helps the Metabase team understand the basic patterns around how users are accessing their data. |
-| SQL Query | When a SQL query is saved or run. | This mostly just gives us a sense for when users are bypassing the GUI query interface. We never capture the actual SQL written. |
-| Admin Settings | We capture some very basic stats about when settings are updated and if there are ever errors. We also capture non-intrusive settings such as the chosen timezone. | We use this information to make sure that users aren't having problems managing their Metabase instance and it provides us some sense for the most common configuration choices so we can optimize for those cases. |
-| Databases | We simply capture when databases are created or removed and what types of databases are being used | This helps Metabase ensure that we spend the most time and attention on the types of databases that are most popular to users. |
-| Data Model | The saving and updates on tables, fields, segments, and metrics are all counted, along with a few other details such as what types of special metadata choices are made. | We use this data to help ensure that Metabase provides an appropriate set of options for users to describe their data and also gives us a sense for how much time users spend marking up their schemas. |
-
+| Category | Action | Why we collect this |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Links and Page Views | General website tracking of what pages are most used | This provides better understanding of what parts of the application are liked and used by customers so we know what's popular and potentially what needs more improvement. |
+| Dashboards | When the dashboard dropdown is used, when dashboards are created and updated, what types of edits occur such as adding/removing cards and repositioning. | We use this information to understand how dashboards are being used and what types of activities users most commonly do on their dashboards. |
+| Pulses | When pulses are created and updated, what types of pulses are created, and how many cards typically go in a pulse. | This is used to have a sense for how teams are structuring their push based communication. When and where is information most often sent and how much information allows Metabase to continue improving features around push based data interactions. |
+| Query Builder | When questions are saved and viewed along with what types of choices are made such as chart types and query clauses used. | Helps the Metabase team understand the basic patterns around how users are accessing their data. |
+| SQL Query | When a SQL query is saved or run. | This mostly just gives us a sense for when users are bypassing the GUI query interface. We never capture the actual SQL written. |
+| Admin Settings | We capture some very basic stats about when settings are updated and if there are ever errors. We also capture non-intrusive settings such as the chosen timezone. | We use this information to make sure that users aren't having problems managing their Metabase instance and it provides us some sense for the most common configuration choices so we can optimize for those cases. |
+| Databases | We simply capture when databases are created or removed and what types of databases are being used | This helps Metabase ensure that we spend the most time and attention on the types of databases that are most popular to users. |
+| Data Model | The saving and updates on tables, fields, segments, and metrics are all counted, along with a few other details such as what types of special metadata choices are made. | We use this data to help ensure that Metabase provides an appropriate set of options for users to describe their data and also gives us a sense for how much time users spend marking up their schemas. |
### Server-side Analytics
-| Metric | An example of why we collect this |
-|--------|-----------------------------------|
-| Number of Users/Admins and whether SSO is enabled | To understand which auth methods are being used, and whether to prioritize features that scale with number of users. |
-| Number of user groups | To understand how complicated a permissions model most of our users have, and to make sure that we don't over-simplify our designs. |
-| Number of Dashboards | Whether we need to provide ways to organize dashboards. |
-| Number of Cards per Dashboards | Do we need to provide more structure to make long dashboards easier to parse? |
-| Number of Dashboards per Card | Are our users only creating a card to put it in a dashboard or are they used in many places? |
-| Types of Databases | Which database driver bugs to prioritize |
-| Number of pulses with attachments | Are people using attachments? |
-| Number of alerts | Are people using alerts? Do they typically have a few or does each user have them? |
-| Number of Collections | Do we need to add additional organization tools? |
-| Number of Databases | Are users using a single DB or many? How large should the icons for a database in the databrowser be? |
-| Number of Schema | Are users actively using namespaces on redshift? Do we actually need to design for 100s of schemas or is that just a small percentage of our users? |
-| Number of Tables | What kind of data models are people using? Do we need table search? |
-| Number of Fields | Can we pre-fetch all the fields in our metadata api to improve performance for most usres, or should we fetch them per table to scale more efficiently? |
-| Number of Segments | Are people using segments widely? If so, should we surface them up higher in the UI? |
-| Number of Metrics | Are metrics common? If not, should we remove the Metrics option in the New Question Flow |
-| Number of Queries Run | How many queries do our most active instances run per day? Do we need to improve caching? |
-| Number of Query Errors | Do we need to change how we display errors in the logs? Are they being spammed? |
-| Query Latencies | What percentage of our user base runs queries that allow for iterative querying (<1second) |
-| Timezone | We have a bug in a certain timezone, how many users are in that timezone? |
-| Language | How many non-english speaking users do we have? How fast should we be pushing internationalization? |
-| OS and JVM Version | Can we deprecate Java 7 already? |
+
+| Metric | An example of why we collect this |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Number of Users/Admins and whether SSO is enabled | To understand which auth methods are being used, and whether to prioritize features that scale with number of users. |
+| Number of user groups | To understand how complicated a permissions model most of our users have, and to make sure that we don't over-simplify our designs. |
+| Number of Dashboards | Whether we need to provide ways to organize dashboards. |
+| Number of Cards per Dashboards | Do we need to provide more structure to make long dashboards easier to parse? |
+| Number of Dashboards per Card | Are our users only creating a card to put it in a dashboard or are they used in many places? |
+| Types of Databases | Which database driver bugs to prioritize |
+| Number of pulses with attachments | Are people using attachments? |
+| Number of alerts | Are people using alerts? Do they typically have a few or does each user have them? |
+| Number of Collections | Do we need to add additional organization tools? |
+| Number of Databases | Are users using a single DB or many? How large should the icons for a database in the databrowser be? |
+| Number of Schema | Are users actively using namespaces on redshift? Do we actually need to design for 100s of schemas or is that just a small percentage of our users? |
+| Number of Tables | What kind of data models are people using? Do we need table search? |
+| Number of Fields | Can we pre-fetch all the fields in our metadata api to improve performance for most usres, or should we fetch them per table to scale more efficiently? |
+| Number of Segments | Are people using segments widely? If so, should we surface them up higher in the UI? |
+| Number of Metrics | Are metrics common? If not, should we remove the Metrics option in the New Question Flow |
+| Number of Queries Run | How many queries do our most active instances run per day? Do we need to improve caching? |
+| Number of Query Errors | Do we need to change how we display errors in the logs? Are they being spammed? |
+| Query Latencies | What percentage of our user base runs queries that allow for iterative querying (less than 1 second) |
+| Timezone | We have a bug in a certain timezone, how many users are in that timezone? |
+| Language | How many non-english speaking users do we have? How fast should we be pushing internationalization? |
+| OS and JVM Version | Can we deprecate Java 7 already? |
Note this is meant to be representative. The actual code that is running to generate this can be audited at [https://github.com/metabase/metabase/blob/master/src/metabase/util/stats.clj](https://github.com/metabase/metabase/blob/master/src/metabase/util/stats.clj).
diff --git a/docs/operations-guide/configuring-application-database.md b/docs/operations-guide/configuring-application-database.md
index ec598561a62208c563fa60ae319477f27770f9e3..ff189cb1178023c5041f91dcf9e5f6bae2dab990 100644
--- a/docs/operations-guide/configuring-application-database.md
+++ b/docs/operations-guide/configuring-application-database.md
@@ -5,18 +5,19 @@ data needed to run the application. The default settings use an embedded H2 data
##### Notes
-* Using Metabase with an H2 application database is not recommended for production deployments. For production
- deployments, we highly recommend using Postgres, MySQL, or MariaDB instead. If you decide to continue to use H2,
- please be sure to back up the database file regularly.
-* You cannot change the application database while the application is running. Connection configuration information is
- read only once when the application starts up and will remain constant throughout the running of the application.
-* Metabase provides limited support for migrating from H2 to Postgres or MySQL if you decide to upgrade to a more
- production-ready database. See [Migrating from H2 to MySQL or Postgres](migrating-from-h2.md) for more details.
+- Using Metabase with an H2 application database is not recommended for production deployments. For production
+ deployments, we highly recommend using Postgres, MySQL, or MariaDB instead. If you decide to continue to use H2,
+ please be sure to back up the database file regularly.
+- You cannot change the application database while the application is running. Connection configuration information is
+ read only once when the application starts up and will remain constant throughout the running of the application.
+- Metabase provides limited support for migrating from H2 to Postgres or MySQL if you decide to upgrade to a more
+ production-ready database. See [Migrating from H2 to MySQL or Postgres](migrating-from-h2.md) for more details.
+#### [H2](https://www.h2database.com/) (default)
-#### [H2](http://www.h2database.com/) (default)
+**For production installations of Metabase we recommend that users [replace the H2 database with a more robust option](./migrating-from-h2.md) such as Postgres.** This offers a greater degree of performance and reliability when Metabase is running with many users.
-To use the H2 database for your Metabase instance you don't need to do anything at all. When the application is first launched it will attempt to create a new H2 database in the same filesystem location the application is launched from.
+To use the H2 database for your Metabase instance you don't need to do anything at all. When the application is first launched it will attempt to create a new H2 database in the same filesystem location the application is launched from.
You can see these database files from the terminal:
@@ -27,7 +28,7 @@ You should see the following files:
metabase.db.h2.db # Or metabase.db.mv.db depending on when you first started using Metabase.
metabase.db.trace.db
-If for any reason you want to use an H2 database file in a separate location from where you launch Metabase you can do so using an environment variable. For example:
+If for any reason you want to use an H2 database file in a separate location from where you launch Metabase you can do so using an environment variable. For example:
export MB_DB_TYPE=h2
export MB_DB_FILE=/the/path/to/my/h2.db
@@ -35,9 +36,7 @@ If for any reason you want to use an H2 database file in a separate location fro
Note that H2 automatically appends `.mv.db` or `.h2.db` to the path you specify; do not include those in you path! In other words, `MB_DB_FILE` should be something like `/path/to/metabase.db`, rather than something like `/path/to/metabase.db.mv.db` (even though this is the file that actually gets created).
-#### [Postgres](http://www.postgresql.org/)
-
-**For production installations of Metabase we recommend that users replace the H2 database with a more robust option such as Postgres.** This offers a greater degree of performance and reliability when Metabase is running with many users.
+#### [Postgres](https://www.postgresql.org/)
You can change the application database to use Postgres using a few simple environment variables. For example:
@@ -54,8 +53,9 @@ This will tell Metabase to look for its application database using the supplied
export MB_DB_CONNECTION_URI="postgres://localhost:5432/metabase?user=<username>&password=<password>"
java -jar metabase.jar
-#### [MySQL](http://www.mysql.com/)
-If you prefer to use MySQL we've got you covered. You can change the application database to use MySQL using these environment variables. For example:
+#### [MySQL](https://www.mysql.com/) or [MariaDB](https://www.mariadb.org/)
+
+If you prefer to use MySQL or MariaDB we've got you covered. The minimum recommended version is MySQL 5.7.7 or MariaDB 10.2.2, and the `utf8mb4` character set is required. You can change the application database to use MySQL using environment variables like this:
export MB_DB_TYPE=mysql
export MB_DB_DBNAME=metabase
@@ -68,4 +68,4 @@ If you prefer to use MySQL we've got you covered. You can change the applicatio
This will tell Metabase to look for its application database using the supplied MySQL connection information. Metabase also supports providing a full JDBC connection URI if you have additional parameters:
export MB_DB_CONNECTION_URI="mysql://localhost:3306/metabase?user=<username>&password=<password>"
- java -jar metabase.jar
\ No newline at end of file
+ java -jar metabase.jar
diff --git a/docs/operations-guide/handling-timezones.md b/docs/operations-guide/handling-timezones.md
index 1ce1a8648e52653421462eebdba66c53d57b5c72..35f5fcbb17615c84a16c87f5fcea03c7a707f27c 100644
--- a/docs/operations-guide/handling-timezones.md
+++ b/docs/operations-guide/handling-timezones.md
@@ -4,19 +4,20 @@ Metabase does its best to ensure proper and accurate reporting in whatever timez
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.
+- `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.
+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.
\ No newline at end of file
+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.
+
+If you are still experiencing timezone problems, then have a look at the [timezone troubleshooting guide](../troubleshooting-guide/timezones.md).
diff --git a/docs/operations-guide/java-versions.md b/docs/operations-guide/java-versions.md
index 486ce99f3a855115c66b63e452512bbadbec5c23..9b1196063a2b1a49e5a699a6454248527b63f4b3 100644
--- a/docs/operations-guide/java-versions.md
+++ b/docs/operations-guide/java-versions.md
@@ -1,3 +1,3 @@
# Java Versions
-Metabase will run on Java version 8, 9, or 10. Java 11 support is still a work in progress, so please be patient while we get everything working.
\ No newline at end of file
+Metabase will run on Java version 8 and 11.
diff --git a/docs/operations-guide/migrating-from-h2.md b/docs/operations-guide/migrating-from-h2.md
index ac65de83e27fc1939f0b8ebc7ddee4bbc8d049d8..014a7a87d1e1783f9f2a08d6ea44bed188866042 100644
--- a/docs/operations-guide/migrating-from-h2.md
+++ b/docs/operations-guide/migrating-from-h2.md
@@ -6,7 +6,7 @@ Metabase provides a custom migration command for upgrading H2 application databa
1. Shutdown your Metabase instance so that it's not running. This ensures no accidental data gets written to the db while migrating.
2. Make a backup copy of your H2 application database by following the instructions in [Backing up Metabase Application Data](backing-up-metabase-application-data.md). Safety first!
-3. Run the Metabase data migration command using the appropriate environment variables for the target database you want to migrate to. You can find details about specifying MySQL and Postgres databases at [Configuring the application database](configuring-application-database.md). Here's an example of migrating to Postgres:
+3. Run the Metabase data migration command using the appropriate environment variables for the target database you want to migrate to. You can find details about specifying MySQL and Postgres databases at [Configuring the application database](configuring-application-database.md). Here's an example of migrating to Postgres:
```
export MB_DB_TYPE=postgres
@@ -22,7 +22,8 @@ It is expected that you will run the command against a brand-new (empty!) databa
###### Notes
-* Avoid upgrading and migrating at the same time, since it can cause problems with one of database schemas not matching.
-* It is required that you can connect to the target MySQL or Postgres database in whatever environment you are running this migration command in. So, if you are attempting to move the data to a cloud database, make sure you take that into consideration.
-* The code that handles these migrations uses a Postgres SQL command that is only available in Postgres 9.4 or newer versions. Please make sure you Postgres database is version 9.4 or newer.
-* H2 automatically adds a `.h2.db` or `.mv.db` extension to the database path you specify, so make sure the path to the DB file you pass to the command *does not* include it. For example, if you have a file named `/path/to/metabase.db.h2.db`, call the command with `load-from-h2 /path/to/metabase.db`.
\ No newline at end of file
+- Avoid upgrading and migrating at the same time, since it can cause problems with one of database schemas not matching.
+- It is required that you can connect to the target MySQL or Postgres database in whatever environment you are running this migration command in. So, if you are attempting to move the data to a cloud database, make sure you take that into consideration.
+- For MySQL or MariaDB, the minimum recommended version is MySQL 5.7.7 and MariaDB 10.2.2, while `utf8mb4` character set is required.
+- The code that handles these migrations uses a Postgres SQL command that is only available in Postgres 9.4 or newer versions. Please make sure you Postgres database is version 9.4 or newer.
+- H2 automatically adds a `.h2.db` or `.mv.db` extension to the database path you specify, so make sure the path to the DB file you pass to the command _does not_ include it. For example, if you have a file named `/path/to/metabase.db.h2.db`, call the command with `load-from-h2 /path/to/metabase.db`.
diff --git a/docs/troubleshooting-guide/bugs.md b/docs/troubleshooting-guide/bugs.md
index 5eee371c2f379a00a5086c28ee4fc246a3401fa1..46224c61d3681af4833bb289ea40c3bc72c071c1 100644
--- a/docs/troubleshooting-guide/bugs.md
+++ b/docs/troubleshooting-guide/bugs.md
@@ -1,6 +1,6 @@
If you come across something that looks like a bug, start by searching our [Github issues](https://github.com/metabase/metabase/issues) to see if it has already been reported. If it has, please let us know you're experiencing the same issue by reacting with a thumbs up emoji or adding a comment providing additional information.
-If the bug has not yet been reported, go ahead and [open a bug report](https://github.com/metabase/metabase/issues/new?assignees=&labels=Bug&template=bug_report.md&title=). We suggest collecting the following information to help us reproduce the issue:
+If the bug has not yet been reported, go ahead and [open a bug report](https://github.com/metabase/metabase/issues/new/choose). We suggest collecting the following information to help us reproduce the issue:
1. Metabase server logs
2. Javascript console logs
@@ -14,12 +14,14 @@ If the bug has not yet been reported, go ahead and [open a bug report](https://g
## Helpful tidbits
### Accessing the Metabase server logs
+
While you can always look for the logs Metabase leaves on your server file system (or however you collect logs), if you are logged into Metabase with an admin account, you can also access them from the gear drop down menu in the upper right hand corner -> Admin -> Troubleshooting -> Logs.
### Checking for Javascript console errors
+
Metabase will send debugging information and errors to your browser's developer console. To open the developer console, follow the instructions for your web browser of choice:
-* [Chrome](https://developers.google.com/web/tools/chrome-devtools/open#console)
-* [Firefox](https://developer.mozilla.org/en-US/docs/Tools/Web_Console/Opening_the_Web_Console)
-* [Safari](https://support.apple.com/guide/safari-developer/develop-menu-dev39df999c1/mac)
-* [Edge](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium)
+- [Chrome](https://developers.google.com/web/tools/chrome-devtools/open#console)
+- [Firefox](https://developer.mozilla.org/en-US/docs/Tools/Web_Console/Opening_the_Web_Console)
+- [Safari](https://support.apple.com/guide/safari-developer/develop-menu-dev39df999c1/mac)
+- [Edge](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium)
diff --git a/docs/troubleshooting-guide/loggingin.md b/docs/troubleshooting-guide/loggingin.md
index 632481d0ad69c506a47ad487206a17f6e4106efe..dac33f56781110fb3b8d568ebd7a52a854053b43 100644
--- a/docs/troubleshooting-guide/loggingin.md
+++ b/docs/troubleshooting-guide/loggingin.md
@@ -1,39 +1,43 @@
## Troubleshooting Process
+
1. Try to log in with a local account
2. Try to log in with a Google Auth SSO account
3. Example JavaScript and Server logs if you are not able to log in.
## Specific Problems:
-
### Invalid Google Auth Token:
+
Sometimes your token from Google will expire.
#### How to detect this:
+
Open up the JavaScript console. Try to log in with Google Auth, see if there are any error messages in the JavaScript console indicating an invalid account.
Also open up your server logs, and see if there are any errors related to authentication. If there are, try recreating the token.
#### How to fix this:
+
Remove the old token from the Google Auth SSO tab in the Admin Panel and create a new one. If the root cause was an invalid auth token, this should fix the problem.
### Forgotten Password
-[This FAQ](../faq/how-do-i-reset-my-password.md) will tell you what to do in the event of a forgotten password.
-
-
+[This FAQ](../faq/using-metabase/how-do-i-reset-my-password.md) will tell you what to do in the event of a forgotten password.
## Helpful tidbits
### Accessing the Metabase server logs
+
While you can always look for the logs Metabase leaves on your server file system (or however you collect logs), if you are logged into Metabase with an admin account, you can view the server logs as well as task and job logs in the Admin Panel by clicking the Troubleshooting tab in the nav bar.
### Checking for JavaScript errors in your web browser
+
Metabase will print debugging information and errors to your browser's JavaScript Console.
You can open the JavaScript console by following the instructions for your specific browser:
-* [Google Chrome](https://developers.google.com/web/tools/chrome-devtools/console/)
-* [Mozilla Firefox](https://developer.mozilla.org/en-US/docs/Tools/Web_Console)
-* [Safari](https://developer.apple.com/library/content/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/Introduction/Introduction.html)
-* [Internet Explorer](https://msdn.microsoft.com/en-us/library/gg589530(v=vs.85).aspx) (On many versions of IE you can also access the console by pressing the F12 key on your keyboard.)
-* [Microsoft Edge](https://docs.microsoft.com/en-us/microsoft-edge/f12-devtools-guide/console)
+
+- [Google Chrome](https://developers.google.com/web/tools/chrome-devtools/console/)
+- [Mozilla Firefox](https://developer.mozilla.org/en-US/docs/Tools/Web_Console)
+- [Safari](https://developer.apple.com/library/content/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/Introduction/Introduction.html)
+- [Internet Explorer](<https://msdn.microsoft.com/en-us/library/gg589530(v=vs.85).aspx>) (On many versions of IE you can also access the console by pressing the F12 key on your keyboard.)
+- [Microsoft Edge](https://docs.microsoft.com/en-us/microsoft-edge/f12-devtools-guide/console)
diff --git a/docs/users-guide/13-sql-parameters.md b/docs/users-guide/13-sql-parameters.md
index 445041b8a14d1779156a17210fd72d725591a176..5f1f1f91d21e2386fa1fc24cb7bdb973be4a9bcf 100644
--- a/docs/users-guide/13-sql-parameters.md
+++ b/docs/users-guide/13-sql-parameters.md
@@ -33,6 +33,7 @@ Setting a variable to the "Field Filter" type allows you to map it to a field in
A field filter variable inserts SQL similar to that generated by the GUI query builder when adding filters on existing columns. This is useful because it lets you do things like insert dynamic date range filters into your native query. When adding a field filter, you should link that variable to a specific column. Field filter variables should be used inside of a `WHERE` clause in SQL, or a `$match` clause in MongoDB.
**Note:** Table aliases are not supported. This is because field filters generate SQL based on the mapped field.
+Some databases require the schema in the `FROM` clause. An example for Oracle would be `FROM "schema"."table"`. In BigQuery, back ticks are needed, like ``FROM `dataset_name.table` ``.
Example:
@@ -85,9 +86,11 @@ Filter widgets **can't** be displayed if the variable is mapped to a field marke
If you input a default value for your field filter, this value will be selected in the filter whenever you come back to this question. If you clear out the filter, though, no value will be passed (i.e., not even the default value). **The default value has no effect on the behavior of your SQL question when viewed in a dashboard.**
-You can also define default values directly in your query, which are useful when defining complex default values.
+###### Default value in the query
-Current date example:
+You can also define default values directly in your query, which are useful when defining complex default values. Note that the hash (`#`) might need to be replaced by the comment syntax of the database you're using. Some databases use double-dashes (`--`) as comment syntax.
+
+Current example for a Date filter:
```
SELECT p.*
diff --git a/docs/users-guide/custom-questions.md b/docs/users-guide/custom-questions.md
index 50f77869af03fc6503c685642ca00026ec8ce4f5..90201809a2d804bb1b204f5e75677d4d73736cfd 100644
--- a/docs/users-guide/custom-questions.md
+++ b/docs/users-guide/custom-questions.md
@@ -14,7 +14,7 @@ The notebook is made up of a sequence of individual steps. Under each step you'l
This first step is required, and is where you pick the data that you want to base your question on. In most cases you'll pick one of the tables in your database, but you can also choose a previously saved question's result as the starting point for your new question. What this means in practice is that you can do things like use complex SQL queries to create new tables that can be used as starting data in a question just like any other table in your database.
-You can use most saved questions 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.
+You can use most saved questions as source data, provided you have [permission](../administration-guide/05-setting-permissions.md) to view that question. You can even use questions that were saved as a chart rather than a table.
There are some kinds of saved questions that can't be used as source data: