Omni Best Practices

Documentation Index

Fetch the complete documentation index at: https://docs.omni.co/llms.txt

Use this file to discover all available pages before exploring further.

​

Housekeeping

• There are documented standards for development
• The homepage is curated using labels set to display on the “Homepage”
• The “Verified” label is used to signal to users which content should be trusted
• The Content Validator has no errors
• The Git integration is set up for version control
• There is an internal Slack/Teams channel for analytics questions, or a clear process for getting help around data

• Users have favorited relevant content
• Unused content is regularly deleted

​

Topic design

• Topics are tidy and intuitive to use, with topic descriptions and ai_context where applicable
• Topics are generally small to ensure both usability and performance
• Limited views are joined into each topic to keep them focused; use hidden, ignored, and field parameters to limit displayed fields
• Topics are organized thematically using group_label on the field or topic level — avoid exposing raw schema naming
• Database columns, tables, and topics use language familiar to users with label and description
• Field names follow consistent naming conventions (e.g. not mixing total_sales, sales_sum, and sales)
• Boolean fields are named appropriately (e.g. Is Returned not Returned)
• No reference to date/time in time dimension groups to avoid “Date Date” field name issues
• Ratios use measure1 / NULLIF(measure2, 0) to handle zero denominators
• Value formats are used consistently across the model

• For new topics not yet fully built out, create an initial set of measures using point-and-click queries to avoid end users accidentally building from dimensions
• Use default_filters or always_where_sql to apply correct defaults and avoid querying excessive data volumes

​

Dashboard design

• Dashboards are built using curated topics rather than the ungoverned All Views & Fields mode
• Dashboards are intuitive to use with a small number of tiles (<10 tiles per page)
• AI summaries and Markdown visualizations are used to make insights easier to read
• Axis labels are straightforward
• Filters have default values to limit the size of queries run by default
• Deliveries are scheduled on key dashboards
• The color scheme works with both dark and light modes

• Company branding and a consistent color scheme is applied; Markdown visualizations are used for custom headers and data readouts
• Links create workflows between dashboards or jump to external applications

​

Modeling

• There are no model validation errors in the shared model
• Primary keys are unique and defined in all views
• The base table of topics is the most granular, joining out with many_to_one or one_to_one joins; inner, cross, one_to_many, and many_to_many joins are generally not needed
• All assumed relationships have been validated and replaced with actual relationships (assumed_many_to_one → many_to_one)
• The relationships defined in the relationships file are correct by checking the cardinality of the tables
• Omni field references (${field_name}) are used over raw table/column names to prevent duplication in your code
• ignored_schemas, included_schemas, and ignored_views are used to include only relevant schemas and tables
• Fields and logic reused across workbooks are added to the shared model; one-off fields live in the workbook model
• drill_fields and drill_queries are used to allow users to drill deeper; default_drill_fields are defined for each view
• Shared logic lives in view/relationship files; topic files are reserved for use-case-specific overrides

• Object names have consistent capitalization; for example: lowercase letters and underscores are used for all object names
• The modeling layer uses view folders and topic group_label to keep the code organized

​

Performance optimization

• Where appropriate, aggregate awareness and rollups are used
• Heavy transformations (window functions, CTEs) happen in dbt or ETL — if applicable, see the dbt integration

​

Security

• Connections use restrictive permissions as the default (Viewer or Restricted Querier)
• User groups are leveraged to make content access control easier to manage
• User attributes are used to manage access to topics and column/row-level security with access_filters and access_grant

​

Next steps

• Learn how to create and configure topics in Omni
• Learn to apply layout, visual, and filter patterns to build effective dashboards
• Manage access control and content permissions in our security and permissions docs