> ## 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.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/getting-started/best-practices",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Omni Best Practices

> A checklist for building clean, performant, and user-friendly Omni environments.

This checklist covers best practices for keeping your model clean and your environment intuitive to navigate for your entire organization. It draws on experience across many implementations and provides a helpful starting point.

<Tip>
  Each section is split into **must haves** and **nice to haves**. If you have questions about anything not covered here, reach out to your Omni team.
</Tip>

## Housekeeping

**Must haves**

* There are documented standards for development
* The homepage is curated using [labels](/content/organize#label-options) set to display on the "Homepage"
* The ["Verified" label](/content/organize#label-options) is used to signal to users which content should be trusted
* The [Content Validator](/modeling/develop/content-validator) has no errors
* The [Git integration](/integrations/git) 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

**Nice to haves**

* Users have [favorited](/content/navigate#personal) relevant content
* Unused content is regularly deleted

## Topic design

**Must haves**

* Topics are tidy and intuitive to use, with [topic descriptions](/modeling/topics/parameters/label) and [`ai_context`](/modeling/topics/parameters/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`](/modeling/dimensions/parameters/hidden), [`ignored`](/modeling/dimensions/parameters/ignored), and [`field`](/modeling/topics/parameters/fields) parameters to limit displayed fields
* Topics are organized thematically using [`group_label`](/modeling/topics/parameters/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`](/modeling/dimensions/parameters/label) and [`description`](/modeling/dimensions/parameters/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

**Nice to haves**

* For new topics not yet fully built out, create an initial set of measures using [point-and-click queries](/analyze-explore/point-click-queries) to avoid end users accidentally building from dimensions
* Use [`default_filters`](/modeling/topics/parameters/default-filters) or [`always_where_sql`](/modeling/topics/parameters/always-where-sql) to apply correct defaults and avoid querying excessive data volumes

Refer to [topic best practices](https://docs.omni.co/modeling/topics/best-practices) for more details on topic design.

## Dashboard design

**Must haves**

* 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](/visualize-present/visualizations/types/ai-summary) and [Markdown visualizations](/visualize-present/visualizations/types/markdown) are used to make insights easier to read
* Axis labels are straightforward
* Filters have [default values](/visualize-present/dashboards/filters#setting-default-values) to limit the size of queries run by default
* Deliveries are [scheduled](/share) on key dashboards
* The [color scheme](/visualize-present/dashboards/theming) works with both dark and light modes

**Nice to haves**

* Company branding and a consistent color scheme is applied; [Markdown visualizations](/showcase/visualizations/gradient-card) are used for custom headers and [data readouts](/showcase/visualizations/data-readout)
* [Links](/modeling/dimensions/parameters/links) create workflows between dashboards or jump to external applications

## Modeling

**Must haves**

* 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`](/modeling/topics/parameters/joins) 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](/modeling/relationships/index) are correct by checking the cardinality of the tables
* Omni [field references](/modeling/measures/parameters/sql) (`${field_name}`) are used over raw table/column names to prevent duplication in your code
* [`ignored_schemas`](/modeling/models/ignored-schemas), [`included_schemas`](/modeling/models/ignored-schemas), and [`ignored_views`](/modeling/models/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`](/modeling/dimensions/parameters/drill-fields) and [`drill_queries`](/modeling/measures/parameters/drill-queries) are used to allow users to drill deeper; [`default_drill_fields`](/modeling/views/parameters/default-drill-fields) are defined for each view
* Shared logic lives in view/relationship files; topic files are reserved for use-case-specific overrides

**Nice to haves**

* Object names have consistent capitalization; for example: lowercase letters and underscores are used for all object names
* The modeling layer uses [view folders](https://docs.omni.co/modeling/views/parameters/folder) and topic [group\_label](https://docs.omni.co/modeling/topics/parameters/group-label) to keep the code organized

## Performance optimization

**Must haves**

* Where appropriate, [aggregate awareness](/analyze-explore/performance/aggregate-awareness) and rollups are used
* Heavy transformations (window functions, CTEs) happen in dbt or ETL — if applicable, see the [dbt integration](https://omni.co/blog/three-ways-to-use-our-dbt-integration)

## Security

**Must haves**

* Connections use restrictive [permissions](/administration/users/permissions) as the default (Viewer or Restricted Querier)
* [User groups](/administration/users/groups) are leveraged to make content access control easier to manage
* [User attributes](/administration/users/attributes) are used to manage access to topics and column/row-level security with [`access_filters`](/modeling/topics/parameters/access-filters) and [`access_grant`](/modeling/models/access-grants)

Refer to [permissions scenarios](https://docs.omni.co/administration/users/permissions-scenarios) to determine the most appropriate configuration for your access.

## Next steps

* Learn how to [create and configure topics](/modeling/topics/setup) in Omni
* Learn to [apply layout, visual, and filter patterns](/visualize-present/dashboards) to build effective dashboards
* Manage access control and content permissions in our [security and permissions docs](/administration/users/permissions)