Skip to main content

Model File

Topics are not the only object in the model file, the model file also holds model-wide configuration for a given analytical environment.

Example Model File

Examples of model file metadata:

auto_run: true

ignored_schemas:
- dbt_test1
- dbt_test2

included_schemas:
- public
- core_data

dynamic-schemas:
- public
- schema_attribute

ignored_views:
- users
- products

access_grants:
- grant_name
- user_attribute
- allowed_values

cache_policies:
name_of_cache_policy:
max_cache_age: "1 minute"
cache_this_forever:
max_cache_age: "24 hours"
dont_cache_at_all:
max_cache_age: "0 seconds"

default_cache_policy: name_of_cache_policy

topics:
...
cache_policy: name_of_cache_policy

access_grants:

access_grants:
<insert_access_grant_name>:
user_attribute: "test"
allowed_values: [val1, val2]

Access Grants:

  • Access grants are defined with a unique name, replace <insert_access_grant_name>: with any string to reference the access grant by
  • Each access grant specifies a user_attribute and a list of allowed_values
  • Users will be granted access if their corresponding user_attribute: has any of the specified allowed_values:

Topics and Required Access Grants:

  • Topics can be associated with access control through the use of required_access_grants:
  • If a user possesses all the required access grants for a particular topic, they are allowed access to that topic
  • Without the necessary access grants, the user cannot view the topic or make direct queries related to it.

Note on Access Grants and References:

  • Access grants are only applied to direct access and queries, i.e. they don't impact references within the model
    • For example, if a user cannot see field "a" but can see field "b," and "b" references "a," the user can still access and query using field "b."

auto_run:

auto_run: false
  • This will force all queries to require a run click to return new results
  • This may be a good option is there are concerns on cost running queries as you build queries, but will reduce UI interactivity

dynamic_schemas:

dynamic_schemas:
<insert_dynamic_schema_name>:
from_schema: <name_of_canonical_schema>
user_attribute: <user_attribute_name>
  • This feature supports embed use cases of Omni with customer data partitioned into separate, but identical schemas
  • The dynamic_schema: specified creates a copy of your canonical schema model as a virtual schema named dynamic_schema_name:. The views in this dynamic_schema are generated from the database schema named canonical_schema_name:. When generating SQL against the dynamic_schema: views, the user_attribute: assigned to the user running the query will be used when scoping table references.
  • This a top level model object for defining dynamic schemas. The dynamic_schema: parameter requires these parameters to be specified: dynamic_schema_name:, from_schema: and user_attribute:
  • All modeling will reference views in the dynamic schema with the following naming convention: dynamic_schema_name__<view_name>:

fiscal_month_offset:

fiscal_month_offset: 11
  • This will set a fiscal calendar in Omni, enabling modelers to add fiscal time metrics to all time dimension groups and to the filter UX
  • Positive month offset will set a fiscal calendar in front of the Gregorian calendar date
    • For example: if your next fiscal year starts in February for Y+1, set the offset to 11 (ie first month of FY 2024 = Feb 2023)

ignored_schemas:

ignored_schemas:
- dbt_test1
- dbt_test2
  • This will exclude schemas that would be available in the workbook experience
  • Note ignored schemas will still be available to query in SQL
  • Omni expects a list either in brackets (comma delimited) or bulleted, tabbed list

included_schemas:

included_schemas:
- public
- core_data
  • This will explicitly include only schemas listed in the workbook experience
  • Note schemas excluded from this list will still be available to query in SQL
  • Omni expects a list either in brackets (comma delimited) or bulleted, tabbed list

ignored_views:

ignored_views: [users, products]
  • This will exclude specific views from the workbook experience
  • Note ignored views will still be available to query in SQL
  • Omni expects a list either in brackets (comma delimited) or bulleted, tabbed list
  • This supports wildcard syntax, * for matching more than one view at a time within a schema
  • The separator syntax between schema and view can be __ or .

week_start_day:

week_start_day: Sunday
  • This will set all weeks to start on the given day of week, rather than the default (Monday)
  • Will impact OMNI_WEEK() and OMNI_DAY_OF_WEEK_NUMBER()

Cache Policies

Omni's default cache policy is 6 hours.

In the model file, you can customize the cache policy by using the cache_policies: parameter. This parameter creates cache policies that can be used at the model and topic level. Model defaults can be set using the default_cache_policy parameter, which will provide a new base policy overriding Omni's default cache policy. Topic level defaults can be set using the cache_policy: parameter within your desired topic in the model file.

Note, in the example above, policy_name_1 or policy_name_2 can be any chosen naming and will be used to reference the cache policies to set at the model or topic levels.

In short:

  1. Make 1-N cache_policies using a policy name and max_cache_age
  2. Set said policy to either default_cache_policy or a given topic's cache_policy

Dashboard-Specific Caching

The Omni caching system is most commonly used to set global defaults (the policies set on the shared model). That said, by editing the cache policy in a given workbook model or query model, the system also allows for dashboard-level (or even query-level) caching for specific use cases (say a TV operations dashboard).

cache_policy:

Sets a topic's cache policy.

topics:
fast_cache:
base_view: order_items
joins: {}
cache_policy: policy_name_2

default_cache_topic:
base_view: order_items
joins: {}

In the example above, queries from the fast_cache topic will have a 5 minute max cache age, whereas queries from the default_cache_topic will leverage the model's default cache policy (24 hours) referenced as policy_name_1 set by the parameter default_cache_policy.

cache_policies:

Creates cache policies that can be applied at the model or topic level.

cache_policies:
policy_name_1:
max_cache_age: 24 hours
policy_name_2:
max_cache_age: 5 minutes

default_cache_policy: policy_name_1

topics:
fast_cache:
base_view: order_items
joins: {}
cache_policy: policy_name_2

default_cache_topic:
base_view: order_items
joins: {}

default_cache_policy:

Sets a model's default cache policy.

cache_policies:
policy_name_2:
max_cache_age: 5 minutes

default_cache_policy: policy_name_2

The cache policy used in the default_cache_policy: parameter applies to all topics within that model. A specific topic can use a different cache policy by using the cache_policy: within the topic. See cache_policy: for more details.

max_cache_age:

Defines the cache policy's time limit.

cache_policies:
policy_name_1:
max_cache_age: 24 hours
policy_name_2:
max_cache_age: 5 minutes

topics:
fast_cache:
base_view: order_items
joins: {}
cache_policy: policy_name_2

Accepted values for the max_cache_age: parameter are between 0 seconds and 24 hours. The maximum time a cache policy can be set to is 24 hours. A value input higher than 24 hours is “invalid” and will yield a warning. If an invalid value is used, the cache policy will default to the model's specified cache policy through the default_cache_policy parameter. If no default_cache_policy: is set, the Omni's default cache policy will be used.