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

included_views:
  - order_items
  - orders

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:`

Syntax

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

Examples

Model File Definition:

access_grants:
  region_access:
    user_attribute: Region
    allowed_values: ["California", "Washington"]

Topic Implementation: Use access grants to limit user access to a topic through user attributes.

topics:
  inventory_items:
    joins:
      products:
        distribution_centers: {}

    required_access_grants: [ region_access ]

    cache_policy: policy_1

  order_items:
    label: Transactional
    joins:
      inventory_items:
        products:
          distribution_centers: {}
      users: {}
      # user_first_order: {}
  
  users:
    joins: {}

Field Implementation:

dimensions:
  email: {}
  age: {}
  city: {}
  state: {}
  country: {}
  zip: {}

  created_at:
    required_access_grants: [ region ]

  id:
    format: ID
    primary_key: true

measures:
  count:
    aggregate_type: count

Use access grants to limit user access to a particular field (dimension or measure) through user attributes.

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

`default_numeric_locale:`

  default_numeric_locale: fr_FR

This sets global number formatting in the model
Current accepted arguments are:
- en_US: default, comma-delimited thousands, period-delimited decimals, dollar default currency
- fr_FR: space-delimited thousands, comma-delimited decimals, euro default currency

`default_timeframes:`

  default_timeframes: [date, week, month]

This will set the default timeframes for any date or time field across the model
By default Omni offers raw, date, week, month, quarter, year
Any of the native timeframes can be set as default objects

`default_topic_access_filters:`

See docs here

`default_topic_required_access_grants:`

See docs here

`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>:

`extends:`

This allows extending an entire data model. Longer form example here

`facet_workbook_filters:`

  facet_workbook_filters: true

This argument will facet all filter suggestion in the workbook to the current filter selections
This may mean that filter suggestion takes more time to run more complex queries with less caching, and may also not return results when suggestions are expected. The default is false, meaning one filter will not facet another filter (ie when selecting State = California, country would still offer US and UK)

`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

`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 .

`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

`included_views:`

Defines a list of the view that will be included in this model from your database schema. Views that are not listed will be excluded and cannot be referenced when modeling.

Syntax:

included_views: [<view_name>, <view_name>,...]

Example:

included_views: [products, users, orders]

`template:`

Coming soon.

`topics:`

See topics

`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 examples below, 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:

Make 1-N cache_policies using a policy name and max_cache_age
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.

Example Model File​

access_grants:​

Syntax​

Examples​

auto_run:​

default_numeric_locale:​

default_timeframes:​

default_topic_access_filters:​

default_topic_required_access_grants:​

dynamic_schemas:​

extends:​

facet_workbook_filters:​

fiscal_month_offset:​

ignored_schemas:​

ignored_views:​

included_schemas:​

included_views:​

Syntax:​

Example:​

template:​

topics:​

week_start_day:​

Cache Policies​

Dashboard-Specific Caching​

cache_policy:​

cache_policies:​

default_cache_policy:​

max_cache_age:​