Running Calculations¶

CalcBridge provides a powerful calculation engine that processes Excel formulas at cloud scale. This guide covers how to trigger calculations, view results, understand status indicators, and troubleshoot errors.

Overview¶

When you upload a workbook or edit data, CalcBridge can automatically recalculate all formulas. The calculation engine:

• Parses formulas into an Abstract Syntax Tree (AST)
• Resolves cell dependencies in topological order
• Executes calculations using vectorized operations
• Returns results with complete audit trail

Triggering Recalculation¶

Automatic Recalculation¶

By default, CalcBridge recalculates automatically when:

You can disable automatic recalculation in workbook settings if you prefer manual control.

Manual Recalculation¶

Via UI¶

1. Open the workbook you want to recalculate
2. Click the Recalculate button in the toolbar
3. Choose calculation scope:
   • Full - Recalculate all formulas
   • Selected Sheet - Recalculate current sheet only
   • Selected Range - Recalculate selected cells only
4. Click Start to begin

Via Keyboard Shortcut¶

Via API¶

# Recalculate entire workbook
curl -X POST https://api.calcbridge.io/api/v1/calculations/recalculate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "scope": "full"
  }'

# Recalculate specific sheet
curl -X POST https://api.calcbridge.io/api/v1/calculations/recalculate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "scope": "sheet",
    "sheet_name": "Portfolio"
  }'

Response:

{
  "job_id": "calc_abc123",
  "status": "queued",
  "estimated_duration_seconds": 5
}

Viewing Calculation Results¶

Results Overview¶

After calculation completes, view results in several ways:

Cell Values¶

Navigate to any cell to see its calculated value:

Cell: D5
Formula: =SUM(A5:C5)
Value: 12,345.67
Last Calculated: 2025-01-15 10:30:00 UTC

Sheet Summary¶

The sheet summary shows aggregate calculation information:

Calculation Report¶

Generate a detailed calculation report:

1. Click Reports in the workbook toolbar
2. Select Calculation Report
3. Choose format (PDF, Excel, JSON)
4. Download the report

Understanding Calculation Status¶

Workbook Status¶

Cell Status¶

Individual cells show their calculation status:

Progress Tracking¶

For large workbooks, track calculation progress:

curl -X GET https://api.calcbridge.io/api/v1/calculations/jobs/{job_id} \
  -H "Authorization: Bearer $TOKEN"

{
  "job_id": "calc_abc123",
  "status": "running",
  "progress": {
    "sheets_total": 5,
    "sheets_completed": 3,
    "cells_total": 50000,
    "cells_completed": 32000,
    "percent_complete": 64
  },
  "started_at": "2025-01-15T10:30:00Z",
  "estimated_completion": "2025-01-15T10:30:45Z"
}

Calculation Dependencies¶

Dependency Resolution¶

CalcBridge automatically resolves formula dependencies:

1. Parses all formulas to identify cell references
2. Builds a dependency graph
3. Sorts cells in topological order
4. Calculates cells in dependency order

flowchart LR
    A1["A1 = 100"] --> C1
    B1["B1 = 200"] --> C1
    C1["C1 = A1+B1"] --> D1
    C1 --> D2
    D1["D1 = C1*2"]
    D2["D2 = C1/2"]

Viewing Dependencies¶

To view a cell's dependencies:

1. Select the cell
2. Click Show Dependencies or press Ctrl+D
3. Precedents (cells this formula depends on) are highlighted in blue
4. Dependents (cells that depend on this cell) are highlighted in green

Circular Dependencies¶

CalcBridge detects and reports circular dependencies:

Error: Circular reference detected
Cycle: A1 -> B1 -> C1 -> A1

Troubleshooting Errors¶

Common Calculation Errors¶

Debugging Errors¶

View Error Details¶

1. Click the cell with the error
2. View the Error Details panel:
   • Error type
   • Error message
   • Formula that caused the error
   • Suggestions for fixing

Step-by-Step Evaluation¶

Use the API to evaluate formulas step-by-step:

curl -X POST https://api.calcbridge.io/api/v1/calculations/evaluate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "formula": "=IF(SUM(A1:A5)/COUNT(A1:A5)>100, \"High\", \"Low\")",
    "context": {"A1": 100, "A2": 200, "A3": 0, "A4": 150, "A5": 50},
    "debug": true
  }'

Response:

{
  "result": "High",
  "steps": [
    {"expression": "SUM(A1:A5)", "result": 500},
    {"expression": "COUNT(A1:A5)", "result": 5},
    {"expression": "500/5", "result": 100},
    {"expression": "100>100", "result": false},
    {"expression": "IF(false, \"High\", \"Low\")", "result": "Low"}
  ]
}

Performance Issues¶

If calculations are slow:

Calculation Settings¶

Workbook-Level Settings¶

Configure calculation behavior per workbook:

User-Level Settings¶

Configure your calculation preferences:

Batch Calculations¶

For programmatic workflows, use batch calculation endpoints.

Batch Evaluate¶

Evaluate multiple formulas in a single request:

curl -X POST https://api.calcbridge.io/api/v1/calculations/batch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "formulas": [
      {"id": "calc1", "formula": "=SUM(1,2,3)"},
      {"id": "calc2", "formula": "=AVERAGE(10,20,30)"},
      {"id": "calc3", "formula": "=IF(TRUE, \"Yes\", \"No\")"}
    ]
  }'

Response:

{
  "results": [
    {"id": "calc1", "result": 6, "type": "number"},
    {"id": "calc2", "result": 20, "type": "number"},
    {"id": "calc3", "result": "Yes", "type": "string"}
  ]
}

Batch Recalculate¶

Recalculate multiple workbooks:

curl -X POST https://api.calcbridge.io/api/v1/calculations/batch-recalculate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_ids": ["uuid-1", "uuid-2", "uuid-3"],
    "priority": "high"
  }'

Calculation History¶

Every calculation is logged for audit purposes:

Access calculation history from the workbook's History tab or via API:

curl -X GET https://api.calcbridge.io/api/v1/workbooks/{id}/calculations \
  -H "Authorization: Bearer $TOKEN"