Creating topics

Omni offers two ways to develop topics: visually (in workbooks) or using code (in the model IDE).

In this guide, each step of the topic development process will show you how to complete the step using either the workbook or the model IDE.

Requirements

To follow the steps in this guide, you'll need:

Querier, Modeler, or Connection Admin permissions to create the topic. Note: Queriers can only create topics in workbooks.
Connection Admin or Modeler permissions to promote the topic to the shared model
Optional: Familiarity with Omni branches. While not required, this is recommended if your organization uses branch-based workflows for Omni development.

Before you begin

You can use the workbook-based topic editor, the model IDE, or both to develop your topics. However, keep the following in mind before you begin:

Queriers can only create topics in workbooks, as they don't have access to the IDE
Changes made outside a branch in the IDE directly edit the shared model. This means that changes are automatically promoted when a file is saved in the IDE. You can revert changes in the IDE using the model history panel.

1. Create the topic

First, you'll start by creating the topic in the workbook or the model IDE.

In the workbook

Using branches

If you know the model you'll be working with is connected to git, we recommend creating a branch before continuing. This can save you a few steps when you're ready to promote the topic to the shared model.

If you're unsure, that's okay! We'll show you what to do to promote the topic, if needed.

Open or create a workbook.
In a query tab, navigate to All views & fields in the field browser.
Hover over a view and click the (three dots icon), then Modeling > Make topic.

This will open the topic editor:

In this editor, you can:

Save the changes and use Use in query to use the topic in a new query, or
Further curate your topic by following the remaining optional steps in this guide

In the IDE

Using branches

If your model is connected to git, you'll need to create a branch before making changes 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:
Topic base view
```
base_view: ecomm__order_items
```

2. Design the topic

info

The steps in this section are optional. You can add metadata, fields, joins, etc. to topics at any time.

Want to work with an existing topic in the topic editor? Open the topic in a workbook and click Model > Edit topic.

In this section, we'll cover how you can further curate your topic by adding metadata like descriptions and labels, AI context, joins, and fields.

2.1. Add metadata & AI context

You'll start designing the topic by adding optional metadata and AI context.

In the workbook

The Overview tab contains a preview of the topic and allows you to do some quick curation like renaming the topic (label), adding it to a topic group (a folder of related topics) adding a description, or providing AI context.

tip

While AI context is optional, Omni recommends using it if you plan to use any AI features. Refer to the Optimizing models for AI guide for more information.

In the IDE

After you create the topic file, you can start designing the topic with topic parameters.

In this example, we'll define the following parameters, which will also display in the Overview tab of the workbook-based topic editor:

label - A user-friendly display name
group_label - The group that the topic belongs to, which is useful for improving workbook navigation for your end users
ai_context - Additional information for the AI, which can help improve results

Topic description, label, group, and AI context
base_view: ecomm__order_items
label: Order Transactions
group_label: Orders & Fulfillment

ai_context: |
  You are an expert data analyst, who has a vast amount of experience analyzing ecommerce data to find useful insights and trends.

  Our data has information about orders at the line item level in the order items table, users in our user table, inventory in our inventory items table, and products in the products table.

2.2. Add joins

By default, Omni adds all joinable non-fanout tables to newly-created topics — 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 add 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.

In the workbook

The Joins tab will display the joins that are available for the dataset:

The view browser allows you to search for and select views to include in the topic.

To add a brand new join - that is, one that is not already defined in your model's relationships file - click the + New button. You'll then be prompted to define and save the join.

In the IDE

Don't lose your work!

Click the Save changes button located near the top-right corner of the IDE before navigating to a different file.

To add joins to a topic in the model IDE, use the joins parameter in the topic file:

Topic-level join
joins:
  ecomm__users: {}
  ecomm__inventory_items:
    ecomm__products:
      ecomm__distribution_centers: {}

The joins you define will also display in the Joins tab of the workbook-based topic editor:

2.3. Add fields

By default, all fields from the topic's base view and any joined views will be accessible in the topic. In this step, we'll show you how to curate the fields in the topic.

In the workbook

The Fields tab displays all the fields that are visible in the topic.

To exclude a field, deselect the checkbox next to the field:

In the IDE

Don't lose your work!

Click the Save changes button located near the top-right corner of the IDE before navigating to a different file.

You can include and exclude fields in the model IDE by using the fields parameter in the topic file.

For example, the following definition would make all fields accessible except the email, first_name, and last_name fields in the ecomm__users view:

Topic field curation
fields:
  [
    all_views.*,
    -ecomm__users.email,
    -ecomm__users.first_name,
    -ecomm__users.last_name
  ]

If you viewed this topic's Fields tab in the workbook topic editor, the excluded fields would be unchecked:

2.4. Curate views & fields

Adding additional context to a topic can be helpful for both your end users and Omni's AI. In this step, we'll show you how to further curate your topic by adding information to included views and fields.

In the workbook

The Curate tab allows you to bulk-add information - such as labels, descriptions, and AI context - to views and fields in the topic.

While working in a workbook query, you can also access these options for individual fields by right-clicking on a field and selecting Edit.

In the IDE

Don't lose your work!

Click the Save changes button located near the top-right corner of the IDE before navigating to a different file.

Unlike the workbook-based topic editor, there isn't a way to bulk-add information to views and fields in the model IDE. Adding curation must currently be accomplished by opening and editing the view file for views included in the topic.

To get started, locate and click the view in the Schema browser. You can then add information to the view and its fields.

In the following example, we added:

A view-level description
A description and ai_context to each of the view's dimensions

Curating the distribution_centers view
# Reference this view as ecomm__distribution_centers
description: |
  This is a dimension table containing information about distribution centers,
  including a unique identifier, their name, which is actually their location in
  the form of city name, and where they are located with regards to latitude and longitude

schema: ECOMM
table_name: DISTRIBUTION_CENTERS

dimensions:
  id:
    sql: '"ID"'
    format: ID
    description: Unique identifier for each distribution center
    primary_key: true
    ai_context: |
      Often users will not pull this into a query directly and we should not include it
      unless specifically requested.

  name:
    sql: '"NAME"'
    description: Name of the distribution center
    ai_context: This is the name of the city where the distribution center is located.

  latitude:
    sql: '"LATITUDE"'
    description: Geographical latitude of the distribution center location
    ai_context: will often be used in tandem with longitude for mapping purposes

  longitude:
    sql: '"LONGITUDE"'
    description: Geographical longitude of the distribution center location
    ai_context: will often be used in tandem with longitude for mapping purposes

measures:
  count:
    aggregate_type: count

If you opened this view in the topic's Curate tab in the workbook topic editor, it would look like the following image:

Refer to the Database view, Dimension, and Measure references for more information about all supported parameters.

3. Review & save

Next, you'll review and save the changes you made to the topic.

In the workbook

The YAML tab will automatically generate the YAML definition for the topic based on what you built in the other topic editor tabs. When finished, click Save changes.

In this tab, you can also:

After saving, click Use in query to create a new workbook query based on the topic
Click Edit in IDE to directly edit the topic's YAML configuration

Some parameters are IDE-only

Some parameters - like default filters, cache policies, and access grants - can only be added to topics by using the model IDE. Refer to the Topic reference for a list of all available topic parameters.

In the IDE

Heads up!

If not using a branch, changes will be automatically promoted to the shared model after every save. Use the model history panel to revert changes, if needed.

At this point, our example Orders Transactions (ecomm__order_items) topic file looks like this:

Example Order Transactions topic
base_view: ecomm__order_items
label: Order Transactions
group_label: Orders & Fulfillment

ai_context: |
  You are an expert data analyst, who has a vast amount of experience analyzing ecommerce data to find useful insights and trends.

  Our data has information about orders at the line item level in the order items table, users in our user table, inventory in our inventory items table, and products in the products table.

joins:
  ecomm__users: {}
  ecomm__inventory_items:
    ecomm__products:
      ecomm__distribution_centers: {}

fields:
  [
    all_views.*,
    -ecomm__users.email,
    -ecomm__users.first_name,
    -ecomm__users.last_name
  ]

When you're finished making changes to the topic, click the Save changes button located near the top-right corner of the IDE.

4. Promote to shared

info

This step requires Connection Admin or Modeler permissions.

The last step is to promote the topic to the shared model. This makes the topic accessible in new and existing workbooks that are built off the underlying model.

How you promote the topic depends on whether you used a branch:

I didn't use a branch

If you didn't use a branch and you created the topic:

In a workbook - While in a published workbook, navigate to Model > View & promote.
- If you see a Use branch to promote message:
  - And you're in a draft, click File > Move to branch. This will move the changes to a branch.
  - Otherwise, click Model > Branch > Create branch to create a new branch in the workbook with the changes.
- Otherwise, click Promote to shared.
In the IDE - Your changes were promoted to the shared model when you clicked Save changes. You're all done!

I used a branch

Promotion from a branch to shared depends on whether the model is connected to git and pull requests are required:

If git isn't enabled or pull requests aren't required, click the Merge button in the green branch header at the top of the page. Follow the prompts to merge the branch.
Otherwise, click the Create pull request button in the green branch header at the top of the page. This will open the connected git repository, where you'll be prompted to create the pull request. The changes in the branch will be applied to the shared model once the pull request is merged.

Requirements​

Before you begin​

1. Create the topic​

2. Design the topic​

2.1. Add metadata & AI context​

2.2. Add joins​

2.3. Add fields​

2.4. Curate views & fields​

3. Review & save​

4. Promote to shared​

Requirements

Before you begin

1. Create the topic

2. Design the topic

2.1. Add metadata & AI context

2.2. Add joins

2.3. Add fields

2.4. Curate views & fields

3. Review & save

4. Promote to shared