Skip to content

Formula Config Models

This page documents the data models related to the formula builder, graph structures, and versioning.

FormulaConfig

Represents a saved formula configuration.

Properties

Property Type Description
id string Formula config identifier
name string Formula name (1-255 chars)
description string? Description (max 1000 chars)
template_id string Template identifier
graph FormulaGraph Graph definition
input_schema object Expected input columns
output_schema object Output column definition
mode FormulaMode Builder or advanced mode
status FormulaStatus Current status
version_count integer Number of versions
current_version string Current active version
created_at string (ISO 8601) Creation timestamp

Example

{
  "id": "fc_abc123",
  "name": "Market Value Calculator",
  "description": "Calculates market value from par and price",
  "template_id": "custom",
  "graph": {
    "version": "1.0",
    "template_id": "custom",
    "nodes": [
      {"id": "n1", "type": "column_ref", "params": {"column": "par_value"}},
      {"id": "n2", "type": "column_ref", "params": {"column": "price"}},
      {"id": "n3", "type": "expression", "params": {"formula": "n1 * n2 / 100"}}
    ],
    "edges": [
      {"id": "e1", "source": {"nodeId": "n1", "port": "out"}, "target": {"nodeId": "n3", "port": "in1"}},
      {"id": "e2", "source": {"nodeId": "n2", "port": "out"}, "target": {"nodeId": "n3", "port": "in2"}}
    ]
  },
  "mode": "builder",
  "status": "active",
  "version_count": 2,
  "current_version": "v2",
  "created_at": "2026-01-25T10:30:00Z"
}

FormulaGraph

Defines the complete formula as a directed acyclic graph.

Properties

Property Type Description
version string Graph schema version
template_id string Template the formula is based on
nodes GraphNode[] Node definitions
edges GraphEdge[] Edge connections between nodes

GraphNode

A single node in the formula graph.

Properties

Property Type Description
id string Unique node identifier
type NodeType Node type
params object Type-specific parameters
outputs object? Output port definitions
inputs object? Input port definitions

GraphEdge

A directed edge connecting two nodes.

Properties

Property Type Description
id string Unique edge identifier
source EdgeEndpoint Source node and port
target EdgeEndpoint Target node and port

EdgeEndpoint

Reference to a specific port on a node.

Properties

Property Type Description
nodeId string Node identifier
port string Port name (e.g., out, in1)

FormulaVersion

A versioned snapshot of a formula configuration.

Properties

Property Type Description
version_id string Version identifier
config_id string Parent formula config ID
graph FormulaGraph Graph at this version
change_notes string? Description of changes
created_at string (ISO 8601) Version creation timestamp

FormulaRun

Record of a formula execution.

Properties

Property Type Description
run_id string Run identifier
config_id string Formula config ID
version_id string Version used
workbook_id string (UUID) Target workbook
sheet_id string (UUID) Target sheet
target_column string Output column
status string Run status
rows_affected integer Rows computed
started_at string (ISO 8601) Start timestamp
completed_at string (ISO 8601)? Completion timestamp

Enumerations

NodeType

Value Description Key Parameters
column_ref Column reference column
constant Literal value value
lookup_exact Exact lookup default
compare Comparison operator (eq, ne, lt, gt, lte, gte)
if Conditional Three inputs (condition, true, false)
and / or Logical Variable inputs
sum / concat Aggregation Variable inputs
expression Raw formula formula

FormulaMode

Value Description
builder Visual node-and-edge builder
advanced Direct expression editing

FormulaStatus

Value Description
draft In development, not applied
active Ready for use
archived No longer in use