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 モデルを使ってください。

インスタンスが混み合っている場合、引数なしの呼び出しはページネーションされ（1 ページあたり 20 件）、name: null の WORKBOOK モデルが大半を占めます。ページをめくって確認しないでください。 サーバー側でフィルターします：omni models list --model-kind SHARED --name "<exact name>" を使うと、共有モデルを名前で 1 回の呼び出しで特定できます。

各モデルのアクティブなブランチも確認するには：

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 には 3 つのレイヤーがあります。

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 を含むトピックを調べ、aggregate_type と sql の定義を含む measures[] 配列を確認します。

フォールバック：yaml-get に想定したビューがない場合

このパターンは、通常の探索では見つからない場合にのみ使用してください。ユーザーが特定のビューを指定したものの、yaml-get または get-topic の応答にそのビューがない場合や、リレーションシップが、表示されていないビューを参照している場合が該当します。yaml-get から期待どおりの情報が返された場合は、このセクションを読み飛ばしてください。

理由： yaml-get が返すのは、現在読み込まれているスキーマのビューのみです。スキーマがオフロードまたは非アクティブの場合、そのビューは表示されません。get-schemas 呼び出しでは、オフロード済みや非アクティブなものも含め、接続が認識しているすべてのスキーマが表示されます。そのため、ユーザーに「見つかりません」と伝える前に、次に実行するのが適切です。

2 ステップでの復旧：

# 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 のルール：

• 1 回の呼び出しで指定できるスキーマ名は1 つのみです。カンマを使うと API で拒否されます。複数のスキーマが必要な場合は、1 つずつ読み込んでください。
• このオプションを設定すると、応答にはそのスキーマに属するビューのみが含まれます。ほかのスキーマ内のビューを参照する場合も、リレーションシップは保持されます。
• ブランチを指定するには、yaml-get または get-schemas に --branch-id <id> を追加します（コマンドによってフラグ名は異なります。API の内部で使用されている大文字・小文字の形式に合わせています）。

計算フィールド

モデル内の計算フィールドでは、通常のディメンションやメジャーとは異なる形式を使用します。フィールドキーは calc_name、式のプロパティは name／sql ではなく sql_expression です。

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-get が返す正確な fileName キーで変更済み YAML をブランチに書き込みます。

yaml-create は、個別の --file-name フラグや --branch-id フラグではなく、JSON ボディとして更新を受け取ります。

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 の検索結果（モデル参照）をまとめ、構造化された影響範囲レポートを作成します。フィールドへの直接参照、依存フィールドを経由する連鎖的な参照、raw SQL の列参照、保存済みコンテンツの破損を分けて示してください。

ドキュメントをページ分割して、クエリを個別に確認しないでください。コンテンツバリデーターが 1 回の呼び出しで処理します。

ドキュメントリファレンス

• モデル API · トピック API · モデリングの概要 · ビュー · トピック · ディメンション · メジャー
• モデルのスキーマ一覧 · モデル YAML の取得

関連スキル

• omni-model-builder — ビュー、トピック、フィールドを作成または変更します
• omni-query — 検出したフィールドに対してクエリを実行します
• omni-ai-optimizer — トピックの AI コンテキストを確認し、改善します