跳到主要内容

Formula Fields

Formula fields are calculated columns that derive their values from other columns on the same board using expressions. They update automatically whenever the referenced values change.

Overview​

Instead of manually computing derived values like totals, averages, or weighted scores, you can create a formula column that does the math for you. ProBeya's formula engine supports arithmetic operations, column references by name, built-in functions, and circular dependency detection. Formulas are validated at creation time to catch syntax errors and invalid references before they reach the board.

Getting Started​

  1. Open a board and click + to add a new column.
  2. Select Formula as the column type.
  3. Enter your formula expression in the formula editor.
  4. Click Validate to check for errors before saving.
  5. The column appears on the board with computed values for each item.

How It Works​

Formula Syntax​

Formulas reference other columns by name enclosed in curly braces:

{Budget} - {Actual Cost}

Standard arithmetic operators are supported:

  • + addition
  • - subtraction
  • * multiplication
  • / division
  • () grouping for precedence

Column References​

When you write {Column Name}, the system resolves the name to the column's internal ID. This means:

  • Column names are case-sensitive in references
  • If a column is renamed, existing formulas referencing the old name will need updating
  • Only columns on the same board can be referenced

Validation​

Before a formula column is created, the system runs validation:

  1. Syntax check — the expression is parsed into an Abstract Syntax Tree (AST). Invalid syntax returns an error with a descriptive message.
  2. Reference resolution — all {Column Name} references are resolved to column IDs. Unknown column names are flagged.
  3. Circular dependency detection — a dependency graph of all formula columns is built and topologically sorted. If adding the new formula would create a cycle, the operation is rejected.

You can also validate a formula without creating a column using the standalone Validate Formula action, which checks syntax and references against the board's current columns.

Dependency Graph​

Formula columns can reference other formula columns, creating dependency chains. The system maintains a directed acyclic graph (DAG) of these dependencies:

  • When column A references column B, an edge B → A is recorded
  • Topological sort determines the evaluation order
  • Circular references (A → B → A) are detected and rejected at creation time

Each formula column stores its formulaDependencies array, listing the IDs of all columns it depends on.

Evaluation​

Formula values are computed on the server when items are fetched. For each item:

  1. Columns are sorted in dependency order
  2. Referenced values are read from the item's stored values
  3. The formula expression is evaluated with the resolved values
  4. The result is returned alongside other column values

Configuration​

  • Formula expression — set when creating the column, can be updated via column edit
  • Dependencies — automatically computed from the formula; no manual configuration needed

Permissions​

ActionRequired Role
View formula column valuesAny member with board "view" permission
Create a formula columnUser with board "edit" permission
Update or delete formula columnsUser with board "edit" permission
Validate a formulaUser with board "view" permission

Tips & Best Practices​

提示

Use the Validate Formula action before adding a formula column to a production board. Validation checks syntax, column references, and circular dependencies without modifying the board, so you can iterate on the expression safely.

提示

Keep formula column names descriptive (e.g., "Remaining Budget" instead of "Calc1"). Other formulas may reference your column by name, and clear naming reduces confusion and maintenance overhead.