lookml-modeling-guidelines

LookML モデリングのガイドライン

このガイドでは、LookML のモデリングタスクを効果的に進めるために、Looker CLI を活用する方法を説明します。LookML 開発のベストプラクティスと、CLI の効果的な使い方をまとめています。

LookML ファイルの種類

LookML プロジェクトにおける各ファイルの役割を理解しましょう。

• プロジェクトマニフェスト（manifest.lkml）：インポートや定数など、プロジェクトのグローバル設定を定義します。
• モデルファイル（.model.lkml）：データベース接続と Explore（ビューの結合方法）を定義します。
• ビューファイル（.view.lkml）：ディメンション、メジャー、派生テーブルを定義するデータの設計図です。
• ダッシュボードファイル（.dashboard.lookml）：LookML で定義するダッシュボード（レイアウト、可視化、フィルター）です。
• 特殊なファイル：リファインメントファイル（上書きやパッチ適用用）、データテストファイル（ロジックの自動チェック用）、ドキュメントファイル（.md）があります。

1. 要件の分析

LookML コードを記述したり変更したりする前に、ユーザーのリクエストを分析し、必要な LookML 要素を判断します。

• リクエストを理解する：中心となるビジネス上の課題や技術的な要件を特定します。
• 既存のリソースを特定する：
  • Discovery ツール（セクション 2 を参照）を使って、既存の LookML プロジェクトを検索します。
  • ユーザーのプロンプトに回答するのに最適な既存の列（ディメンション）とメジャーを特定します。
  • 既存のロジックを再作成しないでください。 可能な限り既存の要素を再利用します。
• 必要な追加要素を判断する：
  • プロンプトへの対応に、新しい LookML 要素が必要かどうかを特定します。
    • 新しいビュー：新しいテーブルや派生テーブルを導入しますか？（注：派生テーブルまたは PDT を作成する場合は、必ず lookml-pdt-guidelines スキルを参照してください）。
    • 新しいディメンション：新しい列を公開したり、既存の列から新しいロジックを定義したりする必要がありますか？
    • 新しいメジャー：新たな集計（例：count、sum、average）や計算指標を追加しますか？
    • その他の要素：Explore に新しい結合や、その他の LookML 要素が必要ですか？

2. 検索と調査（CLI）

• プロジェクトの構成を把握する：次の CLI コマンドを使って、プロジェクトの構造を確認します。
  • プロジェクトの一覧表示：looker-cli api project all_projects
  • モデルの一覧表示：looker-cli api lookmlmodel all_lookml_models
  • モデルの確認：looker-cli api lookmlmodel lookml_model {model_name}
• フィールドの検索：Explore で公開されているディメンションとメジャーを確認するには、次を呼び出します：looker-cli api lookmlmodel lookml_model_explore {model_name} {explore_name}（生のビュー ファイルを読むより簡潔です）。
• スキーマの検索：データベースの列とスキーマを取得するには、次を使います。
  • 接続の一覧表示：looker-cli connection ls
  • スキーマの一覧表示：looker-cli api metadata connection_schemas {connection_name}
  • テーブルの一覧表示：looker-cli api metadata connection_tables {connection_name}
  • テーブル列の一覧表示：looker-cli api metadata connection_columns {connection_name} --schema_name {schema_name} --table_names {table_name}
• データの検索：クエリを実行してデータの結果を確認します：looker-cli query runquery {query_id}。または、インラインクエリを looker-cli api query run_inline_query で実行します。完全修飾フィールド（例：view.field）を使用する必要があります。

3. 検証とテスト（CLI）

LookML が有効であり、期待どおりの SQL または結果を生成することを、必ず検証してください。

• 構文の正確性： すべてのコードは、波括弧の対応が取れ、パラメーターが正しく指定された、完全に正しい構文である必要があります。sql パラメーターは、特定のデータベースの方言（BigQuery、Snowflake など）に合わせてください。
• クエリの実行： looker-cli query runquery を使用して結果を検証します。
• 型の安全性： LookML の型がデータベースのカラム型と一致することを確認します。
• SQL の検証： looker-cli api query run_inline_query を実行し、クエリの SQL フィールドを要求して、生成された SQL を確認します。
• 検証： 開発中は頻繁に looker-cli api project validate_project {project_id} を使用します。
• テスト： 次のコマンドでテストを取得して実行します。
  • テストを取得：looker-cli api project all_lookml_tests {project_id}
  • テストを実行：looker-cli api project run_lookml_test {project_id}

4. 新しいビューの作成（CLI）

自動でビューを生成する CLI サブコマンドはないため、ビューは必ず手動で作成してください。ステップ 2 で取得したカラムスキーマに基づいて、LookML ビュー定義の構造を一から作成し、その内容をローカルファイル（例：/tmp/my_view.view.lkml）に保存してから、アップロードします。

looker-cli project file create {project_id} views/{view_name}.view.lkml /tmp/my_view.view.lkml

命名と一意性の要件

• モデル： インスタンス全体で一意である必要があります（URL の衝突やインスタンスエラーを防ぎます）。
• ビュー： プロジェクト全体で一意である必要があります（フィールドの名前空間として機能します）。
• Explore： モデル全体で一意である必要があります（クエリの開始点です）。
• フィールド： ビュー内で一意である必要があります（ディメンション名／メジャー名はビュー内で一意でなければなりません）。

5. フィードバックループ（検証）

LookML ファイルに変更を加えた後は、次の手順を実行します。

1. looker-cli api project validate_project {project_id} を実行して、構文エラーと参照エラーを確認します。
2. エラーが見つかった場合は修正し、手順 1 を繰り返します。
3. データテストが定義されている場合は、looker-cli api project run_lookml_test {project_id} を実行し、テストに引き続き合格することを確認します。
4. バリデーターがエラーなしを返すまで、タスクを完了したと見なしてはなりません。

---

6. ベストプラクティス

A. モデル

• インクルード： パフォーマンスの肥大化や名前空間の衝突を防ぎ、コンパイル速度を高めるため、広範なワイルドカードではなく、具体的で細分化された include パスを使用します。
  • 推奨： include: "/views/users.view.lkml"
  • 非推奨： include: "/views/*.view.lkml"

B. Explore

• 結合： relationship パラメーター（例：many_to_one）を必ず明示的に指定します。これは、Looker が正しい SQL を生成し、ファンアウトを防ぐうえで重要です。
• 細分化された Explore： ユーザーインターフェースをシンプルにし、トラブルシューティングを容易にするため、モノリシックな Explore よりも、小規模で目的を絞った Explore を優先します。

C. ビュー

• 主キー： テーブルを表す各ビューには主キーを定義する必要があります。主キーは最初のディメンションとし、primary_key: yes を設定してください。これは対称集計に不可欠です。
• フィールド参照： メジャーでは、テーブルカラムを直接参照する（例：${TABLE}.column_name）のではなく、ディメンションを参照します（例：${dimension_name}）。これにより、信頼できる唯一の情報源を維持できます。
• フィールドの説明： 新しいディメンションやメジャーには、必ず人が読んで理解できる description パラメーターを追加します。これにより、エンドユーザーがフィールドピッカーでフィールドの内容を把握しやすくなります。

D. 全般

• DRY の原則とモジュール化： extends、refinements（モジュール化された拡張性の高いコード向け）、および sets を活用して、コードの重複をなくします。
• Refinements と Extensions： 名前を変更せずに既存のオブジェクトへ変更を重ねる場合（例：Blocks のカスタマイズ）は、Refinements（+ 構文）を使用します。元のオブジェクトをそのまま保持しながら、新しい特化型のバリエーションを作成する場合は、Extensions（extends）を使用します。

制約とガードレール

• 必須の主キー： ビュー、派生テーブル、または PDT を作成する際は、必ず primary_key: yes を指定したディメンションを定義してください。すべてのテーブルに明示的な主キーが必要です。
• 適用範囲： このファイルに記載されたガイドラインとベストプラクティスは、ユーザーのプロンプトに対応するために追加する新しいコードにのみ適用されます。明示的に依頼された場合、または新しいコードを機能させるために必要な場合を除き、これらのガイドラインに従うために既存のコードをリファクタリングまたは変更しないでください。既存のコードはそのままにしてください。
• エラーゼロの方針： LookML Validator でエラーになるコードを提出することは固く禁じられています。
• データの最小化： 現在のタスクに必要なデータとスキーマのみを参照してください。
• 検証： 検証の対象は変更箇所のみに限定してください。既存の検証エラーは修正しないでください。