React Query Builderを読む：条件式を編集可能なReact部品へ落とし込む

QueryBuilderが担う条件式の編集

React Query Builderは、Reactアプリケーションへ条件式の編集UIを追加するTypeScript製コンポーネントです。READMEは本体を完全にカスタマイズ可能なクエリビルダーと説明し、SQL、MongoDBなど複数のクエリ言語へのインポートとエクスポートを行うユーティリティも同じリポジトリに置いています。デモと完全な文書はreact-querybuilder.js.orgから参照できます。

条件式を画面で組み立てる場合、利用者の入力とサーバーが実行するクエリを分けて扱います。QueryBuilderが編集状態を返しても、その状態を直接SQLやMongoDBへ連結して実行することが安全だとは限りません。フィールド、演算子、値の型、許可する組合せをサーバー側で検証し、実行権限と取得件数を制限する設計が必要です。READMEはデータベース権限やクエリ安全性の保証を説明していません。

この部品が適するのは、検索条件を利用者が追加、削除、入れ子化する画面です。固定された検索欄だけで足りる画面や、複雑な業務フロー全体をクエリビルダーへ置き換える用途は、素材から適合性を判断できません。条件式の表現と実行の責任境界を最初に決めることが、導入範囲を誤らないための前提です。

最小構成は状態と標準スタイルを結ぶ

READMEの最小例では、react-querybuilderからQueryBuilderを読み込み、react-querybuilder/dist/query-builder.cssまたは.scssを読み込みます。useStateでquery状態を持ち、combinatorをand、rulesを空配列にした初期値をdefaultQueryへ渡します。変更時にはonQueryChangeへsetQueryを渡し、画面の条件をReact状態へ戻します。

この例が示すのは、条件データを親コンポーネントが所有する制御に近い使い方です。初期条件、編集後の状態、保存や送信のタイミングをアプリ側で管理できます。複数画面で同じ条件を共有するなら、状態の保存形式と版を決め、古い条件を新しいフィールド定義へ変換する処理を別に用意します。READMEの最小例は入力と表示の入口であり、永続化形式や権限モデルを定めるものではありません。

本体のREADME、完全なIntroduction、example projectsが追加の入口です。どのプロパティが変更可能か、独自フィールドや演算子をどう定義するか、エラーをどう表示するかは完全な文書で確認します。スタイルシートを読み込んだだけで既存デザインへ適合するとは限らないため、キーボード操作、画面幅、長いフィールド名、エラー表示を自分のUIで検証します。

クエリ言語への変換とデータ境界

React Query Builderには、条件式をSQL、MongoDBなどへ出力するユーティリティと、既存のクエリ言語から取り込むユーティリティがあります。インポートを使えば外部条件を編集可能な状態へ変換し、エクスポートを使えば画面で作った条件を別処理へ渡せます。変換対象の言語と仕様は公式のutils/import、utils/export文書で確認します。

SQLとMongoDBでは、演算子、文字列、日付、配列、NULL、入れ子条件の意味が異なります。同じ画面状態でも、言語ごとに表現できる条件や型が一致しない場合があります。変換不能な条件を黙って削除したり、文字列へ変換したりすると、利用者の意図と実行結果がずれます。インポート後の条件数、演算子、型、出力差分を確認し、変換不能状態を利用者へ返す設計が必要です。

出力されたクエリは、実行前に許可済みのフィールドと演算子へ照合します。テーブル名、コレクション名、並び順、取得件数、結合条件をUI入力から自由に作らせる場合は、クエリビルダーの責任範囲を越えたサーバー設計が必要です。READMEは変換ユーティリティを説明しますが、認証、SQLインジェクション対策、実行計画、性能、データ機密性を保証する資料ではありません。

機能パッケージで編集操作を分割する

READMEは、本体に加えて四つの機能パッケージを案内しています。@react-querybuilder/dndはドラッグアンドドロップ、@react-querybuilder/datetimeは日時処理、@react-querybuilder/exprはルール内の式、@react-querybuilder/rules-engineはif-then-elseのルールエンジンを担います。機能を別パッケージへ分けることで、必要な処理だけを追加する構成を考えられます。

ドラッグ操作はマウスだけでなく、キーボード、タッチ、支援技術、移動後の順序表示を確認します。日時条件はタイムゾーン、夏時間、日付だけの値、時刻付きの値を区別します。式とif-then-elseを許可する場合は、計算可能な項目、再帰の深さ、実行コスト、エラー時の表示を制限します。READMEはパッケージの役割を示していますが、業務データへ安全に適用する規則は利用側で設計します。

追加パッケージを使うときは、コア本体との版対応、依存関係、型定義、CSS、ビルド設定を固定します。ドラッグ操作だけを後から追加しても、条件JSONの保存形式が変わるとは限りませんが、日付や式の追加はサーバー側の変換と検証へ影響します。機能単位で導入し、既存条件の読み込みと新規条件の保存を個別に比較するのが現実的です。

公式互換パッケージとReact Native

このリポジトリは、メインのreact-querybuilderに加えて、複数のUIライブラリ向け公式互換コンポーネントをホストしています。対象はAnt Design、Bootstrap、Bulma、Chakra UI、Fluent UI、Mantine、MUI、PrimeReact、Tremorです。React Native向けの@react-querybuilder/nativeもあります。

互換パッケージは、アプリケーションの既存デザインや入力部品へ合わせる候補になります。ただし、UIライブラリ名が一致しても、テーマ、バージョン、フォーム管理、アクセシビリティ、SSR、スタイル注入の条件はプロジェクトごとに違います。各パッケージの公開版とReactの対応を確認し、QueryBuilderの表示、選択欄、演算子、値入力、グループ操作を実際のテーマで確認します。

React Nativeでは、WebのCSSやマウス操作をそのまま使えません。画面幅、キーボード、タッチ操作、スクロール、モーダル、日付入力を別のUIとして評価します。READMEはReact Nativeコンポーネントの存在を示しますが、iOSとAndroidの表示差、支援技術、性能、オフライン保存を詳細には説明していません。Web版で動くことをモバイル版の合格根拠にしないことが必要です。

旧版とRAQBからの移行判断

READMEには、react-querybuilderの以前の版から移行するためのversion migration guideと、react-awesome-query-builder、通称RAQBから移行するRAQB migration guideへのリンクがあります。移行対象を決めたら、まず既存条件のJSON、独自フィールド、演算子、表示文言、SQLやMongoDB出力を保存します。

移行試験では、空条件、単一条件、複数条件、入れ子グループ、日付、配列、NULL、式、既存クエリの取り込みを代表データにします。旧版と新版で画面が同じに見えても、条件JSONのキー、組合せ順、演算子名、出力クエリ、エラー表示が変わっている可能性があります。保存した旧条件を新コンポーネントで開き、再保存した結果を差分比較してください。

RAQBからの移行では、旧部品の機能とQueryBuilderのデータモデルを一対一で対応させられるとは限りません。変換できない機能は削除せず、利用者へ未対応として示し、手動修正の手順を用意します。READMEは移行ガイドの存在を示すだけで、個別プロジェクトの成功、変換率、停止時間、サポート期間を保証していません。移行完了後も旧形式のバックアップと復元手段を残します。

開発、品質確認、ライセンスの境界

開発手順についてREADMEはCONTRIBUTING.mdを参照しています。CI、codecov、デモ、Discord、npm、ドキュメントのリンクがバッジとして示され、リポジトリはTypeScriptで書かれています。リリース情報は素材のメタデータにあり、最新版はv8.23.1、デフォルトブランチはmain、アーカイブ済みではありません。

利用側の品質確認では、条件入力、状態更新、保存、再読込、インポート、エクスポート、エラー、キーボード、画面幅、UI互換パッケージを分けて確認します。生成されたSQLやMongoDBの文字列は、許可済みの構文と値へサーバー側で検証します。デモが表示されたこと、CIバッジが存在すること、スター数があることは、自社データの安全性や性能を証明しません。

ライセンスはMITです。著作権表示と許可表示を含める条件で、利用、複製、変更、統合、公開、配布、サブライセンス、販売が認められます。ソフトウェアは現状のまま提供され、保証や保守の約束はライセンス本文から読み取れません。コア、互換パッケージ、依存UIライブラリ、React Native部品の条件を分けて確認し、配布物の通知を整えます。

条件検索画面を本番へ置く前に

採用前の第一段階では、利用者が作る条件を列挙します。対象フィールド、型、演算子、ANDとOR、入れ子、日付、式、ルール分岐、並び順、件数制限、保存可否を決め、QueryBuilderの状態へ対応させます。第二段階では、出力先をSQL、MongoDB、別の検索APIのどれにするかを定め、変換不能な条件と未許可の演算子を明示します。

第三段階では、UIを確認します。標準CSS、独自テーマ、公式互換パッケージ、React Nativeの各経路で、追加、削除、移動、値入力、キーボード操作、画面読上げ、狭い画面、長いラベルを確認します。第四段階では、条件JSONを保存して再読込し、版更新後も同じ結果になるかを照合します。変更前の入力、変換結果、実行結果、エラーを記録しておくと、不具合の所在を分けやすくなります。

最後に、サーバー側の認証、フィールド許可、値検証、実行時間、取得件数、監査ログ、個人情報の扱いを決めます。React Query Builderは条件編集の部品であり、データベースの安全な実行層ではありません。READMEの機能説明、公式文書、移行ガイド、ライセンスを根拠として使いながら、本番可否は自社の条件式、データ、権限、復旧手順で判断してください。

条件式の監査では、利用者の役割ごとに作成、保存、共有、実行、削除の権限を分けます。共有された条件を別の利用者が開いたとき、存在しないフィールドや利用禁止の演算子があれば、実行前に明示します。日付の基準時刻、数値の小数、文字列のエスケープ、空値の意味を固定し、画面表示とサーバー解釈が一致するかを確認します。

変換差分は、人間が読める条件表示と実行用クエリの双方で保存します。インポートしたSQLやMongoDB条件が元の条件と同じ意味か、エクスポート後に不要な条件が消えていないか、入れ子のANDとORが反転していないかを代表例で照合します。変換不能な箇所は警告として記録し、利用者の確認なしに近い意味の条件へ置き換えません。

復旧確認では、条件JSON、フィールド定義、演算子定義、UI版、互換パッケージ版、サーバー変換版を同じ履歴へ残します。版更新後に旧条件を開き、表示、再保存、SQL出力、MongoDB出力、実行権限、監査ログを確認します。問題があれば旧版と旧変換処理へ戻せるようにし、管理画面の成功表示だけを本番採用の根拠にしないでください。

条件の保存には、作成者、更新者、作成日時、更新日時、対象データ範囲を記録します。共有条件の変更が他の利用者の検索結果を変える場合は、変更前後の差分と承認者を残します。大量取得や高負荷の条件には、件数上限、実行時間制限、ページングを設定し、利用者へ処理範囲を知らせます。サーバーで許可されない条件を画面から隠すだけでなく、受信時にも拒否します。監査担当者は定期的に保存条件と実行結果を照合し、不要な権限と古い条件を整理します。監査記録は必要期間だけ保管し、権限変更時には再承認します。利用者への説明責任と監査責任を明確に分担します。

編集部の結論

React Query Builderは、利用者が複数条件を組み立てる検索画面、管理画面、レポート画面をReactへ組み込みたい開発者に向いています。QueryBuilder本体は完全にカスタマイズ可能と説明され、SQLやMongoDBなどへのインポート・エクスポート、Ant DesignやMUIなどの公式互換パッケージ、ドラッグ操作や日時処理を補う機能パッケージがあります。一方、生成されたクエリの安全性、データベース権限、入力値の検証、各UIライブラリとの版互換性は利用側の責任です。導入前に必要な条件式、出力言語、UI、権限、サーバー側検証を実データで確認してください。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes