Bringing data in
Upload a file
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,.txtor.xlsxfile. For an.xlsxworkbook, 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.
The steps
- 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.
- 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
newis 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.
- 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
- 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.
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:
- Choose the file. The same files and limits apply as for the first upload.
- 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.
- 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 or Fetch connector instead.
To delete an upload table and its connector together, see Tables.
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. |