create-cubes

Cube の作成

スキルの依存関係

このスキルでは、dbt 関連の知識を create-dbt-transformations に委ねます。 プロジェクトのレイアウト、ゴールドモデルの検索、dbt モデル名から BigQuery テーブル参照への解決、 JSON 配列からのブリッジモデルの作成、dbt の検証コマンドが対象です。

create-dbt-transformations がインストールされていない場合は、find dbt/models/gold -name "*.sql" で ゴールドモデルを直接検索し、ブリッジモデルの作成は委任しないでください。 ユーザーに次のように警告してください。「create-dbt-transformations スキルがインストールされていません。ブリッジモデルの作成と dbt の検証は制限されます。」

BigQuery の調査（テーブルの一覧表示、スキーマの確認、行のプレビュー）が必要な場合は、 必要に応じて explore-lakehouse スキルを読み込んでください。

---

目的

既存の dbt ゴールドモデルを、YAML の定型記述を手作業で作成することなく、クエリ可能な Cube.dev セマンティックモデルとして公開します。ゴールドモデルにはテーブルまたはビューを使用できます。

各キューブは cubes/ に保存される、完全で独立した定義です。パッチ適用やマージは行われません。ファイルに記述されている内容がそのままデプロイされます。

このスキルではゴールドモデルを構築しません。必要なゴールドモデルがない場合は、create-dbt-transformations に引き継いでください。

---

命名規則

キューブ名とファイル名から gold_ プレフィックスを取り除きます。sql_table（物理テーブル）では gold_ を残してください。

キューブの識別子は spec.name（Cube.dev の definition.name）です。これはコンパイラーが解析する名前であり、${CUBE} や結合が参照する名前です。有効な SQL／JS 識別子である必要があります。snake_case（英字、数字、アンダースコア）を使用し、ハイフンは使用しないでください。spec.name にハイフンが含まれていると、フィールドレベルのメッセージがない汎用的な 500 エラーがコンパイラーから返されます。spec.name は必須です。

metadata.name はローカル IaC スラッグであり、cubes/<name>.yml のファイル名、および他のファイルから参照する際の名前です。これはAPI に送信されません。慣例として、他のすべてのリソースと同じスラッグ形式である kebab-case（hubspot-companies）を使用します。したがって、キューブには kebab-case のスラッグと snake_case の識別子の両方があります。結合ではスラッグではなく、snake_case の識別子（${hubspot_companies}）を参照します。

gold SQL file:     dbt/models/gold/gold_hubspot_companies.sql
BigQuery table:    gold_hubspot_companies
cube file:         cubes/hubspot-companies.yml
metadata.name:     hubspot-companies     (local slug — kebab-case)
spec.name:         hubspot_companies     (cube identifier — snake_case, required)
join reference:    ${hubspot_companies}  (references spec.name)
sql_table:         "`<dataset>.gold_hubspot_companies`"

ブリッジキューブにも同じ規則を適用します。gold_deals_companies -> キューブ名は deals_companies、ファイル名は cubes/deals_companies.yml です。

キューブの sql_table 参照

物理ウェアハウステーブルを直接参照します。Cube は Jinja を理解しません。dbt ref() は使用しないでください。

フェーズ 2 で解決した dataset のリテラル値を使用します。BigQuery のバッククォートで囲んでください。

sql_table: "`<dataset>.gold_hubspot_companies`"

refresh_key.sql にも同じ完全修飾形式を使用してください。

---

ユーザー確認ポイント

確認ポイント 1：ゴールドモデルの選択

ゴールドモデルを検索した後、利用可能なモデルを提示し、どのモデルを対象にするかユーザーに確認します。ユーザーが選択するまで先に進まないでください。例外として、ユーザーが特定のモデルを 1 つ指定した場合は、それを選択済みとして扱います。

確認ポイント 2a：コネクターモデルの承認

選択したモデルが直接つながっていない場合は、残りのゴールドモデルからコネクターを検索します。コネクターの経路を提示し、追加する前に承認を求めます。

確認ポイント 2b：ブリッジ／サポートモデルの承認

多対多の関係が検出され、適切なブリッジモデルが存在しない場合は、作成するかどうかを確認します。承認された場合は、create-dbt-transformations に委任してください。

確認ポイント 3：リレーションシップの確認

検証済みのリレーションシップについて、結合の方向、カーディナリティ、マッチ率を提示します。キューブファイルを生成する前に、ユーザーに確認を求めてください。未検証の結合を確定済みとして提示しないでください。validation pending と記してください。

確認ポイント 4：メジャーの確認

デフォルトの count メジャーを生成し、追加のメジャーを提案して、確認するかカスタムメジャーを指定するかをユーザーに尋ねます。

---

ワークフロー

以下のフェーズを順番に実行してください。先のフェーズに進まないでください。

---

フェーズ 1：ゴールドモデルを検出し、対象範囲を選択する

1. find dbt/models/gold -name "*.sql" を実行して、ゴールドモデルを検出します。
2. ゴールドモデルが存在しない場合は停止し、まず create-dbt-transformations を使ってゴールドモデルを作成するようユーザーに伝えます。
3. cubes/ 内の既存の Cube ファイルを 1～2 個確認して、規約（extends:、public:、refresh_key のスタイル）を把握します。新しい Cube にも、把握した規約を適用します。必ずフラットな単一 Cube の YAML を使用します（ルートに cubes: や views: を置かないでください）。
4. ユーザーが特定のモデルを指定した場合は、そのモデルを探します。見つからない場合は停止します。
5. それ以外の場合は、検出したすべてのゴールドモデルを一覧表示し、どれを対象にするかユーザーに尋ねます（チェックポイント 1）。
6. フェーズ 3 でコネクターを検索できるよう、検出したモデルの全リストを保持します。

---

フェーズ 2：選択したモデルのスキーマとキーを分析する

最初に環境変数を解決する

SQL や YAML を生成する前に、$REVOS_BQ_DATASET をリテラル値に解決します。

echo "DATASET=$REVOS_BQ_DATASET"

空の場合は停止し、ユーザーに設定を依頼します。以降はすべてこのリテラル値を使用します。

スキーマの検出

選択した各ゴールドモデルについて、カラムと型を調べます。必要に応じて explore-lakehouse を使用します。

_airbyte_extracted_at が存在するか確認します（refresh_key に必要で、公開する Airbyte ディメンションはこれだけです）。

キーの検出

主キー、二次キー、外部キー、JSON／配列キーを検出します。 一般的なパターンと検出ルールについては、references/key-patterns.md を参照してください。

SQL で主キーの一意性を検証します。references/validation-queries.md のセクション 1 を参照してください。

各モデルについて、スキーマの概要を出力します（形式は key-patterns.md を参照）。

---

フェーズ 3：関連候補を検出する

関連候補のグラフを作成します。これらは候補にすぎず、フェーズ 4 で検証する必要があります。

単一モデルの場合

モデルが 1 つだけ選択され、そのモデルに JSON／配列の関連カラムがない場合は、フェーズ 6 に進みます。JSON／配列カラムがある場合は、ブリッジ／ジャンクションが必要か確認します。

関連の種類と方向

Cube の型を使用します：one_to_one、one_to_many、many_to_one、many_to_many。方向は常に、現在の Cube の視点から示します。

カーディナリティのルール

1. ソースの外部キーが重複し、ターゲットのキーが一意の場合 → many_to_one／逆方向は one_to_many。
2. 両側が一意の場合 → one_to_one。
3. 両側で重複が可能な場合、またはブリッジ経由の場合 → many_to_many。
4. 判断が明確でない場合は、提案する前に検証します。

直接結合の検出

外部キーと主キーの一致、二次キーの一致、既存のブリッジモデル、JSON／配列の関連フィールドを確認します。

コネクターモデルの検索

選択したモデルが互いに接続されていない場合：

1. 検出したすべてのゴールドモデルから、コネクターパスを検索します（長さ 2、次に 3）。
2. 関連の検出のみを目的として、未選択のモデルを調べます。これによって対象範囲に追加されることはありません。
3. コネクターパスを提示し、ユーザーの承認を求めます（チェックポイント 2a）。
4. 承認された場合は対象範囲に追加し、完全なスキーマ検出を実行します。却下された場合は、接続されていないモデルを記録します。

ブリッジ／ジャンクションの検出

dbt/models/gold/ に既存のブリッジモデルが見つかった場合：

1. そのスキーマを調べ、想定されるキーのカラムが含まれていることを確認します。
2. 適合する場合は、それを使用します。きれいに適合しない場合は、不一致を提示し、選択肢（そのまま使用、新規作成、中止）を提示します。

ブリッジが存在せず、ユーザーが作成を承認した場合（チェックポイント 2b）は、create-dbt-transformations に委任します。作成されたら、public: false を指定してブリッジ Cube を生成します。

---

フェーズ 4：候補となるリレーションシップを検証する

BigQuery に対して SQL を実行し、候補となる結合が機能することと、方向が正しいことを確認します。

候補となる各リレーションシップについて、次を検証します。

• キーの一意性
• FK の一致率（LEFT JOIN と一致率）
• 逆方向の集計件数
• ブリッジエッジの整合性（両側）
• JSON 配列の抽出一致率
• INFORMATION_SCHEMA を使用した型の互換性

すべての SQL テンプレートについては、references/validation-queries.md を参照してください。

可能な場合は、候補となるすべてのリレーションシップについて、両方向を検証してください。

検証していない結合を、確認済みとして提示しないでください。検証を実行できない場合は、validation pending と記載してください。

---

フェーズ 5：検証済みのリレーションシップを提示する

選択したモデル、承認済みのコネクター、キー、カーディナリティを含む結合、一致率、検証の根拠を含め、検証済みのリレーションシップをすべてユーザーに提示します。

ユーザーに確認または変更を求めます（チェックポイント 3）。確認が完了するまでファイルを生成しないでください。

リレーションシップを検証できなかったものの、ユーザーが続行する場合は、生成した YAML に # UNVALIDATED: <reason> を付けてください。

---

フェーズ 6：ディメンションを生成する

選択した各ゴールドモデルのすべてのビジネス列を Cube ディメンションとして公開します。

主なルール：

1. PK には primary_key: true を設定します。複合 PK の場合は、合成 CONCAT ディメンションを使用します。references/cube-examples.md の複合主キーのセクションを参照してください。
2. セカンダリーキー、名前、ステータス、タイムスタンプ、数値属性をディメンションに含めます。
3. _airbyte_* 列からは、ディメンション airbyte_extracted_at として _airbyte_extracted_at のみを含めます（${CUBE}._airbyte_extracted_at として参照します）。その他の _airbyte_* 列はすべて除外します。
4. すぐに役立つように見えないという理由だけで、ビジネス列を削除しないでください。
5. リレーションシップに使用する JSON／配列列は、ブリッジモデルを通じて表現します。
6. モデルにビジネス列が 50 を超える場合は、生成前にユーザーに確認します。

型のマッピングとディメンションの例については、references/cube-examples.md を参照してください。

---

フェーズ 7：メジャーを提案して確認する

1. デフォルトの count メジャーを必ず含めます。
2. 列名に基づいて、役立つ追加メジャーを提案します。references/cube-examples.md の「メジャーの提案」セクションを参照してください。
3. FK 列に対する count_distinct は、親 Cube ではなく、FK を所有する Cube 内で定義します。結合によってファンアウトが発生し、個別カウントが歪むためです。
4. 提案したメジャーを確認するか、カスタムメジャーを定義するようユーザーに求めます（チェックポイント 4）。
5. カスタムメジャーの定義が不明確な場合は、ユーザーに確認します。

---

フェーズ 8：Cube ファイルを生成する

cubes/ に Cube.dev の YAML ファイルを作成します。フェーズ 1 で確認した既存のスタイルに従ってください。

主なルール：

1. 1 ファイルにつき 1 つのキューブ、IaC 形式です。 各キューブファイルは、apiVersion / kind: Cube / metadata / spec からなる単一のドキュメントです。キューブ定義は spec の直下にフラットに記述し（spec.name には識別子を設定します）、ルートで cubes: や views: で囲まないでください。
2. ファイル名は metadata.name（gold_ プレフィックスのないケバブケースのスラッグ）+ .yml にします。spec.name はスネークケースの識別子にします。
3. sql_table には、gold_ プレフィックスを付けた完全修飾の BigQuery 参照を使用します。
4. 確認済みのリレーションシップごとに、双方向の結合を設定します。
5. ブリッジ／ジャンクションキューブには public: false を設定します。
6. すべてのキューブに SQL ベースの refresh_key を含める必要があります。次の優先順位で列を使用し、SELECT MAX(<timestamp_col>) を設定します：_airbyte_extracted_at（すべての Airbyte ソースに存在）、updated_at／modified_at（CDC ストリーム）、created_at（挿入のみのファクト）。every: <interval> を使用できるのは、テーブルにタイムスタンプ列が存在しない場合の最終手段のみです。その理由を説明する YAML コメントを追加してください（例：# no timestamp column available）。
7. refresh_key.sql は sql_table と同じテーブルを参照します。
8. 検証されていない結合には # UNVALIDATED: <reason> を付けます。
9. Connection によって取り込まれたデータから派生したキューブ（つまり、gold モデルの元データが、Connection に対して revos apply を実行して生成された bronze テーブルである場合）には、meta.abConnectionId: <connection-id> を設定します。これにより、UI でキューブが元のコネクション別にグループ化されます。接続 ID は revos connections list --json で確認し、gold モデルが読み込む bronze テーブルのプレフィックスと spec.prefix を照合します。コネクション由来のモデルを基に構築したブリッジ／ジャンクションキューブにも、同じ abConnectionId を設定します。純粋なローカルデータ（例：上流にコネクションのない手書きの silver／gold モデル）から派生したキューブには、abConnectionId を設定しません。
10. 行に自然な人間向けのラベルがあるキューブ（companies、contacts、deals、tickets、users、projects など）には、meta.nameDimension: <short-dimension-name> を設定します。値には短いディメンションキーを指定します（${CUBE}. プレフィックスやキューブ名のプレフィックスは付けません）。例：properties_name、displayName、dealname。フロントエンドは、この値を使ってキューブをテーブルとして追加したときに、エンティティ名として表示する列を選択します（フロントエンドの useCubeFromMeta を参照）。「このものの名前」としてユーザーが認識するディメンションを選びます。そのような単一の列がない場合（純粋な結合／ブリッジキューブ、ファクトテーブル、イベントログなど）は、nameDimension を省略します。このディメンションは、このキューブの dimensions: 内に存在する必要があります。
11. meta.icon は必要な場合にのみ設定します。以下の 「各キューブのアイコンを選ぶ」 を参照してください。
12. meta に設定できるのは abConnectionId、nameDimension、icon のみです。いずれも該当しない場合は、meta ブロック全体を省略します。

標準キューブ、ブリッジキューブ、結合方向の例、および refresh key のバリエーションについては、references/cube-examples.md を参照してください。

---

各キューブのアイコンを選ぶ

ブリッジ／ジャンクションキューブ（public: false）では、常に meta.icon を省略します。

その他のキューブについては、meta.icon が必要かどうかを次の手順で判断します。

1. キューブに meta.abConnectionId がある場合 — このコネクションの接続元にブランドアイコンがあるか確認します。 abConnectionId の値は RevOS のコネクション ID です（ルール 9 で確認したものと同じです）。 revos connections get <abConnectionId> --json | jq '.spec.source.id' を実行して接続元 ID を取得し、 次に revos sources get <source-id> --json | jq '.icon' を実行します。

   • icon が空でない文字列 → UI にインテグレーションのロゴが自動表示されます。meta.icon は省略してください。
   • icon が null、空、またはフィールドが存在しない → 以下のカタログを使って meta.icon を設定します。

2. キューブに meta.abConnectionId がない場合 → 以下のカタログを使って、常に meta.icon を設定します。

カタログキー

キー	意味	代表的なキューブ名
users	エンドユーザー、顧客、アカウント保有者	*users*、*customers*、*accounts*
orders	注文、取引	*orders*、*purchases*、*transactions*
events	行動イベント、アクティビティログ	*events*、*activity*、*logs*
products	製品、SKU、アイテム	*products*、*items*、*skus*
sessions	Web／アプリのセッション	*sessions*、*visits*
revenue	収益、支払い、請求書	*revenue*、*payments*、*invoices*
companies	B2B 企業、組織	*companies*、*organizations*、*accounts*
contacts	個人／CRM の連絡先	*contacts*、*people*、*persons*
deals	販売案件、商談	*deals*、*opportunities*
tickets	サポートチケット、問題	*tickets*、*issues*、*cases*
campaigns	マーケティングキャンペーン	*campaigns*、*ads*
emails	メールメッセージ	*emails*、*messages*
leads	見込み客	*leads*
tasks	タスク、やること	*tasks*、*todos*

受け付ける3つの形式

meta:
  icon: "users"                                # catalog key (preferred)
  # — or —
  icon: "url:https://cdn.example.com/icon.svg" # explicit external URL
  # — or —
  icon: "data:image/svg+xml;base64,…"          # inline SVG data URI

可能な限りカタログキーを使用してください。カタログで対応していないカスタムブランドアイコンに限り、url: または data: を使用します。不正な値があると、revos apply は明確なエラーを表示してファイルを拒否します。

---

フェーズ9：生成されたファイルを検証する

1. create-dbt-transformations が呼び出された場合（ブリッジモデル）、dbt モデルはすでに検証されています。それ以外の場合は、dbt parse を実行します。
2. BigQuery に物理テーブルが存在することを確認します：bq show <dataset>.<table_name>。存在しない場合は、保留中として記録します。
3. 生成されたキューブファイルが規約に準拠していることを確認します：フラットな YAML、適切な命名、正しい sql_table、すべてのディメンションの存在、refresh_key の指定、両方向の結合。

---

最終応答の形式

Created cube definitions.

Selected gold models:
- dbt/models/gold/<gold_model_1>.sql

Approved connector models:
- dbt/models/gold/<connector_model>.sql

Bridge/support models created (via create-dbt-transformations):
- dbt/models/gold/<bridge_model>.sql

Cube files:
- cubes/<entity_1>.yml         (cube name: <entity_1>)
- cubes/<bridge_entity>.yml    (cube name: <bridge_entity>, public: false)

Validated relationships:
- <entity_a>.<key> -> <entity_b>.<key> (<relationship_type>)

Measures:
- count
- <approved_measure_1>

Validation:
- dbt: <passed / pending / not run>
- physical tables: <passed / pending>
- join validation: <passed / pending>
- semantic validation: <passed / pending>

Unvalidated joins (tagged with # UNVALIDATED):
- <cube>.<join_target>: <reason>

Assumptions:
- <assumption>

Pending items:
- <pending_item>

Next step:
  revos apply

検証が完了していない場合は、何が保留中かを正確に伝えてください。