トラス構造が幾何学的に組まれた建築物のファサード
現場の実践

Meilisearch導入で検索が無言で0件になる落とし穴と対策

目次を見る

検索エンジンを別サービスに切り出したあと、エラーも出ないのに検索結果だけが空になる障害を見たことはないでしょうか。

この記事は、Laravel(PHPのWebアプリケーションフレームワーク)とScout(Laravel公式の全文検索抽象化レイヤー)、Meilisearch(オープンソースの高速検索エンジン)を使って検索機能をDB内蔵からミドルウェア化する構成を運用・監視する立場の方に向けた内容です。フェイルオーバー設計はしたのに、なぜか本番でだけ検索結果がゼロ件になる、という障害の原因と確認手順を整理しました。

何が起きるか:エラーなしで検索結果だけが消える

典型的な事象は、検索ボックスに何を入力しても候補が1件も出ない、というものです。

サーバーログにはエラーが記録されません。HTTPステータスも200(正常)が返ります。例外(try/catchで捕まえられる異常終了)も発生しないため、通常のアラート監視では検知できません。ユーザーからの「検索が使えない」という問い合わせで初めて気づくケースが多いパターンです。

影響範囲は、フィルタ条件(たとえば「在庫あり」「公開中」などのstatus絞り込み)を使っている検索エンドポイント全体に及びます。単純なキーワード検索は動くのに、条件付き検索だけが沈黙する、という切り分けづらい症状になります。

なぜ起きるか:フィルタ対象フィールドが索引に入っていない

原因を段階的に分解します。

まず前提として、MeilisearchでWHERE句的な絞り込み(filterable attributes、フィルタ可能な属性)を使うには、2つの条件が別々に満たされている必要があります。1つ目は「このフィールドはフィルタに使える」という設定、2つ目は「そのフィールドの値が実際に索引データの中に存在する」という実データの状態です。

1つ目の設定を忘れると、Meilisearchは「invalid_search_filter」というエラーを返します。これは例外として検知できるので、監視の網にかかりやすい失敗です。

問題は2つ目です。設定上はフィルタ可能だと宣言されているのに、実際にインデックス(検索用に整形されたデータの集合)へ投入するデータ(Laravelでは「toSearchableArray()」というメソッドが返す配列)にそのフィールドが含まれていない場合があります。この場合、Meilisearchは「フィルタ条件に一致するドキュメントが0件でした」という、構文的には正しい応答を返します。例外は一切発生しません。

さらに厄介なのは、フェイルオーバー(障害時に代替手段へ切り替える仕組み)を実装していても、この障害を救えないという点です。try/catchでMeilisearchの例外を捕まえてDBクエリにフォールバックする設計にしていても、Meilisearch自体は「正常に0件を返した」だけなので、catchブロックは発火しません。フォールバックは例外からしか守ってくれない、という設計上の盲点です。

自分のプロジェクトが該当するか確認する方法

以下の手順で、自分の環境が同じ落とし穴にはまっていないか確認できます。

# 1. Scoutの設定でフィルタ可能属性が定義されているか確認
cat config/scout.php | grep -A 10 "index-settings"

# 2. モデルのtoSearchableArray()が返すキーを確認
# app/Models/配下の対象モデルを開き、toSearchableArray()の
# 戻り値にフィルタ対象のカラム(status等)が含まれているか目視確認

# 3. 実際にMeilisearchへ投入済みのドキュメントを直接確認
curl -X GET 'http://127.0.0.1:7700/indexes/<インデックス名>/documents?limit=1' \
  -H 'Authorization: Bearer <マスターキー>'

手順3が最も重要です。設定ファイルを読むだけでは「設定は正しいはず」としか分かりません。インデックスに実際に入っているドキュメントの中身を1件取り出し、フィルタに使っているキーが存在するかを目で確認する必要があります。

あわせて、Meilisearchのダッシュボードやログで「filterableAttributes」が空配列になっていないかも見ておきましょう。デフォルトでは空のため、設定し忘れたまま運用しているケースも十分あり得ます。

バージョンについても確認が必要です。Meilisearchは開発が活発で、v1.10前後でもフィルタ関連の挙動やエラーメッセージに差分があります。「docker-compose.yml」のイメージタグ、またはMeilisearchの管理画面やAPIの「/version」エンドポイントでバージョンを控えておくと、障害調査時の切り分けが早くなります。

対策の手順

対策は大きく3段階に分けて進めます。

1. インデックス再構築とスキーマの突き合わせ

フィルタに使う全フィールドを「toSearchableArray()」に含め、「scout:sync-index-settings」を実行してから、「scout:import」でインデックスを作り直します。設定変更後の再インデックスは必須で、設定だけ変えてデータを入れ直さないと反映されません。

php artisan scout:sync-index-settings
php artisan scout:import "App\Models\対象モデル"

2. 「0件は正常応答である」ことを前提にした監視を追加

例外監視だけでは今回のパターンを検知できません。既知の検索語(たとえば在庫がある前提のキーワード)で定期的に検索APIを叩き、結果件数が0件なら警告を出す合成監視(synthetic monitoring)をCronやヘルスチェックに組み込みます。レスポンスタイムだけでなく「意味のある件数が返っているか」まで見る監視設計が必要です。

3. フォールバックの境界を明示する

try/catchによるDBフォールバックは「Meilisearchが落ちている・応答しない」場合の保険であり、「Meilisearchが正常応答として0件を返す」場合は救えません。この境界をコードコメントや運用手順書に明記し、障害対応時に「フォールバックがあるから大丈夫」という誤認を防ぎます。短いタイムアウト設定と合わせて、障害モードを「接続不可」「タイムアウト」「0件応答」の3種類に分けて把握しておくと、障害対応の初動が早くなります。

公開APIとして検索エンドポイントを出している場合は、合わせてレート制限(たとえば1クライアントあたり毎分30リクエストなど)と、返却フィールドの最小化も見直しておくと安心です。検索候補エンドポイントは認証なしで叩けることが多く、予約情報や顧客情報など非公開データが紛れ込んでいないかの棚卸しも兼ねて確認しておく価値があります。

まとめ

検索エンジンを外部サービス化するときの監視設計で押さえておきたい点を整理します。

  • 例外監視だけでは「正常に0件を返す」障害を検知できないため、結果件数を見る合成監視を別途用意する
  • フィルタ可能属性の設定変更後は、必ず再インデックスまで実行し、片方だけで終わらせない
  • フォールバック(DB代替クエリ)が守ってくれるのは例外発生時のみで、応答として返る0件は守備範囲外と理解しておく
  • 本番障害調査の第一歩として、インデックス内のドキュメントを1件直接取得し、フィルタ対象フィールドの有無を目視確認する習慣をつけておく

まずは自分の環境で「toSearchableArray()」の戻り値と、実際にMeilisearchへ入っているドキュメントの中身を突き合わせるところから始めてみてください。

参考

Laravel Scout and Meilisearch: fast search that keeps working when the engine is down

AI 駆動開発のご相談は forva AI へ。

まずはお気軽にどうぞ。