使用 ClickHouse 和 Luzmo 构建用户界面仪表盘

原创已于 2025-09-21 10:07:02 修改 · 848 阅读

9 ·

CC 4.0 BY-SA版权

文章标签：

#clickhouse #ui #信息可视化

于 2024-08-05 17:47:48 首次发布

软件工程专栏收录该内容

130 篇文章

订阅专栏

本文字数：6508；估计阅读时间：17 分钟

作者：Luzmo

本文在公众号【ClickHouseInc】首发

引言

现代企业做决策已不再凭直觉。在我们使用的每一个软件或应用中——即使是像 FitBit、Strava 或银行应用这样的消费类应用——我们都期望有某种仪表盘或图表来帮助我们指导日常决策。

然而，作为软件开发人员，构建这些用户界面的仪表盘可能是一个令人沮丧且耗时的过程。主要有两个原因：

从头开始开发数据可视化和高级分析功能需要大量的时间、专业知识和开发资源。
许多 SaaS 应用程序依赖关系数据库，但这并不是面向用户分析的最佳数据基础设施。

结果，仪表盘加载很慢，影响用户体验。
在本文中，您将学习如何使用 ClickHouse 作为分析数据库和 Luzmo 进行嵌入式数据可视化，从而克服这两个障碍。

在一个简短的教程中，我们将向您展示如何在几分钟内构建以下用户界面的仪表盘，并将其嵌入到您自己的应用中！

为何面向用户的分析需要分析数据模型

大多数 SaaS 公司已经在使用运营数据库来运行和存储平台的事务。因此，可能会有人想：“既然我们的所有数据都存储在一个数据库中，为什么还需要另一个数据库呢？”

然而，使用关系模型进行分析很快会遇到问题。每个事务都存储在单行中，即使您只需要从一两列中获取少量信息，数据库也需要扫描整行数据来检索。这使得查询速度非常慢，因为需要处理大量数据。此外，这还可能给运营系统带来过大的负载，导致整个平台的停机。

像 ClickHouse 这样的列式存储数据库按列存储数据，这意味着它们只需要扫描相关的列来执行查询。这大大减少了处理的数据量，从而提高了查询性能和报告及仪表盘的加载速度。当处理数百万个数据点时，用户通常会采用维度数据建模方法，以充分利用这些功能并处理复杂的报告请求。

我们正在构建什么：嵌入式分析仪表盘

在本教程中，我们将为物业管理应用构建一个面向客户的仪表盘，展示英国房屋的历史价格。房地产投资者和物业经理可以利用这些洞察，以低于市场价购买新物业，为现有物业定价，并最大化他们的收入。

为了创建一个用户友好、加载快速且能无缝集成到现有 Web 应用中的仪表盘，我们将使用两种技术：

ClickHouse 是我们的分析数据库，用于存储和查询数据
Luzmo 是我们的嵌入式分析平台，用于构建交互式可视化并将其直接嵌入我们的 SaaS 应用中

作为数据源，我们使用了一个英国政府开放数据集，该数据集可以通过 ClickHouse Playground 获得并进行查询。

步骤 1：连接您的 ClickHouse 数据集

要开始构建用户界面的仪表盘，我们首先需要将数据从 ClickHouse 导入 Luzmo。只需输入数据库凭证，您就可以将任何 ClickHouse 数据库连接到 Luzmo。

在 Luzmo 中，进入“Connections”并点击“+ New Connection”。从众多数据库选项中选择 ClickHouse，并添加 Host（数据库名称）、Key（用户名）和 Token（密码）。

现在，您已成功将 ClickHouse 数据库连接到 Luzmo，导航到“Datasets”。选择 ClickHouse 作为数据源，您可以看到数据库中所有可用的数据集。批量选择要用于仪表盘的所有数据集以进行导入。

我们将从 playground 中选择英国政府数据集。

完成！使用新的数据集，我们现在可以创建第一个仪表盘了。

数据准备的额外提示

虽然我们强烈建议首先在 ClickHouse 中对数据进行建模，但 Luzmo 也提供了一些数据编辑功能，以防需要。

在我们的例子中，我们使用了一个示例数据集，并想添加一些润色，使我们的仪表盘更完美。

显示正确的货币

房价以数值形式导入，我们希望将其更改为货币形式，使仪表盘自动显示所有价格为英镑。

使用公式操作数据

我们的一个数据列表示房产是新建的还是现有的住宅建筑，形式为布尔值：0 或 1。为了确保可以在仪表盘中使用此列作为过滤器，我们希望将其更改为层次结构。

在 Luzmo 中，您可以通过创建派生列轻松操作，如下所示：

然后我们可以将值 0 和 1 更改为更有意义的内容，如“新建”和“旧建”。

步骤 2：创建仪表盘

现在，最有趣的部分开始了：将原始数据转换为交互式、易理解的数据可视化！

这一部分不需要任何编码，所以您可以交给客户成功经理或支持代表处理，他们最了解客户的报告需求。

添加图表元素

在 Luzmo 中点击“+ New Dashboard”，进入拖放式仪表盘界面。如果您已经确定要可视化的指标，只需将图表拖到仪表盘画布上，并将要使用的数据列拖放到图表上。

如果您正在处理大型数据集，可以先更多地探索数据集，以了解哪些指标最有趣。在“建议”部分，您会根据数据集看到一些推荐的图表供选择。

我们对时间跨度内的价格趋势感兴趣，所以将其添加到仪表盘中！

添加交互性

如果您的平台有成千上万的用户，每个人寻找的数据点都不同。为了确保他们可以在仪表盘中操作数据并找到所需的见解，我们需要添加一些交互性。

过滤器是最直接的方法。在我们的示例仪表盘上，我们添加了：

一个滑块：用于过滤特定时间段的房价
图表之间的交互性：例如，如果只想显示独立房屋的价格数据，可以在甜甜圈图上选择“独立”，整个仪表盘将相应显示数据

除了过滤，还有许多其他方式可以让用户与数据互动。例如，在下图中，您可以使用下钻功能更详细地查看特定位置的价格。下钻到“伦敦市”，即可查看该区域内最昂贵的区、城镇或街道。

如果您想提供大量信息，可能会不断添加图表。然而，拥有 30 多个图表和无尽滚动的仪表盘会让用户不知所措。为了避免这种情况，可以在图表顶部使用“选择器”。

在下面的示例中，您可以轻松切换属性的平均价格、中位数价格或最高价格，而无需创建三个单独的图表。由于我们在 ClickHouse 中优化了数据模型，这些信息可以非常快速地检索和计算！

您的演示仪表盘现在已经准备好嵌入。如果您正在使用自己的数据集进行本教程，您可以尽情探索所有不同的可视化类型，或者让 AI 图表生成器为您完成工作。

步骤 3：在 SaaS 应用中嵌入仪表盘

最后一步，也是最重要的一步，就是将仪表盘嵌入到用户预期的位置：直接在您的 Web 或 SaaS 应用中。为什么要让客户转到单独的 BI 工具，从而远离您的应用呢？如果通过添加有价值的见解可以增加产品使用量，为什么不这样做呢？

在嵌入仪表盘之前，您需要决定几件事：

位置：您希望在应用的哪个位置显示仪表盘？
访问控制：哪些客户可以查看哪些数据？
定制：
- 是否需要以不同语言显示仪表盘？
- 是否支持不同设备？
- 是否需要不同的品牌颜色？

一旦决定了这些因素，实施就相对简单了。

在我们的用例中，我们将演示如何在 Web 应用的分析标签中嵌入仪表盘，并为每个英国郡设定不同的访问权限。例如，伦敦的物业经理只能访问伦敦的数据，不能访问曼彻斯特的数据。

1. 设置访问权限

要定义仪表盘的访问权限，首先需要创建一个 Luzmo 集合，包含项目中使用的所有仪表盘和数据集。您可以在左侧导航的“我的集合”下添加新集合，并将数据集和仪表盘拖到概览页面中。

我们将添加一个仪表盘和一个数据集，您也可以根据需要添加更多。现在，我们已经定义了项目中将使用的仪表盘和数据集，需要为访问这些仪表盘的用户设置正确的访问权限。

在我们的例子中，我们只使用了一个数据集，但我们希望用户只能访问与其所在英国郡相关的特定数据。为此，我们需要在数据集上创建一个参数过滤器，在渲染仪表盘时传递。

在集合中，选择您的数据集并点击“嵌入过滤器”。在过滤器下，选择“郡”，并选择要包含数据的郡。创建一个名为“郡”的参数，以便在代码中嵌入仪表盘时使用。

附注：您不需要将所有数据放在一个数据集中以设置特定的访问权限。如果为每个客户使用不同的数据集或多租户 API，可以这样设置多租户，但过程会有所不同。

2. 创建嵌入令牌

嵌入令牌是在您的 SaaS 应用中安全地渲染仪表盘的方法。它确保用户只能看到您希望他们看到的数据，如上一步所定义。

要生成嵌入令牌，您需要创建 API 密钥和令牌，以便应用程序能够安全地访问 Luzmo。可以通过“Profile Settings > API Tokens”完成此操作。复制并保存您的 API 密钥和令牌，因为之后将无法再访问它们。为了安全起见，授权令牌始终在服务器端生成，因此切勿在客户端使用 API 密钥和令牌！

现在，您的服务器端代码可以发出 API 请求以获取授权令牌。在此过程中，您需要填写 API 密钥和令牌、用户详细信息以及希望用户访问的资源。

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
  });

let promise = client.create('authorization', {
  type: 'embed',
  access: {
  collections: [
   {
   id: '<collection ID>',
   inheritRights: 'use'
            }
      ]
  },
  username: '< unique identifier for your user >',
  suborganization: '< company name >',
  name: '< user name >',
  email : '< user email >',
  parameter_overrides: {
    County: ['< counties visible to this user >']
  }
});

promise.then((result) => {
  // result.id contains the embed authorization key,
  // result.token contains the embed authorization token.
});

让我们看看不同用户的情况。例如，来自伦敦的物业经理 Irvine Seller 正在尝试访问仪表盘。通过以下参数设置，他将只能访问伦敦的数据。

  username: 'irvineseller',
  suborganization: 'Big Ben Properties Co.',
  name: 'Irvine Seller',
  email : 'irvine.seller@bigbenproperties.com',
  parameter_overrides: {
    County: ['GREATER LONDON']
  }

同样，对于曼彻斯特的物业买家，授权令牌将限制他们只能访问曼彻斯特的数据：

  username: 'davidbrickham',
  suborganization: 'Soccer Estates Co.',
  name: 'David Brickham',
  email : 'david.brickham@soccerestates.com',
  parameter_overrides: {
    County: ['GREATER MANCHESTER']
  }

发送此请求后，您将收到一个包含 ID 和令牌的 JSON 对象。您将需要这些信息来进行实际的嵌入步骤。

{
  "type": "embed",
  "id": "<the embed authorization key>",
  "token": "<the embed authorization token>",
  "user_id": "<a uuid used on Luzmo's end to identify the embed user>"
  // ...
}

3. 嵌入仪表盘

现在我们已经设置好安全获取和显示仪表盘数据的方法，可以将其嵌入到应用程序中。

一旦确定了显示位置，只需复制粘贴 5-10 行代码即可完成。

<luzmo-dashboard
  dashboardId="<ID of dashboard you want to embed>"
  authKey="<embed key (id property) returned by step 1>"
  authToken="<embed token (token property) returned by step 1>"
  appServer="https://app.luzmo.com/"
>
</luzmo-dashboard>

<script defer src="https://cdn.luzmo.com/js/luzmo-embed/5.1.5/luzmo-embed.min.js" charset="utf-8"></script>

要找到您的专属代码片段，进入要嵌入的仪表盘并点击“Embed”。选择应用程序使用的前端框架，复制代码片段。仪表盘 ID 已填好；您只需添加在上一步生成的 authKey 和 authToken。

完成！现在，您的应用中已经添加了一个交互式的用户仪表盘，只显示用户被允许查看的数据。

要查看效果，请试用下方嵌入的仪表盘，并在两个用户之间切换：

伦敦的物业经理 Irvine Seller
曼彻斯特的房地产所有者 David Brickham

在这个示例中，我们保持了相对简单，但您可以添加更多属性来定制仪表盘体验：

显示仪表盘的语言
用户的时区
仪表盘应加载的屏幕模式（桌面、移动设备、固定宽度）
仪表盘加载器的样式
根据用户或环境连接不同的数据库

查看开发者文档了解更多自定义内容！

资源

如果您想将用户仪表盘嵌入到自己的 SaaS 或 Web 应用中，以下资源将对您有所帮助。

工具：

免费 Luzmo 试用（10 天）【https://app.luzmo.com/signup】
免费 ClickHouse 试用（30 天）【https://clickhouse.cloud/signin?iss=https%3A%2F%2Fauth.clickhouse.cloud%2F】

文档：

连接数据
- ClickHouse Playground 文档【https://clickhouse.com/docs/en/getting-started/playground】
- 将 ClickHouse 数据集连接到 Luzmo【https://academy.luzmo.com/article/ovvkqfo5】
创建仪表盘
- Luzmo 入门课程【https://academy.luzmo.com/course/a0bf5530-edfb-441e-901b-e1fcb95dfac7】
- 如何设置下钻【https://academy.luzmo.com/article/o0foeour】
- 更改图表上的度量和维度【https://academy.luzmo.com/article/af9i21a0】
嵌入仪表盘
- 仪表盘嵌入指南【https://developer.luzmo.com/guide/dashboard-embedding--embed-into-application】
- 如何处理多租户数据【https://developer.luzmo.com/guide/dashboard-embedding--handling-multi-tenant-data】
- 嵌入 API 组件【https://developer.luzmo.com/guide/embedding--component-api-reference】

征稿启示

面向社区长期正文，文章内容包括但不限于关于 ClickHouse 的技术研究、项目实践和创新做法等。建议行文风格干货输出&图文并茂。质量合格的文章将会发布在本公众号，优秀者也有机会推荐到 ClickHouse 官网。请将文章稿件的 WORD 版本发邮件至：Tracy.Wang@clickhouse.com