使用 Evidence.dev 可视化 BlueSky 数据_evidence markdown-优快云博客

本文字数：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