omni-model-builder

Omni Model Builder

Create and modify Omni's semantic model through the YAML API — views, topics, dimensions, measures, relationships, and query views.

Tip: Always use omni-model-explorer first to understand the existing model.

Prerequisites

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

You need 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.

Safe Development Workflow

Always work in a branch. Never write directly to production.

Step 1: Write YAML to a Branch

branchId is a UUID — retrieve it from the List Models endpoint with ?include=activeBranches. If the branch doesn't exist yet, Omni creates it.

Step 2: Validate

Returns validation errors and warnings with message, yaml_path, and sometimes auto_fix.

Step 3: Merge the Branch

Important: Always ask the user for confirmation before merging. Merging applies changes to the production model and cannot be easily undone.

If git with required PRs is configured, merge through your git workflow instead.

YAML File Types

Write with mode: "extension" (shared model layer). To delete a file, send empty yaml.

Writing Views

Basic View

Dimension Parameters

See references/modelParameters.md for the complete list of 35+ dimension parameters, format values, and timeframes.

Most common parameters:

• sql — SQL expression using ${field_name} references
• label — display name · description — help text (also used by Blobby)
• primary_key: true — unique key (critical for aggregations)
• hidden: true — hides from picker, still usable in SQL
• format — number_2, currency_2, percent_2, id
• group_label — groups fields in the picker
• synonyms — alternative names for AI matching (e.g., [client, account, buyer])

Measure Parameters

See references/modelParameters.md for the complete list of 24+ measure parameters and all 13 aggregate types.

Measure filters restrict rows before aggregation:

Filter conditions: is, is_not, greater_than, less_than, contains, starts_with, ends_with

Writing Topics

See Topics setup for complete YAML examples with joins, fields, and ai_context, and Topic parameters for all available options.

Key topic elements:

• base_view — the primary view for this topic
• joins — nested structure for join chains (e.g., users: {} or inventory_items: { products: {} })
• ai_context — guides Blobby's field mapping (e.g., "Map 'revenue' → total_revenue")
• default_filters — applied to all queries unless removed
• always_where_sql — non-removable filters
• fields — field curation: [order_items.*, users.name, -users.internal_id]

Writing Relationships

Getting relationship_type right prevents fanout and symmetric aggregate errors.

Query Views

Virtual tables defined by a saved query:

Or with raw SQL:

Common Validation Errors

Docs Reference

• Model YAML API · Views · Topics · Dimensions · Measures · Relationships · Query Views · Branch Mode

Related Skills

• omni-model-explorer — understand the model before modifying
• omni-ai-optimizer — add AI context after building topics
• omni-query — test new fields