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 specifiedallowed_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 nameddynamic_schema_name:
. The views in this dynamic_schema are generated from the database schema namedcanonical_schema_name:
. When generating SQL against thedynamic_schema:
views, theuser_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:
anduser_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
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]
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 andmax_cache_age
- Set said policy to either
default_cache_policy
or a given topic'scache_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.