creating-looker-dashboard

创建 Looker 信息中心并建立反馈循环

本技能将指导你完成入门流程的最后一步：构建用户要求的目标信息中心。你将在项目中将信息中心定义为 LookML 信息中心文件，将其导入 Looker 作为用户定义的信息中心（UDD），并根据用户的反馈反复更新和同步。

前提条件

• 必须已安装并完成身份验证的 Looker CLI（步骤 2 和 3）。
• 必须已完成 Looker 项目、连接、视图和模型的设置并通过验证（步骤 4、5 和 6）。

说明

1. 获取信息中心规格并确定目标文件夹

1. 参考对话历史中与用户在**步骤 1（需求探索）访谈期间确定的目标信息中心目标、表格、维度和度量（之后在步骤 7（建模）**中创建）。你必须记住这些规格，以确保信息中心显示正确的数据。
2. 找到用于放置信息中心的目标 Looker 文件夹 ID。由于这是全新的 Looker 实例，我们将指定将信息中心放入默认的 Shared 文件夹：
   • 使用 Looker CLI 列出所有文件夹：looker-cli folder ls
   • 在输出中找到名为 "Shared" 的文件夹。在全新实例中，该文件夹始终存在，其 ID 几乎总是 "1"。
   • 确定此 "Shared" 文件夹的 ID，并将其用作目标文件夹 ID（后续步骤会将其传递给 folder_id 参数）。

2. 创建 LookML 信息中心文件（CLI）

你必须在项目中将信息中心结构定义为 LookML 信息中心文件：

1. 创建 dashboards 目录：如果项目中尚不存在 dashboards/ 目录，请使用 Looker CLI 创建：

   looker-cli project directory create {project_id} dashboards
   

2. 生成信息中心 LookML：在本地编写 LookML 信息中心定义（例如，写入 /tmp/{dashboard_name}.dashboard.lookml）。确保文件使用 .dashboard.lookml 扩展名。

3. 上传信息中心文件：将文件上传到 Looker 项目的信息中心文件夹（路径约定为 dashboards/{dashboard_name}.dashboard.lookml）：

   looker-cli project file create {project_id} dashboards/{dashboard_name}.dashboard.lookml /tmp/{dashboard_name}.dashboard.lookml
   

4. 关键的包含步骤：你必须在 LookML 模型文件（{model_name}.model.lkml）中包含信息中心文件，以便项目验证器和 CLI 导入/同步命令能够发现这些文件：

   include: "/dashboards/**/*.dashboard.lookml"
   

5. 在信息中心文件中编写 LookML 信息中心定义，配置用于显示你在步骤 7 中创建的维度和度量的图块（元素）。强烈建议使用 layout: newspaper（支持以 24 列为基准的网格坐标 row、col、width 和 height），以避免旧版 layout: grid 行分组可能导致的导入错误。

信息中心 LookML 示例（layout: newspaper）：

- dashboard: sales_performance
  title: Sales Performance Overview
  layout: newspaper
  preferred_viewer: dashboards-next

  elements:
    - name: total_revenue_tile
      title: Total Revenue Over Time
      model: ecommerce
      explore: orders
      type: looker_line
      fields: [orders.created_date, orders.total_revenue]
      sorts: [orders.created_date desc]
      limit: 500
      row: 0
      col: 0
      width: 12
      height: 8

    - name: order_count_tile
      title: Top Countries by Orders
      model: ecommerce
      explore: orders
      type: looker_column
      fields: [users.country, orders.count]
      sorts: [orders.count desc]
      limit: 10
      row: 0
      col: 12
      width: 12
      height: 8

注意：确保每个图块上的 model 和 explore 属性与项目中定义的模型和探索名称相匹配，并且 fields 使用完全限定的 view_name.field_name 格式。

3. 验证并提交 LookML

验证项目，确保信息中心语法完全正确且没有引用错误：

looker-cli api project validate_project {project_id}

如果返回错误，请修复 LookML 信息中心定义并重新验证，直至验证通过。

4. 将 LookML 仪表板导入为 UDD（CLI）

将 LookML 仪表板导入目标文件夹，作为用户定义的仪表板（UDD）。这会将其从静态文件转换为 Looker 中由数据库支持的仪表板。

1. 按照 {model_name}::{dashboard_name} 格式构造 lookml_dashboard_id（例如 ecommerce::sales_performance）。

2. 确保处于开发模式工作区上下文：默认情况下，Looker CLI 会话在生产工作区中执行。由于新创建的仪表板仅存在于开发模式中，因此导入／同步前，必须立即将 CLI 会话切换到开发工作区。将会话更新命令与导入命令串联执行：

   looker-cli session update dev && looker-cli dashboard import lookml {model_name}::{dashboard_name} {folder_id}
   

3. 命令将返回一个包含已导入 UDD 详细信息的 JSON 对象。记录响应中的仪表板数字 id（例如 45）或 slug。

5. 验证仪表板内容（SQL 查询验证检查）

Looker 的项目验证只检查 LookML 语法，不会验证每个图块的 SQL 查询能否在数据库中成功执行。为了确保向用户展示前仪表板没有任何查询错误，必须获取并执行仪表板每个图块背后的查询：

1. 获取新导入的 UDD 仪表板元素详情（特别是 query_id）：

   looker-cli dashboard cat {udd_id} --fields "dashboard_elements(query_id)"
   

2. 对 JSON 结果中返回的每个唯一 query_id（排除文本图块中的任何 null 值），执行查询以验证数据库正确性：

   looker-cli query runquery {query_id}
   

3. 确认每个查询都能成功执行并返回数据，且没有 SQL 或数据库错误。如果任何查询失败（表明数据库列不匹配、SQL 方言函数错误或 GCP 权限问题），必须在 LookML 视图中解决问题、提交更改、重新运行 looker-cli api project validate_project {project_id}，使用 looker-cli dashboard sync lookml 同步，并按照此流程重新验证，直到所有查询都能成功执行。

6. 向用户展示并迭代（交互步骤）

1. 向用户展示导入后的仪表板链接： {instance_url}/dashboards/{udd_id}（或 /dashboards-next/{udd_id}）。

2. 停止并询问用户对布局、图表类型或标签的反馈：

   "我已成功构建并导入新仪表板！你可以在此查看： {dashboard_url}

   这样看起来合适吗？如果你希望我更改图表类型、添加新指标或调整布局，请告诉我！"

3. 停止并等待用户回复。不要调用任何工具。

7. 优化并同步更改

如果用户要求修改仪表板（例如“将订单数改为条形图，而不是柱形图”或“添加筛选器”）：

1. 编辑本地的 LookML 仪表板文件，并将其更新到 Looker 服务器：

   looker-cli project file update {project_id} dashboards/{dashboard_name}.dashboard.lookml /tmp/{dashboard_name}.dashboard.lookml
   

2. 验证项目：

   looker-cli api project validate_project {project_id}
   

3. 使用 CLI 同步命令，直接将更改传播到导入的 UDD 仪表板：

   looker-cli dashboard sync lookml {model_name}::{dashboard_name}
   

4. 重新运行查询验证：再次运行查询验证检查，确保优化没有引入新的 SQL 或数据库错误：

   • 再次获取 UDD 元素（以捕获任何新的图表查询）：looker dashboard cat {udd_id} --fields "dashboard_elements(query_id)"
   • 对每个返回的 query_id，运行查询以验证 SQL 是否正确： looker-cli query runquery {query_id}

5. 请用户刷新浏览器并检查更改。重复此流程，直到用户完全满意！