Parameters Catalog
Live catalog documenting all of the parameters that can be used in development, inlcuding a brief description of what each parameter is for or what it does and example syntax to follow for development.
Model Parameters
| Parameter Name | Description | Syntax | Example |
|---|---|---|---|
| ignored_schemas | Excludes schemas from the workbook experience | ignored_schemas: - schema_name1 - schema_name2 | ignored_schemas: - users, - schema_name2 |
| included_schemas | Displays the listed schemas in the workbook, all other schemas excluded | included_schemas: - schema_name1 - schema_name2 | included_schemas: - users, - schema_name2 |
| dynamic_schemas | Supports embed use cases with customer data partitioned into separate, but identical schemas | Dynamic_schemas: <insert_dynamic_schema_name> from_schema: <insert_canonical_schema_name> user_attribute: <insert_user_attribute_name> | Dynamic_schemas: top_users from_schema: users user_attribute: top_sales |
| ignored_views | Excludes specific views from the workbook experience | ignored_views: [view_name_1, view_name_2] | ignored_views: [users, inventory_items] |
| included_views | Defines a list of the view that will be inlcuded in this model from your database schema. | included_views: [<view_name>, <view_name>,...] | included_views: [products, users, orders] |
| access_grants | Creates finer-grained permissions applied at topic or field level | access_grants: <insert_grant_name>:user_attribute: <insert_uset_attribute_name> allowed_values: [insert_allowed_values_list] | access_grants: regional_grants: user_attribute: region allowed_values: [PNW, SE] |
| auto_run | Forces all queries with this connection to require a manual run | auto_run: true or false | auto_run: true |
| week_start_day | Sets all weeks to start on the chosen day; default is Monday | week_start_day: <insert_day_of_week> | week_start_day: monday |
| fiscal_month_offset | Sets a fiscal calendar and adds fiscal time metrics to all time dimension groups | Fiscal_month_offset: <insert_offset_month_number> | Fiscal_month_offset: 3 |
| topics | Defines the views displayed in a workbook UI for users to self-serve | topics: <insert_topic_name> ...add other topic parameters | Learn more about topic parameters |
Topic Parameters
| Parameter Name | Description | Syntax | Example |
|---|---|---|---|
| access_filters | Implements row-level permissions by applying a user attribute filter to the field. | access_filters: - field: products.brand user_attribute: attribute_xyz values_for_unfiltered: [is_admin] | access_filters: - field: products.brand user_attribute: attribute_xyz values_for_unfiltered: [is_admin] |
| always_where_sql | Applies a filter to a field that users with the Querier connection role cannot change. The filter is inserted into the WHERE clause of the generated SQL block for all queries in the topic. Note: users can choose any condition: =, !=, <, >, >=, <= as well as choose string or numeric arguments. | always_where_sql: <insert_topic_name>.<insert_field_name_to_filter_by> = <insert_conditional_value> | always_where_sql: users.company = omni |
| base_view | Used with an aliased topic, often with default_filters | base_view: <insert_view_name> | base_view: inventory_items |
| default_filters | Filters all rows in a topic by default by creating an automatic UI filter in the workbook | default_filters: <view_name>.<field_name> is: <filter_value> | default_filters: users.state is: california |
| fields | Fields allow Omni to curate the specific fields available inside a topic | fields: [list_of_allowed_or_unallowed_fields] | fields: [all_views.*, -inventory_items.*, -tag:pii, -users.id] |
| group_label | This is used to group Topics in the UI, for easier navigation and organization | group_label: <insert_group_label_name> | group_label: Marketing |
| joins | This will declare other views as part of a given topic | joins: {} | joins: inventory_items: products: distribution_centers: {} users: {} |
| label | Label will override the topic name for all UI appearances | label: <insert_label_name> | label: Cats |
| description | Metadata about the field, made available in the workbook UI | description: <insert_topic_description> | description: This topic covers all of the products we have in the inventory. |
| base_view_label | This is used to rename the base view when accessing it from a given topic. | base_view_label: <insert_label_name> | base_view_label: Items Sold |
Relationships & Joins Parameters
| Parameter Name | Description | Syntax | Example |
|---|---|---|---|
| join_to_view | Maps which table to join into the given view | join_to_view: <insert_view_name_to_join> | join_to_view: products |
| join_to_view_as | Aliases the joined table with a new name, i.e. labels the join to the desired name. | join_to_view_as: <insert_alias_name> | join_to_view_as: joined_products |
| join_to_view_as_label | Used to control the view label when using this join. In this example, we want fields from user_facts to look like they are part of the buyers table even though they are in fact from user_facts aliased in the model and generated SQL to buyer_facts | join_to_view_as_label: <insert_label_name> | join_to_view_as_label: buyers_from_user_facts |
| join_type | Defaults to left join. always_left, inner, full_outer, cross | join_type: <insert_join_type> | join_type: inner |
| relationship_type | Ensures metrics across joins are calculated correctly and efficiently. Expects one_to_one, many_to_one, one_to_many, many_to_many | relationship_type: <insert_relationship_type> | relationship_type: one_to_many |
| on_sql | Defines the formula to match rows in the join | on_sql: <insert_sql_formula> | on_sql: products.product_id = orders.product_id |
| reversible | Allows the join to function bi-directionally for topics. Defaults to false | reversible: <true_or_false> | reversible: true |
| where_sql | This will add a where clause to the generated SQL only if a join to the referenced view has been established | where_sql: <insert_sql_where_clause> | where_sql: orders.status = 'shipped' |
Views
| Parameter Name | Description | Syntax | Example |
|---|---|---|---|
| aliases | |||
| To fix broken content due to a table name change, add aliases to the new view file, redirecting references and eliminating errors. | aliases: [OLD_ORDER_ITEMS_NAME] | aliases: [OLD_ORDER_ITEMS_NAME] | |
| default_drill_fields | This will set the default drill set for all measures in a given view. Default drill set will be overridden by a given fields drill_fields. | default_drill_fields: [<insert_list_of_fields>] | default_drill_fields: [id, user_id, users.full_name, inventory_items.product_name, sale_price, margin, "order_items.created_at[date]", status] |
| display_order | For display_order in Omni, use a whole number to prioritize views, overriding alphabetical sorting. | display_order: <insert_whole_num> | display_order: 1 |
| fill_fields | Fills an enumerated list, usually dates, ensuring comprehensive representation in the data set, and requires knowledge of the fill set's start and end in the query. | fill_fields: [ "lead.created_date[week]" ] | fill_fields: [ "lead.created_date[week]" ] |
| hidden | Hide the view in the UI, maintain model access, and note its availability in SQL queries. The difference between ignoring and hiding lies in their impact on model references, with both options concealing the view in the topic pivottable experience. Expects 'true' or 'false'. | hidden: <true_or_false> | hidden: true |
| ignored | Effectively removes the view from the model (soft delete, for example to hide undesirable schema tables). This will result in the breakage of references to the specific view. Note that views will not be removed from the schema itself, so will be available through SQL querying. Expects 'true' or 'false'. | ignored: <true_or_false> | ignored: true |
| label | Label will override the view name for all UI appearances of the view. Omni expects unquoted text (quotes will be removed / ignored) | label: <insert_desired_label> | label: Users With Orders |
| name | Name is implicit in the file name of the view. This is how the view and fields are referenced, independent of the labels applied. | name: schema: <insert_schema_name> table: <insert_table_name> label: <insert_optional_view_label> | name: schema: ECOMMERCE table: Users label: Users with Orders |
| query | Defines a view from a workbook query. The query argument specifies the spec of the query for the view (fields, filters, base_view). Often the easiest way to build query views is via the UI and then promoting the view into the model. | ||
query: fields: <view_name>.<field_name>, <view_name.field_name>:<field_label> filters: lead.created_date base_view: <view_name> | query: fields: users.state, orders.count:count_of_orders filters: lead.created_date base_view: users | ||
| schema | Defines the database schema for the given table_name or raw_sql_select. | schema: <schema_name> | schema: GITHUB |
| sql | For views defined from raw sql queries. The raw_sql_select argument specifies the SQL query for the view (sql:) along with the column metadata (column_name, sql_type_name). It's recommended to build SQL views from the workbook UI and push down to the model. | sql: <insert sql query> | sql: SELECT * FROM users LIMIT 10 |
| table_name | Omni will infer table_name: {view_name} if it is not defined explicitly. | table_name: <table_name> | table_name: Orders |
| tags | Hidden feature, this will be used to curate view and field groups for UI curation and sharing. Expects a comma-delimited array of strings. | tags: [insert list of tags] | tags: [Marketing, Engineering] |
Dimensions
| Parameter | Description | Syntax | Example |
|---|---|---|---|
| dimension | Creates a dimension field | dimension: <insert_field_name> | dimension: product_name |
| group_label | Groups fields together within a topic in the UI of a workbook | group_label: <insert_group_label_name> | group_label: Product Details |
| aliases | Allows saved content with changed/renamed field names to remain functional | aliases: <insert_alias_name> | aliases: renamed_product_name |
| convert_tz | Specifies that a field does not need to be converted to the query timezone | convert_tz: true or false | convert_tz: false |
| description | Metadata about the field, made available in the workbook UI | description: <insert_description_text> | description: This field represents the product name |
| order_by_field | This will set a field to be ordered by another field, which will be pulled into any query silently | order_by_field: <insert_field_name> | order_by_field: product_quantity |
| format | Sets default formatting for numbers in Omni, using a named format (see below) | format: <insert_format_name> | format: Currency |
| hidden | Remove the field from the UI. Still referenceable in the model, but hidden in the workbook UI. | hidden: true or false | hidden: false |
| ignored | Remove the field from the UI, and prevents references to the field | ignored: true or false | ignored: true |
| label | Label will override the field name for all UI appearances of the field | label: <insert_label_name> | label: Product Name |
| links | Links will add external link to a templated URL into the drill menu | links: <insert_link_url> | links: https://example.com/product/{product_id} |
| primary_key | This will set the primary key on a given view | primary_key: true or false | primary_key: true |
| sql | The core declaration of the field definition. Best practice dictates using field references over raw database columns when calling other fields/dimensions. Dimensions may only be derived from other dimensions (rather than measures). Other fields can be called wrapping view.name in $, ie. ${orders.id}. | sql: <insert_sql_definition> | sql: {products.product_id} |
| suggest_from_field | By default, filters will run a SELECT DISTINCT({field}) to populate filter suggestions | suggest_from_field: <insert_field_name> | suggest_from_field: user_name |
| suggestion_list | suggestion_list can be used to explicitly set the list of filter options, both for performance reasons, and curation | suggestion_list: [option1, option2, ...] | suggestion_list: ["High", "Medium", "Low"] |
| tags | Tags are currently used for field picker search in the workbook and to curate fields: and drill_fields: - In the future, tags will be used to curate the field list, mask fields, or for other security and privacy configuration | tags: [tag1, tag2, ...] | tags: ["Sales", "Marketing"] |
| timeframes | Sets the default time segmentations available for date / time fields in workbooks | timeframes: [timeframe1, timeframe2, ...] | timeframes: ["Day", "Week", "Month"] |
| view_label | This will nest a given field under a different view than its default parent view, for example, grouping user_facts fields under the users view for better organization and discovery | view_label: <insert_view_label_name> | view_label: User Details |
| required_access_grants | Limits access to the field to only users whose user attribute values match the access grants | required_access_grants: [grant1, grant2, ...] | required_access_grants: ["Manager", "Admin"] |
| display_order | This will override the sort order for the field picker, inside the field's grouping (ie. inside a given view) | display_order: <insert_order_number> | display_order: 10 |
Measures
| Parameter | Description | Syntax | Example |
|---|---|---|---|
| aggregate_type | Aggregate defines the aggregation method for an underlying dimension | aggregrate_type: <insert_agg_type> | aggregate_type: average |
| Aggregate Type: average | Generates an average (mean) of a field's values in a column | aggregrate_type: <insert_agg_type> | aggregate_type: average |
| Aggregate Type: count | Generates a count of rows | aggregrate_type: <insert_agg_type> | aggregate_type: sum |
| Aggregate Type: max | Generates the maximum value within a column | aggregrate_type: <insert_agg_type> | aggregate_type: sum |
| Aggregate Type: median | Generates the median (midpoint value) of values within a column | aggregrate_type: <insert_agg_type> | aggregate_type: sum |
| Aggregate Type: min | Generates the minimum value within a column | aggregrate_type: <insert_agg_type> | aggregate_type: sum |
| Aggregate Type: sum | Generates a sum of values within a column | aggregrate_type: <insert_agg_type> | aggregate_type: sum |
| aliases | Aliases link old and updated field names, preventing disruptions due to database changes, and mirroring table-level alias behavior. | sql: ${view_name.field_name} | aliases: [OLD_FIELD_NAME] |
| description | Metadata about the field, made available in the workbook UI | description: <insert a description here> | description: calculates the average number of orders |
| display_order | This will override the sort order for the field picker, inside the field's grouping (ie. inside a given view). | display_order: <insert_whole_number> | display_order: 1 |
| drill_fields | Drill fields allow for curation of the drilling behavior for a given measure, using an array of fields for the subsequent query | drill_fields: [view_name.field_name, view_name.field_name] | drill_fields: [users.names, users.state] |
| filters | Filtered measures can be built using aggregation alongside a dimension filter | filters: <insert_field_name>: <insert_condition>: <insert_conditional_value> | filters: state: is: California |
| format | Sets default formatting for numbers in Omni, using a named format | format: insert_format type | format: currency |
| group_label | This will nest a group of fields in the field picker for curated organization of fields in the workbook | group_label: <insert_group_label_name> | group_label: Important Fields |
| hidden | Remove the field from the UI. Still referenceable in the model; hidden in the workbook UI. | hidden: <insert_true_or_false | hidden: true |
| label | Label will override the field name for all UI appearances of the field | label: <insert_label> | label: Full Name |
| links | Links will add external link to a templated URL into the drill menu | field_name: links: [ { url: <insert_url>, label: <insert_optional_label> } ] | country: links: - url: https://www.google.com/search?q=${users.country} label: Google |
| sql | SQL expression to generate the field value | sql: ${view_name.field_name} | sql: ${orders.id} |
| suggest_from_field | By default, filters will run a SELECT DISTINCT({field}) to populate filter suggestions. Curate the suggestion list, using suggest_from_field: to generate an alternative field's distinct values | suggest_from_field: <view_name.field_name> | suggest_from_field: orders.status |
| suggestion_list | By default, filters run a SELECT DISTINCT({field}) to populate filter suggestions, suggestion_list will bypass the default behavior | suggestion_list: [<value>, <value>] | suggestion_list: [complete, pending] |
| tags | Tags are currently used for field picker search in the workbook and to curate fields: and drill_fields: | tags: [<tag_string>, <tag_string>] | tags: [finance, marketing] |
| view_label | This will nest a given field under a different view than its default parent view, for example, grouping user_facts fields under the users view for better organization and discovery | view_label: <view_name> | aggregate: sum, view_label: inventory_items |
| required_access_grants | Limits access to the field to only users whose user attribute values match the access grants; access grants are defined in the model file. Learn more about creating access_grants. | required_access_grants: <access_grant_reference> | required_access_grants: <access_grant_reference> |
Query View Parameters
| Parameter | Definition | Syntax | Example |
|---|---|---|---|
schema: | References the query's underlying schema name from the chosen database connection. | <db_schema_name> | schema: ecommerce |
query: | The overarching parameter that defines all of the sub-parameters of the query view. | query: | query: fields: users.age: age users.created_at[year]: created_at_year calc_1: calc_1 base_view: users calculations: calc_1: sql: ${users.age} OMNI_FX_PLUS 2 |
dimensions: | Lists all of the fields selected in the query and makes them dimensions to allow for aggregation in another query. | dimensions: | dimensions: age: {} created_at_year: {} calc_1: {} |
measures: | Creates a COUNT(*) in the query, counting all rows. This parameter is applied regardless of whether a measure is in the query table. | measures: count: aggregation_type: count | measures: count: aggregate_type: count |
fields: | Lists out all of the fields in the query results tab of the workbook. This is a sub-parameter of query:. | fields: | fields: users.age: age users.created_at[year]: created_at_year calc_1: calc_1 |
base_view: | References which view is used in the FROM of the generated SQL. There is only one base view per query. This is a sub parameter of query:. | base_view: <view_name> | base_view: users |
calculations: | Lists all of the calculations that are defined in the query. This parameter uses OMNI SQL table calculation syntax. This is a sub-parameter of query:. | calculations: | calculations: calc_1: sql: ${users.age} OMNI_FX_PLUS 2 |
default_group_by: | Enables or disables a GROUP BY. This parameter is automatically set to false if there are no measures in the query view. | default_group_by: <true_or_false> | default_group_by: true |
filters: | Lists out all of the filters that are applied in the query. This is a sub-parameter of query:. | filters: | filters: users.age_bin: is: [] users.created_at: is: "2021" |
fill_fields: | Lists the fields that are filled as an enumerated list. This is a sub-parameter of query:. | fill_fields: ["<view_name>.<field_name>"] | fill_fields: [ "users.created_at[year]" ] |
sorts: | Lists the field(s) that the query is sorted by. | sorts: | sorts: - field: users.created_at[year] |
join_via_map: | Generated if the query view contains a user-written SQL query and the joins are not default joins so Omni generates a map for the joins. | join_via_map: | join_via_map: orders: [] order_items: [ orders ] |
topic: | Defines the topic the query is using. If the query is not based on a defined topic, then this parameter will not be included. | topic: <topic_name> | topic: users |
bind_all_filters: | When set to true, queries built on top of the query view will pass the chosen filters into the query view definition. | bind_all_filters: <true_or_false> | bind_all_filters: true |
limit: | Defines the row limit of the query if a limit is set on the query in the workbook. | limit: <limit_value> | limit: 1000 |