custom_formats - Model files

Custom formats are format objects that can be defined once in a model file and referenced throughout your model. Unlike constants, which hold string values, custom formats are complete format objects that can include conditional logic, named formats, Excel-style strings, and other format features. Custom formats are resolved when formatting values in queries and visualizations, making them ideal for format patterns that need to be centrally managed and consistently applied across multiple fields. For example:

Complex conditional formats that vary based on field values
Format patterns that include named formats or custom strings
Formats that need to be maintained in a single location and used across multiple dimensions or measures

Custom formats are also inherited by shared extension models.

Syntax

custom_formats accepts either a string or a conditional object:

String
Conditional

custom_formats:
  <format_name>: <format_string>

custom_formats:
  <format_name>:
    depends_on:
      <field|user_attribute|filter>: <field_name|user_attribute_reference|filter_name>
      conditions:
        - condition:
            <filter_expression>
          value: <format_string>
    else: <fallback_format_string>

Properties

custom_formats is a map of format definitions where each key is the format name. Names must be unique within the model.

String
Conditional

string

required

The format definition. This can be any valid format type:

A named format (e.g., currency_2, percent_1)
An Excel-style string (e.g., '#,##0.00 "kg"')
A reference to another custom format

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.

Hide depends_on properties

string

The name of a field in the same view.

string

The reference of a user attribute.

string

The name of a filter applied to the query.

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

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.

string

required

The format string to apply when the condition matches. Can be a named format or an Excel-style string.

string

Fallback format string used when no condition matches.

Difference from constants

While both custom_formats and constants enable reusability, they serve different purposes:

Use custom_formats when you need to define a complete format object that will be used across multiple fields
Use constants when you need a reusable string value that might be used in format strings or other contexts

Referencing custom formats

Once defined in the model file, custom formats can be referenced in dimension and measure format parameters using either a plain string or explicit object syntax: Plain string syntax (recommended):

format: <format_name>

Explicit object syntax:

format:
  custom_format: <format_name>

The plain string syntax is the recommended approach — it’s cleaner and more concise.

Examples

Named format reference

Define custom formats that reference built-in named formats:

Model file

custom_formats:
  standard_currency: currency_2
  high_precision: number_4
  compact_number: big_1

View file

dimensions:
  price:
    sql: '"price"'
    format: standard_currency
measures:
  total_revenue:
    sql: '"amount"'
    aggregate_type: sum
    format: standard_currency

Excel-style strings

Define custom formats with Excel-style strings:

Model file

custom_formats:
  weight_display: '#,##0.00 "kg"'
  margin_bps: '#,##0.00 "bps"'
  compact_time: 'm:ss "min"'

View file

dimensions:
  product_weight:
    sql: '"weight"'
    format: weight_display
measures:
  avg_margin:
    sql: '"margin"'
    aggregate_type: avg
    format: margin_bps

Conditional formats

Define custom formats with conditional logic that selects different formats based on field values:

Model file

custom_formats:
  dynamic_currency:
    depends_on:
      field: orders.currency_code
      conditions:
        - condition:
            is: USD
          value: usdcurrency_2
        - condition:
            is: GBP
          value: gbpcurrency_2
        - condition:
            is: EUR
          value: eurcurrency_2
    else: currency_2
  
  performance_indicator:
    depends_on:
      field: metrics.status
      conditions:
        - condition:
            is: excellent
          value: '"🚀 "0.0'
        - condition:
            is: poor
          value: '"📉 "-0.0'
    else: number_2

View file

dimensions:
  total_amount:
    sql: '"amount"'
    format: dynamic_currency
measures:
  performance_score:
    sql: '"score"'
    aggregate_type: avg
    format: performance_indicator

Combining custom formats with model constants

Custom formats can reference model constants to create even more flexible formatting patterns.

Use constants to add a unit suffix
Use constants to specify time and numeric formats with suffixes

Model file

constants:
  unit_suffix:
    value: "units"

custom_formats:
  quantity_format: '#,##0 "@{unit_suffix}"'

View file

measures:
  total_quantity:
    sql: '"quantity"'
    aggregate_type: sum
    format: quantity_format

Model file

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

View file

measures:
  avg_duration:
    sql: '"duration_secs"'
    aggregate_type: avg
    format: "@{compact_time}"
  margin:
    sql: '"margin_bps"'
    aggregate_type: avg
    format: "@{margin_display}"

Getting started

Manage content

Analyze & build

Visualize & present

Deliver content

Model data

Manage integrations

custom_formats - Model files

Syntax

Properties

Difference from constants

Referencing custom formats

Examples

Named format reference

Excel-style strings

Conditional formats

Combining custom formats with model constants

​Syntax

​Properties

​Difference from constants

​Referencing custom formats

​Examples

​Named format reference

​Excel-style strings

​Conditional formats

​Combining custom formats with model constants

Syntax

Properties

Difference from constants

Referencing custom formats

Examples

Named format reference

Excel-style strings

Conditional formats

Combining custom formats with model constants