# getFormula

A Formula model is a data model that represents a single numerical statistic, such as an average or a count. Suitable for *headline* or *scorecard* type of visualizations.

## **Usage**

```typescript
const formula = await data.widgetSource.getFormula({
    column: 'column_name',
    operation: 'count',
    // + operationExp for custom operations
    // + base options...
});
```

## **Options**

The `getFormula` model inherits all options from the [base options](https://docs.carto.com/carto-for-developers/reference/carto-widgets-reference/models/..#model-base-options), plus:

```typescript
export interface FormulaRequestOptions extends BaseRequestOptions {
  column: string | '*' | '';
  operation: 'count' | 'avg' | 'min' | 'max' | 'sum' | 'custom' ;
  operationExp?: string;
}
```

* **column:** the name of the column that you will run the statistical operation on. It also accepts the `*` value, that will
  * name of the column
  * `*` for total row count , used with count in operation
  * empty string, in combination with custom + operationExp
* **operation:** the statistical operation that will be performed on the column. Accepted values are:
  * `count`
  * `avg`
  * `min`
  * `max`
  * `sum`
  * `custom`: a custom SQL expression, specified by `operationExp`.
* **operationExp** (optional): when using `operation: 'custom'` you need to specify the exact SQL operation that you want to run on your column. For example: `AVG(column_A) / AVG(column_B) * 100`.

## **Response**

A simple object containing the numerical value of the widget:

```typescript
type FormulaResponse = {value: number}; 
/* example response  
    {value: 1433230}
*/
```

The response can be then mapped to any HTML element, such as a scorecard.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-de84dc6c10c62fce4c5e0a5ea3255f474d169773%2FScreenshot%202024-10-07%20at%2019.51.11.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>