Topics

In Omni, a Topic is a curated dataset that organizes and structures data around a specific area of interest or analysis.

Topics can help you improve:

Self-service. Creating refined subsets of data means users can query and explore without needing to understand the entire data model.
Reusability. Once defined, topics can be re-used in any analysis that utilizes the model containing the topic.
Consistency. Topics ensure that analyses across different users or teams are built using the same data definitions and logic.

What's a topic?

Topics are defined within models and linked to a specific database connection. They specify a primary base table along with any associated tables that can be joined for analysis.

Creating topics

Topics can be created in a few ways:

In the workbook

In the Fields & topics panel of a workbook, right click on a view and select Modeling > Make topic. Note: Topics created using this method must be promoted to the shared model to be accessible outside the workbook.

In the IDE

In the Files panel of the modeling IDE, click the + button in the Topics section.
You'll be prompted to enter a name for the topic. Currently, Omni will use this name to automatically set the topic's base view. If the name doesn't match an existing view, the IDE will display an error.

To resolve this, enter the desired name for the topic and use the base_view parameter to define the base view:
```
base_view: main__sales
```

Defining topic settings

Every topic has an associated topic file, where you can define various settings to apply to the topic. For example, data access control, cache policies, default filters, and so on. Refer to the Topic file parameters reference for more information about these settings.

Using topics in analyses

To use a topic in an analysis, use the topic switcher in the workbook's Fields & topics panel. A list of tables included in the topic will populate the panel, which you can then use in your analysis.

Adding tables to topics using joins

By default, when you create a topic, Omni adds all joinable non-fanout tables to the topic — specifically those with many-to-one or one-to-one relationships to other tables. The list of joinable tables can also be curated, either to remove joins generated by default or to force in tables that would fan out the base table, such as many-to-many or one-to-many joins.

Joins added to the model's relationships file can also be added to topics.

Adding joins can be done a few ways:

In the workbook

In the Fields & topics panel of a workbook, right click on a topic and open the Joins menu.
If joins have been inferred, they'll be listed in this menu above New join. Select an option or New join.
In the Join dialog, you can:
- Add an inferred join by clicking Add, if available
- Manually add a new join by selecting a table, join key, type, and optionally, a relationship. You can also click Infer Relationship. This will examine the cardinality between each join key and select the proper relationship.
  
  We recommend having Omni infer the relationship, as often uniqueness may not match expectation and this can flag potential data issues like duplicated rows or keys.

To make joins available to the shared model, remember to promote them.

In the IDE

To add tables to a topic in the IDE, use the joins parameter in the topic's file. Refer to the Topic file parameter reference for more information.

Transactional (order_items) topic
base_view: order_items
fields: [all_views.*, -inventory_items.*, -tag:pii, -users.id]
label: Transactional
joins:
  inventory_items:
    products:
      distribution_centers: {}           # The final table in each 'node' of the tree requires this empty bracket pair
  users: {}

Refer to the Relationships & Joins documentation for more information.

warning

When joins are deleted or modified to become invalid, they must be manually removed from a topic.

Examples

Topic with specified fields
base_view: order_items
fields: [all_views.*, -inventory_items.*, -tag:pii, -users.id]
label: Transactional
joins:
  inventory_items:
    products:
      distribution_centers: {}
  users: {}

Topic with access grants
joins: {}
required_access_grants: [test, department]

cache_policy: policy_1

Topic with default filters
california_order_items:
  base_view: order_items
  default_filters:
    users.state:
      is: California
  joins:
    inventory_items:
      products:
        distribution_centers: {}
    users: {}

What's a topic?​

Creating topics​

Defining topic settings​

Using topics in analyses​

Adding tables to topics using joins​

Examples​