Datasets & schema deep-dive

This guide goes one level below the datasets overview: how the typed model actually works, what the limits are, and every path data takes in and out of a dataset.

Display names vs field ids

A dataset field has two names, and the distinction matters everywhere:

• The display name is what you type in the schema dialog and what table headers and record editors show. Rename it freely.
• The reference id is the stable key. It auto-fills from the display name when you create the field (Visit frequency → visit_frequency), and the schema dialog lets you edit it right there to set your own — for example a short, code-friendly key that differs from the label. Once the field is created the id is fixed and never changes. Records store values keyed by reference id — it's the key you use in {{item.reference_id}} bindings and what a form field's Maps to schema field picker stores.

The schema dialog shows both — each field row reads Display name · fieldId. The Reference ID input sits directly under Display name in the field editor; it follows the name as you type until you edit it, then keeps your value. The dataset itself likewise has a Singular name and a Plural name; the plural is the dataset's display name — the label its entry shows in "Write to dataset" and repeatable pickers (which store the dataset's id underneath, so renames never break the bindings).

Naming & describing fields

Open the schema dialog and Edit a field to change how it presents:

• Display name — rename it freely, any time. The field id underneath never changes, so {{item.fieldId}} bindings, form field mappings, and stored records are all unaffected by a rename.
• Description — a free-form note on what the field is for. When set, it follows the field around the console:
  • the schema dialog's field list shows it under the Display name · fieldId line,
  • the records table shows it as a tooltip on the column header,
  • the record editor shows it as the input's helper text (a validation error takes its place while present).

Both are trimmed on save, and a blank description is dropped rather than stored. Descriptions are console-facing documentation only — they never render on the published site.

The typed model

A dataset's model is a map of field definitions plus a display order. Each field definition carries its type, whether it's Required, an optional Description and Default value, validation (regex pattern, min/max length, an enum of Options), and — for reference fields — the target dataset and delete behavior.

The types you can author:

Type	Holds
Text	Strings; optionally pattern-, length-, or enum-constrained
Boolean	true / false
Integer	Whole numbers
Number	Floating-point numbers
Date & time	Timestamps
Coordinates	Latitude / longitude pairs
List	Ordered arrays
Reference	A link to a record in another dataset — see relations

Plugins can register custom field types, which appear in the type picker suffixed with the plugin id. Records are validated and coerced against the model on every server-side write.

Legacy datasets

Datasets created before typed models (a flat comma-separated field list) still work: the runtime derives an effective model where every column is an optional text field whose id equals the column name. Open the schema dialog and re-type the fields to upgrade — ids are preserved.

Reference fields configure what happens when a referenced document is deleted: Clear the reference (default) or Block the delete. Tick Allow multiple for many-to-many relations.

Record quotas per plan

Dataset counts and records per dataset are entitlements of your organization's plan:

Plan	Datasets	Records per dataset
Free	— (no data store)	—
Starter	3	1,000
Pro	15	10,000
Business	100	100,000
Advanced	500	1,000,000

• Creating datasets on Free is rejected with "Datasets require a Starter plan or higher."
• Hitting the record cap surfaces "Record limit reached — see Billing to upgrade" in the console, and imports that would overflow are refused with the exact slot math.
• Form submissions never fail on quota — if the dataset is full the record write is skipped silently, but the inbox copy is always kept.
• Add-ons raise the dataset count beyond the base allowance, up to a hard per-plan ceiling.

Import & export

The Data page round-trips CSV and JSON:

• Export — the CSV and JSON toolbar buttons download the loaded records with one column per model field.
• Import — the Import records dialog takes pasted CSV (with a header row) or a JSON array. Columns match by field id first, then case-insensitively by display name; rows are validated against the model on the way in.
• Upsert — pick a Match on field (upsert) key (say, an email field) and matching rows update records in place instead of appending duplicates. Only genuinely new rows count against the record quota.

See import & export for round-trip tips.

Repeatables

Containers (like a Stack) have a Repeat over dataset property. Set it and the container's children become an item template, rendered once per record on the published site:

1. Select the container and set Repeat over dataset to your dataset (stored by id, so renames never break it).
2. Inside the children, reference record values with {{item.fieldId}} — e.g. {{item.name}}, {{item.price}}.
3. Reference fields support one hop: {{item.author.name}} resolves the referenced record's field.
4. Optionally set a Repeat limit, a Repeat filter (price <= 20, operators ==, !=, >, >=, <, <=, contains), and a Repeat sort (price desc).

The canvas doesn't expand rows while designing — it shows a repeat notice on the container ("children render once per record on the live site") so you design a single template. Up to 100 records render per repeatable.

Everything that writes records

Writer	How it behaves
Console — Add record / record editor	Typed inputs per field; validated and quota-checked.
Console — Import records	Bulk CSV/JSON with validation, upsert, and quota math.
Forms — the Form element's Write to dataset	Appends on each submission. The dataset is bound by id (a dropdown; legacy forms still match by name) and each form field can map to a schema field by id via Maps to schema field, with name-matching as the fallback — so renames never lose data. Best-effort (quota-full submissions keep only the inbox copy). See the survey guide.
Automations — the Write to a dataset step	Appends a record from a workflow/action run.
Automations — the Update a dataset record step	Updates a matching record (by email) or appends when none matches.

Automation steps live in the Do list of an action — see workflows & actions.

Deleting a dataset

Delete removes the dataset and every record in it, permanently — the confirmation tells you how many documents go with it. There is no undo and no retention window, so export first (CSV or JSON) if you might want the rows back. Deleting a single record from the table leaves the dataset itself alone.

The same applies to the two other things that hold records inside them: deleting an email list takes its enrolled subscribers, and deleting a collection takes the content entries published under it.

Related

• Build & publish a survey
• Datasets overview
• Build a data model
• Relations
• Bindings, variables & functions