使用 Evidence.dev 可视化 BlueSky 数据

我们刚刚开放了 BlueSky 社交网络数据，以便在 ClickHouse 中进行快速、可扩展的查询，从而开启了令人兴奋的分析和洞察可能性。我一直渴望尝试 Evidence.dev，这是一个用于创建动态、数据驱动型应用程序的强大工具，而这似乎是一个绝佳的机会。

在本博客中，我们将深入探讨 Evidence.dev 的独特之处，以及它与其他构建数据应用程序的工具相比有何突出之处。然后，我们将逐步指导您创建一个仪表板，以探索 BlueSky 数据集并挖掘其潜力。到最后，您将看到将原始数据转换为可操作的见解是多么容易。

这是我们即将构建内容的一个小预告

Evidence.dev 是一个轻量级、开源框架，用于使用 SQL 构建数据应用程序和商业智能产品。它提供了一个代码驱动的工作流程，结合了 SQL、markdown 和数据可视化组件，以创建精美的、交互式 Web 应用程序。

该平台通过提供快速加载的页面、预构建查询和熟悉的格式来优先考虑用户体验。Evidence.dev 通过 Git 支持版本控制，可以轻松部署为静态站点，并与各种数据堆栈良好集成。

其主要功能之一是能够创建动态的、模板化的页面和出版物质量的图形。这使得数据团队可以更轻松地向组织展示数据叙事和指标，简化了构建数据产品的流程，并增强了公司内部的数据沟通方式。

Evidence.dev 提供自托管选项和云服务。

Evidence 与其他工具的不同之处在于，它在构建时而不是运行时运行查询。这实际上意味着我们牺牲了数据新鲜度来换取更快的页面加载时间和改进的交互性。

将查询结果显示在页面上的步骤如下

① 指定数据库凭据。
② 定义要针对该数据库运行的查询。
③ 运行命令以执行这些查询，并将输出存储在 Parquet 文件中。
④ 在运行时，查询这些 Parquet 文件。

让我们看看如何在我们的机器上启动并运行 Evidence.dev。最简单的方法是基于 Evidence 模板之一创建一个项目。我们可以通过运行以下命令创建一个名为 evidence-dashboard 的项目

1npx deit evidence-dev/template evidence-dashboardg

我们已在 bluesky-dashboards/evidence-dashboard 预先准备了一个 Evidence 项目，因此您可以克隆该项目，而忽略上述步骤

1git clone [email protected]:mneedham/bluesky-dashboards.git

无论哪种方式，您都需要 cd evidence-dashboard 并安装所有内容

1npm install

这需要一段时间才能运行，请做好准备。

Evidence 不支持开箱即用的 ClickHouse，但我们可以通过运行以下命令安装 Archie Wood 的 ClickHouse 连接器

1npm install evidence-connector-clickhouse

我们还需要将以下行添加到 evidence.config.yaml 的 plugins.datasources 下

    evidence-connector-clickhouse: {}

现在我们准备好运行 Evidence 了，我们可以使用以下命令来完成

1npm run dev

您的浏览器应该会自动打开，但如果未打开，请打开浏览器并在地址栏中导航到 localhost:3000。您应该看到您的 Evidence 应用程序。

您在屏幕上看到的内容来自 pages/index.md 中的内容。我们稍后会介绍这一点，但首先，我们必须配置与 ClickHouse 实例的连接。

转到 https://127.0.0.1:3000/settings 或单击顶部菜单中的“设置”

然后添加新的数据源。“数据源类型”应为 clickhouse。“源名称”可以是您喜欢的任何名称。我们将使用 ClickHouse。

然后您可以指定以下值

• URL: https://sql-clickhouse.clickhouse.com?request_timeout=60000
• 用户名: demo

您可以将密码字段留空，但如果您使用自己的 ClickHouse 实例，则需要提供密码。

填写完所有值后，按“确认更改”。

配置将写入 sources/<Source Name>/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

现在，我们准备好开始编写一些查询了。Evidence 要求您为每个文件创建一个查询。这些文件位于 sources/<Source Name> 下，并且应具有 .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 下找到一组其他查询。

编写完查询后，我们需要运行它们，我们可以通过运行以下命令来完成

1npm 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

这些是我们的 Evidence 仪表板将查询的文件。

一个 Evidence 仪表板可以包含多个页面，但我们将从一个单页仪表板开始。仪表板在 markdown 文件中定义，主页位于 pages/index.md 下。

markdown 文件可以包含 markdown 格式的文本和 各种组件，这些组件可以在 React 风格的语法中定义。

我们可以在 front matter 中为页面指定标题

---
title: BlueSky Dashboard
---

然后，让我们创建一个条形图，显示基于我们之前看到的 time_of_day 查询的每日帖子数。

我们首先添加一个 SQL 代码块，该代码块查询 <Source Name>.<file_name>（不包括 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 轴的字段名称。

如果我们然后回到 Web 浏览器中的 localhost:3000，我们将看到以下内容

Evidence 默认生成静态站点。如前所述，它不会在运行时查询我们的数据库。相反，它使用 DuckDB WASM 查询预生成的 Parquet 文件。

我们可以使用以下命令在本地生成静态站点

1npm run build

  Wrote site to "./build"
  ✔ done
Build complete --> ./build

我们可以使用 HTTP 服务器在本地提供此目录，或者将其部署到 Web 主机。

或者，我们可以部署到 Evidence Cloud。我们需要将我们的项目发布到 GitHub 存储库才能执行此操作。此项目可在 https://github.com/mneedham/bluesky-dashboards 获得。

然后，我们可以导航到 https://evidence.app 并将存储库添加为 Evidence 项目。您必须为您的项目选择一个 URL，并指示您希望何时刷新数据。每当您对存储库进行任何更改时，应用程序都会自动重新部署。

我们已将此项目部署到 https://bluesky.evidence.app，您可以在其中看到各种可视化效果，探索 BlueSky 数据集。

在这篇文章中，我们探讨了如何使用 Evidence.dev 为 BlueSky 数据集构建仪表板，从设置工具并使用 ClickHouse 配置它，到运行查询和可视化结果。

Evidence.dev 在构建时运行查询并使用静态站点生成的方法使其成为创建快速加载、交互式仪表板的实用选择。

按照此处概述的步骤，您可以有效地分析 BlueSky 数据并创建类似的仪表板来探索您的数据集。您可以在 bluesky.evidence.app 查看已完成的项目，或在 GitHub 上访问代码。