> ## 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.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/modeling/dimensions/parameters/format",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# format

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

export const field_type_0 = "dimension"

export const field_type_upper_0 = "Dimension"

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)

      <Tip>
        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.
      </Tip>
    </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="Time format with timeframe metadata" theme={null}
created_at:
  timeframe_metadata:
    month:
      format: "%Y-%m-%d"
```

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

```yaml title="Custom format reference" theme={null}
total_amount:
  sql: '"amount"'
  format: dynamic_currency
```

```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
```