Skip to main content

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>>
ParameterTypeRequiredDescription
evaluateRequestEvaluateRequestYesFilters 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.

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
}