Skip to content
Snippets Groups Projects
Commit cc9525f9 authored by hansen's avatar hansen Committed by Maz Ameli
Browse files

Docs fixes and clarification of versions and Field Filters (#11117) 


* Docs minor fixes (and prettier) [ci skip]

* old FAQ move-text and Field Filter schema requirement [ci skip]

* Try to fix Server-Side Analytics table in information-collection.md [ci skip]

* Note about minimum MySQL version for application data [ci skip]

* Somehow version got changed when merging [ci skip]

* Maz suggestion: Update docs/operations-guide/configuring-application-database.md

Co-Authored-By: default avatarMaz Ameli <maz@metabase.com>

* Maz suggestion: Update docs/operations-guide/configuring-application-database.md [ci skip]

Co-Authored-By: default avatarMaz Ameli <maz@metabase.com>

* Maz suggestion: Update docs/users-guide/13-sql-parameters.md [ci skip]

Co-Authored-By: default avatarMaz Ameli <maz@metabase.com>

* Maz suggestion: Update docs/users-guide/13-sql-parameters.md [ci skip]

Co-Authored-By: default avatarMaz Ameli <maz@metabase.com>

* Maz suggestion: Update docs/users-guide/13-sql-parameters.md [ci skip]

Co-Authored-By: default avatarMaz Ameli <maz@metabase.com>

* Maz suggestion: Restore /docs/faq.md - will be a PR for another day [ci skip]
parent 5b1735ee
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 140 additions and 128 deletions
docs/administration-guide/01-managing-databases.md
+ 1
− 1
View file @ cc9525f9
......@@ -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
......
docs/administration-guide/05-setting-permissions.md
+ 7
− 4
View file @ cc9525f9
......@@ -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).
docs/enterprise-guide/audit.md
+ 10
− 10
View file @ cc9525f9
......@@ -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
![Team Members](./images/audit-teammember.png)
### 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.
![Data](./images/audit-data.png)
### 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.
![Items](./images/audit-questions.png)
......@@ -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
......
docs/faq/general/how-do-i-ask-for-help.md
+ 2
− 2
View file @ cc9525f9
# 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.
docs/faq/setup/how-do-i-integrate-with-sso.md
+ 1
− 1
View file @ cc9525f9
# 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/).
docs/faq/setup/what-is-h2.md
+ 1
− 1
View file @ cc9525f9
# 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.
docs/faq/setup/when-should-i-migrate-h2.md
+ 1
− 1
View file @ cc9525f9
# 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.
docs/faq/using-metabase/how-do-i-ask-questions.md
+ 1
− 1
View file @ cc9525f9
# 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).
docs/faq/using-metabase/how-do-i-reset-my-password.md
+ 1
− 1
View file @ cc9525f9
# 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.
docs/information-collection.md
+ 54
− 56
View file @ cc9525f9
......@@ -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).
docs/operations-guide/configuring-application-database.md
+ 16
− 16
View file @ cc9525f9
......@@ -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
docs/operations-guide/handling-timezones.md
+ 12
− 11
View file @ cc9525f9
......@@ -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).
docs/operations-guide/java-versions.md
+ 1
− 1
View file @ cc9525f9
# 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.
docs/operations-guide/migrating-from-h2.md
+ 6
− 5
View file @ cc9525f9
......@@ -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`.
docs/troubleshooting-guide/bugs.md
+ 7
− 5
View file @ cc9525f9
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)
docs/troubleshooting-guide/loggingin.md
+ 13
− 9
View file @ cc9525f9
## 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)
docs/users-guide/13-sql-parameters.md
+ 5
− 2
View file @ cc9525f9
......@@ -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.*
......
docs/users-guide/custom-questions.md
+ 1
− 1
View file @ cc9525f9
......@@ -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:
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment