lookml-refinements

Instructions

1. Includes Mechanism

include makes Open LookML objects (views, explores, dashboards) available in the current file.

• Wildcards (*): Matches any string.

  • /views/*.view: All views in the absolute /views directory.
  • *.view: All views in the current directory.
  • /**/*.view: (Recursive) All views in the current directory and any subdirectory.
  • //project-name/views/*.view: Remote project import (Requires project manifest).

• Best Practice: Be specific to avoid namespace collisions and performance bloat.

  • BAD: include: "/**/*.view" (Imports everything, everywhere. Slow and risky).
  • GOOD: include: "/views/users.view" (Explicit).
  • GOOD: include: "/views/finance/*.view" (Scoped to a domain).

2. Refinements (Layering)

Refinements allow you to modify an existing view or explore without changing the original file. This is crucial for:

1. Hub & Spoke: Adapting a core "Hub" model for specific "Spoke" use cases.
2. Vendor Blocks: Customizing read-only blocks (e.g., Google Analytics) without forking.

Syntax

• Original: view: users { ... }
• Refinement: view: +users { ... }
• Requirement: You MUST include the original file before finding it.

Rules of Engagement

1. Last Include Wins: If multiple files refine +users, the order of include determines the final state.
2. Additive: New parameters are added.
3. Override: Existing parameters are replaced.
   • Exception: list parameters (like drill_fields) are often replaced, not merged, depending on the implementation. Explicitly restating the list is safer.
4. Field Modification:
   • To modify a field, re-declare it with the exact same name.
   • You only need to specify the parameters you want to change (e.g., adding description or label).

3. The "One Explore Per File" Pattern

For maintainable, enterprise-scale LookML, follow the One Explore Per File pattern using .explore.lkml files.