# Upload a file

Turn a spreadsheet or CSV file into a table. Accepted files, limits, how columns are named and typed, and what the result means.

An upload turns a spreadsheet or CSV file into a table. It is the quickest way to get data into Topos. An owner does it from the **Data** page.

## What you can upload

- A `.csv`, `.tsv`, `.txt` or `.xlsx` file. For an `.xlsx` workbook, Mestra reads the first sheet.
- Up to 100 MiB.
- Up to 1,000,000 rows. If the file has more, Mestra reads the first 1,000,000 and says "This file has more rows than Mestra reads from one file. The first 1,000,000 were read."
- Up to 50 columns. If an Excel file has more, Mestra says "This file has more columns than Mestra reads from one file."
- A CSV that isn't valid UTF-8 is read as Windows-1252.
- If some rows have more cells than the header, Mestra leaves the extra cells out and says "Some rows have more cells than the header; the extra cells were left out."
- One row can be at most 4 MiB.

Mestra masks card numbers before it keeps the file. See [Send data to Mestra](https://withmestra.com/docs/topos/send-data/#what-mestra-keeps).

## The steps

1. **Choose a file.** On **Data**, select **Upload a file** (inside a folder, the table is filed in that folder). Drop the file on the drop zone or choose it. Mestra reads it and keeps it, sealed, while you decide. A file you don't finish with is kept for a day. After that, Mestra says "That upload has expired. Choose the file again." **Cancel** discards it at once.
2. **Shape it.** Check what Mestra read.
   - **Dataset name** is up to 80 characters. **Dataset key** fills in from the name, in lower case with underscores. You can change it. It must start with a lower-case letter and use lower-case letters, digits and underscores, up to 63 characters. The key `new` is reserved. If a table or connector already has the key, Mestra says so and you choose another.
   - For each column, **Keep** it or leave it out, choose its **Type**, and choose which one is the **Key**: the column that identifies a row. With **No key: use the row number**, a row is identified by its place in the file.
   - Under **When the file is uploaded again**, choose **Add and update** or **Replace everything**.
   - For a **Money** column, enter a three-letter currency such as `AUD`. Money is stored in whole cents: 2400 is $24.00.
   - The first rows of the file show under the headings, so you can check the types.
3. **Read what happened.** **Create dataset** makes the table and a connector with the same key, then lands the file. The result shows four counts.

| Count         | Meaning                                                           |
| ------------- | ----------------------------------------------------------------- |
| **Applied**   | Rows added or changed.                                            |
| **Unchanged** | Rows that were already stored the same.                           |
| **Gone**      | Rows marked gone. Only a **Replace everything** upload does this. |
| **Refused**   | Rows that didn't fit.                                             |

**Refused rows** lists the first 10, as "Row 4, price: not_minor_units", and how many more there were. Row numbers count the file's rows from 1. The reasons are in [Errors and refusals](https://withmestra.com/docs/topos/troubleshooting/#why-a-row-is-refused).

## How columns are named and typed

Mestra names each column from its header: 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.

Mestra guesses each column's type from its cells. A column is **Number**, **True/false** or **Time** only if every filled cell fits. Otherwise it is **Text**. An empty cell says nothing. A column with no filled cells is **Text**. A number with a leading zero, such as `007` or `0412345678`, is treated as text, because it is a code. **Time** needs RFC 3339 with an offset, such as `2026-11-14T09:30:00Z`. Mestra never guesses **Money**. Change a price column to **Money** yourself and give it a currency.

You can change any guess. A cell that doesn't fit its column's type refuses its row.

## After the upload

The new table shows on **Data**, with **Fed by** set to **Upload**. The connector shows on **Ingest** with the type **Upload** and the schedule **By hand**. You can't edit an upload connector.

## Upload a newer file

To bring an upload table up to date, an owner selects **Upload a newer file** on the table's page or on its connector's page. There are three steps:

1. **Choose the file.** The same files and limits apply as for the first upload.
2. **Check what Mestra read.** The first rows show under the headings, with a reminder of what the table does with a new file: **Replace everything** marks a row that is not in the file as gone; **Add and update** adds and changes rows and leaves the others alone. The table's columns and types stay as they are.
3. **Read what happened.** The same four counts show as for the first upload, with any refused rows.

To keep a table fresh without uploading by hand, use a [Receive](https://withmestra.com/docs/topos/send-data/) or [Fetch](https://withmestra.com/docs/topos/fetch-data/) connector instead.

To delete an upload table and its connector together, see [Tables](https://withmestra.com/docs/topos/tables/#delete-a-table).

## When an upload is refused

| What you see                                         | Meaning and fix                                                                             |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| The file is over 100 MiB (`too_large`)               | Split the file.                                                                             |
| One row is too long (`row_too_large`)                | A single row is longer than 4 MiB. Shorten it.                                              |
| Not a CSV file or an .xlsx spreadsheet (`file_kind`) | Use `.csv`, `.tsv`, `.txt` or `.xlsx`.                                                      |
| The CSV is not valid CSV (`unreadable`)              | The message names the line where it stopped. Fix it and upload again.                       |
| No file (`bad_body`)                                 | The request had no file.                                                                    |
| Busy (`429` with `Retry-After`)                      | Mestra can't take the file just now. Nothing was stored. Try again after the seconds given. |
| `key_taken`                                          | A table or connector already has that key. Choose another key.                              |
| `reserved`                                           | The key belongs to a template. Choose another key.                                          |
| `unknown_upload`                                     | The file expired or was discarded. Choose it again.                                         |
| `routing_failed`                                     | Nothing was made and the file is still kept. Try again.                                     |
