Grayrecord Technow

Evidenceを理解する上でのポイントとして、静的サイトジェネレータを箸休めとして説明します。 まず、静的サイトと動的サイトの区別からです。静的サイトとは、コンテンツがファイルとして固定され、サーバはリクエストに基づきただ配信するだけのものです。初期のホームページと言われたもののスタイルです。 次に動的サイト、これはリクエストに応じて何らかのコードがサーバ上で実行され、動的にレスポンスが生成され、それがクライアントに返されるものです。WordpressなどのBLOGサービスなどはこの形態です。 静的サイトとは Wordpressなどではコンテンツはデータベースに格納されたものがベースで、同じようにテーマなどの情報がデータベースに格納され、それがユーザのリクエストによって組み立てられて返答されるという構造です。 静的サイトと動的サイトの差異 これだけで「静的サイトジェネレーター」のすべてがわかりますを参考にすれば以下のように纏められます。 動的サイト 静的サイト 表示されるページ ユーザーに応じて表示するページを変更できる 全員に同じページを表示する スピード 遅い 速い ページが生成される時 アクセスされた時 ビルド時 Wordpressなどが動的サイトとして構成されたのは、データベースにコンテンツ、テーマを格納しそれをリクエスト時に構築するという構造が都合が良かったためです。 静的サイトが再度注目された理由 しかし、今、再度、静的サイトジェネレータが注目された理由があります。まず、宿命的に表示されるコンテンツをユーザに合わせてというのは苦手ですが、通常のBlogサービスであれば、読者は通常ログインなどの手続きをしないため、ユーザに合わせては要件から除外できます。そうすると、動的サイトのメリットはかなり減ります。恐らく、GUIでのWebベースでのコンテンツメインテナンスなどのこの表に書かれていないモノになるでしょう。 そして、「全員に同じページを表示する」であれば、コンテンツへのテーマなどの適用はアクセス時にこだわる必要性はないになります。よって、バッチ的にサイトをコンテンツから生成する静的サイトジェネレータとなるわけです。 静的サイトジェネレータを支える要素 静的サイトジェネレータが注目された理由はそれだけではありません。一つはクライアント端末の性能向上です。例えば、昔の携帯電話のパフォーマンスと今のスマートフォンのパフォーマンスを比べてください。昔の携帯電話、フィーチャーフォン向けに開発された、CHTMLなどはかなりの仕様を削減していました、当然、クライアント側でのコード実行などは考えてすらいませんでした。しかし、今のスマートフォンはクライアント側でのモバイルコードの実行には十分であり、ECMA Script、WebAssemblyなどの支援もあります。故にコードの実行をWebサーバからクライアントに移すことも可能になりました。 故に、無理に、サーバ側で全てのコンテンツをレンダリングする必要はなくなりました、また、動的コンテンツを残すとしても、インラインフレームなどで組み込みむ手段もあります。従って、メインのコンテンツを動的に生成することは必ずしも必要なくなくなりました。 静的サイトジェネレータの限界 とはいえ、最初に上げた、「全員に同じページを表示する」という特性は無くなることはありません。 従って、静的サイトジェネレータを基盤とするBIツールであるEvidenceでは例えば、ユーザを認識してコンテンツを変えるなどは苦手です。例えば、厳密に、Need-to-Knowを実現するのは困難です。サイト自体に認証などは出来るにしても、コンテンツをユーザに合わせてレンダリングするのは困難です。 この辺のポイントを理解するのが、Evidenceを有効活用する道になります。

Covid-19のダッシュボードの作成を例にしています。イメージとしては、表形式でデータが見えるようにして、時系列で合計値がチャートして見えるようにして、カレンダーヒートマップで曜日ごとの動きが見えるようにするというのを考えてみます。仮説としては人の動きに感染者は依存しているのではないかと言う仮説です。だとすれば、曜日ごとに特徴があるのではないかと言う仮説です。 流れとしては、以下のような順番になります。 プロジェクトの作成 データのインポート クエリとビジュアリゼーションコンポーネントの配置 クエリとビジュアリゼーションコンポーネントの配置は主にMarkdownのドキュメントで行います。 プロジェクトの作成 まず、プロジェクトを作成するところから始めます。プロジェクトの作成はVisual Studio Codeから作成します。 プロジェクトの作成(1/5) プロジェクトの作成(2/5) プロジェクトの作成(3/5) プロジェクトの作成(4/5) プロジェクトの作成(5/5) Evidenceのウェルカム画面 プロジェクトを作成すると、Evidenceのサーバを起動可能になります。Evidenceのサーバを起動すると通常はポート1313で待ち受け状態になります。そうすると、Webブラウザで開けるようになります。ウェルカム画面は以下のようになります。 Evidenceサーバの起動 Evidenceサーバの起動はVisual Studio Codeから行います。コマンドパレットから起動できます。 データのインポート https://www.mhlw.go.jp/stf/covid-19/open-data.html から取得した、新規陽性者数の推移（日別）のデータをプロジェクトフォルダのsourcesにcovid19というディレクトリを作成して 配置します。新規陽性者数の推移（日別）のデータはnewly_confirmed_cases_daily.csvというファイル名なので、newly_confirmed_cases_dailyというテーブルとして識別されます。 データのインポートはEvidenceのサーバからやると、設定ファイルなどを簡単に作成できます。 データのインポート データのインポート (1/4) Evidenceのサーバのインポート画面ではインポート可能なデータ形式の確認ができます。 Evidenceでインポート可能なデータについてはEvidenceのWeb画面を起動したときのSettingsの中の画面で確認できる。 データのインポート (2/4) データのインポート (3/4) データのインポート (4/4) 現在Evidenceでインポート可能なもの BigQuery CSV Databricks DuckDB Microsoft SQL Server PostgreSQL Redshift JavaScript Snowflake SQLite Trino MotherDuck 最初のコンテンツの作成 最初のコンテンツの作成 (1/2) 次に、プロジェクトフォルダのpages/index.mdを編集します。index.mdはEvidenceのサーバに接続してデフォルトで表示されるページになります。ここのコンテンツを以下のようにします。 --- title: Welcome to Evidence --- ## Covid19 のCSV確認 ```sql covid19_10 select * from covid19.newly_confirmed_cases_daily limit 10 ``` <DataTable data={covid19_10}/> 最初のコンテンツの作成 (2/2) これにより、covid19.newly_confirmed_cases_dailyから10行取り出して表として出力されます。 ...

目的と対象読者 このドキュメントは、Windows環境を前提にEvidenceの利用方法について記述しています。Evidenceは様々な環境で稼働しますが、執筆時点での環境および設定を基準としています。 対象読者 Evidenceをはじめて利用する方 Windows環境でのセットアップ利用方法に関心のある方 前提条件 インストール済みのソフトウェア Visual Studio Code Git Node.js npm Node.jsのインストール方法 Scoopを利用し、執筆時点のLTSを利用しています。 Evidenceのバージョン バージョン 40.1.1をターゲットにしています。 Evidenceとはなにか 「Evidence」とは、Markdownで管理できるオープンソースのBI（ビジネスインテリジェンス）ツールです。 具体的には、レポート、意思決定支援ツール、埋め込みダッシュボードなどのデータプロダクトを構築するための オープンソースのフレームワークと説明されています。 Evidenceの主な特徴は以下の通りです。 コード駆動型BIツール:ドラッグ＆ドロップ式のBIツールとは異なり、コード（主にSQLとMarkdown）を使用してデータプロダクトを構築します。 Markdownで管理: Markdownファイル内でSQLクエリを記述し、コンテンツやレイアウトを管理します。 多様なデータソースに対応: データウェアハウス、フラットファイル（例：CSV）、非SQLデータソースなど、さまざまな種類のデータソースを扱うことができます。 SQLクエリの実行と結果の可視化: Markdownページに記載されたSQLステートメントに基づいてデータソースに対してクエリを実行し、その結果をグラフや表としてウェブサイトに出力できます。Markdown内で使用されるSQLはDuckDBのSQLです。 静的サイトの生成 出力は静的なウェブサイトとして生成されるため、デプロイや共有が容易です。npm run buildコマンドで静的サイトを生成し、S3などのホスティングサービスに格納して簡単に共有できます。 豊富なコンポーネント: クエリ結果に基づいて、さまざまなチャート（棒グラフなど）、表（DataTable）、大きな単一の値（BigValue）などのコンポーネントをレンダリングできます。 高度な機能: テンプレートページによる複数ページの生成、表示内容の制御のためのループやIf/Else文、クエリ結果のフィルタリング機能（Query Functions）なども備わっています。 Evidenceの適する用途 アーキテクチャなどを踏まえての説明は次回以降になりますが、Evidenceは様々な用途に利用可能です。基本的にはOn the flyのクエリーは困難なので、IoTなどの機器からのリアルタイムなダッシュボードには向きません。どちらかと言うと、日次・月次でしめるような処理が適します。従って、売り上げなどの分析が適すると思われます。

基本的な準備 システム構成の概要 Evidenceのアーキテクチャ Evidenceは基本的には、データソース、DuckDB、レンダリングエンジンという仕組みになっています。実際には更に、 静的サイトジェネレータも重要な位置を示しますが、その性質からここには表現していません。以下の図にEvidenceの基本的なアーキテクチャを示します。 まず、データソースからデータが取り出され、共通のデータ形式であるParquetに変換されます。ParquetはDuckDBによって利用されます。 従って、Evidenceで利用可能なデータは基本的にParquetに抽出されたデータに限定されます。 よって、標準的なBIツールのようにOn the flyのクエリを動的に送出してリアルタイムなデータを反映させることは出来ません。 従って、そのような要件が含まれる場合にはEvidenceは適切な選択肢ではありません。 従って、ドキュメントの流れまで含めて、アーキテクチャを図示すると以下のような形になります。 動作環境 Evidenceを動作させるためには、以下の環境が必要です。 Node.js: バージョン ≥18.13, 20, または 22 が必要です。初めてインストールする場合は、LTS（長期サポート）バージョンの利用が推奨されています。現在のNode.jsのバージョンはコマンド node -v で確認できます。 NPM (Node Package Manager): バージョン 7 以上が必要です。 Git: Gitがインストールされている必要があります。Gitがインストールされていない場合は、インストールする必要があります。GitHubへの登録も推奨されています。 これらの要件を満たすことで、Evidenceをローカル環境にインストールし、データプロダクトの構築を開始することができます。 現在のNode.jsのバージョンの確認方法 node -v 最新のNode.jsへの更新方法 scoop update nodejs-lts npmのバージョン確認方法 npm -v gitのインストール方法 scoop install git Evidenceのインストール方法 Evidenceには幾つかのインストールパターンがありますが、ダッシュボード開発時にはVisual Studio Codeと専用の拡張機能の利用が推奨されます。 本アーティクルでは、基本的にはScoopで環境構築を行っています。 scoopがインストールされている場合は以下のコマンドでnode.jsやNPMを展開できます。 scoopを利用することで、バージョンの管理、アップデートは容易になります。 scoop install nodejs-lts なお、本アーティクル以降ではVisual Studio Codeでの構築を行っていきますので、Visual Studio CodeにEvidenceの拡張機能を導入してください。 また、これらのインストール中にエラーが生じた場合には、そのステップに応じて、ScoopやVisual Studio Code、Evidenceのドキュメントを参照してください。 システム構成の概要 ダッシュボード開発時の典型的な構成は以下のようになります。 ...

今回はちょっとだけ箸休め的にScoopによる環境構築を多少補足します。 本シリーズでは基本的には、環境構築はScoopを用いることを前提としています。 Scoopはコマンド一つで様々なパッケージを展開可能なツールです。 Scoopは悪い意味ではまっとうなパッケージマネージャではありません。しかし、以下の条件の元では極めて有効に働きます。 You’re a programmer/developer You want to set up a machine without having to visit a bunch of websites, download installers and then click through each one You’re comfortable working on the command line, especially with tools like Git You’re familiar with UNIX tools, and you wish there were more of them on Windows You read Hacker News and you feel like you’re ‘stuck’ on Windows and missing out on lots of cool things You wish there was an easier way to tell other developers how to install programs (maybe your own programs) You use Homebrew/apt-get and think, “this is awesome”. https://github.com/ScoopInstaller/Scoop/wiki/So-What より。 ...