Optimizing AI context for retail and ecommerce

This guide provides a hands-on reference for building out AI context within a real-world Omni instance. By following this retail and orders example, you can see exactly how to move beyond basic schema discovery to a high-precision setup where the AI understands your specific business logic, key performance indicators, and reporting nuances.

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 which status codes (e.g., “Shipped,” “Complete”) represent valid revenue
Specifying which unique identifier to use when counting orders
Providing preferred dimensions for “top-n” queries

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.

Layer	Purpose	Example
Model	Universal truths. Global business logic and formatting rules that apply to all queries in the model.	”Our fiscal year starts in Feb; use USD for all currency.”
Topic	The persona. Definitions for specific datasets and how views relate to each other.	”You are a Retail Analyst; use the Order Items table for all sales queries.”
View/Field	Field precision. Specific definitions, synonyms, and allowed values for columns.	”This ID is internal; don’t show it unless asked. `'Bought at'` is a synonym for `created_at`.”

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 retail-related data

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
  - Our Fiscal Year starts in February. If a user asks for "this year" without specifying, assume Fiscal Year.
  - "Revenue" always refers to 'Gross Sales' (before discounts) unless 'Net' is specified.
  - When comparing time periods, always use 'Complete' weeks (Monday-Sunday) to avoid partial-week skew.

  ## Data Handling & Formatting
  - Never display internal database keys or UUIDs in the final result unless explicitly requested for troubleshooting.
  - For any currency output, default to USD.
  - If a query results in zero records, explain that the filters (like 'Status = Shipped') might be too restrictive.

  ## Retail Definitions
  - A "New Customer" is a user whose first_order_date is within the last 30 days.
  - "Active Inventory" refers only to items where 'Stock Count' > 0 and 'Discontinued' is false.

Setting dataset logic in the topic

Topic-level context defines more specific details scoped to your pre-defined datasets. This example shows how to tell the AI how to handle an ecommerce dataset specifically focused on orders and fulfillment.

Topic-level context

base_view: omni_dbt_ecomm__order_items
label: Order Transactions
group_label: Orders & Fulfillment

# Limit the search space to relevant fields to reduce noise
ai_fields: [ all_views.*, -tag:exclude_from_AI ]

ai_context: |-
  You are an expert data analyst with vast experience analyzing ecommerce data to find trends.

  Our data includes order line items (order_items), users (users), inventory (inventory_items), and products (products).

  ## Key Business Logic:
  - Any queries regarding sales should always use the total_sale_price field on the order items table.
  - If asked about drivers of a metric change, start with: country, traffic_source, category, or brand.
  - If asked about "who" or "users", use full_name and email. Never return an ID unless explicitly asked.
  - For total orders or order count, use orders.order_id_count_distinct.
  - For revenue metrics, filter only on valid statuses: Complete, Shipped, Processing.

sample_queries:
  Monthly Sales by Country:
    query:
      fields:
        [
          "omni_dbt_ecomm__order_items.created_at[month]",
          omni_dbt_ecomm__users.country,
          omni_dbt_ecomm__order_items.total_sale_price
        ]
      base_view: omni_dbt_ecomm__order_items
      filters:
        omni_dbt_ecomm__order_items.status:
          not: [ Returned, Cancelled ]
      pivots: [ omni_dbt_ecomm__users.country ]
    description: A monthly breakdown of all sales by user's country
    prompt: What do our sales look like by country?

Use sample queries: Adding sample_queries creates a “happy path” for the AI. It ensures high-value KPIs use your exact join logic and filter sets, mirroring how a human analyst would build the report.

Adding precision at the view level

View-level context eliminates ambiguity when two fields have similar names or when a field has a cryptic database label.

View and field-level context

# order_items.view.omni
dimensions:
  id:
    sql: '"ID"'
    primary_key: true
    ai_context: >
      Generated automatically for each product in an order.
      Do not include this in queries unless specifically requested.

  status:
    sql: '"STATUS"'
    # Prevent hallucinations by defining all possible values
    all_values: [ Complete, Shipped, Processing, Cancelled, Returned ]
    ai_context: Current processing status of the individual item within the order.

  created_at:
    sql: '"CREATED_AT"'
    timeframes: [ date, week, month, quarter, year ]
    synonyms: [ purchase time, bought at ] # Map natural language to the field
    ai_context: >
      Timestamp of record creation. Preferred grains are date, week, and month.

Iterating on AI context

Improving AI quality is an iterative process. Use this workflow to refine your instance based on real usage:

Monitor: Use the AI usage dashboard in the Analytics section to find queries with negative (👎) feedback.
Identify: Did the AI fail due to a cryptic name, a missing join, or a lack of business logic?
Tune: Update the YAML at the appropriate level (model, topic, view).
Verify: Re-run the prompt in the Omni Agent 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

Model-level ai_context — Reference for model-level ai_context syntax
Topic-level ai_context — Reference for topic-level ai_context syntax
View-level ai_context — Reference for view-level ai_context syntax
Optimize models for Omni AI — Broader guidance on optimizing your model for AI