Worksheets

Key Concepts

Worksheets provide a structured way to store tabular data within Ergon. They work like collaborative spreadsheets — each worksheet is a table with typed columns, and every row represents a single data record. The data model is intentionally simple so it can adapt to a wide range of use cases, from inventory tracking to CRM contact lists.

Folders

Folders are the top-level containers that group related worksheets together. Each folder belongs to a single company and can hold any number of worksheets. A folder carries a name, and optional description, icon, and color, making it easy to organize your workspace the way your team thinks about the data.

Worksheets

A worksheet lives inside a folder and represents a single data table. It defines the schema (via columns) and holds the rows that contain your actual data. You can think of each worksheet as one tab in a traditional spreadsheet application — self-contained, with its own column definitions and row set.

Columns

Columns define the schema of a worksheet. Each column has a name and a field_type. Supported types include text, number, date, checkbox, select, multi_select, formula, worksheet_ref, and more. Columns act as the contract for what data each row can contain — every cell value must conform to the column's type.

Rows

Rows are the individual data records in a worksheet. Each row is identified by a unique ID and ordered by a position value. Rows themselves are lightweight — the actual data lives in cell values, one per row–column intersection.

Cell Values

A cell value is the single piece of data at the intersection of a row and a column. It is stored as a JSON value, which means it can hold a string, number, boolean, array, or object depending on the column type. For example, a multi_select column stores an array of selected values, while a text column stores a plain string.

Column Types

Every column has a field_type that determines what kind of data it accepts and how that data is validated, displayed, and queried.

Basic Types

The foundational types cover most everyday data needs: text for free-form strings, number for integers and decimals, date for timestamps, and checkbox for true/false flags. These types require no additional configuration beyond a name.

Select & Multi-Select

Select columns restrict input to a predefined set of choices, supplied as options.choices — a list of strings. The difference between select and multi_select is straightforward: a select column allows exactly one choice per cell, while a multi_select column allows any number. Choices are managed as part of the column definition and can be added or removed at any time.

Formula

Formula columns compute their values automatically based on an expression you provide in the formula_expression field. Expressions can reference other columns in the same worksheet, perform arithmetic, apply string functions, or use conditional logic. Because formula values are computed, they are read-only — you cannot directly set a cell value on a formula column.

Reference

Reference columns (worksheet_ref) create links between worksheets. The column's reference_config specifies which target worksheet and column the reference points to. When a user fills in a reference cell, they select a row from the target worksheet, establishing a relationship between the two records. This is useful for modeling associations like “each order references a customer” or “each task references a project.”

List Columns

Any column can be turned into a list by setting is_list: true. A list column stores an ordered array of values of its underlying type in a single cell. This is useful when a record needs to hold a variable-length collection — for example, a list of tags, a set of email addresses, or a sequence of steps.

The following example creates a worksheet with several column types:

# 1. Create a folder
curl -X POST https://platform.ergondata.ai/api/v1/worksheets/companies/{company_id}/folders \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Product Catalog"}'

# 2. Create a worksheet inside the folder
curl -X POST https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/worksheets \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Inventory"}'

# 3. Add columns
curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/columns \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Product Name", "field_type": "text"}'

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/columns \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Price", "field_type": "number"}'

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/columns \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Category",
    "field_type": "select",
    "options": {"choices": ["Electronics", "Furniture", "Clothing"]}
  }'

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/columns \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "In Stock",
    "field_type": "checkbox"
  }'

Views

Views are saved presentation configurations for a worksheet. They control how the data is displayed — which columns are visible, in what order, which filters are active, and how rows are sorted — without changing the underlying data itself.

Each view specifies a type (currently grid) and a config object holding optional filter rules, per-column settings (visibility, order, width), and a sort string. You can create as many views as you need: one for a quick summary, one filtered to a specific category, another sorted by date. Switching between views is instant because the data never changes — only the presentation does.

A view can be marked as is_default to indicate that it should load automatically when someone opens the worksheet. Only one view per worksheet can be the default at a time.

# Create a filtered view showing only in-stock electronics
curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/views \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "In-Stock Electronics",
    "type": "grid",
    "config": {
      "filters": [
        {"column_id": "{category_col_id}", "operator": "eq", "value": "Electronics"},
        {"column_id": "{in_stock_col_id}", "operator": "eq", "value": true}
      ],
      "columns": [
        {"column_id": "{name_col_id}", "visible": true, "position": 0},
        {"column_id": "{price_col_id}", "visible": true, "position": 1},
        {"column_id": "{category_col_id}", "visible": true, "position": 2}
      ],
      "sort": "{price_col_id}:asc"
    },
    "is_default": false
  }'

Import & Export

Worksheets support bulk data operations so you can move data in and out of the platform efficiently. You can import data from CSV or XLSX files and export worksheets to the same formats. Legacy binary XLS files are not supported.

Importing Data

Imports create a new worksheet in a folder from a CSV or XLSX file. The preview lets you select an XLSX sheet or configure a CSV delimiter, encoding, and header row, then map, rename, exclude, and type columns. Smaller files can be previewed locally; large XLSX files are uploaded in parts and previewed from the staged object so the browser does not expand the workbook. Complete the import with those choices, then poll the folder import job until it returns the new worksheet ID.

Exporting Data

Exports run as durable background jobs. Queue CSV or XLSX generation, poll the returned job ID, then download the completed artifact from its short-lived signed URL.

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/exports \
  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
  -d '{"output_format":"csv","filename":"export"}'

curl https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/exports/{export_job_id} \
  -H "Authorization: Bearer {token}"

Automations

Worksheets emit domain events (worksheets.rows.created, worksheets.rows.updated, worksheets.column.updated, …) and accept actions (worksheets.rows.create, worksheets.rows.update_cells, worksheets.rows.delete) that the central Automations service wires together. Authoring rules, conditions, and recursion safeguards all live in the Automations service.

From a folder you only need to grant the automation access to the folder (or to specific worksheets within it); the Automations rule editor will then surface the available trigger events and actions.