Skip to content
Snippets Groups Projects
Unverified Commit fa94477d authored by frannietrempe's avatar frannietrempe Committed by GitHub
Browse files

docs - new field types page; delete database basics (#19126)

parent 0b43e4d8
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/administration-guide/03-metadata-editing.md
+ 23
− 101
View file @ fa94477d
## The Data Model page: editing metadata
# The Data Model page: editing metadata
Metabase allows you to annotate the data in your database. Annotations can give Metabase a better understanding of what the data actually means, which allows Metabase to make more intelligent decisions when processing and displaying that data.
The **Data Model** section of the **Admin Panel** contains settings to edit metadata for:
......@@ -9,27 +11,21 @@ The **Data Model** section of the **Admin Panel** contains settings to edit meta
This page focuses on editing table and column metadata; another page covers [segments and metrics](07-segments-and-metrics.md).
### What is metadata?
Metadata is data about other data. It's information that tells you about the data found in your database. For example, we could label a column that looks like just a bunch of numbers with the label "latitude", which would give that column additional meaning and context.
Metabase allows you to annotate the data in your database. Annotations can give Metabase a better understanding of what the data actually means, which allows Metabase to make more intelligent decisions when processing and displaying that data.
### Accessing the Data Model page
## Accessing the Data Model page
Click the settings gear in the top right of the Metabase navigation bar, and select **Admin**. Then click on **Data Model** tab from the top menu.
In the sidebar on the left, you can choose which database to configure. Next, select the table to view and edit its metadata.
### Metadata for tables
## Metadata for tables
For table Metadata, you can:
For table metadata, you can:
- Change [table **visibility**](#table-visibility).
- Change [table **name** and **description**](#table-name-and-description).
- View the [original **schema**](#original-schema).
#### Table visibility
### Table visibility
You can set tables to be **Queryable** or **Hidden**. Setting table visibility can be especially useful if you have a lot of tables in your database but your users will only be interested in a subset of those tables. Table visibility can help keep your Metabase instance tidy by hiding unnecessary tables out of the user interface.
......@@ -43,7 +39,7 @@ Here's a gif showing how to hide and unhide tables:
![Hide and unhide tables](./images/hide-unhide-tables.gif)
#### Table name and description
### Table name and description
You can change the **name** and **description** of your tables. Note that the underlying database won’t be affected; changes will only update the name of the table in Metabase.
......@@ -51,11 +47,11 @@ You can add descriptions to tables to let people know the type of data a table c
![Learn about your data in the SQL editor](./images/learn-about-your-data-sql-editor.png)
#### Original schema
### Original schema
If you ever want to see the original underlying schema for a given table, just click the **Show original schema** toggle in the top-right of the screen.
### Metadata for columns
## Metadata for columns
Metabase automatically attempts to classify your columns and assign them a type, but you can also edit the metadata yourself. If Metabase misclassified any columns, you can correct those inaccurate classifications here.
......@@ -66,25 +62,15 @@ For each column, you can edit its:
- Visibility
- Type
### Columns vs fields
A note about **columns** and **fields**, as these terms can be used interchangeably:
- A **field** is an element for storing data (e.g., the `PRODUCT_ID` field stores identification codes for products).
- A **column** is a list of values, and most often a list of values from a single field (e.g., the `PRODUCT_ID` column stores values from the `PRODUCT_ID` field). A column can also, however, be a list of values from multiple fields. For example, a column might contain values from an expression that computes the difference of values from two different fields: a `TOTAL_WITH_DISCOUNT` column, for example, could take values from the `DISCOUNT` field and subtract them from values in the `SUBTOTAL` field, and list the difference.
In Metabase (and elsewhere) you'll often see these two terms used interchangeably, as in most cases a column refers to data from a single field.
#### Column name
### Column name
To change how the column name is displayed, click on the name of the column. For example, if your ORM produces table names like "auth.user", you can replace this with "User" to make the column more readable. This name change only affects how Metabase displays the column; the change does not affect the database itself.
#### Column description
### Column description
You can include a human-readable summary of a column, its source, and use cases. Any caveats about interpretation can go here as well. Descriptions are particularly useful when columns have values that are abbreviated or coded in a particular format.
#### Column visibility
### Column visibility
By default, users can see every column in a table, but you can select other visibility options:
......@@ -94,77 +80,13 @@ By default, users can see every column in a table, but you can select other visi
For the **SQL editor**, **Do Not Include** settings only affect visibility in the **data reference** section. Though columns will not be visible in the **data reference** section, users will still be able to query these columns.
#### Types
A **column's** **type** dictates how Metabase displays its data, as well as the column's special functionality, if any. For example, by marking columns in a table as **Latitude** and **Longitude**, Metabase can use the columns to create pin and heat maps. Similarly, marking a column as a **URL** allows users to click on the link to visit the URL.
You can also designate a column as the table's **primary key** or **foreign key**.
**Types** include (organized by category):
- **Semantic types**
- **Entity Key** The field in this table that uniquely identifies each row. Could be a product ID, serial number, etc.
- **Entity Name**. Different from the entity key, the Entity name represents what each row in the table *is*. For example, in a Users table, the User column might be the entity name.
- **Foreign Key**. The column in this table that (usually) refers to the primary key of another table in order to connect data from different tables that are related. For example, in a Products table, you might have a Customer ID field that points to a Customers table, where Customer ID is the primary key.
- **Common**
- Category
- Comment
- Description
- Title
- **Location**
- City
- Country
- Latitude
- Longitude
- State
- Zip Code
- **Financial**
- Cost
- Currency
- Discount
- Gross margin
- Income
- Price
- **Numeric**
- Quantity
- Score
- Share
- **Profile**
- Birthday
- Company
- Email
- Owner
- Subscription
- User
- **Date and Time**
- Cancelation date
- Cancelation time
- Cancelation timestamp
- Creation date
- Creation time
- Creation timestamp
- Deletion date
- Deletion time
- Deletion timestamp
- Updated date
- Updated time
- Updated timestamp
- Join date
- Join time
- Join timestamp
- UNIX Timestamp (Milliseconds)
- UNIX Timestamp (Seconds)
- **Categorical**
- Enum
- Product
- Source
- **URLs**
- Avatar Image URL
- Image URL
- URL
- **Other**
- Field containing JSON
- No semantic type
### Field type
You can use the Data Model page to edit field types for fields in your database. Use the **Type** dropdown menu to select from this [list of options](../users-guide/field-types.md).
In this same menu, you can also designate a column as the table's **primary key** or **foreign key**.
See the [users guide](../users-guide/field-types.md#list-of-metabase-field-types) for more on types and how they function in Metabase.
### Casting to a specific data type
......@@ -181,7 +103,7 @@ You can cast text in ISO8601 format and numbers representing Unix epoch to date,
To cast a field to a different type, click on the gears icon next to the field you want to cast. If the field is a number or text field, you may see an option to **Cast to a specific data type**, with a default option set to "Don't cast." Select the type you want to cast to, and you're good to go. Casting doesn't affect the original data type; just how Metabase interprets that field.
### Remapping column values
## Remapping column values
One thing that happens commonly in tables is that you'll have a **foreign key column**, like `Product ID`, with a bunch of ID values in it, when what you actually want to see most of the time is the **entity name**, like the `Product Title`. You might also have fields which contain coded values that you'd prefer to show up as translated or readable values in your tables and charts — like changing `0`, `1`, and `2` to `Female`, `Male`, and `Other`.
......@@ -199,7 +121,7 @@ Another option is **custom remapping**, which is currently only possible for num
![Remapping form](./images/remapping/custom-mapping.png)
### Picking the filter user interface for a column
## Picking the filter user interface for a column
Metabase will automatically try to pick the best kind of filter interface for each column based on that column's type, and the number of different values in it. Columns with only a few possible choices, like a `Gender` column, will display a dropdown list by default when filtering on them. Columns with more than 100 possible selections will show a search box with autocomplete.
......@@ -211,7 +133,7 @@ You can manually change the user interface for the filter to:
![Filter options](./images/filter-options.png)
### Column order
## Column order
Metabase will default to the column order native to the database.
......
docs/users-guide/01-what-is-metabase.md
+ 2
− 2
View file @ fa94477d
......@@ -50,6 +50,6 @@ To make a dashboard or pulse, click the plus (+) icon in the top-right of the ma
The search bar at the top of the screen helps you find tables, dashboards, collections, saved questions, metrics, segments, and pulses in an instant.
## A primer on databases
## Next: Exploring Metabase
To fully understand how to use Metabase, it’s useful to have at least a high-level understanding of databases, so we'll discuss [the basics of databases](02-database-basics.md) next.
Now that we've covered the basics of what Metabase is and can do, let's look at [dashboards and questions](03-basic-exploration.md) that your teammates have already made.
docs/users-guide/02-database-basics.md deleted 100644 → 0
+ 0
− 73
View file @ 0b43e4d8
# A Short Overview of Databases
Before you jump into working with Metabase, it's helpful to know a few key database terms.
## Tables
Fundamentally, databases are made up of one or more _tables_. Tables contain one or more _columns_ and one or more _rows_. A row is made up of _cells_, and each cell has a _value_ that corresponds to the column it falls under.
Here's an example of a table:
| Name | Age |
| ----- | --- |
| John | 25 |
| Jenny | 31 |
Here, the columns are `Name` and `Age`. The first row contains two cells, one with `John` and one with `25`, corresponding to the Name and Age columns, respectively.
## Columns
All the cells in a column contain the same type of information. For example, in the sample table above, the `Name` column contains names in each cell, while the `Age` column lists ages.
Columns are also sometimes interchangeably referred to as _fields_. Each field has a type that describes what kind of data is stored in the field.
## Keys
A primary key is a field in a table that uniquely identifies each row. For example, imagine a car reservation app where you can book a car in advance. The ID of the reservation could be the reservation number, and no two reservations would share the same reservation number, allowing each reservation to be uniquely identified by its reservation number.
**Example**
_Reservations Table_
| Reservation ID | Name | Age |
| -------------- | ----- | --- |
| 11 | John | 25 |
| 12 | Jenny | 31 |
In the above table, the `Reservation ID` field is the ID (primary key).
## Relationships
Tables can contain references to other tables, which establishes a relationship between them.
In our hypothetical car booking app’s database, we could have two tables: one for reservations (let's call it **Reservations**) and one for customers, (we'll call this one **Customers**).
To connect the reservation data to the corresponding customer data, you can use a _foreign key_. A foreign key is a special kind of field in a table that references the same column in a different table. Almost always, the field that the foreign key points to is the _ID_ or _primary key_ in the other table.
Using the same example, we could connect each reservation in the Reservations table to the corresponding customer that made the reservation by having the `Customer` column of the reservation contain the same value as the `ID` column of the customer who made the reservation.
**Reservations**
| Customer | Date | Car |
| -------- | ---------- | ------------ |
| 11 | 12/20/2015 | Toyota Camry |
| 12 | 1/2/2016 | Range Rover |
**Customers**
| ID | Name | Age |
| --- | ----- | --- |
| 11 | John | 25 |
| 12 | Jenny | 31 |
If we wanted to analyze our hypothetical app's database with Metabase, we could ask a question, like:
What's the average age of all customers who made reservations in February of 2015?
To do this, we’d open up the Reservation table, add a filter to only look at reservations between February 1 and February 28, 2015, and select `Average of…`. To select the average of Age specifically, we now put our foreign key to use and select Age from the _Customers_ table that our Reservations table references.
---
## Next: Asking questions
Now that we have a shared vocabulary and a basic understanding of databases, let's learn more about [exploring in Metabase](03-basic-exploration.md)
docs/users-guide/field-types.md 0 → 100644
+ 97
− 0
View file @ fa94477d
# Field types in Metabase
While data types indicate to a database how it should interpret the values in a field, __field types__ or __semantic types__ describe the _meaning_ of a field. For example, a column's data type could be ```type/text``` but the semantic type may be __Email__. Field types are just one example of metadata—information about data—that [Admins can change](../administration-guide/03-metadata-editing.md) in Metabase.
Field types dictate how Metabase displays its data, as well as the column’s special functionality, if any. By marking columns in a table as __Latitude__ and __Longitude__, Metabase can use the columns to create pin and heat maps. Similarly, designating a column as a __URL__ allows users to click on the link to visit that URL.
## List of Metabase Field Types
Metabase recognizes the following field types:
- **Overall Row**
- **Entity Key** – The field in this table that uniquely identifies each row. Could be a product ID, serial number, etc.
- **Entity Name** – Different from the entity key, the entity name represents what each row in the table *is*. For example, in a Users table, the User column might be the entity name.
- **Foreign Key** – The column in this table that (usually) refers to the primary key of another table in order to connect data from different tables that are related. For example, in a Products table, you might have a Customer ID field that points to a Customers table, where Customer ID is the primary key.
- **Common**
- Category
- Comment
- Description
- Title
- **Location**
- City
- Country
- Latitude
- Longitude
- State
- Zip Code
- **Financial**
- Cost
- Currency
- Discount
- Gross margin
- Income
- Price
- **Numeric**
- Quantity
- Score
- Share
- **Profile**
- Birthday
- Company
- Email
- Owner
- Subscription
- User
- **Date and Time**
- Cancelation date
- Cancelation time
- Cancelation timestamp
- Creation date
- Creation time
- Creation timestamp
- Deletion date
- Deletion time
- Deletion timestamp
- Updated date
- Updated time
- Updated timestamp
- Join date
- Join time
- Join timestamp
- UNIX Timestamp (Milliseconds)
- UNIX Timestamp (Seconds)
- **Categorical**
- **Enum** - An abbreviation for “enumerated type,” the value of an enum draws on a predefined list of options. An example of an enum would be a field for the months of the year. This list of twelve options is defined in makeup of the column, and no options outside this list would be valid.
- Product
- Source
- **URLs**
- Avatar Image URL
- Image URL
- URL
- **Other**
- Field containing JSON
- **No semantic type** – Used for fields that don't fall into any of the above field types.
## Using field types in Metabase
### X-rays
When you [X-ray](14-x-rays.md) a table, Metabase considers both the data type and the field type to display different charts that summarize that data.
### Field Filters
Knowing what field types are and how they work is helpful when using [field filters](/learn/sql-questions/field-filters.html), as you can only create field filters for [certain field types](./13-sql-parameters.md/#field-filter-compatible-types).
### Editing types in the Data Model page
If you're an administrator, you can edit field types using the [Data Model page](../administration-guide/03-metadata-editing.md) in the Admin Panel.
While data types themselves can't be edited in Metabase, admins can manually [cast data types](../administration-guide/03-metadata-editing.md/#casting-to-a-specific-data-type) to be read differently, like interpreting a numerical data type as a date format.
## Further Reading
- [Exploring data with Metabase's data browser](/learn/getting-started/data-browser.html).
- [The Data Model page: editing metadata](../administration-guide/03-metadata-editing.md).
- [Field Filters: create smart filter widgets for SQL questions](/learn/sql-questions/field-filters.html).
docs/users-guide/start.md
+ 1
− 1
View file @ fa94477d
......@@ -3,8 +3,8 @@
## Some basics
- [An overview of Metabase](01-what-is-metabase.md)
- [The basics of databases](02-database-basics.md)
- [Basic exploration in Metabase](03-basic-exploration.md)
- [Field types in Metabase](field-types.md)
- [Getting automatic insights with X-rays](14-x-rays.md)
## Asking questions with the query builder
......
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