本文字数:5393;估计阅读时间:14分钟
作者: Mark Needham
本文在公众号【ClickHouseInc】首发
我们刚刚将 BlueSky 社交网络数据引入 ClickHouse,使其能够被快速查询和扩展分析,从而带来更多令人兴奋的数据洞察机会。我一直想尝试 Evidence.dev 这个强大的数据应用开发工具,而这正是一个绝佳的尝试机会。
在本篇博客中,我们将深入解析 Evidence.dev 的独特之处,以及它在数据应用构建方面与其他工具的不同之处。接下来,我们会手把手带你创建一个数据看板,深入探索 BlueSky 数据集,挖掘其中的潜力。最终,你会发现,原始数据如何被轻松转化为有价值的商业洞察。
先来看看我们即将构建的成果:
什么是 Evidence?
Evidence.dev 是一个轻量级的开源框架,专门用于使用 SQL 构建数据应用和商业智能(BI)产品。它采用代码驱动的工作流,将 SQL、Markdown 和数据可视化组件结合在一起,帮助开发者构建交互式、精美的数据应用。
Evidence.dev 以用户体验为核心,提供快速加载的页面、预构建查询,并采用简洁直观的格式。它支持 Git 进行版本控制,可轻松部署为静态网站,并能与各种数据技术栈无缝集成。
其核心特性之一是支持创建动态模板页面,并生成专业级的数据可视化图表。这使数据团队能够更高效地构建数据产品,清晰地向组织呈现数据分析结果,并优化企业内部的数据沟通方式。
Evidence.dev 既支持自托管,也提供云端服务,满足不同规模团队的需求。
Evidence 是如何工作的?
Evidence 与其他数据工具的最大区别在于,它在构建时执行查询,而不是在应用运行时查询数据。换句话说,我们牺牲了一定的数据实时性,以提升页面加载速度和交互体验。
获取查询结果并呈现在页面上的流程如下:
① 指定数据库连接信息。
② 定义查询语句,执行相应的数据查询。
③ 运行命令执行这些查询,并将查询结果存储为 Parquet 文件。
④ 在应用运行时,直接从这些 Parquet 文件中读取数据。
安装 Evidence
接下来,我们来看看如何在本地环境中安装并运行 Evidence.dev。最简单的方法是基于 Evidence 提供的模板创建一个新项目。可以使用以下命令创建一个名为 `evidence-dashboard` 的项目:
npx deit evidence-dev/template evidence-dashboardg
我们已经预先准备好了一个 Evidence 项目,位于 bluesky-dashboards/evidence-dashboard,如果你愿意,也可以直接克隆该项目,省略上述步骤:
git clone git@github.com:mneedham/bluesky-dashboards.git
然后,进入 evidence-dashboard 目录并安装所有依赖项:
npm install
请注意,这个安装过程可能需要一些时间,请耐心等待。
默认情况下,Evidence 不支持 ClickHouse,不过,我们可以通过运行以下命令安装 Archie Wood 开发的 ClickHouse 连接器:
npm install evidence-connector-clickhouse
此外,还需要在 evidence.config.yaml 文件的 plugins.datasources 部分添加以下配置:
evidence-connector-clickhouse: {}
运行 Evidence
现在,我们可以运行 Evidence 了,执行以下命令即可启动应用:
npm run dev
通常,浏览器会自动打开 Evidence 应用,如果没有,请手动访问 localhost:3000,即可看到 Evidence 的界面。
当前页面的内容来自 pages/index.md 文件。我们稍后会介绍如何修改它,但首先,我们需要先配置 ClickHouse 连接。
配置 ClickHouse 连接
在浏览器中访问 https://localhost:3000/settings,或者点击顶部菜单栏中的 Settings。
然后,添加一个新的数据源:
-
数据源类型 (Datasource type) 选择 clickhouse。
-
数据源名称 (Source name) 可自定义,这里我们命名为 ClickHouse。
接下来,填写以下连接信息:
-
URL: https://sql-clickhouse.clickhouse.com?request_timeout=60000
-
Username: demo
密码字段可以留空,但如果你使用的是自己的 ClickHouse 实例,则需要提供相应的密码。
确认无误后,点击 Confirm Changes 进行保存。
配置信息会被写入 sources//connection.yaml 文件。例如,在 sources/ClickHouse/connection.yaml 中,你会看到以下内容:
# This file was automatically generated
name: ClickHouse
type: clickhouse
options:
url: https://sql-clickhouse.clickhouse.com?request_timeout=60000
username: demo
在 BlueSky 数据上编写 ClickHouse 查询
现在,我们可以开始在 Evidence 中编写 ClickHouse 查询了。Evidence 要求每个查询文件必须独立存放在 sources/ 目录下,并以 .sql 作为文件后缀。
例如,以下 time_of_day.sql 查询计算了每天的事件数量:
SELECT event, hour_of_day, sum(count) as count
FROM bluesky.events_per_hour_of_day
WHERE event in ['post', 'repost', 'like']
GROUP BY event, hour_of_day
ORDER BY hour_of_day;
此外,你可以在 sources/ClickHouse 目录下找到其他示例查询。
使用 Evidence 运行 ClickHouse 查询
编写完查询后,需要运行它们,可以使用以下命令执行:
npm run sources
运行后,终端会输出类似如下的结果:
[Processing] ClickHouse
events_by_day ✔ Finished, wrote 16 rows.
messages_last_day ✔ Finished, wrote 1 rows.
most_liked ✔ Finished, wrote 100 rows.
most_reposted ✔ Finished, wrote 100 rows.
posts_per_language ✔ Finished, wrote 548 rows.
time_of_day ✔ Finished, wrote 72 rows.
top_post_types ✔ Finished, wrote 31 rows.
total_messages ✔ Finished, wrote 1 rows.
-----
Evaluated sources, saving manifest
✅ Done!
查询结果会以 Parquet 文件的形式存储在 `.evidence` 目录中:
find .evidence -iname \*.parquet
你会看到这些文件:
.evidence/template/static/data/ClickHouse/posts_per_language/posts_per_language.parquet
.evidence/template/static/data/ClickHouse/time_of_day/time_of_day.parquet
.evidence/template/static/data/ClickHouse/most_reposted/most_reposted.parquet
.evidence/template/static/data/ClickHouse/top_post_types/top_post_types.parquet
.evidence/template/static/data/ClickHouse/most_liked/most_liked.parquet
.evidence/template/static/data/ClickHouse/messages_last_day/messages_last_day.parquet
.evidence/template/static/data/ClickHouse/total_messages/total_messages.parquet
.evidence/template/static/data/ClickHouse/events_by_day/events_by_day.parque
这些 Parquet 文件将作为 Evidence 仪表板的数据源。
构建 Evidence 仪表板
Evidence 仪表板可以由多个页面组成,但我们先从一个单页仪表板开始。仪表板页面使用 Markdown 文件定义,首页存放在 pages/index.md。
Markdown 文件不仅可以包含文本内容,还支持使用 React 语法定义各种组件。
我们可以在 `front matter` 配置块中为页面设置标题:
---
title: BlueSky Dashboard
---
接下来,我们创建一个柱状图,展示 time_of_day 查询计算出的每日帖子数量。
首先,添加一个 SQL 代码块,查询 .(去掉.sql 后缀):
## When do people use BlueSky?
What's the most popular time for people to like, post, and re-post?
```sql tod
SELECT *
FROM ClickHouse.time_of_day
```
然后,我们为该查询块命名为 tod,之后会在可视化组件中引用它。接下来,使用以下代码渲染柱状图:
<BarChart
data={tod}
x=hour_of_day
y=count
yFmt=num0m
series=event
/>
data 属性必须对应查询块的名称,x 表示 X 轴字段,y 表示 Y 轴字段。
然后,打开浏览器访问 localhost:3000,你就可以看到最终的可视化结果:
部署到 Evidence Cloud
Evidence 默认生成静态站点。正如前文所述,它不会在运行时查询数据库,而是使用 DuckDB WASM 访问预先生成的 Parquet 文件。
我们可以用以下命令在本地生成静态站点:
npm run build
Wrote site to "./build"
✔ done
Build complete --> ./build
然后,我们可以使用 HTTP 服务器本地托管该目录,或者将其部署到 Web 主机。
我们还可以选择部署到 Evidence Cloud。要实现这一点,需要先将项目推送到 GitHub 仓库。本项目已托管在 GitHub:https://github.com/mneedham/bluesky-dashboards。
接着,访问 https://evidence.app,将该仓库添加为 Evidence 项目。在此过程中,你需要设置项目的 URL,并定义数据的刷新间隔。每次你更新 GitHub 仓库,应用都会自动重新部署。
目前,我们已将该项目部署到 https://bluesky.evidence.app,你可以在这里查看 BlueSky 数据集的各种可视化结果。
总结
在本文中,我们介绍了如何使用 Evidence.dev 构建 BlueSky 数据集的仪表板。从工具安装、配置 ClickHouse 连接,到运行查询并可视化结果,我们详细讲解了整个流程。
Evidence.dev 采用构建时运行查询并生成静态站点的方式,让它成为构建快速加载、交互丰富的仪表板的理想方案。
按照本文的步骤,你可以高效分析 BlueSky 数据,并构建类似的仪表板来探索你的数据集。完整项目可在 bluesky.evidence.app 查看,代码可在 GitHub 获取。
征稿启示
面向社区长期正文,文章内容包括但不限于关于 ClickHouse 的技术研究、项目实践和创新做法等。建议行文风格干货输出&图文并茂。质量合格的文章将会发布在本公众号,优秀者也有机会推荐到 ClickHouse 官网。请将文章稿件的 WORD 版本发邮件至:Tracy.Wang@clickhouse.com