新的 LookML - 如何转换 YAML LookML 项目

Looker 4.0 引入了新的 LookML 语法，该语法在原始 YAML 样式的 LookML 的基础上进行了改进，采用常见但更简单的语法和丰富且实用的 IDE，使 LookML 开发工作得以简化。从 Looker 4.4 开始，所有新的 LookML 项目都必须使用新的 LookML 创建；不过，在转换之前创建的某些项目可能仍会使用 YAML（旧版）LookML 建模。

Looker 提供了一种自动方式来将 YAML LookML 项目转换为新的 LookML。本页介绍了如何执行此过程。每个 LookML 项目都需要单独进行转换，开发者必须做好准备和协调工作，因此在转换项目之前，请务必通读本页面的内容。

准备转换

将 YAML LookML 项目转换为新的 LookML 的任务必须由一位 LookML 开发者执行。 转换在该开发者的开发模式内进行，然后系统会提交和部署这些更改，就像任何普通的 LookML 更改一样。

不过，这个过程需要所有 LookML 开发者的协作。由于转换实质上会改变 LookML 的每一行，因此请务必确保其他 LookML 开发者已在转换流程开始之前提交所有更改并将其部署到项目中。否则，可能会导致一些非常严重的 Git 合并冲突。

虽然转换过程是自动执行的，但新的 LookML 在错误检查方面比 YAML LookML 更全面。也就是说，在转换后，可能会出现之前未发现的错误。解决这些错误将提高项目质量。错误数量必定因项目而异，这意味着修复这些错误可能需要几分钟到几小时的时间。无论采用哪种方式，在修复错误之前，所有 LookML 开发者都必须保持暂停状态。

在 Looker 实例上查找 YAML 项目

如需查看 Looker 实例上的 YAML 项目，请执行以下操作：

  1. 从 Develop 菜单中，选择 Manage LookML Projects 或 Projects 选项（根据您访问 Develop 菜单的位置，此选项会略有不同）。
  2. 在 LookML 项目页面上，在项目的表行中查找 YAML LookML 标签：

    提示：您可以在表格中选择项目的名称，以转到项目的 LookML。

在转换之前与开发者协调

如需准备转换为新的 LookML，请执行以下操作：

  1. 选择一名 LookML 开发者来运行转换过程。
  2. 运行 LookML 验证器来确保项目没有错误。请修复所有错误，在继续下一步之前提交并部署更改。
  3. 指定执行转化的时间。
  4. 告知所有其他 LookML 开发者，告知他们需要在指定时间之前提交并部署正在处理的任何更改。也就是说，项目的所有开发模式副本都应处于生产环境的 Git 状态是最新版本。
  5. 告知所有其他 LookML 开发者在转换完成前，他们不应进行、提交或部署任何更改。

转换为新的 LookML

如需转换为新的 LookML，请运行该转换器：

  1. 进入开发模式。
  2. 打开要转换的项目。
  3. 确保左上角的 Git 状态显示正式版的最新版本。
  4. 运行 LookML 验证器以确保项目中没有错误，结果应该为“No LookML Issues”（无 LookML 问题）。（如需运行 LookML 验证工具，请选择 Looker IDE 右上角的验证 LookML 按钮；或选择 IDE 顶部的项目运行状况图标以打开项目运行状况面板，然后选择验证 LookML）。
  5. 如需将项目从 YAML LookML 转换为新的 LookML，请执行以下操作：

    1. 从 Looker IDE 的导航边栏中选择 Git Actions 图标。
      • 或者，选择 IDE 顶部的 Project Health 图标：

    2. 从 Git Actions 面板或 Project Health 面板底部选择 Convert Project to New LookML 选项。
    3. 在确认对话框中选择 Convert to New LookML 按钮。

验证新的 LookML

转换器运行完毕后，IDE 会通过每个文件名旁边有一个圆点来指示您的文件已更改：

如需验证新的 LookML，请执行以下操作：

  1. 选择验证 LookML 按钮以运行 LookML 验证器。如果没有错误，您可以跳至本页面的提交和部署新的 LookML 部分。
  2. 您可能会看到之前没有任何错误。如前所述，与 YAML LookML 相比，新版 LookML 在检查错误方面更为全面。查看并修正错误。如果您在解析错误时遇到困难，请参阅本页末尾的解决错误部分。

提交和部署新的 LookML

此时，请像处理任何普通 LookML 更改一样提交和部署。请注意：此提交将触发重新构建永久性派生表 (PDT)。部署提交后，请告知所有其他 LookML 开发者转换已完成，并且依赖于 PDT 的查询的运行时间可能比平常稍长，至少要等到重新构建所有内容为止。开发者可以在开发模式下从生产环境中拉取数据，引入更改，然后继续开发。现在，你可以使用经过改进且更直观的 LookML 语法，以及更实用、更强大的 IDE。

解决错误

由于新的 LookML 更加全面的模型验证，因此您在转换后可能会看到之前未出现的错误。此外，在某些情况下，新 LookML 的临时错误检查需要更多信息；转换器会尝试为您找出答案，但在某些情况下，您可能需要在一两个视图文件中添加一个额外的 include 行。

字段引用无效

在某些情况下，YAML（旧版）LookML 并不确保您引用的字段或集实际已在模型中的某个位置定义。最可能出现的位置是深入分析字段列表和字段集。

例如，如果您的旧 LookML 包含 drill_fields: [id, name, email]，但在模型开发过程中的某个时刻，您移除了 name 字段，改为使用 first_name 和 last_name 字段，YAML LookML 不会提醒您所引用的字段 (name) 在此深入分析字段列表中不存在。如果您引用维度组中的字段，但 YAML LookML 未像新 LookML 一样指定字段，也可能会发生这种情况。

另一方面，新的 LookML 将显示这些类型的错误。因此，在转换项目并运行 LookML 验证器后，您可能会看到之前从未见过的有关无效字段引用的错误。修正这些错误可提高模型的整体质量。

视图文件中缺少包含内容

在某些情况下，新 LookML 的临时错误检查需要的上下文比 YAML LookML 中所需的上下文略多。具体而言，可能需要在某些视图文件中放置 include 行，最常见的情况是一个视图扩展了另一个视图。

当不清楚需要将哪个文件包含在视图中时，转换器会自动在新的 LookML 视图文件中添加适当的 include 声明，并且您不会看到任何错误。

但在某些情况下（例如对于包含多个模型的项目），可能会有两个或更多个使用相同名称的视图在单独的视图文件中声明。转换器无法确定哪个是要包含的视图，因此会在新的 LookML 文件顶部添加注释，指明应仅包含其中一个视图。请转到视图文件并取消注释正确的建议，以解决产生的错误。

搁浅 extension_required 探索

与前面描述的无效字段引用问题一样，在新的 LookML 中，LookML 验证工具会提醒您使用 extension: required 声明但实际上并未扩展的探索。如需解决此错误，请将这些探索重新连接到其扩展对象；如果未使用的对象，请将其移除。

版本控制

由于 LookML 转换过程会将您的 .lookml 视图和模型文件替换为 .lkml 版本，因此，如果一位或多位开发者在转换期间提交到您的项目，那么您将面临合并冲突。因此，只有一位开发者运行转换器极为重要，而且他们应进行协调，以确保在开始转换流程之前，每个人的开发模式副本都干净且是最新的。

为避免版本控制问题，转换期间必须出现代码冻结。 其他开发者不应在阻止转换期间检查更改。

如果执行转换的开发者在转换过程中遇到任何问题，但在提交更改并推送到生产环境之前，他们可能会发现还原为正式版会很有帮助。下拉菜单中的此选项（如本页的运行转换器部分所示）可撤消转换，让开发者重新开始转换过程。