lookml-refinements

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Instructions

操作指南

1. Includes Mechanism

1. Include机制

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).

include

可让Open LookML对象（视图、探索、仪表盘）在当前文件中可用。

通配符 (
*
)：匹配任意字符串。
- ```
/views/*.view
```
  ：绝对路径
```
/views
```
  目录下的所有视图。
- ```
*.view
```
  ：当前目录下的所有视图。
- ```
/**/*.view
```
  ：（递归匹配）当前目录及所有子目录下的所有视图。
- ```
//project-name/views/*.view
```
  ：导入远程项目（需项目清单支持）。
最佳实践：明确指定路径，避免命名空间冲突和性能损耗。
- 不推荐：
```
include: "/**/*.view"
```
  （导入所有目录下的所有内容，加载缓慢且易出问题）。
- 推荐：
```
include: "/views/users.view"
```
  （明确指定单个文件）。
- 推荐：
```
include: "/views/finance/*.view"
```
  （限定业务域范围）。

2. Refinements (Layering)

2. 细化（分层）功能

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

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

细化功能允许你在不修改原始文件的前提下，调整现有视图或探索。这在以下场景中至关重要：

中心-分支模式：针对特定分支场景适配核心中心模型。
供应商模块定制：无需复刻即可修改只读模块（如Google Analytics模块）。

Syntax

语法

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

原始代码：
```
view: users { ... }
```
细化代码：
```
view: +users { ... }
```
要求：在使用细化前必须
```
include
```
原始文件。

Rules of Engagement

规则说明

Last Include Wins: If multiple files refine
```
+users
```
, the order of
```
include
```
determines the final state.
Additive: New parameters are added.
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.
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
```
  ).

最后导入生效：若多个文件对
```
+users
```
进行细化，
```
include
```
的顺序决定最终效果。
增量添加：新增参数会被追加到原对象中。
覆盖现有参数：已存在的参数会被替换。
- 例外：列表型参数（如
```
drill_fields
```
  ）通常会被替换而非合并，具体取决于实现逻辑，建议显式重写列表以确保效果。
字段修改:
- 修改字段时，需使用完全相同的名称重新声明。
- 只需指定需要修改的参数（如添加
```
description
```
  或
```
label
```
  ）。

3. The "One Explore Per File" Pattern

3. “每个探索对应一个文件”模式

For maintainable, enterprise-scale LookML, follow the One Explore Per File pattern using

.explore.lkml

files.

对于可维护的企业级LookML项目，建议遵循每个探索对应一个文件的模式，使用

.explore.lkml

文件。

Structure

结构

File:
```
explores/orders.explore.lkml
```
Content:
1. ```
include
```
  only the views needed for this explore.
2. Define
```
explore: orders { ... }
```
  .

Model File:

models/my_model.model.lkml

include: "/explores/orders.explore.lkml"

No
explore
definitions in the model file itself.

文件：
```
explores/orders.explore.lkml
```
内容:
1. 仅
```
include
```
  当前探索所需的视图。
2. 定义
```
explore: orders { ... }
```
  。

模型文件：

models/my_model.model.lkml

include: "/explores/orders.explore.lkml"

模型文件本身不定义任何
explore
。

Benefits

优势

Performance: The connection only parses what is needed for the requested Explore.
Namespace Hygiene: View naming collisions are isolated to the specific Explore file where they are included.
Collaboration: Developers can work on different Explores without merge conflicts in the Model file.

性能优化：连接仅解析当前请求探索所需的内容。
命名空间整洁：视图命名冲突被隔离到对应的探索文件中。
协作高效：开发人员可独立开发不同探索，避免模型文件的合并冲突。

Examples

示例

Scenario: Modifying a Vendor View

场景：修改供应商视图

Original (ReadOnly):

//lkr_block/users.view

lookml

view: users {
  dimension: id { primary_key: yes }
  dimension: name {}
}

Refinement:

views/users_rfn.view

lookml

include: "//lkr_block/users.view"

view: +users {
  # 1. New Dimension
  dimension: email {
    sql: ${TABLE}.email ;;
  }

  # 2. Modify Existing Dimension
  dimension: name {
    label: "Full Name"
    description: "Legal name of the user."
  }
}

原始代码（只读）：

//lkr_block/users.view

lookml

view: users {
  dimension: id { primary_key: yes }
  dimension: name {}
}

细化代码：

views/users_rfn.view

lookml

include: "//lkr_block/users.view"

view: +users {
  # 1. 新增维度
  dimension: email {
    sql: ${TABLE}.email ;;
  }

  # 2. 修改现有维度
  dimension: name {
    label: "Full Name"
    description: "Legal name of the user."
  }
}

Scenario: Explore-Specific Logic

场景：探索专属逻辑

File:

explores/marketing_orders.explore.lkml

lookml

include: "/views/orders.view"
include: "/views/users.view"

文件：

explores/marketing_orders.explore.lkml

lookml

include: "/views/orders.view"
include: "/views/users.view"

Refine users ONLY for this explore to add marketing-specific fields

仅为当前探索细化users视图，添加营销专属字段

view: +users { dimension: acquisition_channel { sql: ${TABLE}.utm_source ;; } }

explore: marketing_orders { view_name: orders from: orders # mapping 'orders' view to 'orders' alias (standard)

join: users { sql_on: ${orders.user_id} = ${users.id} ;; } }

undefined

view: +users { dimension: acquisition_channel { sql: ${TABLE}.utm_source ;; } }

explore: marketing_orders { view_name: orders from: orders # 将'orders'视图映射到'orders'别名（标准用法）

join: users { sql_on: ${orders.user_id} = ${users.id} ;; } }

undefined