# Mappings

What a mapping is, how the rows of a keyed table become items in your model, how links are made, and what the Point of sale mapping does.

A mapping turns the rows of a keyed table into **items** in your organisation's model. Your model is the set of things Mestra knows about: places, screens and the items that belong to them. A decision can read the items that belong to a screen's place, so a mapping is how your table data reaches a decision. See [The decision language](https://withmestra.com/docs/topos/decision-language/#what-a-decision-receives).

## What a mapping says

A mapping is a small document that reads one keyed table.

| Field         | Meaning                                                                                                                                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `dataset`     | The table it reads. It must keep the latest state of each row, so it must be a keyed table.                                                                                                                                    |
| `type`        | The type of item it makes, such as `menu_item`. 1 to 64 lower-case letters and underscores. A type that another Mestra system fills can't be used.                                                                             |
| `name_column` | The column that gives each item its name.                                                                                                                                                                                      |
| `attrs`       | Which columns become which attributes, as `{"price_minor": "price"}`. An attribute name uses lower-case letters, digits and underscores.                                                                                       |
| `links`       | How an item links to another. Each link has `rel` (the relation, such as `at`), `to_type` (the type to link to), `match_attr` (the attribute to look at on that type) and `column` (the column holding the value to look for). |

Mestra saves a mapping whole or not at all, and lists every problem with a path such as `attrs.price_minor` or `links[0].rel`.

## How rows become items

- Each live row becomes one item. The item's name comes from the `name_column`. Its attributes come from `attrs`.
- When a row changes, its item changes. When a row goes (a **Replace everything** run left it out), its item is archived. If the row comes back, so does the item.
- A link looks up the value of its column among the active items of `to_type`, by their `match_attr`. Exactly one match makes the link. None, or more than one, makes no link. Mestra never guesses between two.
- Deleting a mapping forgets it. The items it made stay in your model, with their links, and stop updating.
- Mapping happens as data lands. If it fails because of the data, the payload is kept with a `routing_failed` error that names the mapping, and nothing is written to the table.

## The Point of sale mapping

Adding the [Point of sale](https://withmestra.com/docs/topos/templates/) connector adds a mapping called **Menu items**.

|            |                                                                                                   |
| ---------- | ------------------------------------------------------------------------------------------------- |
| Reads      | **Menu items**                                                                                    |
| Makes      | `menu_item` items, named by `name`                                                                |
| Attributes | `item_id`, `location`, `price_minor` (from `price`), `currency`, `category`, `available`, `stock` |
| Link       | `at` the `place` whose `code` equals the item's `location`                                        |

So an item at `queen-st` is linked to the place whose code is `queen-st`. A screen at that place can read it. Money stays whole cents: the attribute is `price_minor`, and `money(price_minor, currency)` in a decision writes it as `$4.50`.

## See what is downstream

A connector's page shows **Downstream**: its tables, the mappings that read them, the model types those fill, and the decisions that read them. Use it to see what changes when a connector changes.

## Make and change a mapping

Mappings have their own page, **Mappings**, in the Topos menu (the **Data** page links to it too). Everyone in the organisation can see the mappings; an owner makes and changes them.

1. Select **New mapping**.
2. Give it a **Mapping name**. The key fills in from the name.
3. Choose the **Table** it reads (only keyed tables are offered), the **Item type**, and the **Name column**.
4. Under **Attributes**, select **Add an attribute** for each one: the attribute's name and the column that fills it.
5. Under **Links**, select **Add a link** for each one: the relation, the type it links to, the attribute to match on that type, and the column holding the value to look for.
6. Select **Save mapping**. If something is wrong, the message shows beside the field.

Once a mapping is saved, its table and item type are fixed. To read another table or make another type, make a new mapping.

From a mapping's menu, or its page:

- **Rebuild** maps every live row of the table again, and says how many rows it mapped.
- **Delete** forgets the mapping. The items it made stay in your model, with their links, and stop updating.

The Point of sale connector adds its own mapping, which you can open and change like any other.
