omni-ai-optimizer

Omni AI Optimizer

Optimize your Omni semantic model so Blobby (Omni's AI assistant) returns accurate, contextual answers.

Tip: Use omni-model-explorer to inspect current AI context before making changes.

Prerequisites

export OMNI_BASE_URL="https://yourorg.omniapp.co"
export OMNI_API_KEY="your-api-key"

Requires Modeler or Connection Admin permissions.

API Discovery

When unsure whether an endpoint or parameter exists, fetch the OpenAPI spec:

curl -L "$OMNI_BASE_URL/openapi.json" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Use this to verify endpoints, available parameters, and request/response schemas before making calls.

How Blobby Works

Blobby generates queries by examining:

1. Topic structure — which views and fields are joined
2. Field labels and descriptions — how fields are named
3. synonyms — alternative names for fields
4. ai_context — explicit instructions you write
5. ai_fields — which fields are visible to AI
6. sample_queries — example questions with correct queries
7. Hidden fields — hidden: true fields are excluded

Impact order: ai_context > ai_fields > sample_queries > synonyms > field descriptions.

Writing ai_context

Add via the YAML API:

curl -L -X POST "$OMNI_BASE_URL/api/v1/models/{modelId}/yaml" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "order_transactions.topic",
    "yaml": "base_view: order_items\nlabel: Order Transactions\nai_context: |\n  Map \"revenue\" → total_revenue. Map \"orders\" → count.\n  Map \"customers\" → unique_users.\n  Status values: complete, pending, cancelled, returned.\n  Only complete orders for revenue unless specified otherwise.",
    "mode": "extension",
    "commitMessage": "Add AI context to order transactions topic"
  }'

What Makes Good ai_context

Terminology mapping — map business language to field names:

ai_context: |
  "revenue" or "sales" → order_items.total_revenue
  "orders" → order_items.count
  "customers" → users.count or order_items.unique_users
  "AOV" → order_items.average_order_value

Data nuances — explain what isn't obvious from field names:

ai_context: |
  Each row is a line item, not an order. One order has multiple line items.
  total_revenue already excludes returns and cancellations.
  Dates are in UTC.

Behavioral guidance — direct common patterns:

ai_context: |
  For trends, default to weekly granularity, sort ascending.
  For "top N", sort descending and limit to 10.

Persona prompting — set the analytical perspective:

ai_context: |
  You are the head of finance analyzing customer payment data.
  Default to monetary values in USD with 2 decimal places.

Curating Fields with ai_fields

Reduce noise for large models:

ai_fields:
  - all_views.*
  - -tag:internal
  - -distribution_centers.*

# Or explicit list
ai_fields:
  - order_items.created_at
  - order_items.total_revenue
  - order_items.count
  - users.name
  - users.state
  - products.category

Same operators as topic fields: wildcard (*), negation (-), tags (tag:).

Adding sample_queries

Teach Blobby by example. Build the correct query in a workbook, retrieve its structure, then add to the topic YAML:

sample_queries:
  revenue_by_month:
    prompt: "What month has the highest revenue?"
    ai_context: "Use total_revenue grouped by month, sorted descending, limit 1"
    query:
      base_view: order_items
      fields:
        - order_items.created_at[month]
        - order_items.total_revenue
      topic: order_transactions
      limit: 1
      sorts:
        - field: order_items.total_revenue
          desc: true

Note: When exporting queries from Omni's workbook, you'll get JSON with table, join_paths_from_topic_name, and sorts using column_name/sort_descending. Map these to YAML as follows:

• table → base_view
• join_paths_from_topic_name → topic
• column_name → field, sort_descending → desc
• Workbook JSON includes filters, pivots, limit, column_limit which you can include in YAML (though filter syntax requires consulting the Model YAML API docs directly)

Focus on questions users actually ask — check Analytics > AI usage in Omni.

AI-Specific Topic Extensions

Create a curated topic variant for Blobby using extends:

# ai_order_transactions.topic
extends: [order_items]
label: AI - Order Transactions

fields:
  - order_items.created_at
  - order_items.status
  - order_items.total_revenue
  - order_items.count
  - users.name
  - users.state
  - products.category

ai_context: |
  Curated view of order data for AI analysis.
  [detailed context here]

sample_queries:
  top_categories_last_month:
    prompt: "Top selling categories last month?"
    query:
      base_view: order_items
      fields:
        - products.category
        - order_items.total_revenue
      topic: ai_order_transactions
      limit: 10
      sorts:
        - field: order_items.total_revenue
          desc: true

Improving Field Descriptions

dimensions:
  status:
    label: Order Status
    description: >
      Current fulfillment status. Values: complete, pending, cancelled, returned.
      Use 'complete' for revenue calculations.

Good descriptions help both Blobby and human analysts.

Adding synonyms

Map alternative names, abbreviations, and domain-specific terminology so Blobby matches user queries to the correct field. Works on both dimensions and measures.

dimensions:
  customer_name:
    synonyms: [client, account, buyer, purchaser]
  order_date:
    synonyms: [purchase date, transaction date, order timestamp]

measures:
  total_revenue:
    synonyms: [sales, income, earnings, gross revenue, top line]
  average_order_value:
    synonyms: [AOV, avg order, basket size]

Synonyms vs ai_context: Use synonyms for field-level name mapping. Use ai_context for topic-level behavioral guidance, data nuances, and multi-field relationships.

Optimization Checklist

1. Inspect current state with omni-model-explorer
2. Check AI usage dashboard for real user questions
3. Write ai_context mapping business terms to fields
4. Add synonyms to key dimensions and measures
5. Curate ai_fields to remove noise
6. Add sample_queries for top 3-5 questions
7. Improve field description values
8. Consider extends for AI-specific topic variants
9. Test iteratively — ask Blobby and refine

Docs Reference

• Optimizing Models for AI · Synonyms · Topic Parameters · Model YAML API · Omni AI Overview

Related Skills

• omni-model-explorer — inspect existing AI context
• omni-model-builder — modify views and topics
• omni-query — test queries to verify Blobby's output