Skip to main content

GridHeim: Advanced Spreadsheet Component for ValkyrAI

GridHeim is a powerful online spreadsheet component that integrates seamlessly with ThorAPI REST APIs. It provides a flexible and intuitive interface for working with tabular data, formulas, and business logic within your ValkyrAI applications.

Overview​

GridHeim allows you to work with spreadsheets via a secure REST API, as well as embed spreadsheet functionality in your applications. Used internally by ValkyrAI and HeimdaLLM, GridHeim is the ultimate end-user development UI allowing for easy building of data-management systems, formula-driven business logic, logic tables, dashboards, and reports.

Key Features​

Spreadsheet Functionality​

GridHeim provides comprehensive spreadsheet functionality:

  • Cell Editing: Edit cell contents with support for text, numbers, dates, and formulas
  • Formatting: Apply formatting to cells, including fonts, colors, borders, and alignment
  • Formulas: Use a wide range of formulas for calculations, data manipulation, and analysis
  • Data Validation: Apply validation rules to ensure data integrity
  • Sorting and Filtering: Sort and filter data based on various criteria
  • Charts and Visualizations: Create charts and visualizations from your data

REST API Integration​

GridHeim exposes a comprehensive REST API for interacting with spreadsheets:

  • CRUD Operations: Create, read, update, and delete spreadsheets, sheets, rows, columns, and cells
  • Formula Execution: Execute formulas and calculations via API calls
  • Data Import/Export: Import and export data in various formats (CSV, JSON, Excel)
  • User Management: Manage user access and permissions for spreadsheets

Embedding Capabilities​

GridHeim can be embedded in your applications:

  • React Component: Use the GridHeim React component to embed spreadsheets in your web applications
  • Iframe Integration: Embed GridHeim in any web application using iframes
  • Custom Styling: Apply custom styling to match your application's look and feel
  • Event Handling: Handle events from the embedded spreadsheet component

Architecture​

GridHeim is built on a modular architecture that integrates with ValkyrAI and ThorAPI:

Components​

  • GridHeim Core: The core spreadsheet engine that handles data storage, formula execution, and business logic
  • GridHeim API: The REST API layer that exposes GridHeim functionality to external applications
  • GridHeim UI: The user interface components for displaying and interacting with spreadsheets
  • GridHeim Connectors: Connectors for integrating with various data sources and external systems

Integration with ValkyrAI​

GridHeim integrates with other ValkyrAI components:

  • ThorAPI: GridHeim uses ThorAPI for generating its REST API and data models
  • SecureFieldKMS: Sensitive data in GridHeim spreadsheets is protected using SecureField encryption
  • HeimdaLLM: AI-powered insights and suggestions for spreadsheet data
  • Workflow Engine: Spreadsheet operations can be incorporated into ValkyrAI workflows

Data Model​

GridHeim uses a comprehensive data model to represent spreadsheets and their components:

Workbook​

The top-level container for spreadsheets:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Financial Analysis",
  "description": "Financial analysis for Q2 2025",
  "created_date": "2025-04-01T10:00:00Z",
  "last_modified_date": "2025-04-15T14:30:00Z",
  "owner_id": "789e0123-e45b-67d8-a901-234567890123"
}

Sheet​

A single sheet within a workbook:

{
  "id": "456e7890-e12b-34d5-a678-901234567890",
  "workbook_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Revenue Projections",
  "index": 0,
  "row_count": 100,
  "column_count": 26
}

Cell​

An individual cell within a sheet:

{
  "id": "789e0123-e45b-67d8-a901-234567890123",
  "sheet_id": "456e7890-e12b-34d5-a678-901234567890",
  "row": 0,
  "column": 0,
  "value": "Product",
  "formula": null,
  "format": {
    "font_weight": "bold",
    "background_color": "#f0f0f0",
    "text_color": "#000000",
    "horizontal_alignment": "center"
  }
}

Formula​

A formula used in a cell:

{
  "id": "012e3456-e78b-90d1-a234-567890123456",
  "sheet_id": "456e7890-e12b-34d5-a678-901234567890",
  "cell_id": "789e0123-e45b-67d8-a901-234567890123",
  "formula": "=SUM(A1:A10)",
  "dependencies": ["A1", "A2", "A3", "A4", "A5", "A6", "A7", "A8", "A9", "A10"]
}

Named Range​

A named range within a sheet:

{
  "id": "345e6789-e01b-23d4-a567-890123456789",
  "sheet_id": "456e7890-e12b-34d5-a678-901234567890",
  "name": "ProductList",
  "range": "A1:A10"
}

API Endpoints​

GridHeim exposes a comprehensive REST API for interacting with spreadsheets:

Workbook Endpoints​

  • GET /api/workbooks: List all workbooks
  • POST /api/workbooks: Create a new workbook
  • GET /api/workbooks/{id}: Get workbook details
  • PUT /api/workbooks/{id}: Update a workbook
  • DELETE /api/workbooks/{id}: Delete a workbook

Sheet Endpoints​

  • GET /api/workbooks/{workbookId}/sheets: List all sheets in a workbook
  • POST /api/workbooks/{workbookId}/sheets: Create a new sheet
  • GET /api/sheets/{id}: Get sheet details
  • PUT /api/sheets/{id}: Update a sheet
  • DELETE /api/sheets/{id}: Delete a sheet

Cell Endpoints​

  • GET /api/sheets/{sheetId}/cells: List all cells in a sheet
  • POST /api/sheets/{sheetId}/cells: Create or update cells
  • GET /api/cells/{id}: Get cell details
  • PUT /api/cells/{id}: Update a cell
  • DELETE /api/cells/{id}: Delete a cell

Formula Endpoints​

  • POST /api/formulas/evaluate: Evaluate a formula
  • GET /api/sheets/{sheetId}/formulas: List all formulas in a sheet
  • POST /api/sheets/{sheetId}/formulas/recalculate: Recalculate all formulas in a sheet

Import/Export Endpoints​

  • POST /api/workbooks/import: Import a workbook from a file
  • GET /api/workbooks/{id}/export: Export a workbook to a file
  • POST /api/sheets/{id}/import: Import data into a sheet
  • GET /api/sheets/{id}/export: Export a sheet to a file

Using GridHeim​

Creating a Workbook​

To create a new workbook, send a POST request to the /api/workbooks endpoint:

curl -X POST http://localhost:8080/api/workbooks \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Financial Analysis",
    "description": "Financial analysis for Q2 2025"
  }'

Adding a Sheet​

To add a sheet to a workbook, send a POST request to the /api/workbooks/{workbookId}/sheets endpoint:

curl -X POST http://localhost:8080/api/workbooks/123e4567-e89b-12d3-a456-426614174000/sheets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenue Projections",
    "row_count": 100,
    "column_count": 26
  }'

Adding Cells​

To add cells to a sheet, send a POST request to the /api/sheets/{sheetId}/cells endpoint:

curl -X POST http://localhost:8080/api/sheets/456e7890-e12b-34d5-a678-901234567890/cells \
  -H "Content-Type: application/json" \
  -d '[
    {
      "row": 0,
      "column": 0,
      "value": "Product",
      "format": {
        "font_weight": "bold",
        "background_color": "#f0f0f0"
      }
    },
    {
      "row": 0,
      "column": 1,
      "value": "Q1",
      "format": {
        "font_weight": "bold",
        "background_color": "#f0f0f0"
      }
    },
    {
      "row": 0,
      "column": 2,
      "value": "Q2",
      "format": {
        "font_weight": "bold",
        "background_color": "#f0f0f0"
      }
    }
  ]'

Adding a Formula​

To add a formula to a cell, update the cell with a formula:

curl -X PUT http://localhost:8080/api/cells/789e0123-e45b-67d8-a901-234567890123 \
  -H "Content-Type: application/json" \
  -d '{
    "formula": "=SUM(B2:B10)"
  }'

Evaluating a Formula​

To evaluate a formula without adding it to a cell, send a POST request to the /api/formulas/evaluate endpoint:

curl -X POST http://localhost:8080/api/formulas/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "sheet_id": "456e7890-e12b-34d5-a678-901234567890",
    "formula": "=SUM(B2:B10)"
  }'

Embedding GridHeim in Your Application​

React Component​

To embed GridHeim in a React application, use the GridHeim React component:

import { GridHeim } from '@valkyrlabs/gridheim-react';

function SpreadsheetView() {
  return (
    <GridHeim
      workbookId="123e4567-e89b-12d3-a456-426614174000"
      apiUrl="http://localhost:8080/api"
      height="600px"
      width="100%"
      readOnly={false}
      onCellChange={(cell) => console.log('Cell changed:', cell)}
    />
  );
}

Iframe Integration​

To embed GridHeim in any web application using an iframe:

<iframe
  src="http://localhost:8080/embed/workbooks/123e4567-e89b-12d3-a456-426614174000"
  width="100%"
  height="600px"
  frameborder="0"
></iframe>

Security Considerations​

Authentication and Authorization​

GridHeim uses ThorAPI's authentication and authorization mechanisms:

  • JWT Authentication: All API requests require a valid JWT token
  • Role-Based Access Control: Access to workbooks, sheets, and cells is controlled by roles
  • Object-Level Security: Fine-grained access control at the workbook, sheet, and cell level

Data Encryption​

GridHeim uses SecureFieldKMS for encrypting sensitive data:

  • Cell-Level Encryption: Sensitive cell data is encrypted using SecureField
  • Formula Protection: Formulas containing sensitive business logic can be encrypted
  • Secure Transport: All API communication is encrypted using TLS

Best Practices​

Performance Optimization​

  • Limit Sheet Size: Keep sheets to a reasonable size (under 10,000 cells) for optimal performance
  • Batch Operations: Use batch operations for updating multiple cells
  • Pagination: Use pagination when retrieving large datasets
  • Caching: Implement caching for frequently accessed data

Formula Best Practices​

  • Keep Formulas Simple: Break complex formulas into smaller, more manageable parts
  • Use Named Ranges: Use named ranges to make formulas more readable and maintainable
  • Avoid Circular References: Circular references can cause performance issues and calculation errors
  • Document Formulas: Document complex formulas to make them easier to understand and maintain

Data Validation​

  • Input Validation: Validate user input to prevent errors and ensure data integrity
  • Data Types: Use appropriate data types for cells (text, number, date, etc.)
  • Validation Rules: Apply validation rules to cells to enforce business rules
  • Error Handling: Implement error handling for formula evaluation and data validation

Future Enhancements​

The GridHeim roadmap includes:

  • Collaborative Editing: Real-time collaborative editing of spreadsheets
  • Advanced Visualization: Enhanced charting and visualization capabilities
  • AI-Powered Insights: Integration with HeimdaLLM for AI-powered insights and suggestions
  • Mobile Support: Improved support for mobile devices
  • Offline Mode: Support for offline editing and synchronization
  • Custom Functions: Support for custom functions and extensions

Conclusion​

GridHeim is a powerful spreadsheet component that integrates seamlessly with ValkyrAI and ThorAPI. It provides a flexible and intuitive interface for working with tabular data, formulas, and business logic within your applications. With its comprehensive API and embedding capabilities, GridHeim is the ultimate end-user development UI for building data-management systems, formula-driven business logic, dashboards, and reports.

For more information on GridHeim, refer to the ValkyrAI API documentation and the GridHeim developer guide.