Formulas And Equations

Formulas and Equations API

Learn how to manage and recalculate formula and equation fields programmatically using the REST API.

What are Formulas and Equations?

Formula and equation fields in Tadabase automatically calculate values based on other fields. They can perform mathematical operations, date calculations, text concatenation, and more.

When to Recalculate Formulas

Formula fields typically recalculate automatically, but you may need manual recalculation when:

Making bulk updates via API
Importing data
Changing formula definitions
Updating source fields without triggering auto-calculation

Update All Formulas (Entire App)

Recalculate all formula fields across your entire application:

POST /api/v1/update-all-formula

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Response

{
  "type": "success",
  "msg": "All formulas are being updated"
}

⚠️ Use Sparingly

This recalculates formulas for ALL records in ALL tables. Use table-specific or field-specific updates when possible to avoid unnecessary processing.

Update All Formulas (Specific Table)

Recalculate all formula fields in a specific table:

POST /api/v1/update-all-formula/{dataTableId}

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Response

{
  "type": "success",
  "msg": "Formulas for table {dataTableId} are being updated"
}

Update Specific Formula Field

By Field Slug

POST /api/v1/update-field-formula-by-slug/{fieldSlug}

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

By Field Slug (Force Recalculation)

POST /api/v1/update-field-formula-by-slug/{fieldSlug}/force

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

By Field ID

POST /api/v1/update-field-formula-by-id/{fieldId}

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

By Field ID (Force Recalculation)

POST /api/v1/update-field-formula-by-id/{fieldId}/force

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Force vs Normal Update

Mode	Description
Normal	Only recalculates if source fields changed
Force	Recalculates all records regardless of changes

Formula Execution Control Headers

When creating or updating records, control formula execution with these headers:

Header	Value	Description
`X-Tadabase-Queue-Equation`	`0` or `1`	Queue formula execution (async, faster response)
`X-Tadabase-Update-Equation`	`0` or `1`	Execute formulas immediately (default: 1)
`X-Tadabase-Table-Rules`	`0` or `1`	Run table rules (default: 1)
`X-Tadabase-Update-Table-Equation`	`0` or `1`	Update table-level equations (default: 1)

Skip Formula Execution (Faster Bulk Operations)

POST /api/v1/data-tables/{tableId}/records

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret
  X-Tadabase-Update-Equation: 0
  Content-Type: application/json

Body:
{
  "quantity": 10,
  "unit_price": 50.00
}

Then recalculate formulas after bulk operations:

POST /api/v1/update-all-formula/{tableId}

Queue Formula Execution (Faster Response)

POST /api/v1/data-tables/{tableId}/records

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret
  X-Tadabase-Queue-Equation: 1
  Content-Type: application/json

Body:
{
  "quantity": 10,
  "unit_price": 50.00
}

Formulas execute asynchronously in the background, API responds immediately.

Common Formula Update Patterns

1. After Bulk Data Import

async function importAndRecalculate(tableId, records) {
  console.log('Importing records...');

  // Import records without calculating formulas
  for (const record of records) {
    await fetch(
      `https://api.tadabase.io/api/v1/data-tables/${tableId}/records`,
      {
        method: 'POST',
        headers: {
          'X-Tadabase-App-id': 'your_app_id',
          'X-Tadabase-App-Key': 'your_app_key',
          'X-Tadabase-App-Secret': 'your_app_secret',
          'X-Tadabase-Update-Equation': '0',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(record)
      }
    );
  }

  console.log('Recalculating formulas...');

  // Recalculate all formulas for the table
  await fetch(
    `https://api.tadabase.io/api/v1/update-all-formula/${tableId}`,
    {
      method: 'POST',
      headers: {
        'X-Tadabase-App-id': 'your_app_id',
        'X-Tadabase-App-Key': 'your_app_key',
        'X-Tadabase-App-Secret': 'your_app_secret'
      }
    }
  );

  console.log('Import and recalculation complete');
}

2. After Changing Formula Definition

// After modifying formula in builder, recalculate all records
async function updateFormulaField(fieldSlug) {
  console.log(`Recalculating ${fieldSlug}...`);

  const response = await fetch(
    `https://api.tadabase.io/api/v1/update-field-formula-by-slug/${fieldSlug}/force`,
    {
      method: 'POST',
      headers: {
        'X-Tadabase-App-id': 'your_app_id',
        'X-Tadabase-App-Key': 'your_app_key',
        'X-Tadabase-App-Secret': 'your_app_secret'
      }
    }
  );

  const data = await response.json();
  console.log('Formula updated:', data.msg);
}

// Usage after changing formula
await updateFormulaField('total_price');

3. Selective Field Updates

// Update only specific formula fields
async function updateSpecificFormulas(tableId, fieldSlugs) {
  for (const fieldSlug of fieldSlugs) {
    console.log(`Updating formula: ${fieldSlug}`);

    await fetch(
      `https://api.tadabase.io/api/v1/update-field-formula-by-slug/${fieldSlug}`,
      {
        method: 'POST',
        headers: {
          'X-Tadabase-App-id': 'your_app_id',
          'X-Tadabase-App-Key': 'your_app_key',
          'X-Tadabase-App-Secret': 'your_app_secret'
        }
      }
    );
  }

  console.log('All specified formulas updated');
}

// Usage
await updateSpecificFormulas('lGArg7rmR6', [
  'total_price',
  'tax_amount',
  'grand_total'
]);

4. Conditional Formula Updates

// Update formulas only for records matching criteria
async function updateFormulasForRecords(tableId, filters) {
  // Get records matching criteria
  const response = await fetch(
    `https://api.tadabase.io/api/v1/data-tables/${tableId}/records`,
    {
      method: 'POST',
      headers: {
        'X-Tadabase-App-id': 'your_app_id',
        'X-Tadabase-App-Key': 'your_app_key',
        'X-Tadabase-App-Secret': 'your_app_secret',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ filters })
    }
  );

  const data = await response.json();

  // Update each record to trigger formula recalculation
  for (const record of data.items) {
    await fetch(
      `https://api.tadabase.io/api/v1/data-tables/${tableId}/records/${record.id}`,
      {
        method: 'POST',
        headers: {
          'X-Tadabase-App-id': 'your_app_id',
          'X-Tadabase-App-Key': 'your_app_key',
          'X-Tadabase-App-Secret': 'your_app_secret',
          'X-Tadabase-Update-Equation': '1',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          // Dummy update to trigger recalculation
          last_updated: new Date().toISOString()
        })
      }
    );
  }

  console.log(`Updated formulas for ${data.items.length} records`);
}

Performance Considerations

Bulk Operations Strategy

Records	Strategy
< 100	Calculate formulas per record (immediate)
100-1000	Queue formula execution per record
> 1000	Skip formulas during import, recalculate once after

Example: Optimized Bulk Insert

async function optimizedBulkInsert(tableId, records) {
  const batchSize = 100;
  let processedCount = 0;

  for (let i = 0; i

Formula Management Class

class FormulaManager {
  constructor(headers) {
    this.headers = headers;
    this.baseUrl = 'https://api.tadabase.io/api/v1';
  }

  async updateAll() {
    const response = await fetch(
      `${this.baseUrl}/update-all-formula`,
      {
        method: 'POST',
        headers: this.headers
      }
    );

    return await response.json();
  }

  async updateTable(tableId) {
    const response = await fetch(
      `${this.baseUrl}/update-all-formula/${tableId}`,
      {
        method: 'POST',
        headers: this.headers
      }
    );

    return await response.json();
  }

  async updateField(fieldSlug, force = false) {
    const url = force
      ? `${this.baseUrl}/update-field-formula-by-slug/${fieldSlug}/force`
      : `${this.baseUrl}/update-field-formula-by-slug/${fieldSlug}`;

    const response = await fetch(url, {
      method: 'POST',
      headers: this.headers
    });

    return await response.json();
  }

  async updateFieldById(fieldId, force = false) {
    const url = force
      ? `${this.baseUrl}/update-field-formula-by-id/${fieldId}/force`
      : `${this.baseUrl}/update-field-formula-by-id/${fieldId}`;

    const response = await fetch(url, {
      method: 'POST',
      headers: this.headers
    });

    return await response.json();
  }

  async updateMultipleFields(fieldSlugs, force = false) {
    const results = [];

    for (const fieldSlug of fieldSlugs) {
      const result = await this.updateField(fieldSlug, force);
      results.push({ fieldSlug, result });
    }

    return results;
  }
}

// Usage
const formulaManager = new FormulaManager(headers);

// Update all formulas in app
await formulaManager.updateAll();

// Update formulas for specific table
await formulaManager.updateTable('lGArg7rmR6');

// Update specific field
await formulaManager.updateField('total_price');

// Force update specific field
await formulaManager.updateField('calculated_field', true);

// Update multiple fields
await formulaManager.updateMultipleFields([
  'total_price',
  'tax_amount',
  'grand_total'
]);

Best Practices

Skip formulas for bulk operations: Disable formula calculation during bulk inserts, then recalculate once
Use queue mode for medium datasets: Queue formula execution for 100-1000 records
Update specific fields when possible: Don't recalculate all formulas if only one changed
Force recalculation after formula changes: Use force mode when formula definition changes
Test formula changes: Test on single records before bulk recalculation
Monitor performance: Track execution time for formula-heavy operations
Consider dependencies: Recalculate dependent fields in correct order

Debugging Formula Issues

New Equation Engine

In the app settings > Support, enable the new equation engine if you see some equations aren't running as they should when records are updated.

Next Steps

Learn how to work with data imports and exports programmatically:

→ Imports and Exports API

Discover how to trigger imports, exports, and monitor their progress.

How did we do ?

Tasks Api

Imports And Exports Api

Formulas And Equations

Formulas and Equations API

What are Formulas and Equations?

When to Recalculate Formulas

Update All Formulas (Entire App)

Response

⚠️ Use Sparingly

Update All Formulas (Specific Table)

Response

Update Specific Formula Field

By Field Slug

By Field Slug (Force Recalculation)

By Field ID

By Field ID (Force Recalculation)

Force vs Normal Update

Formula Execution Control Headers

Skip Formula Execution (Faster Bulk Operations)

Queue Formula Execution (Faster Response)

Common Formula Update Patterns

1. After Bulk Data Import

2. After Changing Formula Definition

3. Selective Field Updates

4. Conditional Formula Updates

Performance Considerations

Bulk Operations Strategy

Example: Optimized Bulk Insert

Formula Management Class

Best Practices

Debugging Formula Issues

New Equation Engine

Next Steps

How did we do ?

We'd love to hear your feedback.