Skip to main content
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: 
custom_formats:
  <format_name>: <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.
​
format_name
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

​
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:
            equals: USD
          value: usdcurrency_2
        - condition:
            equals: GBP
          value: gbpcurrency_2
        - condition:
            equals: EUR
          value: eurcurrency_2
    else: currency_2
  
  performance_indicator:
    depends_on:
      field: metrics.status
      conditions:
        - condition:
            equals: excellent
          value: '"🚀 "0.0'
        - condition:
            equals: 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.
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