Evaluator & Cells API

Low-level APIs for formula evaluation, cell operations, and on-demand calculation.

Evaluator

Accessed via client.evaluator.

evaluate(request)

Evaluates formula expressions and returns computed cell values.

evaluate(evaluateRequest: EvaluateRequest): Promise<Array<EvaluateCell>>

Parameter	Type	Required	Description
evaluateRequest	EvaluateRequest	Yes	Filters and cell queries to evaluate

const cells = await client.evaluator.evaluate({
    filters: [
        ['RV', `$${revenue.id}`],
        ['P', `$${plan.id}`],
    ],
    cellQueries: [
        { type: 'VARIABLE', formula: 'sum(RV,P)' },
    ],
});

console.log(cells[0].value);      // 1250000
console.log(cells[0].readonly);   // false
console.log(cells[0].calculated); // true

exportDatabase(configuration?)

Exports the database with an optional configuration string.

exportDatabase(configuration?: string): Promise<Blob>

invalidateCache()

Invalidates the evaluator cache.

invalidateCache(): Promise<void>

stats()

Returns evaluator statistics.

stats(): Promise<object>

---

Cells

Accessed via client.cells.

Only calculateOnDemandCells() is implemented

Every other operation in this section responds 501 Not Implemented. They are generated from API endpoints that were never built, so they are typed and discoverable but cannot be used. Use these instead:

Instead of	Use
cells.create / cells.update / cells.updateValue / cells.updateBatch	client.model.updateCells
cells.copyCells	client.copyCells or client.model.copyCells
cells.query / cells.search	client.evaluator.evaluate
cells.copyAllCells / cells.copyVariable	No replacement yet — client.copyAllCells wraps cells.copyAllCells and is therefore also unavailable

calculateOnDemandCells()

Triggers calculation of all on-demand cells in the model. This is required before exporting data if your model has calculated fields.

calculateOnDemandCells(): Promise<void>

tip

This can be a long-running operation on large models. Use a timeout wrapper:

const calc = client.cells.calculateOnDemandCells();
const timeout = new Promise(resolve =>
    setTimeout(() => resolve('timeout'), 10 * 60 * 1000)
);

const result = await Promise.race([calc, timeout]);
if (result === 'timeout') {
    console.log('Calculation timed out');
}

copyAllCells(request)

Copies all cells between versions/scenarios.

copyAllCells(copyAllCellsRequest: CopyAllCellsRequest): Promise<void>

copyCells(request)

Copies specific cells.

copyCells(copyCellsRequest: CopyCellsRequest): Promise<void>

copyVariable(request)

Copies a variable's cell values.

copyVariable(copyVariableRequest: CopyVariableRequest): Promise<void>

query(request)

Queries cells by criteria.

query(cellQueryRequest: CellQueryRequest): Promise<CellQueryResponse>

search(request)

Searches cells.

search(searchCellsRequest: SearchCellsRequest): Promise<Array<CellRepresentation>>

create(request)

Creates a new cell.

create(createCellRequest: CreateCellRequest): Promise<CellRepresentation>

update(request)

Updates an existing cell.

update(cellUpdateRequest: CellUpdateRequest): Promise<CellRepresentation>

updateValue(request)

Updates only the value of a cell.

updateValue(updateCellValueRequest: UpdateCellValueRequest): Promise<CellRepresentation>

deleteCells(request)

Deletes cells by criteria.

deleteCells(deleteCellsRequest: DeleteCellsRequest): Promise<void>

---

Types

EvaluateRequest

interface EvaluateRequest {
    filters: Array<Array<string>>;  // [alias, value] pairs
    cellQueries: Array<CellQuery>;  // Queries to compute
}

CellQuery

A discriminated union type:

type CellQuery =
    | { type: 'VARIABLE'; formula: string }    // Variable formula evaluation
    | { type: 'DTABLE'; tableGid: number;      // Dimension table query
        columnIds: number[];
        fkColumnId?: number;
        formula: string };

EvaluateCell

interface EvaluateCell {
    value: any | null;       // Computed value
    readonly: boolean;       // Read-only cell
    calculated: boolean;     // Calculated field
    frozen: boolean;         // Frozen cell
    goal?: number;           // Target value
}