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

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 ]

    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

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.