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

# format - Measures

> Sets default formatting for measures—named formats, Excel-style strings, conditional formats, model constants, and Markdown table cells.

export const field_type_0 = "measure"

export const field_type_upper_0 = "Measure"

The `format` parameter sets the default display format for a {field_type_0}'s values. {field_type_upper_0}s can use one of Omni's [named formats](/modeling/models/format-values#named-formats), an [Excel-style string](/modeling/models/format-values#excel-style-strings), a [Mustache template](/modeling/models/format-values#mustache-templates), or a [conditional format](/modeling/models/format-values#conditional-formats) that selects a format dynamically.

Formats can also be set on a per-query basis from visualization configuration, using the same format types.

See [Formatting values](/modeling/models/format-values) for more information on format types and examples.

<Note>
  Formats are applied **after** the SQL runs, so they do not impact grouping. To handle grouping with truncation, use `ROUND()` or `FLOOR()`.
</Note>

## Syntax

`format` accepts either a string or a conditional object:

<Tabs>
  <Tab title="String">
    ```yaml theme={null}
    <dimension_or_measure_name>:
      format: <format_string>
    ```
  </Tab>

  <Tab title="Conditional">
    ```yaml theme={null}
    <dimension_or_measure_name>:
      format:
        depends_on:
          field: <field_name>
          conditions:
            - condition:
                <filter_expression>
              value: <format_string>
        else: <fallback_format_string>
    ```
  </Tab>
</Tabs>

## Properties

Use the tabs to view the properties for string values and conditional objects.

<Tabs>
  <Tab title="String" id="string-properties">
    <ParamField path="format" type="string" required>
      The format definition. This can be any valid [format type](/modeling/models/format-values#choosing-a-format-type):

      * A named format (e.g., `currency_2`, `percent_1`)
      * An Excel-style string (e.g., `'#,##0.00 "kg"'`)
      * A reference to a model-level [custom format](/modeling/models/custom-formats)

      See [Formatting values](/modeling/models/format-values) for the full reference on all format types, including named formats, Excel-style strings, conditional formats, model constants, locale settings, and more.
    </ParamField>
  </Tab>

  <Tab title="Conditional" id="conditional-properties">
    <ParamField path="depends_on" type="object" required>
      Defines the source value to evaluate conditions against. Set exactly one of `field`, `user_attribute`, or `filter`.

      These options resolve as follows:

      | Source | Resolution timing | Behavior |
      | - | - | - |
      | `field` | At display time (per row) | Evaluated against each row's value after query results are returned. Each row can resolve to a different format. |
      | `user_attribute` | At query preparation time | The user attribute value is evaluated once. The entire field uses the single resolved format. |
      | `filter` | At query preparation time | The filter value is evaluated once. The entire field uses the single resolved format. |

      <Expandable title="depends_on properties" defaultOpen="true">
        <ParamField path="field" type="string">
          The name of a field in the same view.
        </ParamField>

        <ParamField path="user_attribute" type="string">
          The reference of a [user attribute](/administration/users/attributes).
        </ParamField>

        <ParamField path="filter" type="string">
          The name of a filter applied to the query.
        </ParamField>

        <ParamField path="conditions" type="object[]" required>
          An ordered list of condition entries. Each entry contains a `condition` using [Omni filter syntax](/modeling/filters) and a `value` specifying the format string to apply when the condition matches.

          <Expandable title="conditions properties" defaultOpen="true">
            <ParamField path="condition" type="object" required>
              An Omni filter expression. Supported condition types:

              | Condition | Description | Example |
              | - | - | - |
              | `is` | Exact match | `is: "USD"` |
              | `not` | Not equal | `not: "USD"` |
              | `greater_than` | Greater than | `greater_than: "1000"` |
              | `greater_than_or_equal_to` | Greater than or equal to | `greater_than_or_equal_to: "1000"` |
              | `less_than` | Less than | `less_than: "0"` |
              | `less_than_or_equal_to` | Less than or equal to | `less_than_or_equal_to: "100"` |
              | `between` | Between two values (inclusive) | `between: [10, 100]` |
              | `not_between` | Outside a range | `not_between: [10, 100]` |
              | `starts_with` | String starts with | `starts_with: "US"` |
              | `ends_with` | String ends with | `ends_with: "Corp"` |
              | `contains` | String contains | `contains: "special"` |
              | `not_starts_with` | String does not start with | `not_starts_with: "US"` |
              | `not_ends_with` | String does not end with | `not_ends_with: "Corp"` |
              | `not_contains` | String does not contain | `not_contains: "special"` |

              Additional conditions follow the same structure as [filters](/modeling/filters).
            </ParamField>

            <ParamField path="value" type="string" required>
              The format string to apply when the condition matches. Can be a named format or an Excel-style string.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="else" type="string">
      Fallback format string used when no condition matches.
    </ParamField>
  </Tab>
</Tabs>

## Examples

```yaml title="Currency format" theme={null}
sale_price:
  format: currency_2
```

```yaml title="Big number format" theme={null}
revenue:
  format: big_2
```

```yaml title="Custom Excel-style format with units" theme={null}
avg_weight:
  sql: '"weight"'
  aggregate_type: avg
  format: '#,##0.00 "kg"'
```

```yaml title="Custom format reference" theme={null}
avg_margin:
  sql: '"margin"'
  aggregate_type: avg
  format: margin_bps
```

```yaml title="Conditional format" theme={null}
revenue:
  format:
    depends_on:
      field: orders.currency_code
      conditions:
        - condition:
            equals: USD
          value: usdcurrency_2
        - condition:
            equals: EUR
          value: eurcurrency_2
      else: currency_2
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.