lookml-modeling-guidelines

LookML 建模指南

本指南介绍如何有效使用 Looker CLI 辅助完成 LookML 建模任务，并结合 LookML 开发最佳实践与高效的 CLI 使用方法。

LookML 文件类型

了解 LookML 项目中不同文件类型的用途：

• 项目清单（manifest.lkml）：项目的全局配置，包括导入项和常量。
• 模型文件（.model.lkml）：定义数据库连接和 Explore（视图的联接方式）。
• 视图文件（.view.lkml）：数据蓝图，用于定义维度、度量和派生表。
• 仪表板文件（.dashboard.lookml）：由 LookML 定义的仪表板（布局、可视化和筛选器）。
• 专用文件：细化文件（用于覆盖或修补）、数据测试文件（自动化逻辑检查）和文档文件（.md）。

1. 分析需求

在编写任何 LookML 代码或进行修改之前，先分析用户的请求，确定所需的 LookML 元素。

• 理解请求：确定核心业务问题或技术需求。
• 识别现有资源：
  • 使用发现工具（见第 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. 模型

• Includes： 使用具体、细粒度的 include 路径，而不是宽泛的通配符，以避免性能膨胀和命名空间冲突，并提高编译速度。
  • 推荐：include: "/views/users.view.lkml"
  • 不推荐：include: "/views/*.view.lkml"

B. Explores

• 联接：始终明确指定 relationship 参数（例如 many_to_one）。这对 Looker 生成正确的 SQL 并避免扇出至关重要。
• 细粒度 Explores：优先选择小型、专注的 Explore，而非庞大的单体 Explore，以简化用户界面并便于排查问题。

C. 视图

• 主键：表示表的每个视图都应定义主键。主键必须是第一个维度，并设置 primary_key: yes。这对于对称聚合至关重要。
• 字段引用：度量应引用维度（例如 ${dimension_name}），而不是直接引用表列（例如 ${TABLE}.column_name）。这样可确保单一事实来源。
• 字段描述：始终为任何新维度或度量添加便于用户理解的 description 参数。这有助于最终用户在字段选择器中了解该字段。

D. 通用

• DRY 原则与模块化： 使用 extends、refinements（实现模块化、可扩展的代码）和 sets，消除代码重复。
• Refinements 与 Extensions： 使用 Refinements（+ 语法）在不重命名的情况下对现有对象叠加更改（例如自定义 Blocks）。使用 Extensions（extends）创建新的专用变体，同时保留原始对象。

约束与防护措施

• 必须指定主键： 创建任何视图、派生表或 PDT 时，必须始终为一个维度定义 primary_key: yes。每张表都必须显式指定主键。
• 应用范围： 本文件中的所有指南和最佳实践仅适用于为满足用户提示而新增的代码。除非用户明确要求或新代码正常运行所必需，否则不要重构或修改现有代码以遵循这些指南。保持现有代码不变。
• 零错误政策： 严禁提交未通过 LookML Validator 的代码。
• 数据最小化： 仅访问当前任务所需的数据和架构。
• 验证： 验证范围仅限于你所做的更改。不要修复现有的验证错误。