# Tables

The two kinds of table in Topos, the five column types, folders, and how to browse, filter and sort a table.

A table is a set of typed rows, such as your menu or your sales. Tables live on the **Data** page. A connector builds and fills a table. You can't type rows into a table by hand, and the table viewer only reads.

Some pages call a table a dataset. They are the same thing. A table has a **name** and a **key**. The key is how Mestra refers to it, and it uses lower-case letters, digits and underscores, starts with a letter, and is at most 63 characters. The key `new` is reserved.

## Kinds of table

A connector's route decides which kind of table it fills. See [Routes, modes and columns](https://withmestra.com/docs/topos/routes-and-modes/).

| Kind            | What a row is                                                                           | Made by                                                       | How it changes                                                                                                                                   |
| --------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Keyed table** | The latest state of one thing, found by its key, such as one menu item at one location. | A route in **Add and update** or **Replace everything** mode. | A row is added when its key is new, and updated when it changes. With **Replace everything**, a row missing from a full snapshot is marked gone. |
| **Log table**   | One event, such as one sold line, with the time it happened.                            | A route in append mode, which needs a time column.            | An event is added once. An event with a key that is already stored is left alone.                                                                |

A keyed table with no chosen key column keys each row by its position in the file (the `row` column).

A **gone** row is not deleted. Mestra marks it gone, the viewer stops listing it, and it isn't counted. It comes back if a later run sends it again.

## Column types

Each column has one type. When a connector reads a record, it checks every value against the column's type and refuses a row that doesn't fit. The refusal names the row, the field and a reason. See [Errors and refusals](https://withmestra.com/docs/topos/troubleshooting/#why-a-row-is-refused).

| Type (as shown) | What it holds                                  | What is accepted                                                                                                        |
| --------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Text**        | Words. Up to 500 characters.                   | A string, or a number, which is kept as its digits. Spaces at the ends are trimmed. An empty string counts as no value. |
| **Number**      | A whole or decimal number.                     | A number, or a string that holds one.                                                                                   |
| **Money**       | An amount in whole minor units, such as cents. | A whole number, or a string of digits, including a negative one. A decimal such as `24.50` is refused.                  |
| **True/false**  | Yes or no.                                     | `true` or `false`, as a JSON boolean or as the text `true` or `false`.                                                  |
| **Time**        | A moment.                                      | A string in RFC 3339 with an offset, such as `2026-11-14T09:30:00+11:00`. It is stored in UTC.                          |

Money is stored in whole cents: `2400` means $24.00. Each money column has a three-letter upper-case currency, such as `AUD`, either typed on the column or taken from a column called `currency` or `<column>_currency`. Mestra never converts between currencies.

A column can be **Required**. A row with no value in a required column is refused with the reason `missing`. For every type except text, a blank cell counts as no value.

When you upload a file, Mestra names each column from its header. The name is lower case, every run of other characters becomes one `_`, a leading digit gets `c_` in front, and an empty header becomes `column`. Repeated names get `_2`, `_3` and so on.

## Folders

Folders keep the **Data** page tidy. Select a folder to open it. The path to it shows above the list as a trail you can select.

An owner can:

- select **New folder** to make a folder in the folder you are in. A folder name is 1 to 80 characters. It must be different from every other folder name in the same place, whatever the case. Folders can nest as deep as you like.
- use the menu beside a folder to **Rename**, **Move to…** or **Delete** it. A folder can't go inside itself or a folder under it. **Delete** works only on an empty folder. Otherwise the page says "Empty the folder first."
- use the menu beside a table, or **Move to…** on its page, to file it in a folder. Moving a table changes only where it is shown. Its key and the connectors that fill it don't change.

The list shows each row's **Name**, **Fed by** (the connector that fills it, or "Not fed by a connector"), **Rows** and **Updated**. A folder shows how many items it holds. A table that has never received data shows "Not updated yet".

Uploading from inside a folder files the new table there.

## The table viewer

Select a table to open its viewer. The title shows the row count. The toolbar has these controls.

| Control                                    | What it does                                                                                                                                       |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Datasets** (the panel icon)              | Shows or hides a list of every table in its folders, so the next table is one click away.                                                          |
| **Filters**                                | Keeps only rows that match every filter you add.                                                                                                   |
| **Sort**                                   | Orders the rows by a column. Choose **Ascending**, **Descending** or **No sort**. Select a column heading to cycle ascending, descending and none. |
| **Columns**                                | Shows or hides columns. **Show all** brings them all back.                                                                                         |
| The range, for example "1 to 500 of 1,204" | Where you are in the matching rows.                                                                                                                |
| **Previous page**, **Next page**           | Moves through the pages.                                                                                                                           |
| **Rows per page**                          | 100, 500 or 1,000 rows. The default is 500.                                                                                                        |
| **Refresh**                                | Reads the table again.                                                                                                                             |

Without a sort, a keyed table is ordered by row key and a log table shows its newest events first. Sorting uses the column's type: numbers and money by value, times in order, true/false with false first, text in the database's usual order. Rows with no value in the sorted column come last.

Select a row to open **Row details** at the right. It lists every column with its type, a **Copy** button for each value, and **Copy row as JSON**. Use **Previous row** and **Next row**, or the up and down arrow keys, to move between rows. Escape closes it.

### Filters

Add a filter by choosing a column, a test and a value. You can add as many filters as you like. A row must match all of them. The tests depend on the column's type.

| Column type                     | Tests                                                                                                                            |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Text**                        | **is**, **is not**, **contains**, **starts with**, **is empty**, **is not empty**. **contains** and **starts with** ignore case. |
| **Number**, **Money**, **Time** | **is**, **is not**, **greater than**, **at least**, **less than**, **at most**, **is empty**, **is not empty**.                  |
| **True/false**                  | **is**, **is empty**, **is not empty**.                                                                                          |

- **is not** also matches rows with no value.
- For money, enter a whole number of cents.
- For a time, enter a full RFC 3339 time or a date such as `2026-11-14`. A date means the start of that day in UTC. With **is** and **is not**, a date means any time on that UTC day.

The filters, the sort and the page size are in the page address, so you can copy the address to share a view. Which columns you hide and how wide you drag them are remembered in your browser only.

If a filter can't be applied, the viewer marks it and explains why, for example an unknown column or a value that doesn't read as the column's type. If a view takes too long to read, it says "That view took too long to read. Add a filter to narrow it, or sort by another column." Select **Reset the view** to clear the sort and filters.

## Delete a table

An owner can select **Delete** on a table that came from an upload or a connector. Its rows go with it, and what has landed is kept. This can't be undone.

- A table that a connector still writes to can't be deleted. The page says which connector fills it. Delete the connector, or change it so it stops writing there, and then delete the table. A table made by a file upload is deleted together with its upload connector.
- A table that belongs to a [template](https://withmestra.com/docs/topos/templates/) can't be deleted, and its columns are fixed.
