format

The format parameter sets the default display format for a dimension’s values. Numeric, currency, and date dimensions can use one of Omni’s named formats, an Excel-style custom format string, or a conditional format that selects a format dynamically. Formats can also be set on a per-query basis from visualization configuration, using the same format types.

Grouping is not impacted when format is used, as formatting is applied after SQL runs. To handle grouping with truncation, use ROUND() or FLOOR().

Syntax

format accepts either a string or a conditional object:

String
Conditional

<dimension_name>:
  format: <format_name>

<dimension_name>:
  format:
    depends_on:
      field: <field_name>
      conditions:
        - condition:
            <filter_expression>
          value: <format_string>
    else: <fallback_format_string>

Choosing a format type

format accepts three shapes. Pick the one that matches your use case:

Use this	When you want to	Examples
Named format	Apply a built-in format. Start here — named formats handle currency, percentages, compact numbers, and d3 time formats. Use a currency prefix like `usd`, `gbp`, or `jpy` for a specific currency; omit the prefix to use the locale’s default.	`currency_2`, `usdaccounting_0`, `percent_1`, `big_2`
Custom format string	Control layout beyond what named formats offer — append units, add text, use semicolon sections for positive/negative display, or interpolate other fields with Mustache.	`'#,##0.00 "kg"'`, `'"🚀 "0.0;"📉 "-0.0'`
Conditional format	Choose the format at runtime based on a field value, user attribute, or filter. Each branch can reference a named format, a custom string, or a model constant.	`depends_on: { field: currency_code }`

Named formats

Numeric and currency formats default to two decimal places, with the exception of id. You can explicitly set decimal places by appending _<number_of_places> to a numeric or currency format. For example, format: number_4, format: big_1, format: usdaccounting_0. When decimal length isn’t set, decimals will be truncated to the shortest possible length for each row.

Numeric formats

Format	Example	Notes
`number`	1,234.50 (`number_2`)
`percent`	24.4% (`percent_1`)
`id`	123450	Numbers, no commas
`billions`	1.20B (`billions_2`)
`millions`	5.6M (`millions_1`)
`thousands`	8.90K (`thousands_2`)
`big`	5.60M; 1.23K; 12.23 (`big_2`)	Uses `millions` if `>1M`; `thousands` if `>1000`; otherwise `number`

Currency formats

Currency formats are available for USD, EUR, GBP, AUD, JPY, and BRL. Prefix the format category with the currency code (for example, usdcurrency, jpyaccounting). Formats without a currency prefix use the organization’s default currency.

Format category	Example	Notes
`accounting` (e.g. `usdaccounting`, `jpyaccounting`)	$(1,234.50) (`usdaccounting_2`)
`currency` (e.g. `usdcurrency`, `gbpcurrency`)	-£1,234.50 (`gbpcurrency_2`)
`bigcurrency` (e.g. `bigusdcurrency`, `bigjpycurrency`)	€5.60M; €1.23K; €12.23 (`biggbpcurrency_2`)	Compact display
`financial` (e.g. `audfinancial`, `brlfinancial`)	(1,234.50) (`financial_2`)	Does not contain a currency mark
`bigaccounting`, `bigfinancial` (e.g. `bigusdaccounting`, `bigjpyfinancial`)	Same compact rules as `big*` formats

Time formats

Format	Notes
d3 time formats	Individual timeframe elements can be formatted using `timeframe_metadata`. Refer to the Examples.
`"%Y-%m"`
`"%Y-%m-%d"`
`"%Y-%m-%d %H:%M:%S"`

Custom format strings

In addition to named formats, format accepts Excel-style custom format strings. These follow the same conventions as spreadsheet number formats.

For standard currency display, prefer named formats like usdcurrency_2 or gbpaccounting_0. Use custom format strings when you need layout control that named formats don’t offer — for example, appending units, mixing text with numbers, or using semicolon sections for positive/negative display.

Pattern	Description	Example output
`#,##0`	Number with thousands separator, no decimals	1,234
`#,##0.00`	Number with thousands separator, 2 decimals	1,234.56
`0%`	Percentage, no decimals	75%
`0.00%`	Percentage, 2 decimals	75.00%
`0.00E+00`	Scientific notation	1.23E+03
`#,##0 "units"`	Number with literal text suffix	1,234 units
`#,##0.0,`	Divide by 1,000 (trailing comma)	1.2
`#,##0.0,,"M"`	Divide by 1,000,000 with suffix	1.2M

Semicolon-separated sections

Excel-style format strings support up to four sections separated by semicolons, applied in order: positive values; negative values; zero; text. You can omit trailing sections — for example, two sections apply the first to positive values and the second to negative values.

format: '"🚀 "0.0;"📉 "-0.0;0'

This renders:

Positive values as 🚀 1.5
Negative values as 📉 -1.5
Zero as 0

Use quoted YAML strings so " and ; parse correctly.

Mustache field references

Custom format strings can include Mustache references to other field values using {{view_name.field_name.property}}. This lets you build format strings that incorporate values from other fields in the query, such as a dynamic currency symbol. Supported properties:

Property	Description
`value`	The formatted field value
`raw`	The unformatted field value
`value_url_encoded`	The URL-encoded formatted value

Dynamic currency symbol from another field

total:
  sql: '"total"'
  format: '#,##0.00 "{{orders.currency_symbol.value}}"'

Referencing other fields in a format string implicitly requires those fields to be included in the query results. Omni will automatically add them, which may change the GROUP BY clause of the generated SQL.

Conditional format

Conditional format applies different format strings depending on a runtime value — for example, formatting a revenue measure with the right currency symbol based on a currency_code dimension, or showing different decimal precision based on a user attribute. Define a depends_on source and an ordered list of conditions using Omni filter syntax. The first matching condition determines the format. If no condition matches, the else format is used.

format

object

Hide format properties

depends_on

object

required

Defines the source value to evaluate conditions against. Set exactly one of field, user_attribute, or filter. See Resolution timing for how each option resolves.

Hide depends_on properties

field

string

The name of a field in the same view.

user_attribute

string

The reference of a user attribute.

filter

string

The name of a filter applied to the query.

conditions

object[]

required

An ordered list of condition entries. Each entry contains a condition using Omni filter syntax and a value specifying the format string to apply when the condition matches.

Hide conditions properties

condition

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.

value

string

required

The format string to apply when the condition matches. Can be a named format or a custom format string.

else

string

Fallback format string used when no condition matches.

Resolution timing

The depends_on source determines when and how the format is resolved:

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.

Examples

Currency format

sale_price:
  format: currency_2

Big number format

revenue:
  format: big_2

Time format with timeframe metadata

created_at:
  timeframe_metadata:
    month:
      format: "%Y-%m-%d"

Custom Excel-style format with units

weight_kg:
  sql: '"weight"'
  format: '#,##0.00 "kg"'

Conditional format based on a field value

dimensions:
  currency_code:
    sql: '"currency_code"'
measures:
  revenue:
    sql: '"amount"'
    aggregate_type: sum
    format:
      depends_on:
        field: currency_code
        conditions:
          - condition:
              is: "USD"
            value: usdcurrency_0
          - condition:
              is: "GBP"
            value: gbpcurrency_0
        else: currency_0

Conditional format with numeric conditions

dimensions:
  age:
    sql: '"age"'
measures:
  total:
    sql: '"amount"'
    aggregate_type: sum
    format:
      depends_on:
        field: age
        conditions:
          - condition:
              greater_than: "18"
            value: "#,##0.00"
          - condition:
              between:
                - 10
                - 18
            value: "#,##0"
        else: "0"

Conditional format based on a user attribute

revenue:
  sql: '"amount"'
  aggregate_type: sum
  format:
    depends_on:
      user_attribute: preferred_currency
      conditions:
        - condition:
            is: "USD"
          value: usdcurrency_2
        - condition:
            is: "EUR"
          value: eurcurrency_2
      else: currency_2

Conditional format based on a filter value

revenue:
  sql: '"amount"'
  aggregate_type: sum
  format:
    depends_on:
      filter: currency_filter
      conditions:
        - condition:
            is: "USD"
          value: usdcurrency_2
        - condition:
            is: "GBP"
          value: gbpcurrency_2
      else: currency_2

Branch formats referencing model constants

constants:
  high_precision:
    value: "#,##0.0000"
  low_precision:
    value: "#,##0.0"

measures:
  measurement:
    sql: '"value"'
    aggregate_type: avg
    format:
      depends_on:
        field: unit_type
        conditions:
          - condition:
              is: "scientific"
            value: "@{high_precision}"
          - condition:
              is: "summary"
            value: "@{low_precision}"
      else: "@{low_precision}"

Reporting currency filter driving named formats

filters:
  reporting_currency:
    type: string
    suggestion_list:
      - value: converted_EUR
        label: Converted to EUR
      - value: converted_USD
        label: Converted to USD

measures:
  revenue_display:
    sql: '"amount"'
    aggregate_type: sum
    format:
      depends_on:
        filter: reporting_currency
        conditions:
          - condition:
              is: converted_EUR
            value: eurcurrency
          - condition:
              is: converted_USD
            value: usdcurrency
      else: usdcurrency

Model constants in format strings

You can reuse a model constant inside any format string — named, custom Excel-style, or a conditional format branch — with @{constant_name}:

Model file

constants:
  compact_time:
    value: 'm:ss "min"'
  margin_display:
    value: '#,##0.00 "bps"'

Dimension or measure

dimensions:
  margin:
    sql: '"margin_bps"'
    format: "@{margin_display}"

Constants are most useful for custom Excel-style patterns that appear in several fields, or that you want to maintain in one place. If a named format like usdcurrency_2 or percent_1 already does what you need, use it directly — there is no benefit to wrapping a named format in a constant.

Constants are validated against the model: unknown names and malformed @{...} references surface as model validation issues in the IDE.

Locale and number formatting

The default_numeric_locale model parameter controls how all formatted numbers are displayed — including the thousands delimiter, decimal delimiter, and default currency symbol. When you set a locale, every named format and custom format string in that model respects the locale’s conventions automatically.

Locale	Thousands	Decimal	Default currency	`currency_2` renders as
`en_US` (default)	`,`	`.`	`$`	$1,234.50
`en_GB`	`,`	`.`	`£`	£1,234.50
`fr_FR`	(space)	`,`	`€`	€1 234,50
`de_DE`	`.`	`,`	`€`	€1.234,50
`ja_JP`	`,`	`.`	`¥`	¥1,234.50
`br_BR`	`.`	`,`	`R$`	R$1.234,50
`nl_NL`	`.`	`,`	`€`	€1.234,50

Setting the locale

Set default_numeric_locale in any model file:

Model file

default_numeric_locale: fr_FR

Dynamic locale per user

Use a user attribute so each user sees numbers formatted for their region:

Model file

default_numeric_locale: {{ omni_attributes.user_locale }}

This resolves at query time. A user whose user_locale attribute is de_DE sees 1.234,50 €, while a user with en_US sees $1,234.50 — from the same query and the same format strings.

Locale interaction with format types

Named formats (currency_2, accounting_0, etc.) — the locale’s default currency symbol is used when no currency prefix is specified. Prefixed formats like usdcurrency_2 override the locale’s default symbol.
Custom format strings (#,##0.00) — the #, ,, . tokens are locale-aware. A format of #,##0.00 renders 1.234,50 under de_DE.
Currency-prefixed named formats (gbpcurrency_2, jpyaccounting_0) — always use the specified currency symbol, regardless of locale. The delimiter and decimal conventions still come from the locale.

Durations and wallclock-style times

Timestamp dimensions should use strftime-style strings (they must include % in the format). See Time formats. For numeric durations stored as milliseconds (or seconds) that you want to display as hours, minutes, or seconds, you need to convert the value to a fraction of a day before applying a time format string. Omni uses the same convention as spreadsheets: one day = 86400000 milliseconds. Divide your millisecond value by 86400000 to get the fraction that Excel-style time format codes expect. Then use either:

A custom format string (possibly through a model constant), or
A conditional format that picks a shorter or longer pattern based on how large the duration is (for example, show h:mm:ss when duration is at least 1 hour, otherwise m:ss).

h displays clock hours (wraps at 24). If your durations can exceed 24 hours, use [h] for elapsed hours — for example, [h]:mm:ss renders 25 hours as 25:00:00 instead of 1:00:00. The same applies to [m] for elapsed minutes.

Duration dimension: scale ms to Excel day fraction

dimensions:
  total_duration_ms:
    sql: '"total_duration_ms"'

  duration_as_excel_day:
    sql: ${total_duration_ms} / 86400000.0
    label: Total duration
    format:
      depends_on:
        field: total_duration_ms
        conditions:
          - condition:
              greater_than_or_equal_to: 3600000
            value: 'h "hr" mm "min" ss.0 "sec"'
          - condition:
              greater_than_or_equal_to: 60000
            value: 'm "min" ss.00 "sec"'
      else: 'ss.000 "sec"'

Adjust the thresholds (3600000 ms = 1 hour, 60000 ms = 1 minute) to control when the display switches between hour-, minute-, and second-scale patterns.

Rich text in data tables

The markdown parameter is separate from format:

Parameter	Use it for
`format`	Numeric, currency, percentage, and date/time display formatting after SQL runs.
`markdown`	A Mustache template whose output is rendered as Markdown in data table cells (for example, bold labels, links, badges).

You can set both on the same field: format affects how measures and numbers appear in standard value cells; markdown applies when the column is shown as Markdown in a table visualization. See Dimension markdown and Measure markdown for syntax and examples.

Getting started

Manage content

Analyze & build

Visualize & present

Deliver content

Model data

Manage integrations

Syntax

Choosing a format type

Named formats

Numeric formats

Currency formats

Time formats

Custom format strings

Semicolon-separated sections

Mustache field references

Conditional format

Resolution timing

Examples

Model constants in format strings

Locale and number formatting

Setting the locale

Dynamic locale per user

Locale interaction with format types

Durations and wallclock-style times

Rich text in data tables

Getting started

Manage content

Analyze & build

Visualize & present

Deliver content

Model data

Manage integrations

​Syntax

​Choosing a format type

​Named formats

​Numeric formats

​Currency formats

​Time formats

​Custom format strings

​Semicolon-separated sections

​Mustache field references

​Conditional format

​Resolution timing

​Examples

​Model constants in format strings

​Locale and number formatting

​Setting the locale

​Dynamic locale per user

​Locale interaction with format types

​Durations and wallclock-style times

​Rich text in data tables

Syntax

Choosing a format type

Named formats

Numeric formats

Currency formats

Time formats

Custom format strings

Semicolon-separated sections

Mustache field references

Conditional format

Resolution timing

Examples

Model constants in format strings

Locale and number formatting

Setting the locale

Dynamic locale per user

Locale interaction with format types

Durations and wallclock-style times

Rich text in data tables