implementing-search-filter

検索とフィルタリングの実装

包括的なフロントエンドコンポーネントとバックエンドのクエリ最適化により、検索・フィルタリングのインターフェースを実装します。

目的

このスキルでは、フルスタックにわたって検索・フィルタリング機能を実装するための、本番環境で利用できるパターンを紹介します。フロントエンド向けのReact/TypeScriptコンポーネント（検索入力、フィルターUI、自動補完）と、バックエンド向けのPythonパターン（SQLAlchemyクエリ、Elasticsearch連携、API設計）を扱います。パフォーマンスの最適化、アクセシビリティ、ユーザーエクスペリエンスを重視します。

使用する場面

• カテゴリーや価格フィルターを備えた商品検索を構築する
• 自動補完／タイプアヘッド検索を実装する
• 動的な件数表示を備えたファセット検索インターフェースを作成する
• データテーブルやリストに検索機能を追加する
• 上級ユーザー向けの高度なブール検索を構築する
• SQLAlchemyまたはDjango ORMでバックエンド検索を実装する
• 全文検索にElasticsearchを連携する
• デバウンスやキャッシュによって検索パフォーマンスを最適化する
• アクセシブルな検索エクスペリエンスを作成する

主なコンポーネント

フロントエンドの検索パターン

デバウンス付き検索入力

• パフォーマンス向上のため、300msのデバウンスを実装する
• 検索中に読み込み状態を表示する
• リセット用のクリアボタン（X）を設ける
• キーボードショートカット（Cmd/Ctrl+K）を用意する
• references/search-input-patterns.mdを参照してください

自動補完／タイプアヘッド

• キーボード操作に対応した候補のドロップダウンを表示する
• 候補内で一致したテキストを強調表示する
• 最近の検索と人気の項目を表示する
• デバウンスによってリクエストの集中を防ぐ
• references/autocomplete-patterns.mdを参照してください

フィルターUIコンポーネント

• 複数選択にはチェックボックスフィルターを使用する
• 数値には範囲スライダーを使用する
• 単一選択にはドロップダウンフィルターを使用する
• 選択中の項目を示すフィルターチップを表示する
• references/filter-ui-patterns.mdを参照してください

バックエンドのクエリパターン

データベースクエリの構築

• SQLAlchemyで動的にクエリを構築する
• Django ORMのフィルターチェーンを使用する
• 検索対象の列にインデックスを最適化して設定する
• PostgreSQLで全文検索を行う
• references/database-querying.mdを参照してください

Elasticsearch連携

• ドキュメントのインデックス戦略
• 複雑な検索に対応するQuery DSL
• ファセット集計
• 関連度スコアリングとブースティング
• references/elasticsearch-integration.mdを参照してください

API設計

• RESTfulな検索エンドポイント
• クエリパラメーターの検証
• カーソルまたはオフセットによるページネーション
• レスポンスのキャッシュ戦略
• references/api-design.mdを参照してください

実装ワークフロー

クライアントサイド検索（1000件未満）

1. データをメモリに読み込む
2. JavaScriptでフィルター関数を実装する
3. テキスト入力にデバウンス付き検索を適用する
4. 結果を即座に更新する
5. Reactでフィルターの状態を維持する

サーバーサイド検索（1000件超）

1. 検索APIエンドポイントを設計する
2. クエリパラメーターを検証してサニタイズする
3. データベースクエリを動的に構築する
4. ページネーションを適用する
5. メタデータとともに結果を返す
6. 頻繁に実行されるクエリをキャッシュする

ハイブリッド方式

1. すぐに結果を反映するため、クライアントサイドのフィルタリングを使用する
2. バックグラウンドでサーバーの結果を取得する
3. 結果を統合して重複を除去する
4. UIを段階的に更新する
5. 最近の検索をローカルにキャッシュする

パフォーマンスの最適化

フロントエンドの最適化

デバウンスの実装

• lodashのdebounceまたは独自の実装を使用する
• 新しい入力があったら保留中のリクエストをキャンセルする
• データ取得中にスケルトンローダーを表示する
• スクリプト：scripts/debounce_calculator.js

クエリパラメーターの管理

• 共有可能な検索にするため、フィルターをURLと同期する
• URLの状態管理にReact RouterまたはNext.jsを使用する
• 複雑なクエリを圧縮する
• references/query-parameter-management.mdを参照してください

バックエンドの最適化

クエリの最適化

• 適切なデータベースインデックスを作成する
• クエリアナライザーを使用してボトルネックを特定する
• クエリ結果のキャッシュを実装する
• スクリプト：scripts/generate_filter_query.py

検証とセキュリティ

• すべての検索入力をサニタイズする
• SQLインジェクションを防止する
• 検索エンドポイントにレート制限を設定する
• スクリプト：scripts/validate_search_params.py

アクセシビリティ要件

ARIA パターン

• 検索領域には role="search" を使用します
• 検索結果の更新には aria-live を実装します
• フィルターには明確なラベルを付けます
• キーボードのみでのナビゲーションに対応します

キーボード操作

• すべての操作可能な要素を Tab キーで移動します
• オートコンプリートの移動には矢印キーを使用します
• Escape キーでドロップダウンを閉じます
• Enter キーで選択または送信します

技術スタック

フロントエンドライブラリ

主なライブラリ：Downshift（オートコンプリート）

• アクセシブルなオートコンプリートのプリミティブ
• 柔軟に使えるヘッドレス／スタイルなしの設計
• WAI-ARIA に準拠
• インストール：npm install downshift

代替：React Select

• 多機能な選択／フィルターコンポーネント
• 非同期検索を標準搭載
• 複数選択に対応

バックエンド技術

Python/SQLAlchemy

• 動的なクエリの構築
• リレーションシップ読み込みの最適化
• クエリ結果のページネーション

Python/Django

• Django Filter バックエンド
• Django REST Framework のフィルター
• PostgreSQL による全文検索

Elasticsearch（Python）

• elasticsearch-py クライアント
• クエリ構築用の elasticsearch-dsl

同梱リソース

リファレンス

• references/search-input-patterns.md - 入力の実装
• references/autocomplete-patterns.md - タイプアヘッドのパターン
• references/filter-ui-patterns.md - フィルターコンポーネント
• references/database-querying.md - SQL クエリのパターン
• references/elasticsearch-integration.md - Elasticsearch のセットアップ
• references/api-design.md - API エンドポイントのパターン
• references/performance-optimization.md - パフォーマンスの最適化に関するヒント
• references/library-comparison.md - ライブラリの評価

スクリプト

• scripts/generate_filter_query.py - SQL/ES クエリを構築
• scripts/validate_search_params.py - 入力を検証
• scripts/debounce_calculator.js - デバウンスのタイミングを計算

例

• examples/product-search.tsx - E コマースの検索
• examples/autocomplete-search.tsx - オートコンプリートの実装
• examples/sqlalchemy_search.py - SQLAlchemy のパターン
• examples/fastapi_search.py - FastAPI の検索エンドポイント
• examples/django_filter_backend.py - Django のフィルター

アセット

• assets/filter-config-schema.json - フィルター設定
• assets/search-api-spec.json - OpenAPI 仕様