Skip to main content

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 NameDescriptionSyntaxExample
ignored_schemasExcludes schemas from the workbook experienceignored_schemas: - schema_name1 - schema_name2 ignored_schemas: - users, - schema_name2
included_schemasDisplays the listed schemas in the workbook, all other schemas excludedincluded_schemas: - schema_name1 - schema_name2included_schemas: - users, - schema_name2
dynamic_schemasSupports embed use cases with customer data partitioned into separate, but identical schemasDynamic_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_viewsExcludes specific views from the workbook experienceignored_views: [view_name_1, view_name_2]ignored_views: [users, inventory_items]
included_viewsDefines 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_grantsCreates finer-grained permissions applied at topic or field levelaccess_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_runForces all queries with this connection to require a manual runauto_run: true or falseauto_run: true
week_start_daySets all weeks to start on the chosen day; default is Mondayweek_start_day: <insert_day_of_week>week_start_day: monday
fiscal_month_offsetSets a fiscal calendar and adds fiscal time metrics to all time dimension groupsFiscal_month_offset: <insert_offset_month_number>Fiscal_month_offset: 3
topicsDefines the views displayed in a workbook UI for users to self-servetopics: <insert_topic_name> ...add other topic parametersLearn more about topic parameters

Topic Parameters

Parameter NameDescriptionSyntaxExample
access_filtersImplements 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_sqlApplies 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_viewUsed with an aliased topic, often with default_filtersbase_view: <insert_view_name>base_view: inventory_items
default_filtersFilters all rows in a topic by default by creating an automatic UI filter in the workbookdefault_filters: <view_name>.<field_name> is: <filter_value>default_filters: users.state is: california
fieldsFields allow Omni to curate the specific fields available inside a topicfields: [list_of_allowed_or_unallowed_fields]fields: [all_views.*, -inventory_items.*, -tag:pii, -users.id]
group_labelThis is used to group Topics in the UI, for easier navigation and organizationgroup_label: <insert_group_label_name>group_label: Marketing
joinsThis will declare other views as part of a given topicjoins: {}joins: inventory_items: products: distribution_centers: {} users: {}
labelLabel will override the topic name for all UI appearanceslabel: <insert_label_name> label: Cats
descriptionMetadata about the field, made available in the workbook UIdescription: <insert_topic_description>description: This topic covers all of the products we have in the inventory.
base_view_labelThis 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 NameDescriptionSyntaxExample
join_to_viewMaps which table to join into the given viewjoin_to_view: <insert_view_name_to_join>join_to_view: products
join_to_view_asAliases 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_labelUsed 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_factsjoin_to_view_as_label: <insert_label_name>join_to_view_as_label: buyers_from_user_facts
join_typeDefaults to left join. always_left, inner, full_outer, crossjoin_type: <insert_join_type>join_type: inner
relationship_typeEnsures metrics across joins are calculated correctly and efficiently. Expects one_to_one, many_to_one, one_to_many, many_to_manyrelationship_type: <insert_relationship_type>relationship_type: one_to_many
on_sqlDefines the formula to match rows in the joinon_sql: <insert_sql_formula>on_sql: products.product_id = orders.product_id
reversibleAllows the join to function bi-directionally for topics. Defaults to falsereversible: <true_or_false>reversible: true
where_sqlThis will add a where clause to the generated SQL only if a join to the referenced view has been establishedwhere_sql: <insert_sql_where_clause>where_sql: orders.status = 'shipped'

Views

Parameter NameDescriptionSyntaxExample
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_fieldsThis 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_orderFor display_order in Omni, use a whole number to prioritize views, overriding alphabetical sorting.display_order: <insert_whole_num>display_order: 1
fill_fieldsFills 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]" ]
hiddenHide 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
ignoredEffectively 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
labelLabel 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
nameName 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
queryDefines 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
schemaDefines the database schema for the given table_name or raw_sql_select.schema: <schema_name>schema: GITHUB
sqlFor 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_nameOmni will infer table_name: {view_name} if it is not defined explicitly.table_name: <table_name>table_name: Orders
tagsHidden 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

ParameterDescriptionSyntaxExample
dimensionCreates a dimension fielddimension: <insert_field_name>dimension: product_name
group_labelGroups fields together within a topic in the UI of a workbookgroup_label: <insert_group_label_name>group_label: Product Details
aliasesAllows saved content with changed/renamed field names to remain functionalaliases: <insert_alias_name>aliases: renamed_product_name
convert_tzSpecifies that a field does not need to be converted to the query timezoneconvert_tz: true or falseconvert_tz: false
descriptionMetadata about the field, made available in the workbook UIdescription: <insert_description_text>description: This field represents the product name
order_by_fieldThis will set a field to be ordered by another field, which will be pulled into any query silentlyorder_by_field: <insert_field_name>order_by_field: product_quantity
formatSets default formatting for numbers in Omni, using a named format (see below)format: <insert_format_name>format: Currency
hiddenRemove the field from the UI. Still referenceable in the model, but hidden in the workbook UI.hidden: true or falsehidden: false
ignoredRemove the field from the UI, and prevents references to the fieldignored: true or falseignored: true
labelLabel will override the field name for all UI appearances of the fieldlabel: <insert_label_name>label: Product Name
linksLinks will add external link to a templated URL into the drill menulinks: <insert_link_url>links: https://example.com/product/{product_id}
primary_keyThis will set the primary key on a given viewprimary_key: true or falseprimary_key: true
sqlThe 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_fieldBy default, filters will run a SELECT DISTINCT({field}) to populate filter suggestionssuggest_from_field: <insert_field_name>suggest_from_field: user_name
suggestion_listsuggestion_list can be used to explicitly set the list of filter options, both for performance reasons, and curationsuggestion_list: [option1, option2, ...]suggestion_list: ["High", "Medium", "Low"]
tagsTags 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 configurationtags: [tag1, tag2, ...]tags: ["Sales", "Marketing"]
timeframesSets the default time segmentations available for date / time fields in workbookstimeframes: [timeframe1, timeframe2, ...]timeframes: ["Day", "Week", "Month"]
view_labelThis 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 discoveryview_label: <insert_view_label_name>view_label: User Details
required_access_grantsLimits access to the field to only users whose user attribute values match the access grantsrequired_access_grants: [grant1, grant2, ...]required_access_grants: ["Manager", "Admin"]
display_orderThis 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

ParameterDescriptionSyntaxExample
aggregate_typeAggregate defines the aggregation method for an underlying dimensionaggregrate_type: <insert_agg_type> aggregate_type: average
Aggregate Type: averageGenerates an average (mean) of a field's values in a columnaggregrate_type: <insert_agg_type> aggregate_type: average
Aggregate Type: countGenerates a count of rowsaggregrate_type: <insert_agg_type> aggregate_type: sum
Aggregate Type: maxGenerates the maximum value within a columnaggregrate_type: <insert_agg_type> aggregate_type: sum
Aggregate Type: medianGenerates the median (midpoint value) of values within a columnaggregrate_type: <insert_agg_type> aggregate_type: sum
Aggregate Type: minGenerates the minimum value within a columnaggregrate_type: <insert_agg_type> aggregate_type: sum
Aggregate Type: sumGenerates a sum of values within a columnaggregrate_type: <insert_agg_type> aggregate_type: sum
aliasesAliases 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]
descriptionMetadata about the field, made available in the workbook UIdescription: <insert a description here>description: calculates the average number of orders
display_orderThis 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_fieldsDrill fields allow for curation of the drilling behavior for a given measure, using an array of fields for the subsequent querydrill_fields: [view_name.field_name, view_name.field_name]drill_fields: [users.names, users.state]
filtersFiltered measures can be built using aggregation alongside a dimension filterfilters: <insert_field_name>: <insert_condition>: <insert_conditional_value>filters: state: is: California
formatSets default formatting for numbers in Omni, using a named formatformat: insert_format typeformat: currency
group_labelThis will nest a group of fields in the field picker for curated organization of fields in the workbookgroup_label: <insert_group_label_name>group_label: Important Fields
hiddenRemove the field from the UI. Still referenceable in the model; hidden in the workbook UI.hidden: <insert_true_or_falsehidden: true
labelLabel will override the field name for all UI appearances of the fieldlabel: <insert_label>label: Full Name
linksLinks will add external link to a templated URL into the drill menufield_name: links: [ { url: <insert_url>, label: <insert_optional_label> } ]country: links: - url: https://www.google.com/search?q=${users.country} label: Google
sqlSQL expression to generate the field valuesql: ${view_name.field_name}sql: ${orders.id}
suggest_from_fieldBy 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 valuessuggest_from_field: <view_name.field_name>suggest_from_field: orders.status
suggestion_listBy default, filters run a SELECT DISTINCT({field}) to populate filter suggestions, suggestion_list will bypass the default behaviorsuggestion_list: [<value>, <value>]suggestion_list: [complete, pending]
tagsTags 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_labelThis 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 discoveryview_label: <view_name>aggregate: sum, view_label: inventory_items
required_access_grantsLimits 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

ParameterDefinitionSyntaxExample
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