biff.graph データ可視化ガイド

biff.graph

を利用することで、データベースおよびビジネスロジック／派生データを単一かつ拡張可能なグラフとして一元管理し、照会（クエリ）が可能になります。

• データモデルのコードは小さな独立した単位（「リゾルバー」）に分割できるため、アプリケーション側では必要なデータの形状を宣言するだけで、取得方法を記述する必要がなくなります。
• これにより、特にコードベースが大きくなるにつれて理解しやすく、テストも容易になります。

---

概要と特徴

biff.graph

は本質的に Pathom の軽量版です。Pathom の機能サブセットのみを実装しており、意図的に簡素化されています。

メリットとデメリット

• メリット
  • コードベース全体が約 600 行（クエリ実行部は約 200 行）という軽量構造です。
  • デフォルトで Biff に含まれることがありますが、学習コストをかけずにコード構造上の利点を活かすことができます。
• デメリット
  • Pathom よりも一部のクエリが効率的に実行されない可能性があります。
  • クエリ計画（プランニング）のステップを持たない点が最大の違いです。

機能サポート

• バッチリゾルバーをサポートしています。
• キャッシング機能をサポートしています。

---

依存関係

Maven Central での依存追加例です。

com.biffweb/graph {:mvn/version "2.0.0-rc7"}

ステータス

本ライブラリは、他の Biff 2 ライブラリが全てリリースされるまで**ベータ版（RC）**の状態です。

• 互換性:現時点では重大な不互換の変更を予定しておりません。

---

API リファレンス

• 主要なパッケージ名：

  com.biffweb.graph

コンセプト

biff.graph

は、EQL / Datomic の

pull

パターンに基づき、データを定義する際に少し改良されたサブセットを採用しています。

リゾルバー (Resolver)

**「リゾルバー」**とは、入力および出力のクエリが関連付けられた関数のことです。

• 入力のクエリ形状: データベースから取得すべきデータの鍵（ID など）を受け取ります。
• 出力のクエリ形状: 計算された結果や関連データを含んだマップを返します。

複数のリゾルバーを定義した後、

biff.graph

のクエリエンジンはそれらを利用して、照会された任意の形状のデータを返します。

---

コード例

バナナグラフモデル

以下のスニペットでは：

1. シミュレートされたリゾルバー（

   rss-feed

   と

   post

   ）を定義しています。
2. 派生データ計算のリゾルバー（

   clean-post-title

   ）を定義し、絵文字を除去したバージョンを返しています。
3. どの属性がデータベース取得か、派生処理かが自動で区別されます。

(require '[com.biffweb.graph :as biff.graph :refer [defresolver]])
(require '[clojure.string :as str])

;; --- 1. RSS Feed リゾルバー ---
(defresolver rss-feed
  {:input  [:rss-feed/id]
   :output [:rss-feed/title]}
  [_ctx {:rss-feed/keys [id]}]
  (get {1 {:rss-feed/title "My Blog"}}
       id))

;; --- 2. ポストリゾルバー ---
(defresolver post
  {:input  [:post/id]
   :output [:post/title
            :post/url
            {:post/rss-feed [:rss-feed/id]}]}
  [_ctx {:post/keys [id]}]
  (get {2 {:post/url      "https://example.com/my-post"
           :post/title    "My Post 🎅"
           :post/rss-feed {:rss-feed/id 1}}
        3 {:post/title    "My Other Post 🎅"
           :post/rss-feed {:rss-feed/id 1}}}
       id))

;; --- 3. デリバリーフ（派生ロジック） ---
(defn remove-emojis [s]
  (str/replace s #"🎅" ""))

(defresolver clean-post-title
  {:input  [:post/title]
   :output [:post/clean-title]}
  [_ctx {:post/keys [title]}]
  {:post/clean-title (-> title
                         remove-emojis
                         str/trim)})

;; --- 4. コンテキスト作成とクエリ実行 ---
(def resolvers [rss-feed
                post
                clean-post-title])

(def ctx (biff.graph/new-ctx resolvers))

(biff.graph/query ctx
                  [{:post/id 2}
                   {:post/id 3}]
                  [:post/id
                   :post/clean-title
                   ;; オプションの属性は [:? ...] で示します
                   [:? :post/url]
                   ;; ジョイン属性はネストされたマップで示します
                   {:post/rss-feed [:rss-feed/title]}
                   ;; オプションのジョイン属性
                   {[:? :post/rss-feed] [:rss-feed/title]}
                   ])
;; =>
[{:post/id           2,
  :post/clean-title "My Post",
  :post/url         "https://example.com/my-post",
  :post/rss-feed    {:rss-feed/title "My Blog"}}
 {:post/id          3,
  :post/clean-title "My Other Post",
  :post/rss-feed    {:rss-feed/title "My Blog"}}]

---

使用方法

リゾルバーの定義

通常、データベーススキーマに基づいてリゾルバーを自動生成する機能が必要です（

com.biffweb.graph/resolver

を使用）。ガイドラインは以下の通りです：

• 1 トピック 1 リゾルバー: テーブル／エンティティタイプ 1 つに対して 1 つのリゾルバーを用意します。
• 入力クエリ: 主キーのみを含めるべきです（例：

  [:person/id]

  ）。
• 出力クエリ: 他のすべての列／属性を含めるべきです（例：

  [:person/age, :person/favorite-color, ...]

  ）。
• ジョインキー: 外部キー／参照属性に対して、ジョインキーおよびそのサブクエリとして当該エンティティの主キーを含めるべきです（例：

  [{:person/pet [:pet/id]}, ...]

  ）。
• バッチ処理: リゾルバーオプションに

  :batch true

  を含めます。これにより複数のエンティティを一括で取得できます。この設定を持つリゾルバーは、入力マップのベクトルを受け取り、同じ順序の出力マップのベクトルを返す必要があります。
• 実装: リゾルバー関数は事実上

  SELECT *

  を実行し、ジョインキーを確認しながらネストされたマップとしてフォーマットする必要があります。

※公開されていない

biff.sqlite

ライブラリには SQLite 向けの機能が用意されています（未編集の AI コードによる注記）。

その後、任意のリゾルバーを

com.biffweb.graph/defresolver

で定義できます。ヘルパー関数からのロジックを gradually に移動させることも可能です。

コンテキストの作成

最後に、定義したリゾルバーを

com.biff.web.graph/new-ctx

に渡します。

• クエリエンジンが使用する単純なインデックス処理が行われます。
• リゾルバーは、キャッシングや検証などの処理を行うミドルウェアでラップされます。

クエリの実行

リゾルバー定義後、必要な場所（例：Ring リクエストハンドラー）からクエリを実行します。

(defn settings-page [{:keys [session] :as ctx}]
  (let [user (biff.graph/query ctx
                               {:user/id (:uid session)}
                               [:user/email
                                :user/display-name
                                :user/subscribed])]
    ...))

上記の例では、

com.biffweb.graph/new-ctx

の出力が入ってくる Ring リクエストにマージされるミドルウェアがあることを前提としています。

デバッグ

com.biffweb.graph/query

内部で発生した例外は、

:biff.graph/trace

キーを通じて以下を教えてくれます：

• クエリエンジンがグラフ走査のどの位置にあったか。
• 入力データを解決しようとしたのはどのリゾルバーか。
• 失敗したパスに焦点を当てて最小再現例を作成できます。

テスト

リゾルバー関数は

:biff.graph/resolve-fn

キーの下に格納されます。

(defresolver my-resolver
  {:input [:user/id]
   :output [...]}
  [ctx input]
  ...)

(deftest test-my-resolver
  (is (= ((:biff.graph/resolve-fn my-resolver)
          {:biff.graph/input {:user/id 1}})
         ...)))

---

biff.fx との統合

biff.fx

を使用している場合、ハンドラーマップに

com.biffweb.graph/fx-handlers

をマージできます。これにより、

:biff.graph.fx/query

キー下でクエリが公開されます。

(require '[com.biffweb.fx :refer [defmachine]])

(defmachine do-something
  :start
  (fn [{:keys [session]}]
    {:user [:biff.graph.fx/query
            {:user/id (:uid session)}
            [:user/email
             ...]]
     :biff.fx/next :next})
  ...)

defresolver

も、リゾルバーの本体を

biff.fx

マシンの形式として定義する変形をサポートします。これにより、リゾルバー内部でデータベース照会や外部サービス呼び出しなどの副作用処理を行うことができます。

注意点:

defresolver

で定義された状態関数は、通常の

biff.fx

マシンとは異なり、1 つではなく **2 つのパラメータ（

ctx

と

input

）**を受け取ることに注意してください。

---

biff.core との統合

(com.biffweb.graph/module)

をモジュールに含んでいる場合：

• 他のモジュール上に

  :biff.graph/resolvers

  ベクトルを備えたリゾルバーを配置できます。
• アプリケーションスキーマを

  com.biffweb.core/register

  で登録した場合は、

  biff.graph

  がリゾルバー出力がそのスキーマに適合していることを保証します。

ヒントとベストプラクティス

1. ファイル構成: リゾルバーを

   model/

   配下に配置し、各ネームスペースが

   :biff.graph/resolvers

   を設定した

   biff.core

   モジュールを公開します。
2. UI コンポーネント: hiccup を返すリゾルバーを作成することも可能です（例：ボタンやモーダルなど）。これらを

   ui_components/

   配下に配置し、特定のデータモデル向けの再利用可能なコンポーネントとします。

   (defresolver ... {:com.example/my-component (fn [{:keys [href]}] [:div ...])})
   

3. グローバルリゾルバー: インプットクエリを持たない「グローバル」リゾルバーもあります。
   • 特定の条件を満たす全ユーザーを照会したいバックグラウンドジョブ用。

   • ctx

     から明示的な ID が不要なセッションデータ返信用。
4. 認証（パラムス）: パラメータからエンティティ ID を受け取り、権限確認を行いジョインとして返すリゾルバーを作成します。

   :output [{:params/widget [:widget/id]}]
   

   • 無権限の場合：例外を投げるか、出力からエンティティを省略するかのいずれかを選択可能です（HTTP 4XX への転換方法を探求中）。