新的 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 合并冲突。

虽然转换过程是自动进行的，但与 YAML LookML 相比，新的 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 开发者，他们需要在指定时间之前提交和部署所做的所有更改。也就是说，项目的所有开发模式副本都应与正式版处于最新状态。
  5. 请告知所有其他 LookML 开发者，在转换完成之前，他们不得进行任何更改、提交任何更改，也不得部署任何更改。

转换为新的 LookML

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

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

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

    2. 从 Git 操作面板或 Project Health 面板底部选择 Convert Project to New LookML 选项。
    3. 在确认对话框中，选择转换为新的 LookML 按钮。

验证新的 LookML

转换器运行完毕后，IDE 会在每个文件名旁边显示一个圆点，以指示文件已发生更改：

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

  1. 选择 Validate LookML（验证 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 验证器后，您可能会看到之前从未见过的关于无效字段引用的错误。解决这些错误有助于提高模型的整体质量。

视图文件中缺少包含项

在某些情况下，与 YAML LookML 相比，新版 LookML 的临时错误检查需要更多上下文。具体而言，您可能需要在某些 View 文件中添加 include 代码行，最常见的情况是，一个 View 扩展了另一个 View。

如果视图中需要包含的文件没有任何歧义，转换器会自动在新 LookML 视图文件中添加适当的 include 声明，并且您不会看到任何错误。

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

搁浅的 extension_required 探索

与之前所述的字段引用无效问题类似，在新版 LookML 中，LookML 验证器会提醒您，如果有探索是使用 extension: required 声明的，但实际上并未扩展，如需解决此错误，请将这些探索重新关联到其扩展对象，或者如果它们未使用，请将其移除。

版本控制

由于 LookML 转换过程会将您的 .lookml 视图和模型文件替换为 .lkml 版本，因此如果一个或多个开发者在转换期间向您的项目提交了代码，您最终会遇到合并冲突。 因此，请务必让一位开发者运行转换器，并且他们应协调一致，确保在开始转换流程之前，每个人的开发者模式副本都干净且是最新的。

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

如果执行转换的开发者在转换流程期间（但在提交更改并推送到正式版之前）遇到任何问题，则回滚到正式版可能会有所帮助。下拉菜单中的此选项（如本页的运行转换器部分所示）会撤消转换，以便开发者重新开始该流程。