Help

Each table on the left side of the screen is a list of one kind of thing, for example, customers, orders, or events. Select a table to edit it. The fields in each table are the columns for the data set.

Tables relate in two ways, and choosing between them is the main structural decision in a model. Something that belongs to one row is nested inside it, so each customer gets orders of their own. Something shared, that many rows across the model point at, stays a separate table with a Reference field pointing at it: one product catalog, drawn on by every cart. The test is whether the rows are owned by one parent or drawn from a common pool.

Most of the time one kind of thing belongs to another. An order belongs to a customer. A customer does not belong to anything. When that is true, you nest the order table under the customer table, so that it sits inside it. There are three ways: set “nested under” at the top of the order table, drag one table onto another, or use the + beside a table to add a new one already inside it. Once it is nested that control changes, and reads “Each customer has 2 to 8 orders” instead. The builder handles the rest.

The highlighted column is the one nesting adds for you. Every order carries the ID of the customer it belongs to, so the first two orders above are both Dana’s. You do not create that column or point anything at it. It appears on the order table as a column you cannot edit or remove, and it is what lets any tool you load the files into put the right orders beside the right customer.

Nesting also decides how many rows you get. A table at the top level has a row count you type in. A nested table does not: you say how many rows each parent should have, as a range, and the total follows from that. So you type 500 customers and “2 to 8 orders each”, and the order count works itself out.

Because it is a range rather than a fixed number, a nested table’s size is always an estimate. And a model’s total is every table added together, which is why it grows faster than it looks: adding 100 more customers here adds around 600 rows, not 100.

When the rows are shared rather than owned, do not nest. A product does not belong to one cart, and nesting products under carts would give every cart its own private copies of the catalog. Instead keep products as its own table at the top level and add a Reference field to the table that needs it. That column holds a real id from the table it points at, so the two join, and any number of tables can point at the same list.

The highlighted column looks like the one nesting adds, and holds the same kind of value, but you created it and you control it: which table it points at, whether some rows are far more popular than others, and whether the same row can be pointed at twice within one group, meaning within one parent row where this table is nested, or across the whole table where it is not. The one thing it cannot do is point at a nested table, because a nested table’s row count is only an estimate.

No date in a model is stored as a calendar date. Each one is stored as a distance from a single reference day, the as-of date: “90 days before”, “within the last two years”, “3 days after created_at”.

The As of section at the top of the rail sets that day, and there are two choices. Current date (“updated every time you generate”) means the reference day is whatever day it is when the rows are made, so the data is current every time and never needs revisiting. Fixed date (“stays the same every time you generate”) pins it to one date and keeps it there.

Whichever you choose is saved with the model, so every download of it uses that setting, wherever you start the download from.

Moving the as-of date moves the dates and nothing else. Ids, names, numbers, categories, addresses and row counts all stay exactly as they were. That is the part worth knowing if you demo from this data: regenerate next month and your script still points at the same records, with dates that make sense.

Generation is repeatable, not random: the same model and the same as-of day always produce the same rows. Adding a field or changing a row count does not reshuffle the values that were already there.

A date field is either a single moment or a range of time that rows are spread across. A range is the usual choice: a signup date somewhere in the last two years, rather than every customer signing up on the same afternoon.

The beginning and end dates of the range are built from four parts: a number (e.g. 30), a unit (e.g. days), a before or after selection, and where to count from (e.g. the as-of date for your model or another field’s date). For example: 30 days after the created_at date. You can also count from a date on the table this one is nested under, which is how a child row stays behind its parent.

Anchoring each date to the one before it is what keeps a chain in order at any as-of date. Nothing ships before it was placed, and no order predates the customer who made it, because the order is not written against a calendar at all.

There are three other controls. Spread decides where rows bunch up inside a range: evenly, toward the earlier end, or toward recent. Format chooses date only, date and time, or an ISO timestamp. And two checkboxes let a date sit in the future (due dates, upcoming events) or be earlier than the record it hangs off (a date of birth on a customer created last week). The future one only appears when the date could actually reach the future. If the whole range counts backwards from the as-of date, there is nothing for it to do, so it stays out of the way.

There is one thing to watch out for. If a date counts from a field that is sometimes empty, the rows where it is empty count from the as-of date instead. Keep a gated date and the date it counts from gated the same way.

An address is several columns that have to agree with each other, which no other field type has to do. Set up three separate fields for city, region and postal code and every row gets a place that does not exist: Portland, Texas, 02134.

So you set up one address, and it hands out the columns you asked for. All of them read the same record on each row, so they agree by construction.

Choosing “Place” adds the address immediately, along with four columns: street, city, region and postal code. Its settings panel opens beside them, and that is where you set which countries it draws from and in what mix, and tick the other parts you need: county, country, a one-line full address, and latitude and longitude. There is no separate setup step to finish, and no undo, so if you did not mean to add it, “Remove this address” takes every column back in one press.

Once added, each part is a normal field card. Rename it, reorder it, gate it, blank it, delete it. Deleting one leaves the rest coherent, because they read the shared record rather than reading each other. Deleting every part does not delete the address, though. It stays, making no columns until you tick one again. “Remove this address” is the only thing that removes it.

One thing is deliberately not solved: names do not match countries. A row in Germany can hold an American-sounding person.

Two controls sit on a field card and answer different questions. They sound similar, so it is worth knowing which one you want before you open either.

A field cannot depend on a field that depends on it, so the picker will not offer a choice that would make a loop.

Real data has holes in it, and software that has only ever been demoed against complete rows tends to fall over on the first empty one. Every field type except ID carries a “% blank” so you can put those holes in deliberately.

A blank is an absence, in whatever way the format has one: null in JSON, an empty cell in XLSX, an empty field in CSV. It is never the text “null” or an empty string standing in for a value somebody supplied.

“% blank” and “Only fill this in when” express different things and can be used together. A gate says the field does not apply to this row: an order that never shipped has no ship date. A blank says it applies and is missing: the customer has a phone number and you do not have it.

The dock at the bottom shows real generated rows from the table you have selected, not a mockup, and it updates as you edit. It shows a handful of rows however big the model is, so a large model stays responsive to type in.

There are four formats, and they do not all contain the same thing:

• XLSX gives you every table, one sheet each, with a type per column.
• JSON gives you every table, with real numbers, booleans and nulls.
• CSV gives you one table: the one you have selected. A CSV file cannot hold more than one, so if you need all of them, take XLSX, JSON or SQL, or download each table in turn.
• SQL gives you every table as insert statements, ready to load straight into a database. Pressing it opens two options: whether to include the statements that create the tables, and whether to empty them first. The second one deletes rows when you run the file, so it is off unless you tick it.

Every download generates the data again before writing the file, so a download is never a stale snapshot from earlier in the session. If the model’s as-of date is set to today, that means the file you just got is dated today, whichever page you started the download from. One thing that does differ by page: downloads from My models use the saved copy of a model, so unsaved changes you made in the builder are not in them. After it lands, a line in the dock tells you the filename and how many rows, and on a model with more than one table, which tables you got.

A table with no columns yet cannot be written as SQL, since there is nothing to insert, so it is left out of that file and the options tell you before you export. Every other format writes it as an empty table.

CSV has one quirk worth knowing about, and it is the format’s fault rather than ours. A CSV file cannot say what it contains, so it carries a marker that tells Excel on Windows to read it as UTF-8. Without it, accented names arrive mangled. Anything that is not Excel ignores the marker.

A model bigger than your plan allows can still be built and previewed, but it cannot be saved or downloaded until it is smaller. The dock says so, and your Account page shows where each of your models stands.