Tip: Always use

omni-model-explorer

first to understand the existing model.

1. Schema Layer — Auto-generated from your database. Reflects tables, views, columns, and their types. Kept in sync via schema refresh.
2. Shared Model Layer — Your governed semantic model. Where you define dimensions, measures, joins, and topics that are reusable across the organization.
3. Workbook Model Layer — Ad hoc extensions within individual workbooks. Used for experimental fields before promotion to shared model.
4. Branch Layer — Intermediate development layer. Used when working in branches before merging changes to shared model.

• New tables added to your database
• Column added, renamed, or deleted in an existing table
• Creating a new view from scratch and you want auto-generated base dimensions
• Model is out of sync with the database

hidden: true

omni models refresh <modelId>

omni models create-branch <modelId> --name "my-feature-branch"

model.id

branchId

omni models list --include activeBranches

Git-connected models: If your model is connected to a git repo (

omni models git-get <modelId>

returns an

sshUrl

), merging an Omni branch will automatically commit the changes back to your git

baseBranch

. Choose one workflow and stick to it — either edit via the Omni branch API (then

git pull

to sync local files), or edit local files and push via git. Mixing both leads to conflicts.

omni models yaml-create <modelId> --body '{
  "fileName": "my_new_view.view",
  "yaml": "dimensions:\n  order_id:\n    primary_key: true\n  status:\n    label: Order Status\nmeasures:\n  count:\n    aggregate_type: count",
  "mode": "extension",
  "branchId": "{branchId}",
  "commitMessage": "Add my_new_view with status dimension and count measure"
}'

Note: The

branchId

parameter must be a UUID from the server (Step 0). Passing a string name instead will return

400 Bad Request: Unrecognized key: "branchName"

.

omni models validate <modelId> --branchid <branchId>

• If any issue has

  is_warning: false

  , it's an error — fix before proceeding
• Common errors: broken column references, duplicate field names, invalid SQL syntax, missing join paths
• If

  auto_fix

  is present, review the suggestion before applying

omni query run --body '{
  "query": {
    "modelId": "<modelId>",
    "table": "your_view",
    "fields": ["your_view.new_dimension", "your_view.new_measure"],
    "limit": 10,
    "join_paths_from_topic_name": "your_topic"
  },
  "branchId": "<branchId>"
}'

Two complementary validation tools:

• omni query run

  — structured validation using explicit field expressions; use to precisely test specific dimensions, measures, and join paths

• omni ai job-submit --branch-id <branchId> --topic-name <topicName>

  — natural language validation; use to confirm the topic answers business questions correctly against live branch data.

  omni ai generate-query --run-query true

  does not resolve branch-only topics at execution time and should not be used for branch validation.

• No error in response — if the query returns an error, the field SQL is broken (bad column reference, wrong aggregate, dialect mismatch)

• summary.row_count

  > 0 — confirms the field resolves to actual data
• Values look correct — spot-check that a

  sum

  isn't returning a

  count

  , that a boolean dimension returns true/false (not 0/1 unexpectedly), etc.
• Joins work — if your field references another view (e.g.,

  ${users.id}

  ), include fields from both views to confirm the join resolves

omni query run --body '{
  "query": {
    "modelId": "<modelId>",
    "table": "base_view",
    "fields": ["base_view.id", "joined_view.some_field"],
    "limit": 10,
    "join_paths_from_topic_name": "your_topic"
  }
}'

undefined

Important: Always ask the user for confirmation before merging. Merging applies changes to the production model and cannot be easily undone. Only merge after validation and testing pass (Step 2).

omni models merge-branch <modelId> <branchName>

omni models validate <modelId>

Every view that participates in joins MUST have a real

primary_key: true

dimension. Without a genuine row-unique primary key, queries that join to this view can produce fanout errors or incorrect aggregations. Use the table's natural unique identifier (e.g.,

id

,

order_id

,

user_id

). If no single column is unique, build a composite key from row-level columns that are jointly unique, for example

sql: ${order_id} || '-' || ${line_number}

. If you cannot define a row-unique expression, do not mark a dimension as

primary_key: true

yet; fix the grain first or avoid joining the view until a real key exists.

• Schema layer: Auto-generated base dimensions, one per column. Types come from the database. Read-only, synced via schema refresh.
• Extension layer: Your custom YAML. Can override base dimensions, add new dimensions/measures, hide columns, add business logic.

created_at

revenue

undefined

references/modelParameters.md

• 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]

  )

Before writing a topic, verify all views you plan to reference actually exist. Run

omni models yaml-get <modelId>

and confirm each view appears. If a view is missing, run the lazy-load fallback above before concluding it doesn't exist — it may simply be in an offloaded schema.

• 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 WHERE filter using a SQL expression (cannot be removed by users)

• always_where_filters

  — non-removable WHERE filter using filter specifications (cannot be removed by users)

• always_having_sql

  — non-removable HAVING filter using a SQL expression, applied after aggregation (cannot be removed by users)

• always_having_filters

  — non-removable HAVING filter using filter specifications, applied after aggregation (cannot be removed by users)

• fields

  — field curation:

  [order_items.*, users.name, -users.internal_id]

Before defining, check the global relationships file for a join between the same two views in either direction. Same

on_sql

→ redundant, use

joins:

only. Different

on_sql

→ default to the extended views pattern below rather than a silent override. Confirm intent with the modeler.

undefined

• join_from_view: order_items join_to_view: users on_sql: ${order_items.user_id} = ${users.id} relationship_type: many_to_one join_type: always_left

> **`joins` vs `relationships`:** `joins` declares which views are in the topic and their hierarchy; `relationships` defines the join conditions. A topic using only global relationships needs only `joins`. A topic with a one-off join needs both.

users

join_to_view_as

.view

extends:

description:

views:

references/topic-scoped-relationships.md

If you see a

relationship alias duplicates view name

error, this pattern is the fix.

views:

display_order

label

Before adding any topic-scoped field to an existing view:

1. Read the view YAML (

   omni models yaml-get

   ) and confirm the field doesn't already exist. If it does with the same definition, skip it.
2. If a field with the same name exists but uses different SQL, this is an override. Confirm explicitly with the modeler — queries through this topic will use the topic-scoped definition; all other topics keep the shared one.

undefined

user_id

users

user_id

primary_key: true

dimensions:

custom_compound_primary_key_sql: [field_a, field_b]

primary_key: true

query:

sql:

sql:

${view_name}

CATALOG.SCHEMA.TABLE

references/query-view-examples.md

If the user is unsure which field is unique, ask before writing the view. A query view without a primary key will trigger a "Joins fan out the data without a primary key" error when joined. See: https://community.omni.co/t/why-am-i-getting-the-error-joins-fan-out-the-data-without-a-primary-key/37

views:

references/topic-scoped-views.md

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

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