Omni’s modeling syntax provides flexible and powerful ways to reference fields, views, and filters in your data models. This guide outlines best practices for using field references and Mustache templating to make your models clear, maintainable, and dynamic.
Field Reference Best Practices
When referencing fields, best practices is to use the fully scoped syntax unless you are inside the same view file. This ensures that field references remain explicit and unambiguous, especially in large models.
Fully Scoped Syntax
Use the following pattern:
${view_name.field_name}
This syntax ensures Omni correctly resolves both the view and field, regardless of where it’s used.
Understanding view_name
In Omni, the view name typically follows the pattern:
schema_name__view_name
Note: There are two underscores between the schema and view names.
You can always confirm the correct reference by checking the comment at the top of a view file:
# Reference this view as analytics__orders
If a default_schema is set on the connection, any views in that schema will omit the schema prefix, simplifying references to views in the default schema:
${orders.total_amount}
instead of
${default_schema__orders.total_amount}
Referencing Inside a View File
When you’re working within the same view file, Omni allows shorthand syntax:
${field_name} – refers to a field within the same view
${view_name} – can reference another view directly (depending on context)
Using Mustache for Dynamic References (Templated Filters)
Omni supports Mustache templating for dynamic or conditional logic within your models. This is especially useful for parameterizing filters, attributes, and SQL fragments. Mustache syntax can also be used to build dynamic content on the dashboard.
- Referencing User Attributes
User attributes can be accessed via the omni_attributes object:
{{ omni_attributes.attribute_name }}
Use this to dynamically insert attribute values into queries or logic blocks.
2. Referencing Templated Filters
Templated filters allow models to dynamically adapt to user selections or parameters.
Basic Filter Value Reference
Use filter values as strings (for example, in a FROM or WHERE clause):
{{ filters.view.field.value }}
Date Range Start and End References
When dealing with date filters, you can reference the start and end of a templated range:
{{ filters.view.field.range_start }}
{{ filters.view.field.range_end }}
This dynamically computes time differences between the start and end of a chosen date range.
Default values
Default values can be set with templated filters using default value syntax.
{{^ view.field.filter }} default_value_sql{{/ view.field.filter }}
For more on templated filters, see our docs