Evidence で構築するお手軽データ分析基盤

posted at 2024/12/16

以前 Kotlin DataFrame + Kotlin Kandy on GitHub Pages で構築するお手軽データ分析基盤という記事で、それ用の SaaS などを契約、運用することなくローカルに csv ファイルなどを配置して GitHub Pages などに静的サイトとして分析基盤をホストすることを書いた。
実際、本業のチームでもこれで一部運用を開始していたのだが、 Evidence というフレームワークを見つけてしまい以前書いていた手法をやめて移行しようと思ったのでそのメモ。

Evidence のサイトから拝借した画像にもあるように「何かしらのデータソース」x 「Markdownで書いたコンテンツ」で静的サイトをビルドすることができるというもので
https://omuomugin.github.io/sample-evidence/ のように GitHub Pages にもホストすることができるというもの。
(ちなみに上記のサイトは Build Your First App に従ってやってみたもの)

Markdown は具体的には以下のようなものを書くことになる。
特に sql を埋め込む部分などは独自の記法になっている。
(詳細は SQL Queries で説明されている)

### Orders by Month

```orders_by_month
select order_month, count(*) as orders from needful_things.my_query
group by order_month order by order_month desc
limit 12
```
<BarChart
    data={orders_by_month}
    x=order_month
    y=orders
	xFmt="mmm yyyy"
	xAxisTitle="Month"
	yAxisTitle="Orders"
/>

https://omuomugin.github.io/sample-evidence/new_page/ のページに該当する Markdown は omuomugin/sample-evidence/blob/main/pages/new_page.md に記述されている。

BarChart などはコンポーネントのようなもので、All Components にもある通り、かなりの種類が用意されていてフォーカスを当てると数字が見れたりとインタラクションも割とリッチなものが多い印象。

Data Sources にもある通りかなりの種類のデータソースを入力元にすることができるが、CSV files がかなり簡単に読み込めてそこに対してクエリを実行できるという点が個人的にはニーズにあっている。

Introducing Universal SQL のブログを読む限り、 Duck DB が SQL の処理としては動いているようでゆえに多くのデータソースをサポートできている様子。
実際 SQL Queries にも以下のようにある。

Evidence runs markdown code fences as SQL queries. These queries use the DuckDB dialect.

また GitHub Pages のデプロイも簡単だった。
まず Deployment Overview にある通り npm run build で静的コンテンツとしてビルドすることができる。
(CIなどのために sql が不正な場合などにエラーとする npm run build:strict もある)

あとは、 GitHub Pages の説明通り以下を実施するだけで良い

evidence.config.yaml を編集して base path を設定する
同ページ内にある GitHub Actions の定義を deploy.yml として GitHub Pages にデプロイする

自分の環境のせいなのかわからないが、 https://github.com/evidence-dev/evidence/issues/2919 でも Issue をあげたように以下のようにしないと正しく動作しなかったので注意

 - name: build
   env:
-    BASE_PATH: '/${{ github.event.repository.name }}'
     ## Add and uncomment any environment variables here
     ## EVIDENCE_SOURCE__my_source__username: ${{ secrets.EVIDENCE_SOURCE__MY_SOURCE__USERNAME }}
     ## EVIDENCE_SOURCE__my_source__private_key: ${{ secrets.EVIDENCE_SOURCE__MY_SOURCE__PRIVATE_KEY }}
   run: |
     npm run sources
     npm run build

 - name: Upload Artifacts
 uses: actions/upload-pages-artifact@v3
 with:
-    path: 'build/${{ github.event.repository.name }}'
+    path: './build

Templated Pages などの機能もあるようなのでその辺をもうちょっと調べて本格的に分析基盤を移行していきたい。

(追記)
BASE_PATH がうまくいかなかった件は、どうやら https://github.com/evidence-dev/evidence/pull/2921 にもあるように Configuring the Build Directory in package.json を適用していなかったことが原因のようだった。

package.json の build を以下のように変更する必要があるとのことだった

 "build": "EVIDENCE_BUILD_DIR=./build/my-base-path evidence build"