---
title: "Field calculations and value formatting"
slug: "field-calculations-and-value-formatting"
updated: 2026-10-27T15:51:43Z
published: 2026-10-27T15:51:43Z
canonical: "docs.supermetrics.com/field-calculations-and-value-formatting"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Field calculations and value formatting

A metric or dimension field doesn't have to return the raw value it reads from the API. You can process a field's value in two ways:

- **Calculations** compute a field's value from other fields — for example dividing clicks by impressions to get a rate. Defined with `subfields` and `calculation`.
- **Value formatting** transforms the value into the shape you want — for example turning a timestamp into a plain date, or rounding a number. Defined with `valueFormat`.

Both are set on the field itself, and both can be used together. When a field has both, the **calculation runs first**, then the **value formatting is applied to the result**.

## Field calculations

Calculations let you compute a field's value from other fields instead of reading it directly from the API response. This is useful when the data source doesn't return a value you need — for example a rate the API doesn't provide, but which you can derive from two fields it does return.

A calculation is defined on a metric or dimension field with two parts:

- `subfields` — the list of fields whose values feed the calculation, in order.
- `calculation` — an array of operations applied to those subfields, each with an `operation` and, for some operations, `parameters`.

### How subfields work

The `subfields` array lists the IDs of the fields used in the calculation. Operations refer to them by position — "subfield 1" is the first entry, "subfield 2" the second, and so on.

For example, a click-through rate metric that divides clicks by impressions lists both as subfields and applies the `divide` operation:

```
{
  "id": "ctr",
  "label": "CTR",
  "description": "Click-through rate",
  "dataType": "float.number.ratio",
  "subfields": [
    "clicks",
    "impressions"
  ],
  "calculation": [
    {
      "operation": "divide"
    }
  ]
}
```

Here `divide` takes the value of subfield 1 (`clicks`) and divides it by subfield 2 (`impressions`).

`calculation` is an array, so you can chain several operations — each runs in order on the result of the previous one.

### Metric operations

| Operation | Parameters | Description |
| --- | --- | --- |
| `sum` | None | Adds the subfield values together: `subfield1 + subfield2`. |
| `minus` | None | Subtracts subfield 2 from subfield 1: `subfield1 - subfield2`. |
| `multiply` | None | Multiplies subfield 1 by subfield 2: `subfield1 * subfield2`. |
| `divide` | None | Divides subfield 1 by subfield 2: `subfield1 / subfield2`. |
| `minus_and_divide` | None | `(subfield1 - subfield2) / subfield3`. |
| `plus_and_divide` | None | `(subfield1 + subfield2) / subfield3`. |
| `weighted_average` | None | Weighted average of subfield 1 weighted by subfield 2: `∑(subfield1 · subfield2) / ∑subfield2`. |
| `currency_conversion` | 1: source currency (optional — taken from subfield 2 if empty), 2: target currency (or `fromFieldValue` to read it from subfield 2) | Converts a value between currencies. An optional third subfield holding a date selects the conversion rate for that date; otherwise the latest rate is used. |
| `date_diff` | 1: subfield index of the start date, 2: subfield index of the end date, 3: fallback value if a date is missing (default `null`), 4: unit — `days`, `hours`, `minutes`, or `seconds` (default `days`) | Calculates the difference between two dates. |
| `discard_after_1st` | None | Keeps only the first subfield's value and discards the rest. |
| `math` | An array of step objects (see below) | Runs a sequence of math steps for calculations the simple operations above can't express. |

#### Example: divide

```
{
  "id": "ctr",
  "subfields": [
    "clicks",
    "impressions"
  ],
  "calculation": [
    {
      "operation": "divide"
    }
  ]
}
```

With `clicks` = 100 and `impressions` = 1000, the result is `0.1`.

#### Example: currency_conversion

```
{
  "id": "cost_usd",
  "subfields": [
    "cost",
    "advertiser_currency",
    "date"
  ],
  "calculation": [
    {
      "operation": "currency_conversion",
      "parameters": [
        "",
        "USD"
      ]
    }
  ]
}
```

With `cost` = 100, `advertiser_currency` = `EUR`, and `date` = `2020-01-01`, the value is converted from EUR to USD using that date's rate.

#### Example: math

The `math` operation runs a sequence of steps. Each step is an object with a `type` and the parameters that type needs (most commonly `sfnum`, the subfield number to act on). Available step types include `plus`, `minus`, `mult`, `div`, `get` (take the value from a subfield), `div_target` (divide the running value into the given subfield's value), `div_sum_by_sum` (sum two groups of subfields and divide one by the other), and `replace`.

```
{
  "id": "engagement_rate",
  "subfields": [
    "likes",
    "profile_views",
    "shares"
  ],
  "calculation": [
    {
      "operation": "math",
      "parameters": [
        { "type": "plus", "sfnum": 2 },
        { "type": "plus", "sfnum": 3 },
        { "type": "div_target", "sfnum": 1 }
      ]
    }
  ]
}
```

With `likes` = 10, `profile_views` = 2, and `shares` = 3, this computes `likes / (profile_views + shares)` = `10 / 5` = `2`.

### Dimension operations

| Operation | Parameters | Description |
| --- | --- | --- |
| `concat` | 1: glue string | Joins the subfield values into one string, separated by the glue. |
| `subfield_value` | 1: subfield index | Takes the value from the given subfield and discards the rest. |
| `take_1st_nonempty` | None | Takes the value of the first subfield that isn't empty. |
| `replace_with_subfield_values` | 1: template string with placeholders `{sf1}`–`{sf4}` | Fills a template string with subfield values. |
| `filter` | 1: subfield index, 2: `EQUALS` or `NOT_EQUALS`, 3: value to check | Blanks the value when the condition matches the subfield (the row is kept, the value is emptied). |
| `remove_row_if` | 1: subfield index, 2: `EQUALS` or `NOT_EQUALS`, 3: value to check | Removes the whole row from the result when the condition is true for the subfield. |
| `date_diff` | Same as the metric `date_diff` above | Calculates the difference between two dates. |
| `discard_after_1st` | None | Keeps only the first subfield's value and discards the rest. |

#### Example: concat

```
{
  "id": "full_name",
  "subfields": [
    "first_name",
    "last_name"
  ],
  "calculation": [
    {
      "operation": "concat",
      "parameters": [
        " "
      ]
    }
  ]
}
```

With `first_name` = `Jane` and `last_name` = `Doe`, the result is `Jane Doe`.

#### Example: replace_with_subfield_values

```
{
  "id": "campaign_url",
  "subfields": [
    "campaign_id"
  ],
  "calculation": [
    {
      "operation": "replace_with_subfield_values",
      "parameters": [
        "https://www.example.com/campaign/{sf1}/"
      ]
    }
  ]
}
```

With `campaign_id` = `123456`, the result is `https://www.example.com/campaign/123456/`.

## Value formatting

Value formatting transforms a field's value before it's returned, using the `valueFormat` property. This is useful when the raw value isn't in the shape you want — for example converting a timestamp into a plain date, rounding a number, or cleaning up a string.

`valueFormat` takes an `items` array, where each item has an `operation` and, for most operations, `parameters`. Items run in order, so you can chain several transformations.

```
{
  "id": "article_creation_date",
  "label": "Ad creation date",
  "dataType": "string.time.date",
  "value": {
    "source": "jsonPath",
    "value": "$.article_creation_date"
  },
  "valueFormat": {
    "items": [
      {
        "operation": "convert_date",
        "parameters": ["U", "Y-m-d"]
      }
    ]
  }
}
```

When a field also has a `calculation`, the calculation runs first and the value formatting is applied to its result — so you can, for example, round a derived rate.

### Dimension formatting operations

| Operation | Parameters | Description |
| --- | --- | --- |
| `none` | None | No formatting; returns the value unchanged. |
| `convert_date` | 1: source date format (PHP `date` format; `U` for Unix timestamp, or empty to auto-detect), 2: output date format | Converts a date from one format to another. E.g. `["U", "Y-m-d"]` turns `1626862281` into `2021-07-21`. |
| `start_date` | 1: output date format | Returns the query's start date in the given format. E.g. `["d.m.Y"]` → `01.06.2021`. |
| `prepend` | 1: constant to add in front | Prepends a constant to the value. E.g. `["prefix_"]` turns `supermetrics` into `prefix_supermetrics`. |
| `append` | 1: constant to add at the end | Appends a constant to the value. E.g. `["_postfix"]` turns `supermetrics` into `supermetrics_postfix`. |
| `divide` | 1: divisor | Divides the value by the divisor. E.g. `[1000]` turns `1234567` into `1234.567`. |
| `static` | 1: constant to return | Replaces the value with a fixed constant. |
| `implode` | 1: glue string | Joins an array value into a single string using the glue. E.g. `["-"]` turns `["first","second","third"]` into `first-second-third`. |
| `explode` | 1: delimiter | Splits a string value into an array on the delimiter. E.g. `[";"]` turns `first;second;third` into `["first","second","third"]`. |
| `url_parameter` | 1: parameter name | Returns the value of a query parameter from a URL value. E.g. `["param2"]` on `https://example.com?param1=val1&param2=val2` returns `val2`. |
| `capitalize` | 1 (optional): a string to replace with a single space | Capitalizes the first character and lowercases the rest. If a parameter is given, each occurrence of that string is first replaced with a space. E.g. with `["-"]`, `supermetrics-is-GREAT!` becomes `Supermetrics is great!`. |
| `regular_expression_replace` | 1: PCRE pattern, 2: replacement string | Replaces text matching the pattern. E.g. `["/~/", ":"]` replaces `~` with `:`. |

### Metric formatting operations

| Operation | Parameters | Description |
| --- | --- | --- |
| `none` | None | No formatting; returns the value unchanged. |
| `divide` | 1: divisor | Divides the value by the divisor. E.g. `[1000]` turns `1234567` into `1234.567`. |
| `multiply` | 1: multiplier | Multiplies the value by the multiplier. E.g. `[0.1]` turns `1234567` into `123456.7`. |
| `round` | 1: precision (number of decimals) | Rounds the value. E.g. `[2]` turns `123.4567` into `123.46`. |
| `format_separators` | None | Removes thousands separators and normalizes the decimal separator to `.`. E.g. `123 456,78` and `123,456.78` both become `123456.78`. |
| `to_percent` | None | Multiplies the value by 100. E.g. `0.23` becomes `23`. |
| `to_micros` | None | Multiplies the value by 1,000,000. E.g. `0.23` becomes `230000`. |
| `to_null` | None | Sets the value to `null`. |
| `to_1` | None | Sets the value to `1`. |
| `regular_expression_replace` | 1: PCRE pattern, 2: replacement string | Replaces text matching the pattern. |

> **Note:** A single `operation`/`parameters` pair can also be set directly on `valueFormat` (without `items`) — but the `items` array is the current form and should be used for new configurations.