# Databases

> A database is a live collection of the notes that match its conditions. Each note is a row, its properties are the columns, and nothing is copied.

Source: https://terramd.io/docs/databases

In Terra, a *database* is a set of conditions, such as "every note in `projects/field-guide`" or "every note tagged `#recipe`", and the live list of notes that match them. Each note is a row and its [properties](https://terramd.io/docs/properties) are the columns. Nothing is copied: edit a cell and you've edited the note; move a note out of the folder and it leaves the database. A note belongs to every database whose conditions it matches.

If you know Obsidian Bases, it's the same idea. Unlike a Notion database, the rows aren't stored inside the database: they're ordinary Markdown notes in your folders. For a worked example, see [Run a project](https://terramd.io/docs/project-suite).

![Terra's sidebar lists All notes, Tasks, Calendar and Sprouts under System, then Inbox, Today, Favorites, Trash, References and Links under Databases, and Field guide launch under User. The Field guide launch table shows ten notes with status, owner, start, due and effort columns.](https://terramd.io/docs/shots/db-sidebar.webp "Built-in databases sit under System and Databases; the ones you make are listed under User. This one collects every note in a project folder.")

## How a database works

| Part | What it is | Where you change it |
| --- | --- | --- |
| Conditions | The rule for which notes belong: a folder, a tag, a property value and so on | **View preferences › Database** |
| Rows | The notes that match, kept up to date as your notes change | In the notes themselves |
| Columns | The notes' properties, plus any [computed properties](https://terramd.io/docs/formulas-threads-and-gathers) you add | The table header, or a note's properties |
| [Views](https://terramd.io/docs/views-and-layouts) | Saved ways to look at the rows: a table, a board, a calendar, a chart | The view menu in the database's header |

A database you make is one small file, `.terra/databases/<id>.json` in your Library, holding its name, conditions and views. Your notes stay where they are. Conditions skip notes in the Trash; only **Trash** shows those.

## Built-in databases

Every Library comes with these. You can give each one its own views, pin it to the rail or change its icon, but you can't rename or delete it. To tidy the sidebar, right-click one and choose **Hide**; **Hidden** in the same menu brings it back.

| Database | Sidebar section | What it collects |
| --- | --- | --- |
| **All notes** | System | Every note in the Library |
| **Tasks** | System | Every checkbox task in your notes, as a board by status. Its rows are tasks, not notes. See [Tasks](https://terramd.io/docs/tasks). |
| **Calendar** | System | Notes placed on a calendar by date, with task due dates and events from connected calendars. See [Calendar](https://terramd.io/docs/calendar). |
| **Sprouts** | System | Every [Sprout](https://terramd.io/docs/sprouts) in your notes, as a board grouped by kind |
| **Inbox** | Databases | Notes in the `Inbox` folder, where new notes and captures land |
| **Today** | Databases | Notes edited today |
| **Favorites** | Databases | Notes tagged `#favorite` |
| **Trash** | Databases | Deleted notes, waiting in the `Trash` folder |
| **References** | Databases | Notes with bibliographic details, such as the papers and books you cite |
| **Links** | Databases | Web pages you've saved |

**Graph** in the System section is a view of All notes. **Templates** and **Ask** sit there too, but they aren't databases. **Today** starts its day at midnight UTC, so west of Greenwich it turns over during your evening.

### Folders, tags and options open as databases

Click a folder under **Folders** and it opens as a database of the notes in that folder and its subfolders, with saved views like any other: a folder can be a board or a calendar. Two more things open the same way:

- A `#tag` in a note: click it to open its tag page, every note with that tag.
- An option of a select or status property: in **Tools › Property Manager…**, click the option and choose **Open database** to see every note that has it.

You can't change what these collect, and [computed properties](https://terramd.io/docs/formulas-threads-and-gathers) need a database you made.

## Make a database

1. In the sidebar, point at **Databases** and click **+** (**New database**).
2. Type a name.
3. Click **+** (**Add condition**) and build a condition from a field, a test and a value, such as **Folder** · **starts with** · `projects/field-guide`.
4. Add more conditions if you need them. Once there are two, click the **And** beside them to switch to **Or** or **Not**. Click **{ }** (**Add group**) for a nested set.
5. Click **Save**, or press <kbd>Return</kbd> in the name field.

![The New database popover named Field guide launch, with two conditions joined by Or: Folder starts with projects/field-guide, and tags contains field-guide.](https://terramd.io/docs/shots/db-new-database.webp "With Or, a note belongs if it matches either condition: it's in the project folder, or it's tagged field-guide.")

The database opens as a table with **View preferences** beside it, ready for its first [view](https://terramd.io/docs/views-and-layouts), and it's listed under **Databases › User**. A database with no conditions collects every note.

**File › New Database** and **New… › New database** in the toolbar skip the popover. They make a database called *Untitled* that collects every note; rename it from the sidebar and add conditions on its **Database** tab.

Conditions can use **Title**, **Status**, **Tags**, **Folder**, **Type**, **Source**, **Updated**, **Created**, every property in your Library, and **Note Body**, the text of the note. The tests depend on the field's type; [Filter, sort and group](https://terramd.io/docs/filter-sort-and-group#tests-by-property-type) lists them. Good to know:

- Tests ignore capitals.
- A note's **Folder** is the folder that holds it, such as `projects/field-guide`. **is** matches that folder only; **starts with** takes in its subfolders too. Notes at the top of the Library have no folder.
- **Note Body** reads every note's text, so it's the slowest test. Terra reads at most 5,000 notes for it.

## Change what a database collects

Open the database, click **View preferences** at the right end of its header, and choose the **Database** tab.

![View preferences open on the Database tab: Match by Filter, one condition Folder starts with projects/field-guide, and the line 10 notes · 4 ms.](https://terramd.io/docs/shots/db-database-tab.webp "The Database tab holds the conditions. The line under them counts the notes that match and how long the match took.")

- **Match by** switches between **Filter**, the conditions, and **SQL**, a `SELECT` statement that picks the notes. See [Queries](https://terramd.io/docs/queries#make-a-database-from-sql).
- Changes save themselves after a moment. They aren't part of **Save view**.
- These conditions decide which notes belong. A view's **Filters** only hide rows in that one view; see [Filter, sort and group](https://terramd.io/docs/filter-sort-and-group).

The **Database** tab appears only on databases you made. Built-ins and folders keep their fixed rules.

## Child databases

Some built-ins can hold databases of their own: a narrower slice that opens like its parent and keeps its own views.

1. Right-click **Tasks**, **Calendar** or **Sprouts** under System, or **Links** or **References** under Databases.
2. Choose the first item: **New task database**, **New calendar database**, **New sprout database**, **New link database** or **New reference database**.
3. Type a **Database name** and click **Create**. The new database sits under its parent in the sidebar.

![The right-click menu on Links: New link database, New note, New from template…, Pin to rail, Change icon and Hide.](https://terramd.io/docs/shots/db-child-menu.webp "Built-ins that take children offer them as the first item of their right-click menu.")

- A child of **Calendar**, **Links** or **References** starts with all of its parent's notes. Narrow it with conditions on its **Database** tab: a *To read* child of Links that keeps pages tagged `#to-read`, for example.
- A child of **Tasks** or **Sprouts** opens as a board. Pick the notes it reads with **Sources** in its header. See [Tasks](https://terramd.io/docs/tasks).
- Children go one level deep, and databases you make can't have children.

**Favorites** works differently. Right-click it and choose **New favorites collection** for a hand-picked list instead of a rule, then add notes from a note's right-click **Favorite** menu. Collections can hold collections.

## Add a note to a database

To add a note you already have, give it what the database collects: move it into the folder, add the tag or set the property. It appears straight away.

To start a new note from a database:

- Point at a database you made in the sidebar and click **New note here**, or right-click it and choose **New note**.
- On a Board view, click **+ Add note** at the foot of a column. The note takes that column's value.

| Starting from | The new note goes to |
| --- | --- |
| A folder | That folder |
| A database you made | Your `Inbox` folder, with the column's value if you used a board |

> [!WARNING] A new note can miss the database you started it from
> Terra doesn't fill in your conditions for you. If the database collects a folder, a note made from it waits in `Inbox` and stays out of the database until you move it into that folder or give it the tag or property the conditions ask for. To add work to a folder-based database, use **New note here** on the folder itself.

## Rename or delete a database

Right-click a database you made and choose **Rename** (type the new **Database name**, then click **Rename**) or **Delete**. Deleting asks first and reminds you: "Notes are kept; only the database is removed." Deleting a database's last view deletes the database too, with an **Undo** in the message that follows. Built-ins can only be hidden.

## Put a database in a note

A database can sit inside any note, such as a weekly review, a project page or a [dashboard](https://terramd.io/docs/dashboards), and it stays live there.

1. On an empty line, type `/database` and press <kbd>Return</kbd>.
2. In **Insert database**, pick a database, or click **New database** to make one.

![A note with a sentence followed by an embedded database: the All work header with its view menu and controls, then a table of field-guide work items with status, owner and due.](https://terramd.io/docs/shots/db-embed.webp "A database inside a note, with the same header as the database itself.")

The block is the database, not a copy: change a status in it and the note changes; change the view's filters or sorting and the database's view changes too. In the note's file, the block is one line that points at the database by its id:

```markdown
Where the launch stands on Friday. The table below is the live database, not a copy.

<!-- terra:inline-db eyJkYXRhYmFzZUlkIjoiMDFKUThaQjRLMk03WDlUM1I1VjZXOFkwQzEiLCJtb2RlIjoibGlua2VkIiwidmlld092ZXJyaWRlIjpudWxsfQ== -->
```

Other Markdown apps, Obsidian included, show nothing for that comment. If the database is deleted, the block reads **Database not found** with **Pick another** and **Remove**.

## Related

- [Views and layouts](https://terramd.io/docs/views-and-layouts) — tables, boards, calendars, timelines and charts of the same notes.
- [Filter, sort and group](https://terramd.io/docs/filter-sort-and-group) — every test, sort and grouping a view can use.
- [Properties](https://terramd.io/docs/properties) — the values that become a database's columns.
- [Run a project with boards, timelines and burndowns](https://terramd.io/docs/project-suite) — a database built end to end.