Skip to content
Snippets Groups Projects
Commit 3ca9c42f authored by Sameer Al-Sakran's avatar Sameer Al-Sakran
Browse files

more info

parent 5c88521d
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/administration-guide.md
+ 62
− 13
View file @ 3ca9c42f
# Administration Guide
It is assumed you've already installed a copy of Metabase. If you need help doing that, check out our [Installation Guide](www.github.com/metabase/metabase-init/issues/X)
It is assumed you've already installed a copy of Metabase. If you need help doing that, check out our [Installation Guide](installation-guide.md)
## Connecting to databases
## Managing databases
To see a list of all databases click on "Databases"
### Adding a database connection
Click on "add database".
you can currently add databases of types
* H2
* MySQL
* Postgres
for each you'll need the approriate connection information.
## Managing user accounts
## Annotating data for your users
### SSL
when you first add a database, we'll try to connect with and without ssl. if ssl is possible, we'll mark it as an ssl connection as a first choice. you can change this after addition
### Deleting databases
you can delete a database by either clicking "Remove this database" under "connection details" or hovering over the database row in the list and clicking on the red "Delete" button. Be extra careful when doing this because it's not reversible and all saved questions and dashboard cards based on this database will be deleted.
### metadata syncing
after a database is connected and the connection is validated, we'll get all the table and column schema information.
we'll also do this on a nightly basis
To sync manually, click on a database in this list, click on "connection details" and click syn
### database analysis
we'll try to guess your field types based on name
we'll also pull out a sample of each table and look for urls, json encoded strings, etc
if we get it wrong you can edit it later
## Setting up email
Once you've connected to a database, the next thing you should do is set up email. Email is used to reset passwords, onboarding new users and notifying you when something happens.
### Setting it up
## Production Deployments
* Beanstalk
* running a container
* injecting database variables vs using an embedded database
* running a jar
* where to put the database?
* HTTPS!
* if beanstalk, use an ELB and terminate there
* otherwise, recommend nginx as a proxy + provide instructions
* set up an smtp server
* if you use google apps, credentials will be from X
* if you use SES, credentials from X
* if you use mandrill, you can get crendentials from X
* SSL is preferred here
* if your email service has a whitelist of email addresses that are allowed to send email, make sure to set the "Sender of system notifications" setting to a whitelisted email address
## Metadata editing
a full description of the metadata Metabase understands and takes advantage of can be found in our [Metadata Guide](metadata-guide.md)
### Tables
* add description to let people know what the table contains and how it can be used
* descriptions will be displayed in the data model reference
* control visibility by hiding
* once you've hidden a field, you should give us the reason
### Fields
* if metabase got the field type wrong, you should update it here.
* adding a description allows users to understand what the field contains
* a description is especially useful when the fields have values that are abbreviations or encoded in some way
* descriptions will be displayed in the data model reference
## Managing user accounts
* if you click on "people" you can see a list of all user accounts on this system
* you can add accounts by clicking "Add person" and telling Metabase their name and email
* once you have added them, they will get an email and a link where they can set their password
* to make a user an admin click on "grant admin"
* to remove admin priveledges click on "revoke admin"
* to delete an account, click on "remove". Note that this will delete all the cards this user has created.
docs/getting-started.md
+ 128
− 70
View file @ 3ca9c42f
## Getting Started
### Installation
* download jar from www.metabase.com/download
* make sure you have java by running `java —version` and verify that you have version 1.6 or greater
* place the jar in a directory and run `java -jar metabase.jar`. this will create a file called metabase.db.h2.db which contains application data. Do not delete this file.
* go to http://localhost:3000 to start the installation process
### Configure your instance
* enter your name, email and a password
* collect the information you’ll need to point to a database
* Heroku:
* go to https://postgres.heroku.com/databases
* select the database you want to connect to and click it
* find the hostname, port, username, database name and password
* Amazon RDS:
* go to your AWS management console
* click RDS under ‘Database’ services
* click “instances"
* click on the database you want to use
* the hostname is the “Endpoint” parameter, the port parameter under “Security and Network”, DB name and username are under “configuration details". You’ll need to ask you DB Administrator for password
* other remote MySQL or Postgres: ask your DB Administrator (or check you records) for hostname, port, database name, user name and password
* Mongodb
* collect the database name, host, port, username and password
* H2 database (including examples)
* get the file path
* Taking the connection information above, fill out the remainder of the form.
* Metabase will attempt to connect to your database and validate the information you’ve given it. If you get a validation error, double check the spelling and punctuation of the information you’ve connected.
* If successful, Metabase will run a few queries against your database to build a model of your data and you can click “continue” to move on to see what data Metabase has found!
### Seeing what data you have
* In the bottom portion of the home page, you’ll see the tables that metabase was able to find
* note the number of rows
* click on one of these that you find interesting
### Asking your first question
* you’re now in the question asking interface
* try getting the “Count” of records in this table.
* click “Find out"
* this should match the number of rows you saw previously
* try performing a “group by” and selecting a field that looks interesting.
* click “find out”.
* this should result in a table of how many rows have each value in that column
* click on the download icon and note that you’ve downloaded a csv with this information
* you can also filter results, try clicking “filter"
* you should see a list of fields. select an interesting one, and filter your results
* click “find out”
* note that the numbers changed
### Visualizing answers
* If the grouped by dimension was a date, try displaying it as a “line” graph, otherwise try clicking “bar” chart
* note that you can display your answer in a variety of ways
### Saving your question for later
* Click “save" and give the answer a name
* for now ignore description and permissions
* note that you can now favorite the card as well
### Dashboards
* go to the question you previously saved and click on the add to dashboard icon
* select “Create new” and give your new dashboard a name
* click ok, you should see a confirmation box that gives you a link to the new dashboard
* click on the link and check out the new dashboard. you’ll notice that the visualization of your question has been added to the dashboard.
* create another card and add it to this dashbaord
* go back to the dashboard and click on the edit layout link
* note that you can resize cards on the dashboard and drag them around
* click the edit layout link again to save the dashboard in this form
Congrats! you’ve learned how to ask questions, save them for later use or sharing and publish them to a dashboard you can use or share with others
##Welcome to Metabase
Metabase lets you ask questions about your data, drill into specific records, and utilize dashboards to help you keep organized. Metabase is a tool that allows you to get the most out of your data. Let's get started!
##Step 1: Installing Metabase
Metabase uses Java to operate, so you'll need at least version 1.6 or later. Not sure what version of Java you're using? No problem. Here's how to check:
###Mac Users
In Terminal, insert the command prompt: "java-version". You will receive a message similar to:
```
java version "1.6.0_65"
Java (TM) SE Runtime Environment (build 1.6.0_65-b14-466.1-11M4716)
Java HotSpot (TM) 64-Bit Server VM (build 20.65-b04-466.1, mixed mode)
```
As long as the version is at least 1.6, you're all set to go!
###Windows Users
Under Programs, click on the "Java" icon. Click on "About" and then find the version number listed. If you're using version 1.6 or greater, then you're good to go!
If you don't have the latest version of Java, download it at: [https://java.com/en/download/]()
Once you take care of checking the version of java on your computer, **Download the Metabase file from [www.metabase.com/download]()**. Place the Metabase JAR file in a directory. Run the command "java -jar metabase.jar" to create a file called, "metabase.db.h2.db". **This file contains important application data, so don't delete it.**
Now that you have Metabase installed, you can sync it to your database. Go to [http://localhost:3000]() to connect your database.
##Step 2: Configuring your Instance
Create a Metabse account by entering your name, email, and super-secretive password—we don't recommend using password123!
Now Metabase needs to find your data. Where does your data live? Depending on where you keep your database, the steps to connect with Metabase vary. Not to worry, though, we outlined the configuration steps for each of the major platforms.
**If you use Heroku:**
1. Go to [https://postgres.heroku.com/databses]().
2. Click on the databse you want to connect to Metabase.
3. Write down the following information based on your database.
* Hostname
* Port
* Username
* Database Name
* Password
You'll need to input this information into the remainder of the Metabase form.
**If you use Amazon RDS:**
1. Go to your AWS Management Console.
* Need help finding that? Visit https://**My_AWS_Account_ID**.signin.aws.com/console/ Be sure to insert your own AWS Account ID, though!
2. Under "Databse" services, click "RDS".
3. Then click "Instances".
4. Select the databse you want to connect to Metabase.
5. Write down the following information based on your database.
* Hostname - This is listed as the "Endpoint" parameter
* Port - Find the port parameter under "Security and Network"
* Username - Find this under "Configuration Details"
* Database Name - Find this under "Configuration Details"
* Password - Ask your database administrator for the password
You'll need this information to finish syncing Metabase with your database.
**If you use anoter Remote MySQL or Postgres:**
1. Ask your database administrator (or check your own records) for the following information:
* Hostname
* Port
* Username
* Database Name
* Password
You'll need to input this information into the Metabase form.
**If you use MONGODB:**
1. Collect the following information about the database you'd like to connect:
* Hostname
* Port
* Username
* Database Name
* Password
Metabase needs this information to finish connecting to your database.
**If you use H2:**
1. You'll need the file path for your database.
**Now that you have your database information,** use the information to fill out the remainder of the form.
After you enter your database's information, Metabase will try to connect to your database and validate the credentials. If you get a validation error, no need to panic. Validation errors occur when the wrong credentials are entered. Simply double check the spelling and punctuation of the information you entered and try to connect to the database once more.
Once Metabase successfully connects to your database, it'll run a few queries against your database to build a model of your data. Click the prompt "continue" to see what data Metabase found in your database!
##Step 3: Discovering your Data
If you look at your homepage, you'll see the different tables that Metabase was able to find in your data source set and pull for you. Click a table you want to lear more about. Note the number of rows.
For example, in the sample data set above, the database (data source) is "Bird Impact"(it's a database of the number of collisions between birds and aircrafts). The table is "strikes" and the number of rows is 151,069.
##Step 4: Asking your Question
By clicking on an individual table, you enter the interface (pictured below) that allows you to ask Metabase questions based on your data.
Your screen will reflect the data source you connected to Metabase and the table you selected. In our example, the data source is "Bird Impact" and the table is "strikes" (exactly what we selected on the previous screen).
For now, let's start with a basic question using our data set. How many collisions were there between aircrafts and birds? More precisely, this question translates to "How many records are in the table 'strikes'?" To find a number, we want to see the **total count**.
Click **total count** from the dropdown menu next to **I want to see**. Then, click the **Find Out** button in the bottom right hand corner of the screen.
There were 151,069 collisions between aircraft and birds. Stated in terms of the database, there are 151,069 records in the table. *Does this number look familiar?* When selecting a table on the homepage in Step 3 (See *Figure 1*), 151069 was labeled as "total" and listed next to the table "strikes".
**The total number listed next to each table is the number of records. Each record is an iteration of the event your database records.**
Metabase can present the answers to your questions in a variety of formats. To change the format, select one of the options from the dropdown menu in the bottom left hand corner of the screen next to **Show as**.
Not every format is the best way to show an answer to a question. If Metabase thinks that's the case with a specific question and display format, it'll say that the format is "not sensible" for the question. For example, it wouldn't make sense to show the number of collisions between aircraft and birds as a singular bar graph.
You can "group" your data into categories. Next to **Grouped by:** select the category to filter your answers by. Metabase will analyze your database to discover valid categories for adding filters to your question. For example, by grouping the results by the filter "PRECIP" (short for "precipitation"), we can use Metabase to view the number of collisions between aircraft and birds categorized by the weather conditions at the time.
**When you make any changes to the question (called the "query"), an orange alert appears to let you know that the answer displayed is outdated.** Click **Find Out!** to refresh the answer and to find the answer to your new query.
By clicking **Hide Query**, you're able to view all your results clearly. Metabase temporarily hides the query interface, so you can easily see the results. To ask a new question, select **Show query** to return to the question asking interface.
docs/installation-guide.md
+ 11
− 0
View file @ 3ca9c42f
......@@ -57,3 +57,14 @@ On our roadmap are
If you are interested in the status of any of these drivers, click through to the issues to see what work is being done. If you are interested in a driver to another database, please open an issue!
## Production Deployments
* Beanstalk
* running a container
* injecting database variables vs using an embedded database
* running a jar
* where to put the database?
* HTTPS!
* if beanstalk, use an ELB and terminate there
* otherwise, recommend nginx as a proxy + provide instructions
docs/users-guide.md
+ 108
− 31
View file @ 3ca9c42f
......@@ -9,27 +9,9 @@ It's an open source business intelligence server
* group them into dashboards
* and share questions + dashboards with others
### Questions
The core concept in Metabase are Questions and their corresponding Answers.
Questions are made up of a number of parts:
* source data - database + table
* optional filter
* aggregation clause - bare rows, count, etc
* group by field or fields
* Advanced Options
* Limit to 1, 10,1000 or more entries
* Sort by a column: either by clicking on the column header or by selecting the column in the advanced section
And can be visualized in a number of ways
* scalar
* table
* charts
* maps
Once answered they can be saved, favorited or downloaded
### A Short Overview of Databases
Before we talk about metabase, it's useful to give a short overview of the terminology we will use.
A database is a collection of tables.
#### Tables
......@@ -77,6 +59,28 @@ For example, in our hypothetical application, we could connect each reservation
If your database contains these kinds of relationships (and many do), you can use linked objects in this way. So if our hypothetical application database were examined with Metabase, we could ask questions like:
-- Example of a join --
### Questions
The core concept in Metabase are Questions and their corresponding Answers.
Questions are made up of a number of parts:
* source data - database + table. Typically you will be working with a single table in your database as the starting point for you questions.
* optional filter - this narrows down the source data to an interesting subset, like "active users" or "bookings after June 15th, 2015"
* aggregation clause - bare rows, count, etc
* group by field or fields
* Advanced Options
* Limit to 1, 10,1000 or more entries
* Sort by a column: either by clicking on the column header or by selecting the column in the advanced section
And can be visualized in a number of ways
* scalar
* table
* charts
* maps
Once answered they can be saved, favorited or downloaded
### Dashboards
* made up of multiple cards in a given position
* used to share groups of questions that should be
......@@ -90,7 +94,7 @@ Useful to see the data you're working with, or for exploring small tables.
Useful when combined with Filtering to see segments of interesting Users, venues, etc. These segments can be saved and passed around.
### Different kinds of metrics
What is a metric? It's a number that is derived from your data.
What is a metric? It's a number that is derived from your the source table (filtered by any filters you've added described later).
#### Basic Metrics
* Count: Total of number of rows in the answer
......@@ -100,8 +104,42 @@ What is a metric? It's a number that is derived from your data.
* Number of Distinct Values: Number of unique values of a column among all the rows in the answer
* Cummulative Sum: Additive sum of all the columns, eg. total revenue over time
* Standard Deviation: Number which expresses how much the values of a column vary among all rows in the answer
### Filtering your data
### Breaking out metrics
Metrics are single numbers.
Often you'll want to know more detailed information.
For example, the sum of all invoiced amounts is a metric.
It's natural to want to look at this metric across either time or another dimension, such as whether the invoice is paid or not.
You can do this by adding a "Grouping" to your question.
You can breakout by any date or time dimension you have, as well as any category field.
If you break out by a single dimension you get a table where the leftmost column is the dimension and the rightmost column is the value of the metric for that point.
Two dimension breakouts are equivalent to a pivot table in excel and are one of the workhorses of the business intelligence world.
If you break out by additional dimensions, you will add columns to the left of the dimension.
--Exmaple of a 2 and 3 d breakout--
### Filtering your data
You can filter by any fields in the table you're working with or any connected tables through foreign keys in that table.
Different fields can have different filters based on them.
All fields can be filtered by:
* is a value, eg. "Status is 'closed'"
* is not a value eg. "Status is not 'closed'"
* is null, i.e. it isn't set in the record
* is not null
Some fields will have a limited number of possible values. Metabase will pick up on this and limit the choices in the filter selection to only valid values.
Some field (eg. price) will have too many.
Fields that are comparable, like numbers or dates, can also be filtered using the following operators:
* Less than a value you enter
* Greater than a value you enter
* Between two values you enter
If filtering by dates, a datepicker should appear to allow you to input them easily.
## Digging into individual records
......@@ -109,31 +147,68 @@ What is a metric? It's a number that is derived from your data.
* you can see all the fields that are hidden for readability
* you can see all connected tables
## Saving questions + dashboards
### what are dashboards?
* public dashboards contain canonical KPIs, etc
* personal dashboards can be used for projects and deleted or for long standing areas of interest
### arranging dashboards
* resizing cards
* reordering cards
### tips on creating dashboards
## Graphing things
## Asking more advanced questions in SQL
* If you ever need to ask questions that can't be expressed using our interactive GUI query builder, you can use SQL.
* SQL is short for Structured Query Language and is a widely used standard for getting data from databases. To learn more about it read: [SQL Tutorial](http://www.w3schools.com/sql/default.asp)
* Even if you don't understand SQL or how to use it, it's worthwhile understanding how to use SQL inside Metabase as sometimes other people will share SQL based questions that are useful to you.
* You can switch a card from GUI mode to SQL mode by clicking on the cursor icon in the upper right
* Once there you can write SQL directly.
* To see how it work try running `select count(*), date from purchases group by date`. Don't worry if you don't understand this just yet. Click 'run query' and note the table that comes back is the same as if you had graphed "count" broken out by "date"
* Note also that you can treate the result the same way you would treat a result of the GUI, and yu can save it, download the results, or add it to a dashboard.
## Visualizing results
While tables are useful to lookup information and to pull out hard numbers, it is usually easier to see trends and make sense of data using graphs.
Metabase offers a number of charting options.
### line graphs
### Area graphs
### Bar + Pie graphs
## Mapping things
## Maps
### US State maps
* default GeoJSON
* requires a column that is a state in the result
* expect states as abbreviations or full names
### Country maps
* default GeoJSON
* requires a column that is a country in the result
* expect countrys as full names or abbreviations
### Pin maps
* requires your admin to set up a google maps api key
* requires both a latitude and a longitude marked column in the result
* heat maps vs pin maps
## Saving questions + dashboards
### what are dashboards?
* a collection of saved questions that are meant to be referred back to regularly
* meant to be consumed together
* public dashboards contain canonical KPIs, etc
* personal dashboards can be used for projects and deleted or for long standing areas of interest
### arranging dashboards
to make any changes to a dashboard, click on the edit button
this will allow you to resize, reorder or remove cards
* resizing cards
clicking on the borders or the handle on the lower right corner will allow you to drag the cursor to resize the card
* reordering cards
to reorder cards, click+drag the card to its new place. Note that other cards will rearrange as you do this.
* removing cards vs deleting cards
when you click on the "x" icon t
### deleting dashboards
when you delete a dashboard, you aren't deleting the cards
be careful deleting public dashboards
### tips on creating dashboards
* figure out which cards you need
* once you have all the cards, try to find a structure that will allow a user to consume related information together
* if you have more than 10 cards, strongly consider
## Getting help on your data model
* You can get to the data model reference at any time by clicking on the book icon
* You will see a list of databases available to you and the tables in them
......@@ -146,3 +221,5 @@ What is a metric? It's a number that is derived from your data.
* bar chart of count grouped by this field
* line chart of count grouped by this field
* See all the connections
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