Design columns and data shapes

Name data source columns and choose how each value is stored, so your software can sort, filter, and match records correctly.

A data source is a table of data with named columns and one row per record. Choose your column names and the form of each value before you build, so your software can sort, filter, and match records correctly.

Before you start

This page applies to data sources in Fliplet Studio, and to the Fliplet JavaScript SDK for changes made from code. You need a data source to work in. To make one, see Create and configure a Data Source. [UNVERIFIED: the role and plan needed to change columns]

Fliplet doesn't check values against a column for you:

The column list holds names only, so a column has no type and no required setting.
Each row stores its values as one JSON object, keyed by column name.
Other column settings, such as unique, live in the data source's definition.
Each row has its own id and order outside the columns, so you don't need an ID column to identify a row.

Choose column names

Follow these rules before you type a name:

Case matters. Email and email are two different columns.
Use plain characters. To sort by a column through the API, its name can use only the letters A to Z, numbers, spaces, hyphens, and underscores. Other characters, including accented letters, give the error Invalid order column name.
Don't use a dot. A dot also breaks API sorting, because the name is cut at the dot: First.Name is read as First.
Stay under the limit. A column name is stored with at most 255 characters, and a longer name is cut to 255.

Avoid these names for your own data, because they're left out when Fliplet clones a data source:

flUserId, flUserToken
code, codeCreatedAt, verifiedAt
signInCode, signInToken, signInSessionId, signInAttempts, signInCreatedAt

Add a column

The grid on Entries keeps column names in row 1, and it handles names in these ways:

A repeated name gets a number added, such as Email(1), because the grid doesn't keep two columns with the same name.
Clearing a name gives the column a placeholder name in the form Column (1).
Typing a value under a column with no name also gives that column a placeholder name.
A column with a placeholder name and no values is removed on save.

To add a column:

Select Data Sources in the project sidebar.
Select the data source's name.
On Entries, select the first empty cell in row 1.
Type the column name.
Press Enter to confirm the name. [UNVERIFIED: Studio UI, typing in the grid wasn't tried in the live check]
Select Save changes. [UNVERIFIED: Studio UI, the label on Entries is read from code because it only shows after a change]

To put a column between others, use Insert column before or Insert column after in the toolbar.

Choose a shape for each value

A column can hold a different kind of value in each row, so the way you enter a value decides how it behaves.

Value	What to enter in the grid	How it's stored
Text	The text	Text, with leading and trailing spaces removed
Number	Digits only, such as `1200` or `-12.5`	Text that API sorting treats as a number
Yes or no	`true` or `false` in lowercase	A real true or false value, while `True` stays text
List	A JSON list, such as `["Red","Blue"]`	A real list, or text if the JSON isn't valid
Object	A JSON object, such as `{"city":"Leeds"}`	A real object, or text if the JSON isn't valid
Date	A year-first date, such as `2026-11-05`	Text that sorts by date
Nothing	Leave the cell blank	No value for that column in that row

undefined, NaN, and null typed in a cell count as blank.

Numbers

API sorting treats a value as a number only when it's digits, with an optional leading minus and decimal point. So 1,200 and £1200 sort as text. Numeric values and text values form two separate groups in a sort.

Filter comparisons such as > against a number leave out rows whose value isn't numeric.

Lists

The oneof filter matches any text item of a JSON list, and any part of comma-separated text. The match is case-sensitive.

Dates

Dates aren't numbers, so an API sort orders them as text. 2026-11-05 sorts by date and 05/11/2026 doesn't.

Filters compare dates only when the value can be read as a timestamp, and a value that can't is left out of the comparison. A value in the form HH:mm means today (UTC) at that time.

Files

A file uploaded with a row, as form submissions do, is stored as its URL. Its media file ID goes in a second column named after the first, such as PhotoMediaFileId for a Photo column. Several files, or a column that already holds a list, are stored as lists of URLs and IDs.

Keep a column's values unique

The unique setting refuses a write that gives a row a value another live row already has in that column.

Before you add the setting, check two things:

Each name in unique must match a column exactly, including case and spaces, or the setting is refused once the data source has columns.
The definition must stay valid JSON, or Fliplet Studio shows Definition must be a valid JSON. [UNVERIFIED: Studio UI, message read from code]

To turn it on:

Open the Settings tab.
In Data source definition, add a unique list of column names to the JSON object, for example { "unique": ["Email"] }.
Select Save changes.

A refused write gives this message: [UNVERIFIED: Studio UI, quoted from the API, not seen in Studio]

The value in the column Email is already in use. Please use a different value.

The setting works like this:

Values are compared ignoring case and leading and trailing spaces.
Blank values aren't compared, and neither are lists or objects.
Rows that already shared a value before you added the setting can still be edited, because only changed values are checked.
There's no lock, so two writes at the same moment can both pass.

Rename a column

> [!WARNING] > Screen code and security rules that use the old name keep using it after a rename. Update them yourself.

A grid save can't rename a column listed in unique. Remove the column from the unique setting first, or the save is refused with this message:

The column "Email" is set as unique. Remove it from the unique setting before renaming or deleting it.

To rename a column:

On Entries, select the column's name in row 1.
Type the new name.
Press Enter to confirm the new name.
Select Save changes.

The grid saves each row's values under the new name and sends the new column list.

Delete a column

> [!WARNING] > Deleting a column removes its values from the rows the save writes.

A grid save can't delete a column listed in unique. The save is refused with the same message as a rename, so remove the column from the unique setting first.

To delete a column:

On Entries, select a cell in the column.
Select Delete column in the toolbar.
Select Save changes.

Add or change columns from code

Fliplet.DataSources.create() takes a columns list of names. After that, any new key in a saved row is added to the column list, so a misspelled key creates a new column.

Use connection.commit() to rename or delete columns across every live row. Send entries: [] and append: true with the change, because a commit without append replaces rows it doesn't list.

await connection.commit({
  entries: [],
  append: true,
  renameColumns: [{ column: 'Mail', newColumn: 'Email' }],
  deleteColumns: ['Fax']
});

A renameColumns rename also carries the unique setting to the new name.

On a data source with security rules, renameColumns and deleteColumns work for App Tasks and for Studio users outside preview. A request checked against the rules, such as one from an app user, can still add columns, but changing them is refused with this message:

The security rules of this data source do not allow changing its columns.

Fliplet AI can also set up columns: its create tool takes a list of column names, and its update tool can add columns.

Check it worked

Select See all my project's data sources.
Select the data source's name.

Row 1 shows your column names, and Version history shows the column count. A JSON list or object shows as JSON text in its cell.

If it didn't work

A column you deleted comes back. A row still holds that key, and the grid shows every key it finds on a row. Delete the column with deleteColumns, from a place the security rules allow.

Numbers look out of order in a sort. The values hold commas or currency signs, so they sort as text. Remove those characters.

The error Invalid order column name appears. The error ends with the name, and it has three causes:

The name has a character that sorting doesn't accept.
The sort uses a column name without the data. prefix.
The column holds a password or login code.

The error Column 'Region' does not exists appears. The name in the sort isn't in the column list.

The unique setting is refused. A name that differs only in case or spaces gets a message naming the real column. A name that matches no column gets this message:

The "unique" setting lists "Region", which is not a column of this data source.

To link records across data sources, see Model relationships between Data Sources. For faster queries, see Data Source performance and query design.