Skip to main content

Topic best practices

Designing effective topics is about creating a bridge between your data model and your users. A well-designed topic gives users an approachable, curated view of your data that feels familiar and intuitive without requiring SQL or deep knowledge of the underlying data model.

This guide shares best practices for structuring topics that balance usability, performance, and maintainability. Whether you’re migrating an existing model or starting fresh, these recommendations will help you design topics that empower teams to confidently explore data, build dashboards, and answer their own questions.

Build for your audience​

Approach topic design with your business users in mind. Rather than mirroring your database schemas, think through the needs of each department (i.e. Sales, Finance, Marketing, etc). Some departments may be fine with a simple dataset while others will benefit from multiple topics grouped together.

Avoid analysis paralysis​

Topics don't need to be fully planned in advance - you can always add more and refine existing topics as you go.

  • If you're migrating, you may want to spend some time analyzing current usage and distilling it down to the main topics users will continue to depend on.
  • If you're starting from scratch, try a model-as-you-go approach. Take an educated guess at building a few key topics and then refine as you go by soliciting feedback. As time goes on you’ll see usage go up and requests start to decrease.
tip

Get insight into how topics are being used with the Topic Usage summary in your Analytics dashboard.

Curate with metadata​

Help your users understand what a topic is and how to use it with metadata:

Check out the Topic examples for additional examples.

Example topics with labels, descriptions, and groups

Be specific​

Tailor your topics to focus on specific audiences and use cases rather than trying to cater to everyone at once. Keep in mind that a topic should be easily navigated by a business user - if it has dozens of joins and hundreds of fields, it's likely too large.

When building, keep in mind that:

  • A topic can be as narrow as a single table. There are still numerous benefits to single-table topics, including the ability to add default filters, AI context, caching policies, etc. Most importantly, this topic will remove all the extra clutter of seeing all possible views at once, many of which may be unrelated.

  • A single table can be used in multiple topics, so there's no need to worry about being able to only use it once.

    This is common with fact tables. For example, a users table might be the base view for its own topic as well as being joined into a separate Sales topic. This unlocks the ability to model the table differently for each use case, so you can easily reuse shared logic but tailor specific aspects differently in each topic.

Favor small topics​

While you can build a single large topic, smaller topics are recommended as they:

  • Are easier to navigate
  • Can create a more focused experience for business users
  • Generally translate to simpler queries with less joins, which run faster
  • Make model management more straightforward

Keep shared logic in view & relationship files​

Since topics act as a curation layer, modeling done in a topic file supersedes the base logic in model, view, or relationship files. This means that shared logic should be kept in the view or relationship files and anything use case-specific should be kept in the topic file.

Consider many-to-one joins​

Omni recommends building topics with many-to-one joins, where the base view is the most transactional table and fact tables are selectively joined in. This can help improve the performance of your topics.

Additionally, note that:

  • You may need to specify primary keys for these fan-out joins to work
  • Even with multiple joins in a topic, Omni will bring in only the required join path to build each query

To further improve performance, consider setting default filters, caching policies, and auto-run.