Tables and columns
Configure data views with columns, filters and a Query.
Define the source before columns
A table view presents a data collection. Declare its Query and parameters first, then choose columns. A Data Space’s main view is a natural use; a record or home screen can also embed the result where the Model defines that placement.
| Configuration | Options / expected values | Description |
|---|---|---|
| Source | Named Query binding | Determines retrieved rows |
| Columns | Admitted native property, Field or metric | Selects displayed values |
| Labels | Readable text | Names columns |
| Format | Variant suited to the type | Text, number, date, badge or link |
| Filters | Declared Query controls | Restricts results |
| Sort | Admitted keys and direction | Orders the collection |
| Opening | Record Action or destination | Moves from row to detail |
Example: client quotes
The Query receives North Studio and returns its quotes. The table displays Number, Status, Amount and Last updated. A Status filter selects For approval. Opening a row displays the Quote record and preserves client context for navigation back.
Editing, totals and pagination
Editable cells use their Fields and corresponding authorized operations. Calculated values and totals come from canonical projections. A total representing the complete collection cannot be calculated from loaded rows alone.
In an independent Space, edit an eligible cell through the form and Action declared by its Model. Only that Space’s own authorized records can be changed this way; displaying another Space’s records grants no editing rights. Calculated and linked values remain read-only. Save validates the form and refreshes the Query with the same criteria. If the record or reading context changes, your input stays visible without being applied; close the form and reload the current result before editing again.
Select a range on the loaded page to copy its visible cells; hidden columns and other pages are not included. Pasting into editable scalar cells prepares one review using each record’s declared form, for at most 100 rows and 1,000 cells. Confirm once to save the whole set, or cancel. An invalid or read-only destination prevents the entire paste rather than saving only some cells. Empty text, clearing an optional value, zero and false remain distinct choices. After saving, Surface refreshes the same Query with its filters and sort.
The table component preserves selection, filters and drafts while the Query supplies the authorized records. Sorting and filtering apply to that source, including results beyond the current page.
When a column has a declared sort, its header offers the choices defined by the Model. A choice orders the complete authorized collection, not just the displayed rows, and preserves its secondary criteria. “Default order” restores the Query’s order. If the current sort belongs to another column, the selector indicates this without replacing it. A column with no admitted choice, including a calculated metric, has no sort command.
Toolbar and header filters use the same Query parameters. Apply your choices to refresh results; resetting restores their defaults. Changing the interface language preserves unsubmitted input, focus and selection. Column names and choices declared by your Model remain those of the application.
Filters follow the Model’s types: exact integers and amounts retain their values without rounding or approximate conversion, while real numbers use their explicitly declared approximate precision.
Show related records
A related-records column displays authorized titles for the items associated with each row, using the Query and limit declared by your Model. Select a title to open that exact record; Surface prepares your current input first. Titles are read-only content, not Fields to edit inside the cell. This column does not offer local sorting or grouping.
The number of additional items covers the complete authorized result, not only the displayed titles. “No related items” describes a complete empty list; loading or unavailable does not mean zero. An export must support this source explicitly: Surface refuses an unsupported combination instead of silently dropping the column from the file.
Group records
When the Model declares grouping options, use Group by to choose a column, such as quote status. Each group’s record count covers the complete authorized Query with its filters and context, not only the displayed rows. Record groups are distinct from header groups that bring several columns together.
Open a group to browse its records; only one group is open at a time. More groups continues the group list, while More group items continues the selected group’s records. No grouping restores the ordinary Query presentation. These choices change neither the data nor your personal column preferences. See the grouping layout reference for the declared options.
Your personal presentation
Choose the visible columns, their order and width, the density and the columns pinned at the start of the table. Keep at least one column visible; a declared column group stays together. Your choices belong to your account and this table’s placement in the Workspace or independent Space. They do not change a colleague’s presentation or the Model’s shared defaults.
An application Reader can personalize their own presentation while retaining read-only access to the records. Saving a layout grants no additional access and changes neither the Query nor the data. Restoring the default presentation removes only your saved choices for this table.
A compatible Model update preserves your choices while using the current column labels and formats. If a column is added, removed or changes its source, or a group becomes incompatible, Surface asks you to review the layout rather than silently applying an outdated choice.
See the layout reference for exact properties and variants.
Export a collection
When the Model declares an export profile for the table, choose the complete Query, the displayed page or selected rows from that page, then the profile and one of its offered formats. The export preserves filters, sorting, context and displayed columns in their order. Complete scope is never limited to rows already loaded. PDF for printing downloads a real PDF to open and print in your usual application. Within a record, each table retains its own origin and parameters, even when sections share a binding. If the record or Query changes before the export opens, reopen it from the intended table.
Linked Field values and calculated columns come from the same authorized projections on every page. Exact decimal values and their declared units are preserved in the export.
The same journey applies to declared tables on Home, in an independent Space or in a Work. A Work retains the Model that defines its work. Counts stay complete; a related-record cell keeps its display limit and indicates how many other records exist, without silently exporting their titles.
Local V2 table controls
In the Application Builder, Data table behavior controls direct cell editing, inline record creation and whether a record opens as a full page or a right panel. Double-click an editable cell; use its title link to open the complete record. Label Fields display Model-defined colored values.
The Columns menu has drag handles; focus a handle and use Up/Down for keyboard reordering. Applied query filters remain highlighted after their menu closes, and the sorted column shows its direction. Select rows to duplicate or delete them. Both operations check current versions and save atomically. Copies retain Fields and rich content, without duplicating Tags or relations.
Collection actions provide JSON import and JSON/CSV export. Export chooses visible rows, selected rows, all query matches or all records, plus visible columns or all Fields. Import creates new records from Model Field keys, with a maximum of 100 records per request. Complete exports are limited to 1,000 records and refuse oversized collections instead of returning an incomplete file.
Record Fields and rich content save automatically after a short pause. Fields keep the same compact layout during editing. Section and relation labels belong to the Model and are configured in the Builder; the record itself does not expose link configuration.
Inline creation uses the last row of the table: click a cell and enter its value. Commit a cell to create the row once all required values are valid. Missing required fields are marked and keep the entered values; incomplete rows are never created. Optional typed Field defaults are configured in Builder → Data and prefill new rows. There is no Add button inside the row. No separate form opens.
Set Default sort and Sort direction in the Application Builder to choose the order used when the table opens.
Automatic saving keeps editing available, batches typing during writes into the next idle save, and flushes pending changes before closing. A discreet status replaces the saving spinner.
Data record choice and label fields use a shared searchable combobox. Use the arrow keys and Enter to choose an option, Escape to close, or click outside the menu. Label colors and stored values are unchanged.
Outside editing, an empty Date field displays a dash and a populated date uses the browser locale. Focusing the field keeps the native date picker; stored dates remain ISO calendar dates without timezone conversion.
In Columns, the moved column remains highlighted. Drag its handle to the insertion marker, or focus the handle and use Up/Down; keyboard focus follows the same column after each move.
In a page or side panel, new records stay as drafts until Add. The creation footer provides Add and Cancel; the drawer X also cancels without creating a record. Existing records continue to save automatically.
After Add, missing or invalid Fields receive a red outline and a message appears at the top of the creation panel. Correcting a Field removes its outline immediately. Add and Cancel stay in the panel footer while the content scrolls.
The trailing row shows only + Add record until clicked. Its other cells stay empty. Clicking + Add record activates the draft and reveals the Model defaults; after creation the next row is empty again.
Filters, Sort and Group by use the same combobox for all choices: matching mode, Field, condition, choice/Boolean value, sort order and grouping. Select your values, then Apply to run the query.
Combobox search appears only when the choices exceed one visible menu page. Short lists, including the Table view chooser, display their choices directly.
Surface loading shows one centered indicator over the content without moving the toolbar or panes. Background saving keeps the layout stable. An operation indicator stays inside its initiating button without resizing it.
Applied examples : Collection columns and formats
Declare each column source before its format, order and filters.
Configuration
Fragment placed in presentation.tableViews[]. Properties and accepted values.
{
"viewKey": "quotes-table",
"columns": [
{
"key": "number",
"label": "Number",
"source": {
"kind": "native",
"property": "title"
}
},
{
"key": "status",
"label": "Status",
"source": {
"kind": "field",
"fieldPath": "fields/status"
}
},
{
"key": "amount",
"label": "Amount",
"source": {
"kind": "field",
"fieldPath": "fields/amount"
}
}
],
"openLabel": "Open quote"
}Variation and connection
Fragment placed in presentation.tableViews[].layout. Properties and accepted values.
{
"contract": "WorkspaceTableLayout@1",
"grouping": null,
"columns": [
{
"columnKey": "number",
"visible": true,
"width": null,
"frozen": true,
"format": {
"kind": "text"
},
"headerFilterParameterKey": null
},
{
"columnKey": "status",
"visible": true,
"width": null,
"frozen": false,
"format": {
"kind": "badge"
},
"headerFilterParameterKey": null
},
{
"columnKey": "amount",
"visible": true,
"width": null,
"frozen": false,
"format": {
"kind": "number",
"maximumFractionDigits": 2
},
"headerFilterParameterKey": null
}
],
"columnGroups": []
}UI layout example
The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.
- Number
- Status
- Amount
- Last updated
| Number | Status | Amount | Open |
|---|---|---|---|
| S-1042 | Draft | 12 500 | ↗ |
| S-1041 | Approved | 8 200 | ↗ |
| S-1040 | Sent | 4 750 | ↗ |