omni-model-explorer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Omni Model Explorer

Omni模型探索器

Explore and understand an Omni semantic model through the Omni CLI. This is the starting point — understand what exists before building, querying, or modifying anything.

Tip: Start with the Shared model — it contains the curated analytics layer.

通过Omni CLI探索并了解Omni语义模型。这是起点——在构建、查询或修改任何内容之前，先了解现有内容。

提示：从Shared模型开始——它包含经过精心整理的分析层。

Prerequisites

前提条件

Configure the Omni CLI:

bash

undefined

配置Omni CLI：

bash

undefined

Verify the Omni CLI is installed — if not, ask the user to install it

验证Omni CLI是否已安装——如果未安装，请告知用户进行安装

See: https://github.com/exploreomni/cli#readme

参考：https://github.com/exploreomni/cli#readme

command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."


```bash

command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."


```bash

Show available profiles and select the appropriate one

显示可用配置文件并选择合适的配置文件

omni config show

If multiple profiles exist, ask the user which to use, then switch:

如果存在多个配置文件，请询问用户要使用哪个，然后切换：

omni config use <profile-name>


API keys: Settings > API Keys (Organization Admin) or User Profile > Manage Account > Generate Token (Personal Access Token).

omni config use <profile-name>


API密钥：组织管理员可通过“设置 > API密钥”获取，个人用户可通过“用户资料 > 管理账户 > 生成令牌”获取个人访问令牌。

Discovering Commands

发现命令

When unsure what operations or flags are available:

bash

omni models --help              # List all model operations
omni models <operation> --help  # Show flags and positional args

Tip: Use
-o json
to force structured output for programmatic parsing, or
-o human
for readable tables. The default is
auto
(human in a TTY, JSON when piped).

当不确定可用的操作或标志时：

bash

omni models --help              # 列出所有模型操作
omni models <operation> --help  # 显示标志和位置参数

提示：使用
-o json
强制输出结构化内容以便程序解析，或使用
-o human
输出易读的表格。默认值为
auto
（在终端中输出人类可读格式，管道传输时输出JSON）。

Core Workflow

核心工作流

Explore top-down: List models → Pick a model → List topics → Inspect a topic → Explore views and fields.

自上而下探索：列出模型 → 选择模型 → 列出主题 → 查看主题详情 → 探索视图和字段。

Step 1: List Available Models

步骤1：列出可用模型

bash

omni models list

Returns models with

id

name

connectionId

, and

modelKind

(SCHEMA or SHARED). Use the SHARED model — it contains the curated semantic layer.

To also see active branches on each model:

bash

omni models list --include activeBranches

Each model in the response will include a

branches

array. Each branch has an

id

(UUID) and

name

— use the

id

as the

branchId

parameter in other API calls.

bash

omni models list

返回包含

id

、

name

、

connectionId

和

modelKind

（SCHEMA或SHARED）的模型。使用SHARED模型——它包含经过精心整理的语义层。

要查看每个模型上的活跃分支：

bash

omni models list --include activeBranches

响应中的每个模型将包含一个

branches

数组。每个分支包含

id

（UUID）和

name

——在其他API调用中使用

id

作为

branchId

参数。

Step 2: List Topics in a Model

步骤2：列出模型中的主题

Topics are entry points for querying. Each topic defines a base view and the set of joined views available.

bash

omni models list-topics <modelId>

Returns topic names, base views, labels, and descriptions.

主题是查询的入口点。每个主题定义一个基础视图以及可用的关联视图集合。

bash

omni models list-topics <modelId>

返回主题名称、基础视图、标签和描述。

Step 3: Inspect a Topic

步骤3：查看主题详情

Get full detail including all views, dimensions, measures, relationships, and AI context:

bash

omni models get-topic <modelId> <topicName>

The response includes:

```
base_view_name
```
— the primary table
```
views[]
```
— all accessible views, each with
```
dimensions[]
```
and
```
measures[]
```
```
relationships[]
```
— how views join together
```
default_filters
```
— filters applied by default
```
ai_context
```
— instructions for Blobby (Omni's AI)

获取包含所有视图、维度、度量、关系和AI上下文的完整详情：

bash

omni models get-topic <modelId> <topicName>

响应包含：

```
base_view_name
```
—— 主表
```
views[]
```
—— 所有可访问的视图，每个视图包含
```
dimensions[]
```
和
```
measures[]
```
```
relationships[]
```
—— 视图之间的连接方式
```
default_filters
```
—— 默认应用的过滤器
```
ai_context
```
—— Omni的AI工具Blobby的指令

Step 4: Read the Model YAML

步骤4：读取模型YAML

For the full semantic model definition:

bash

undefined

获取完整的语义模型定义：

bash

undefined

All YAML files

所有YAML文件

omni models yaml-get <modelId>

Specific file

特定文件

omni models yaml-get <modelId> --filename order_items.view

Regex filter

正则过滤

omni models yaml-get <modelId> --filename '.sales.'

From a branch (branchId is a UUID from the list models response)

从分支获取（branchId来自列出模型响应中的UUID）

omni models yaml-get <modelId> --branchid <branchId>


The `mode` parameter: `combined` (default) merges schema + shared model; `extension` shows only shared model customizations.

omni models yaml-get <modelId> --branchid <branchId>


`mode`参数：`combined`（默认）合并schema + shared模型；`extension`仅显示shared模型的自定义内容。

Model Architecture

模型架构

Omni has three layers:

Schema Model — auto-generated from your database (read-only)
Shared Model — analytics engineer customizations (dimensions, measures, labels, topics, AI context)
Workbook Model — per-dashboard customizations (ad-hoc, not shared)

When exploring, use the

combined

view to see everything available.

Omni包含三层：

Schema模型 —— 从数据库自动生成（只读）
Shared模型 —— 分析工程师的自定义内容（维度、度量、标签、主题、AI上下文）
Workbook模型 —— 每个仪表板的自定义内容（临时，不共享）

探索时，使用

combined

视图查看所有可用内容。

Key Concepts

核心概念

Views correspond to database tables. Each has dimensions (groupable fields) and measures (aggregations).

Topics join views together into queryable units — curated starting points for analysis. A topic has a base view, joined views, default filters, and AI context.

Relationships define joins:

join_from_view

join_to_view

on_sql

relationship_type

(one_to_one, many_to_one, one_to_many, many_to_many), and

join_type

(always_left, inner, full_outer).

Field naming:

view_name.field_name

with bracket notation for date granularity:

orders.created_at[week]

Views对应数据库表。每个视图包含维度（可分组字段）和度量（聚合计算）。

Topics将多个视图关联成可查询单元——是分析的精心整理起点。主题包含基础视图、关联视图、默认过滤器和AI上下文。

Relationships定义连接方式：

join_from_view

、

join_to_view

、

on_sql

、

relationship_type

（one_to_one、many_to_one、one_to_many、many_to_many）和

join_type

（always_left、inner、full_outer）。

字段命名：

view_name.field_name

，日期粒度使用括号表示法：

orders.created_at[week]

。

Exploration Patterns

探索模式

"What data do we have about X?" — List topics → inspect the most relevant one → review views and fields.

"How do these tables relate?" — Inspect the topic's

relationships[]

— check

join_from_view

join_to_view

on_sql

, and

relationship_type

"What measures are available for Y?" — Inspect the topic containing view Y → review the

measures[]

array with

aggregate_type

and

sql

definitions.

“我们有关于X的哪些数据？” —— 列出主题 → 查看最相关的主题 → 查看视图和字段。

“这些表之间是如何关联的？” —— 查看主题的

relationships[]

—— 检查

join_from_view

、

join_to_view

、

on_sql

和

relationship_type

。

“Y有哪些可用的度量？” —— 查看包含视图Y的主题 → 查看带有

aggregate_type

和

sql

定义的

measures[]

数组。

Fallback: Expected View Missing from

yaml-get

备用方案：

yaml-get

未返回预期视图

Use this pattern only when normal exploration comes up short — the user names a specific view and it's absent from the

yaml-get

get-topic

response, or a relationship references a view that doesn't appear. If

yaml-get

returned what you expected, skip this section.

Why it happens:

yaml-get

only returns views from currently-loaded schemas. If a schema is offloaded or inactive, its views won't show up. The

get-schemas

call surfaces all schemas the connection knows about — including offloaded and inactive ones — so it's the right next step before telling the user "not found."

Two-step recovery:

bash

undefined

仅当常规探索无法得到结果时才使用此模式——用户指定了某个特定视图，但该视图未出现在

yaml-get

或

get-topic

的响应中，或者某个关系引用了未显示的视图。如果

yaml-get

返回了预期内容，请跳过本节。

原因：

yaml-get

仅返回当前已加载的schema中的视图。如果某个schema被卸载或处于非活跃状态，其视图将不会显示。

get-schemas

调用会显示连接所知的所有schema——包括已卸载和非活跃的schema——因此在告知用户“未找到”之前，这是正确的下一步操作。

两步恢复流程：

bash

undefined

1. List every schema (loaded, offloaded, and inactive)

1. 列出所有schema（已加载、已卸载和非活跃）

omni models get-schemas <modelId>

→ {"schemas": ["ANALYTICS", "PUBLIC", "STAGING", ...]}

2. If the target schema is in the list, load just that schema

2. 如果目标schema在列表中，仅加载该schema

omni models yaml-get <modelId> --includeschemas PUBLIC


**If the schema isn't in the list at all**, this isn't a lazy-load issue — the connection likely doesn't have access or the schema isn't synced. Check with a Connection Admin.

**Rules for `--includeschemas`:**
- Accepts exactly **one schema name** per call — commas are rejected by the API. Load schemas one at a time if you need multiple.
- When set, the response contains only views belonging to that schema. Relationships are preserved even when they reference views in other schemas.
- To scope to a branch, add `--branchid <id>` to `yaml-get` or `--branch-id <id>` to `get-schemas` (the flag names differ per command — this matches the API's underlying casing).

omni models yaml-get <modelId> --includeschemas PUBLIC


**如果schema完全不在列表中**，这并非延迟加载问题——连接可能没有访问权限，或者该schema未同步。请联系连接管理员。

**`--includeschemas`规则**：
- 每次调用仅接受**一个**schema名称——API会拒绝逗号分隔的多个名称。如果需要多个schema，请逐个加载。
- 设置该参数后，响应仅包含属于该schema的视图。即使关系引用了其他schema中的视图，关系仍会被保留。
- 要限定到分支，请在`yaml-get`中添加`--branchid <id>`，或在`get-schemas`中添加`--branch-id <id>`（不同命令的标志名称不同——这与API底层的大小写一致）。

Calculation Fields

计算字段

Calculation fields in the model use a different format than regular dimensions/measures. The field key is

calc_name

and the expression property is

sql_expression

— not

name

sql

模型中的计算字段使用与常规维度/度量不同的格式。字段键为

calc_name

，表达式属性为

sql_expression

——而非

name

sql

。

Field Impact Analysis

字段影响分析

Assess the blast radius of a field migration or removal before pushing changes to dbt:

Create a model branch with
```
omni-model-builder
```
where the field is removed or renamed
Run the content validator against that branch:

bash

omni models content-validator-get <modelId> --branch-id <branchId>

This returns all dashboards and tiles with broken references to the removed field.

Search model YAML for additional references (run in parallel with step 2):

bash

omni models yaml-get <modelId> --filename '.*'

Search the response for the field name to find references in other views, topics, and calculated fields.

Report: Combine content-validator results (broken dashboards/tiles) with YAML search results (model references) into a structured blast-radius report.

Do NOT paginate documents and check queries individually — the content validator does this for you in one call.

在将更改推送到dbt之前，评估字段迁移或移除的影响范围：

使用
omni-model-builder
创建模型分支，在该分支中移除或重命名字段
针对该分支运行内容验证器：

bash

omni models content-validator-get <modelId> --branch-id <branchId>

这会返回所有包含对已移除字段的无效引用的仪表板和图表。

搜索模型YAML中的其他引用（与步骤2并行运行）：

bash

omni models yaml-get <modelId> --filename '.*'

在响应中搜索字段名称，以查找其他视图、主题和计算字段中的引用。

报告：将内容验证器的结果（无效的仪表板/图表）与YAML搜索结果（模型引用）合并，生成结构化的影响范围报告。

请勿分页查看文档并逐个检查查询——内容验证器会一次性为你完成此操作。

Docs Reference

文档参考

Models API · Topics API · Modeling Overview · Views · Topics · Dimensions · Measures
List model schemas · Get model YAML

Models API · Topics API · Modeling Overview · Views · Topics · Dimensions · Measures
List model schemas · Get model YAML

omni-model-explorer

Original

Translation

Omni Model Explorer

Omni模型探索器

Prerequisites

前提条件

Verify the Omni CLI is installed — if not, ask the user to install it

验证Omni CLI是否已安装——如果未安装，请告知用户进行安装

See: https://github.com/exploreomni/cli#readme

参考：https://github.com/exploreomni/cli#readme

Show available profiles and select the appropriate one

显示可用配置文件并选择合适的配置文件

If multiple profiles exist, ask the user which to use, then switch:

如果存在多个配置文件，请询问用户要使用哪个，然后切换：

Discovering Commands

发现命令

Core Workflow

核心工作流

Step 1: List Available Models

步骤1：列出可用模型

Step 2: List Topics in a Model

步骤2：列出模型中的主题

Step 3: Inspect a Topic

步骤3：查看主题详情

Step 4: Read the Model YAML

步骤4：读取模型YAML

All YAML files

所有YAML文件

Specific file

特定文件

Regex filter

正则过滤

From a branch (branchId is a UUID from the list models response)

从分支获取（branchId来自列出模型响应中的UUID）

Model Architecture

模型架构

Key Concepts

核心概念

Exploration Patterns

探索模式

Fallback: Expected View Missing from yaml-get

备用方案：yaml-get未返回预期视图

1. List every schema (loaded, offloaded, and inactive)

1. 列出所有schema（已加载、已卸载和非活跃）

→ {"schemas": ["ANALYTICS", "PUBLIC", "STAGING", ...]}

→ {"schemas": ["ANALYTICS", "PUBLIC", "STAGING", ...]}

2. If the target schema is in the list, load just that schema

2. 如果目标schema在列表中，仅加载该schema

Calculation Fields

计算字段

Field Impact Analysis

字段影响分析

Docs Reference

文档参考

Related Skills

相关技能

Fallback: Expected View Missing from
`yaml-get`

备用方案：
`yaml-get`
未返回预期视图