Skip to main content
This guide provides a hands-on reference for building out AI context within a real-world Omni instance, focusing on media organizations and advertising technology (AdTech) datasets. Whether you’re managing a portfolio of global publications or a high-traffic digital platform, providing clear context ensures Omni’s AI accurately interprets metrics across subscriptions, advertising spend, and content engagement. By defining how your data relates to industry-standard concepts like CPM, audience segments, and multi-channel revenue, you empower your team to ask complex questions and receive reliable, data-driven answers.

Why AI context matters

While Omni automatically understands your schema, ai_context allows you to codify company-specific knowledge that isn’t captured in table names or column labels. Think of this as training your AI analyst on your company’s specific playbook. In a retail environment, this means:
  • Defining terminology: Does Revenue refer to gross ad billings, net publisher payout, or recurring subscription MRR?
  • Handling personas: Automatically filtering by a brand manager’s specific publication or a sales rep’s assigned advertiser categories when they ask about my performance.
  • Calculating yield: Defining industry-standard formulas like CPM (Cost Per Mille) or ARPU (Average Revenue Per User) so the AI can track monetization efficiency without manual intervention.

The AI context hierarchy

To help the AI return accurate, business-aligned answers, you can add context to the underlying data model. For this example, think of the context in three layers: model, topic, and view. Omni applies this logic from the top down - starting at the model level - allowing you to set universal rules that get more specific as you move toward individual fields.
LayerPurposeExample
ModelUniversal truths. Global business logic and formatting rules that apply to all queries in the model.Setting the revenue_by_brand table as the source of truth for all Total Revenue queries.
TopicThe persona. The topic level defines more specific details scoped to your pre-defined datasets.Instructing the AI to use minutes_on_site as the primary metric when a user asks about “stickiness.”
View/FieldField precision. Specific definitions, synonyms, and allowed values for columns.Mapping Publication or Property as synonyms for the brand_name dimension.

Requirements

To implement this example in your own Omni instance, you’ll need:
  • Familiarity with Omni’s modeling layer
  • Permissions in Omni that allow you to edit a shared model
  • A connected data source that contains media or AdTech data
1

Setting universal rules in the model file

The model file defines your universal rules that will exist across the entire model. These rules act as permanent guardrails, ensuring the AI adheres to your core business standards regardless of which topic in the model a user is exploring.
Model-level context
ai_context: |-
    ## Global Business Logic
    - Brands are the primary entities.
    - Revenue is diversified across Advertising (Campaign Spend), 				Subscriptions (MRR), and Commerce.
    - Customers are readers/viewers categorized by Segments (Free vs. Subscriber).
    - When asked for 'Total Revenue', default to the 'revenue_by_brand' table as the consolidated source of truth.
    - When users say "My Brands" or "My Vertical," always reference the `user_attributes` for assigned Brand Category.
    
    ## Data Handling & Formatting
    - Traffic and Content Performance measure engagement across formats like Articles and Videos.
    - Always use 'Signup Date' for subscriber cohort analysis and 'Campaign Start Date' for ad performance trends.
    - Hide internal technical IDs from final visualizations unless explicitly asked for "Raw Data" or "ID Level" details.
    
    ## Media & AdTech Definitions
    - "Stickiness" refers primarily to 'minutes_on_site' and session frequency.
    - A "Subscriber" refers to a unique Customer ID with an active 'plan_type'. 
    - "Yield" is calculated by dividing total ad spend by total impressions and multiplying by 1000 to return CPM.
2

Setting dataset logic in the topic

Topic-level context defines more specific details scoped to your pre-defined datasets. This tells the AI how to navigate things like your campaign spend, traffic, and customer data.
Topic-level context
base_view: media_dataset_main__brands
label: Brand Topic

joins:
	media_dataset_main__campaign_spend:
		media_dataset_main__advertisers: {}
	media_dataset_main__content_performance: {}
	media_dataset_main__customer_monthly_activity: {}
	media_dataset_main__customers: {}
	media_dataset_main__revenue_by_brand: {}
	media_dataset_main__traffic_by_brand: {}

ai_context: |
  Use this topic to analyze Brand health, Advertiser spend, and Audience engagement.
  ## Revenue
  - Analyze monetization via 'revenue_by_brand' for high-level totals across all streams. 
  - Use 'campaign_spend' when the user asks about specific Advertisers or Ad Categories (e.g., CPG, Tech). 
  - To calculate 'Yield', always divide spend by impressions and multiply by 1000 to get CPM.
  
  ## Audience
  - Evaluate user growth and retention using the 'customers' and 'customer_monthly_activity' views. 
  - Prioritize 'segment' (Free vs. Subscriber) to understand how different cohorts consume content. 
  - Use 'minutes_on_site' as the primary metric for user "stickiness" and attention.
  
  ## Content
  - Assess editorial performance using 'content_performance' grouped by 'content_type'. 
  - Compare 'total_views' against 'content_pieces' to identify the most efficient formats (e.g., Quizzes vs. Articles). 
  - When analyzing engagement, focus on 'total_engagement' relative to total page views.
3

Adding precision at the view level

View-level context ensures the AI understands technical identifiers, distinguishes between different types of spend and delivery, and maps editorial jargon like Properties or Verticals to the correct dimensions.
View-level context: Brands view
  view: media_dataset_main__brands
  dimensions:
    brand_id:
      sql: '"BRAND_ID"'
      primary_key: true
      ai_context: Unique 2-3 letter code for the brand.
    
	brand_name:
      sql: '"BRAND_NAME"'
      synonyms: [ publication, property, title, site ]
      ai_context: The primary display name of the media brand.
    
	category:
      sql: '"CATEGORY"'
      all_values: [ Lifestyle, Fashion, Tech, Business, Entertainment ]
      synonyms: [ vertical, pillar ]
      ai_context: The industry vertical the brand operates within.
View-level context: Campaign Spend view
  view: media_dataset_main__campaign_spend
  dimensions:
    campaign_id:
      sql: '"CAMPAIGN_ID"'
      primary_key: true
      ai_context: Unique ID for an ad campaign. Do not include in totals unless requested.
    
	spend_usd:
      sql: '"SPEND_USD"'
      type: number
      synonyms: [ ad revenue, billing, client spend, booked revenue ]
      ai_context: Gross dollar amount spent by the advertiser on a specific brand.
    
	impressions:
      sql: '"IMPRESSIONS"'
      type: number
      synonyms: [ ad delivery, ad views, served ads ]
      ai_context: Total count of ads served; the denominator for CPM.

Iterating on AI context

Improving AI quality is an iterative process. Use this workflow to refine your context:
  1. Monitor: Use the AI usage dashboard in the Analytics section to find queries with negative (👎) feedback.
  2. Identify: Did the AI fail due to a missing synonym or lack of business logic?
  3. Tune: Update the YAML at the appropriate level (model, topic, or view).
  4. Verify: Re-run the prompt in the Query Helper to ensure the fix worked.
When you correct the AI in a chat session (e.g., "Actually, always use Fiscal Year"), click the (brain) icon to have the AI learn from the conversation and propose model changes to incorporate the correction.

Next steps