omni-model-builder

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

The response model.id is your branchId — a UUID you'll pass to all subsequent API calls. To list existing branches at any time:

omni models list --include activeBranches

⚠️ Git-connected models — never hand-edit model YAML in git. The repo is a projection of Omni's model for governance (PRs, review, audit) — not the source of truth and not a surface to author against. Omni regenerates the default branch from its own authoritative state and deletes git-only model files that state doesn't contain — an observed customer incident where files committed only to git silently vanished on the next sync. So author through the Omni APIs on a branch → omni models commit (Step 3) → review/merge in your git provider; never push hand-edited model YAML directly.

Model content vs. repo governance — the split that makes this safe:

• Omni model content (view / topic / relationship YAML): author on an Omni branch → omni models commit → PR. Never commit it directly in git — Omni will regenerate over it.
• Repo-governance / non-model files (a root omni/OWNERS.yaml, CODEOWNERS, CI config, docs, scripts): not Omni model content, so direct git commits are fine — Omni's regeneration leaves them untouched.

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".

⚠️ Editing an existing file = whole-file read-modify-write at its exact path. yaml-create replaces a file's authored content (no field-by-field merge), so yaml-get it first, edit, and write the complete file back, or the other authored fields are dropped. fileName is the file's exact path (not a regex, unlike on read) — reuse the full-path key verbatim, folder prefix included (e.g. MARTS/fct_ai_events.view); a non-matching name doesn't error, it silently creates a duplicate at that path (success: true). (Schema base columns live in the schema layer, so they're unaffected.) To inspect a branch, yaml-get without --file-name enumerates the whole model — --mode extension for just the branch's changed files (your deltas), --mode combined for the full composed model (schema + shared + branch); then drill into any file by its exact path.

dbt-connected models: omni models branch-dbt-get <modelId> <branchName> (CLI ≥ 1.1.2) reads the dbt environment a branch resolves to, including the dbt git branch it compiles against. A branch with no environment of its own resolves to the connection's default (production) environment, reported with is_default_environment: true.

Every YAML write must be validated and tested before merging — a field can be valid YAML yet produce wrong results or broken queries.

# 1. Validate — a NEW issue with is_warning:false that references your changed file is blocking; fix before proceeding
omni models validate <modelId> --branch-id <branchId>

# 2. Query the fields you changed — confirm no error, and cache_metadata.num_rows > 0
#    (the row count is at cache_metadata.num_rows; there is NO summary.row_count — see omni-query)
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>"}'

# 3. Read it back — confirm the field is present (and not duplicated at a second path)
omni models yaml-get <modelId> --file-name your_view.view --branch-id <branchId>

Triage validation errors — most aren't yours. On a fresh/inherited model, blocking not found errors (missing table/view/column) usually mean a stale schema: run a schema refresh (omni models refresh <modelId>) first — it clears them; a not found that persists after refresh is real (connection lacks DB access, or a genuinely broken reference). For what remains, baseline before your change (or filter issues by yaml_path) and treat as blocking only the new errors referencing your changed files — report the pre-existing ones, don't chase them.

Spot-check that values look right (a sum isn't returning a count; booleans read true/false), and if a field references another view include fields from both to confirm the join resolves. See references/validation-and-testing.md for join-path testing, natural-language validation via omni ai job-submit, the full results checklist, and duplicate-file recovery.

Window-shaped result columns are table calculations, not model fields. A running total, moving average, period-over-period / MoM %, percent-of-total, or rank is computed per query on the result set — author it as a table calculation (query.calculations[]) per omni-query → references/table-calculations.md, not as a measure/dimension here. Only model an in-warehouse field when the window must span rows outside the result set.

Important: Always ask the user for confirmation before shipping. Changes applied to the production model cannot be easily undone. Only ship after validation and testing pass (Step 2).

Check whether the model is git-connected — omni models git-get <modelId>. A config with sshUrl / baseBranch → git-connected → Path A (open/update a PR); a 404/no config → not git-connected → Path B (merge directly in Omni).

Push the branch contents to git. Creates a new git branch + PR if one doesn't exist; otherwise updates the existing PR:

omni models commit <modelId> --body '{
  "branch_id": "<branchId>",
  "commit_message": "Add my_new_view with status dimension and count measure"
}'

Surface the returned pr_url to the user. The reviewer merges the PR in your git host; changes flow back to baseBranch on the next sync. Run omni models commit --help for optional body flags (allow_branch_exists, require_branch_exists) when you need to enforce open-only or update-only behavior.

After the merge, Omni regenerates the default branch from its own (authoritative) model state — re-serializing to canonical form, and adding a normalization commit only when the merged git content differs from that state. Content authored through the Omni APIs is already canonical, so a clean merge often adds no extra commit — don't go hunting for one; verify by resolution instead. (A non-git merge promotes the branch into the shared model.) Either way — and especially for net-new topics or views — confirm the files resolve against the production model (no --branch-id):

# 1. Files resolve in production — the new view appears / the new topic resolves
omni models get-views <modelId>                 # new view is listed
omni models get-topic <modelId> <topicName>     # new topic resolves (base_view_name + join_via_map present)

# 2. Production model validates — no blocking errors (any is_warning:false is blocking)
omni models validate <modelId>

# 3. Run at least one semantic query against the new topic/view
omni query run --body '{"query":{"modelId":"<modelId>","table":"<base_view>","fields":["<base_view>.<field>"],"limit":10,"join_paths_from_topic_name":"<topicName>"}}'

In the query response, confirm summary.missing_fields is [] (and summary.invalid_calculations is empty — note it comes back as {}, not []). A non-empty missing_fields means a field didn't resolve — the signature of a model file dropped or renamed during the merge. If anything is missing, re-author it through Omni; never patch it back by hand in git.

When you create a view, Omni separates schema (database structure) from model (your business logic):

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

When both layers exist for a field with the same name, your extension definition wins but type information comes from the schema layer.

Example: Table has columns created_at (DATE) and revenue (NUMERIC).

# Schema layer (auto-generated)
dimensions:
  created_at: {}  # type: DATE, auto-generates timeframes
  revenue: {}     # type: NUMERIC

# Extension layer (your YAML)
dimensions:
  created_at:
    label: "Order Created"
    description: "When the order was placed"

  revenue:
    hidden: true  # Hide the raw column

measures:
  total_revenue:
    sql: ${revenue}
    aggregate_type: sum
    format: currency_2

Result: created_at inherits its type from the schema layer (DATE with automatic week/month/year granularities) but gets your label. The raw revenue column is hidden, only exposed through the total_revenue measure.

Key insight: If your extension defines a dimension but there's no schema layer base dimension to provide type information, Omni can't infer granularities or types. Trigger a schema refresh to auto-generate the schema layer first.

Reading back what you wrote — --mode. yaml-get returns your extension layer by default — just the deltas you authored, not the auto-generated base columns. To see the fully-composed result (schema base + your extension merged), read with --mode combined:

# What you authored (deltas only) — default
omni models yaml-get <modelId> --file-name your_view.view --branch-id <branchId> --mode extension

# What the model actually resolves to (schema + extension merged)
omni models yaml-get <modelId> --file-name your_view.view --branch-id <branchId> --mode combined

Use extension to confirm what you changed, and combined to confirm what the model resolves to. When the model is git-integrated, the combined output mirrors what's written to the repository — which is why committed *.view.yaml files carry the schema-layer table_name: and base columns, while the extension layer holds only your deltas. (Other --mode values: staged, merged, history.)

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

Most common: sql, label, description (also used by Blobby), primary_key (unique key — critical for aggregations), hidden (hides from picker, still usable in SQL), format (number_2/currency_2/percent_2/id), group_label, synonyms (AI-matching aliases). Two gotchas: a raw column auto-maps by name (no sql: needed); there is no ${TABLE} construct — ${TABLE}.column errors Column "__omni_scoped" not found at validate/query time (reference fields via ${field}/${view.field}).

See references/modelParameters.md (24+ params, all 13 aggregate types) and references/yaml-filter-syntax.md (filter operators + measure-filter examples). Prefer a measure filters: block for filtered aggregates over CASE WHEN/WHERE in sql — keep sql focused on the value being aggregated:

measures:
  completed_revenue:
    sql: ${sale_price}
    aggregate_type: sum
    filters:
      status:
        is: Complete

Cross-view fields (dimensions or measures whose sql references ${other_view.field}) in a global view file are evaluated in every topic that exposes the host view. A global relationship can make the dependency reachable in topics that inherit the global join graph, but it does not override a topic's explicit/frozen joins: map. If that map omits the dependency, validation returns a blocking field_broken_in_topic issue and queries using the field fail to plan.

Placement follows intended availability and resolved join context, not field namespace. Define the field in the topic's views.<host_view> block (see "Topic-Scoped View Definitions") when it is meaningful only in that topic or depends on a topic-specific, aliased, or frozen join. The field remains queryable as <host_view>.<field>; topic scoping limits where it is available, not the namespace the user requested.

Use the global view file when the field is universally meaningful and its dependency resolves unambiguously in every topic that exposes the host view. Before choosing, list those topics and inspect each resolved get-topic join_via_map — not only the global relationships file — then validate the branch and query at least one topic for each distinct join context. Topics without explicit joins may inherit a global relationship; topics with explicit joins may exclude it.

When a query can't be answered by an existing topic, first check whether you should simply extend one rather than create a new one. Extending is usually right when the request's base view (the FROM) matches an existing topic's base view — e.g. add a relationship/join so a needed view becomes reachable, or add a field/label. Create a new topic when any of these is fundamentally different:

• Subject / object — a different base view (FROM). What is the query fundamentally describing — orders? users? time (dates)? A different core entity warrants its own topic.
• Constraints — conditions that are always applied (e.g. an always_where that excludes test users from order data). Different always-on filters → a different topic.
• Audience — the same fields but different labels/terminology for a different consumer; jargon that differs by audience justifies a separate topic.

Prompt the requestor when it's a judgment call, and build new topics on a branch (see the Safe Development Workflow above). Note that querying on a topic (vs a bare base view) is also what makes the result accessible to restricted queriers/viewers.

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

When configuring default_filters, always_where_filters, or always_having_filters on a topic, use the YAML filter condition syntax — the same syntax used in measure filters. See references/yaml-filter-syntax.md for the complete reference.

If the right filter configuration for a given use case isn't obvious, use the Omni AI CLI to search the docs:

omni ai search-omni-docs "how do I configure always_where_filters on a topic in Omni?"

Use targeted questions to get precise YAML examples for your specific filtering need before writing the model YAML.

Global relationships are defined in the shared relationships file and are available across all topics. Use these for standard, reusable joins.

- 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

Getting relationship_type right prevents fanout and symmetric aggregate errors.

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.

Use topic-scoped relationships for one-off joins not in the shared model, or joining the same table multiple times under different conditions.

# .topic file
relationships:
  - 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:
  users: {}

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.

Silent footgun — both are required, and omitting joins passes validation. If you add the relationships entry but forget the view's joins entry, the model still validates clean (no error) — but the joined view's fields are silently not exposed in the topic (a query/markdown referencing them comes back empty). Don't trust validate for this; confirm the fields are actually exposed with get-topic (see validation-and-testing.md). (Topic file shapes vary: some list views under a joins: map, others as top-level <view>: {} entries — match the existing file's form.)

When the same table needs multiple joins (e.g., users as buyer and seller), use the extended views pattern — not join_to_view_as. Two variants:

Variant 1 — Global (reusable): Create a standalone .view file with extends:, a role-descriptive name, and a description:. Define the relationship globally — any topic can then join it like any other view.

Variant 2 — Topic-scoped (inline): Define the alias in the topic's views: block with its relationship in the same file. Use when the alias is not generally applicable in other topics.

See references/topic-scoped-relationships.md for full YAML examples of both variants.

If you see a relationship alias duplicates view name error, this pattern is the fix.

Topics can define or override views inline using a views: block — controlling display_order, overriding label, adding topic-specific filtered measures or derived dimensions, defining cross-view fields, and joining the same view multiple ways with per-alias conditions.

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.

# Example: display order + topic-specific filtered measure
views:
  order_items:
    display_order: 0
    measures:
      us_revenue:
        sql: ${sale_price}
        aggregate_type: sum
        format: currency_2
        filters:
          users.country:
            is: US

See references/topic-scoped-views.md for a full pattern gallery (label overrides, derived dimensions, cross-view fields, multi-join lifecycle, topic-scoped query views).

Cross-view fields in views: blocks: Before writing ${view_name.field_name} references, confirm every referenced view is declared in the topic's joins: block — the model validator throws errors for any reference to a view that isn't joined.

Joining the same view multiple ways (e.g., ARR at Start / Current / End): Use extends: inside the topic's views: block to create named aliases, each with its own on_sql in relationships:. Each alias inherits all base view fields and can override labels independently. For a full YAML example, see references/topic-scoped-views.md.

Topic-scoped query views: A query view can also be defined inside a topic's views: block, scoping it to that topic only. Same primary key rules apply (primary_key: true or custom_compound_primary_key_sql). Include a relationships: entry and a joins: entry for the new view — see Query Views section above, and references/topic-scoped-views.md for a complete example.