omni-model-explorer

Omni 模型浏览器

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

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

前置条件

配置 Omni CLI：

# Verify the Omni CLI is installed — if not, ask the user to install it
# See: https://github.com/exploreomni/cli#readme
command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."

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

# Confirm the active profile is authenticated and inspect your permissions:
omni whoami whoami

身份验证：配置文件通过 API 密钥或 OAuth 进行身份验证。如果 whoami（或任何调用）返回 401，请转交处理 — 请用户运行 ! omni config login <profile>（OAuth 2.1 浏览器流程；会在浏览器打开期间阻塞约 2 分钟）。不要在无头/CI 会话中自行运行 config login（没有浏览器 → 超时）；在本地交互式机器上则可以运行。有关配置文件设置（omni config init --auth oauth）以及如何通过 --schema 发现命令和请求正文结构，请参阅 omni-api-conventions 规则。

API 密钥：Settings > API Keys（Organization Admin），或 User Profile > Manage Account > Generate Token（Personal Access Token）。

发现命令

不确定有哪些操作或标志可用时：

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

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

核心工作流

自顶向下探索：列出模型 → 选择模型 → 列出主题 → 检查主题 → 探索视图和字段。

步骤 1：列出可用模型

omni models list

返回模型（位于 records 键下 — {pageInfo, records:[…]}，而非顶层），包含 id、name、connectionId 和 modelKind（SCHEMA 或 SHARED）。使用 SHARED 模型 — 它包含经过整理的语义层。

在繁忙的实例上，直接调用会分页（每页 20 条），且结果大多是 name: null 的 WORKBOOK 模型 — 不要逐页浏览。 在服务端进行筛选：omni models list --model-kind SHARED --name "<exact name>" 可通过一次调用按名称查找共享模型。

如需同时查看每个模型上的活动分支：

omni models list --include activeBranches

响应中的每个模型都会包含一个 branches 数组。每个分支都有一个 id（UUID）和 name — 在其他 API 调用中，将 id 用作 branchId 参数。

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

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

omni models list-topics <modelId>

返回主题名称、基础视图、标签和说明。列表中混有常规主题和复合主题：复合条目的 is_composite: true，并会在 topics[] 中列出其组成主题（以及在 import_models 中列出任何跨模型导入项），且没有 base_view_name — 因此，对每个条目读取 base_view_name 的代码会得到 undefined。对复合主题执行 get-topic 会返回相同结构，并附带其 views 和 relationships。

步骤 3：检查主题

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

omni models get-topic <modelId> <topicName>

响应包含：

• base_view_name — 主表
• views[] — 所有可访问的视图，每个视图都包含 dimensions[] 和 measures[]
• relationships[] — 视图之间的联接方式
• default_filters — 默认应用的筛选条件
• ai_context — 给 Blobby（Omni 的 AI）的指令
• 配置后提供的 sample_queries 和 AI 字段选择元数据
• 对于复合主题：成员 topics、shared_views、带有各主题映射的 shared_dimensions，以及可寻址的字段范围（@_shared_dimensions_.<name>、@_shared_views_.<view>.<field>、@<topic>.<view>.<field>）；不存在 base_view_name

步骤 4：读取模型 YAML

如需查看完整的语义模型定义：

# All YAML files
omni models yaml-get <modelId>

# Specific file
omni models yaml-get <modelId> --file-name order_items.view

# Regex filter
omni models yaml-get <modelId> --file-name '.*sales.*'

# From a branch (branchId is a UUID from the list models response)
omni models yaml-get <modelId> --branch-id <branchId>

mode 参数：combined（默认值）会合并架构和共享模型；extension 仅显示共享模型的自定义内容。

files 映射以每个文件的完整存储路径为键（例如 MARTS/order_items.view），而 --file-name 会在读取时按正则表达式匹配。使用 omni-model-builder 编辑时，请复用这个完全相同的键，包括任何文件夹前缀；使用缩短的名称会创建重复项，而不是编辑原文件。

模型架构

Omni 分为三层：

1. 架构模型 — 根据数据库自动生成（只读）
2. 共享模型 — 分析工程师的自定义内容（维度、度量、标签、主题、AI 上下文）
3. 工作簿模型 — 每个仪表板的自定义内容（临时内容，不共享）

探索时，请使用 combined 视图查看所有可用内容。

关键概念

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

主题将视图连接起来，形成可查询的单元，是经过整理的分析起点。主题包含一个基础视图、已连接的视图、默认筛选条件和 AI 上下文。

关系用于定义连接：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]。

探索模式

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

“这些表之间有什么关系？” — 检查主题的 relationships[] — 查看 join_from_view、join_to_view、on_sql 和 relationship_type。

“Y 有哪些可用度量？” — 检查包含视图 Y 的主题 → 查看 measures[] 数组及其 aggregate_type 和 sql 定义。

回退方案：yaml-get 中缺少预期视图

仅当常规探索未能找到结果时，才使用此模式 — 用户指定了某个视图，但它不在 yaml-get 或 get-topic 的响应中，或者某个关系引用了一个未出现的视图。如果 yaml-get 返回了预期内容，请跳过本节。

原因：yaml-get 只会返回当前已加载架构中的视图。如果某个架构处于卸载或非活动状态，其视图就不会显示。get-schemas 调用会列出连接知道的所有架构，包括已卸载和非活动的架构，因此在告知用户“未找到”之前，下一步应先调用它。

两步恢复：

# 1. List every schema (loaded, offloaded, and inactive)
omni models get-schemas <modelId>
# → {"schemas": ["ANALYTICS", "PUBLIC", "STAGING", ...]}

# 2. If the target schema is in the list, load just that schema
omni models yaml-get <modelId> --include-schemas PUBLIC

如果列表中完全没有该架构，这并非延迟加载问题 — 连接可能无权访问该架构，或者该架构尚未同步。请咨询连接管理员。

--include-schemas 的规则：

• 每次调用只能接受一个架构名称 — API 不接受逗号分隔的名称。如需加载多个架构，请逐个加载。
• 设置此参数后，响应只包含属于该架构的视图。即使关系引用了其他架构中的视图，这些关系也会保留。
• 如需限定到某个分支，可在 yaml-get 中添加 --branch-id <id>，或在 get-schemas 中添加 --branch-id <id>（不同命令的标志名称不同 — 此处与 API 底层使用的大小写形式一致）。

计算字段

模型中的计算字段使用的格式与常规维度/度量不同。字段键为 calc_name，表达式属性为 sql_expression — 而不是 name/sql。

AI 上下文检查

当用户询问 Blobby 对某个主题了解什么时，请检查该主题并报告实际的 AI 配置，不要根据字段名称推断：

omni models get-topic <modelId> <topicName>
omni models yaml-get <modelId> --file-name '<topicName>\.topic'

读取 ai_context、sample_queries 和 AI 字段选择值。根据 CLI/API 的返回结构，get-topic 可能会将这些内容包装在顶层 topic 对象下；如果顶层的 ai_context 为 null，请检查 topic.ai_context，再判断是否不存在。如果 get-topic 未公开完整的 ai_fields 列表，请读取主题 YAML 并报告其中配置的 ai_fields。如果存在，请列出已配置的示例查询名称/提示词，以及这些查询使用的字段。

字段影响分析

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

1. 创建模型分支，确保运行验证器检查前字段确实已不存在：

omni models create-branch <modelId> --name "field-impact-<field-name>"

然后，根据正在测试的变更使用相应的设置方式：

• 删除/重命名数据库列：在仓库变更生效后，于分支上刷新架构，然后验证该分支。
• 仅修改模型中的字段：使用 omni models yaml-create 将修改后的 YAML 写入分支，并使用 yaml-get 返回的准确 fileName 键。

yaml-create 接受 JSON 请求体作为更新内容，不接受单独的 --file-name 或 --branch-id 标志：

omni models yaml-create <modelId> \
  --body '{"branchId":"<branchId>","fileName":"public/order_items.view","yaml":"<full modified YAML string>"}'

使用响应以及 yaml-get --branch-id 回读结果，确认文件已写入分支。对于仅修改模型字段的影响分析，请从分支 YAML 中删除该字段自身的定义，但保留现有的依赖字段引用，除非用户计划的变更也会删除这些引用。omni models validate 正是利用这些未解析的引用，找出可能受影响的度量、维度、主题和联接。

除非 yaml-get --branch-id <branchId> 证明目标字段在已有分支中不存在或已重命名，否则不要复用该分支。名称相符但 YAML 未变更的分支不是有效的影响范围分析分支。

2. 验证分支设置，再解读内容验证结果：

omni models yaml-get <modelId> --file-name '<viewName>\.view' --branch-id <branchId>
omni models validate <modelId> --branch-id <branchId>

精确验证字段定义，不要对整个文件进行子字符串搜索。例如，删除 dimensions: sale_price: {} 定义后，sql: ${sale_price} 中仍可能出现 sale_price；这是有效的影响测试分支，应报告为依赖引用。如果原字段定义仍出现在分支 YAML 中，请说明分支设置无效，并且不要声称验证器结果代表字段删除的影响。

3. 针对已验证的分支运行内容验证器：

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

这会返回所有存在已删除字段的失效引用的仪表板和图块。

大型内容集的干净结果可能仅代表引用检查通过。 内容量较大时，验证器会检查字段、视图和主题引用，而不会为每个查询生成执行计划，因此，即使查询引用的字段有效但已无法生成执行计划，也可能显示为干净结果。传入 --force-full-validation true（CLI ≥ 1.3.1）可为每个查询生成执行计划；对于大型模型，此操作会更慢。

4. 搜索模型 YAML，查找其他引用（与第 3 步并行运行）：

omni models yaml-get <modelId> --file-name '.*'

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

5. 报告：综合分支验证、内容验证器结果（失效的仪表板/图块）和 YAML 搜索结果（模型引用），生成结构化的影响范围报告。分别列出直接字段引用、经由依赖字段产生的连锁引用、原始 SQL 列引用，以及已保存内容的损坏情况。

不要对文档进行分页并逐个检查查询——内容验证器会通过一次调用为你完成此操作。

文档参考

• 模型 API · 主题 API · 建模概览 · 视图 · 主题 · 维度 · 度量
• 列出模型架构 · 获取模型 YAML

相关技能

• omni-model-builder — 创建或修改视图、主题和字段
• omni-query — 对已发现的字段运行查询
• omni-ai-optimizer — 检查并改进主题上的 AI 上下文