Your First Workbook¶

This guide walks you through uploading your first Excel workbook to CalcBridge, understanding how it's processed, and working with your data through the API.

What is a Workbook in CalcBridge?¶

In CalcBridge, a workbook represents an uploaded Excel file. When you upload an Excel file:

1. Parsing: The file is parsed to extract structure and data
2. Validation: Formulas are validated against supported functions
3. Storage: Data is stored in PostgreSQL with JSONB for flexibility
4. Indexing: Columns are analyzed and typed automatically

flowchart LR
    A[Excel File] --> B[Parser]
    B --> C{Validate}
    C -->|Valid| D[Database]
    C -->|Invalid| E[Error Report]
    D --> F[Ready for Analysis]

    style A fill:#DBEAFE,stroke:#3B82F6
    style D fill:#DCFCE7,stroke:#22C55E
    style E fill:#FEE2E2,stroke:#EF4444

Supported File Formats¶

CalcBridge supports the following Excel formats:

Preparing Your Excel File¶

Before uploading, ensure your Excel file follows these best practices:

Recommended Structure¶

+------------------+------------------+------------------+
| Column A         | Column B         | Column C         |
+------------------+------------------+------------------+
| CUSIP            | Issuer Name      | Par Amount       |  <- Header row
+------------------+------------------+------------------+
| 123456789        | Acme Corp        | 1000000          |  <- Data rows
| 987654321        | Beta Inc         | 2500000          |
+------------------+------------------+------------------+

Best Practices¶

Supported Excel Functions¶

CalcBridge supports 50+ Excel functions including:

See the Function Reference for the complete list.

Uploading via the Web UI¶

If you're using the CalcBridge frontend:

1. Navigate to the Workbooks page
2. Click "Upload Workbook"
3. Select your Excel file
4. Wait for processing to complete
5. View your uploaded data

Uploading via the API¶

Step 1: Authenticate¶

First, get an access token:

# Login to get tokens
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=analyst@example.com&password=SecurePass123!"

Save the token:

export TOKEN="eyJhbGciOiJIUzI1NiIs..."

Step 2: Upload the File¶

curl -X POST http://localhost:8000/api/v1/workbooks/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@portfolio_data.xlsx"

import requests

TOKEN = "your-access-token"

with open("portfolio_data.xlsx", "rb") as f:
    response = requests.post(
        "http://localhost:8000/api/v1/workbooks/upload",
        headers={"Authorization": f"Bearer {TOKEN}"},
        files={"file": ("portfolio_data.xlsx", f, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")}
    )

if response.status_code == 201:
    workbook = response.json()
    print(f"Workbook created: {workbook['id']}")
    print(f"Name: {workbook['name']}")
    print(f"Sheets: {workbook['sheet_count']}")
    print(f"Total rows: {workbook['row_count']}")
else:
    print(f"Error: {response.json()}")

const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('http://localhost:8000/api/v1/workbooks/upload', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: formData
});

const workbook = await response.json();
console.log('Workbook ID:', workbook.id);

Response Format¶

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "portfolio_data",
  "description": null,
  "original_filename": "portfolio_data.xlsx",
  "status": "ready",
  "sheet_count": 3,
  "row_count": 1250,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:05Z"
}

Viewing Your Data¶

List All Workbooks¶

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/workbooks?page=1&page_size=20"

Response:

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "portfolio_data",
      "status": "ready",
      "sheet_count": 3,
      "row_count": 1250
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "total_pages": 1
}

List Sheets in a Workbook¶

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/workbooks/$WORKBOOK_ID/sheets"

Response:

[
  {
    "id": "sheet-uuid-1",
    "name": "Holdings",
    "sheet_index": 0,
    "row_count": 500,
    "column_count": 25,
    "column_definitions": [
      {"name": "CUSIP", "index": 0, "letter": "A", "data_type": "string"},
      {"name": "Issuer", "index": 1, "letter": "B", "data_type": "string"},
      {"name": "Par Amount", "index": 2, "letter": "C", "data_type": "number"}
    ]
  },
  {
    "id": "sheet-uuid-2",
    "name": "Trades",
    "sheet_index": 1,
    "row_count": 150,
    "column_count": 12
  }
]

Get Sheet Data¶

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/workbooks/$WORKBOOK_ID/sheets/Holdings/data?page=1&page_size=100"

Response:

{
  "items": [
    {
      "id": "row-uuid-1",
      "row_key": "row_1",
      "data": {
        "CUSIP": "123456789",
        "Issuer": "Acme Corporation",
        "Par Amount": 1000000,
        "Market Value": 1025000,
        "Spread": 250
      },
      "version": 1
    }
  ],
  "total": 500,
  "page": 1,
  "page_size": 100
}

Understanding Sheet Structure¶

When CalcBridge parses your Excel file, it analyzes each column:

Column Definitions¶

Each column has metadata:

Data Types¶

CalcBridge automatically detects these data types:

Updating Data¶

You can update individual rows through the API:

curl -X PUT "http://localhost:8000/api/v1/workbooks/$WORKBOOK_ID/sheets/Holdings/data/row_1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Par Amount": 1100000,
    "Market Value": 1130000
  }'

Promoting Header Rows¶

If your Excel file has headers on a row other than the first:

curl -X POST "http://localhost:8000/api/v1/workbooks/$WORKBOOK_ID/sheets/Holdings/promote-header" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"row_index": 2}'

This re-parses the sheet using row 2 (zero-indexed) as the header row.

Deleting Workbooks¶

To delete a workbook and all its data:

curl -X DELETE "http://localhost:8000/api/v1/workbooks/$WORKBOOK_ID" \
  -H "Authorization: Bearer $TOKEN"

Common Issues¶

File Too Large¶

Unsupported Format¶

Parsing Timeout¶

Next Steps¶

Now that you've uploaded your first workbook:

• Run Compliance Tests: Set up automated compliance testing
• Create What-If Scenarios: Simulate trade impacts
• Explore the API: Full API documentation
• Configure Settings: Customize your environment