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.
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>
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.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
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 fieldAt display time (per row) Evaluated against each row’s value after query results are returned. Each row can resolve to a different format. user_attributeAt query preparation time The user attribute value is evaluated once. The entire field uses the single resolved format. filterAt query preparation time The filter value is evaluated once. The entire field uses the single resolved format.
Hide depends_on properties
The name of a field in the same view.
The name of a filter applied to the query.
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
An Omni filter expression. Supported condition types: Condition Description Example isExact match is: "USD"notNot equal not: "USD"greater_thanGreater than greater_than: "1000"greater_than_or_equal_toGreater than or equal to greater_than_or_equal_to: "1000"less_thanLess than less_than: "0"less_than_or_equal_toLess than or equal to less_than_or_equal_to: "100"betweenBetween two values (inclusive) between: [10, 100]not_betweenOutside a range not_between: [10, 100]starts_withString starts with starts_with: "US"ends_withString ends with ends_with: "Corp"containsString contains contains: "special"not_starts_withString does not start with not_starts_with: "US"not_ends_withString does not end with not_ends_with: "Corp"not_containsString does not contain not_contains: "special"
Additional conditions follow the same structure as filters . The format string to apply when the condition matches. Can be a named format or an Excel-style string.
Fallback format string used when no condition matches.
Difference from constants While both custom_formats and constants
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
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):Explicit object syntax :format : custom_format : <format_name>
The plain string syntax is the recommended approach — it’s cleaner and more concise.
Examples Define custom formats that reference built-in named formats:
custom_formats : standard_currency : currency_2 high_precision : number_4 compact_number : big_1
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:
custom_formats : weight_display : '#,##0.00 "kg"' margin_bps : '#,##0.00 "bps"' compact_time : 'm:ss "min"'
dimensions : product_weight : sql : '"weight"' format : weight_display measures : avg_margin : sql : '"margin"' aggregate_type : avg format : margin_bps
Define custom formats with conditional logic that selects different formats based on field values:
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
dimensions : total_amount : sql : '"amount"' format : dynamic_currency measures : performance_score : sql : '"score"' aggregate_type : avg format : performance_indicator
Custom formats can reference model constants to create even more flexible formatting patterns.
constants : unit_suffix : value : "units" custom_formats : quantity_format : '#,##0 "@{unit_suffix}"'
measures : total_quantity : sql : '"quantity"' aggregate_type : sum format : quantity_format
constants : compact_time : value : 'm:ss "min"' margin_display : value : '#,##0.00 "bps"'
measures : avg_duration : sql : '"duration_secs"' aggregate_type : avg format : "@{compact_time}" margin : sql : '"margin_bps"' aggregate_type : avg format : "@{margin_display}"
