ElasticsearchのためのLuceneクエリ入門ガイド

Elasticsearch を使っていると、クエリ記述には KQL や ES|QL、Query DSLなどいくつかの書き方が登場します。しかし、そのすべての下で動いているのは Apache Lucene の検索エンジンです。

Luceneを「高性能なエンジン」だとすれば、Elasticsearchはそのエンジンを搭載した「高級車」のようなものです。Lucene を一言でいうと、テキストを検索しやすい形に変えて、素早く答えてくれるエンジンです。

この記事では、Kibanaにデフォルトで入っているKibana Sample Data Logsを使い、Lucene クエリの基本とよく使う構文を整理します。

Luceneモードへの切り替え

Kibanaの検索バーは現在、デフォルトでKQL (Kibana Query Language) になっています。この記事で紹介するクエリ（特に ~ を使う近接検索や TO を使う範囲指定）を正しく動作させるには、以下の手順でモードを切り替えてください。

検索のやり方として２つあります。

フリーテキスト検索を実行するには、テキスト文字列を入力するだけです。たとえば、Web サーバーのログを検索する場合、safari と入力してすべてのフィールドを検索できます。

特定のフィールドが特定の値と一致するものを探します。

クエリ	説明
response: 404	ステータスコードが 404 のログのみを検索します。
machine.os: “win 8”	OSが “win 8” というフレーズと完全に一致するものを検索します。
geo.src: US -geo.dest: US	アクセス元がアメリカで、かつ目的地がアメリカではないものを検索します（マイナス記号 – は除外を意味します）。

文字の一部が不明な場合や、パターン検索に使用します。

クエリ	説明
agent: Mozilla*	User Agentが “Mozilla” で始まるすべてのログを検索します。
extension: d*	拡張子が “d” で始まるファイル（debなど）へのアクセスを検索します。
referer: twitter	リファラー（参照元URL）の中間に “twitter” が含まれるログを検索します。

⚠️ 注意: 先頭に * を置く検索（例： *name ）は、全インデックスを走査するため非常に遅くなる可能性があり、推奨されません。

2つの単語が互いに指定した距離（単語数）以内で出現するドキュメントを探します。

クエリ	説明
“beats HTTP”~4	メッセージ内で “beats” と “HTTP” が 4単語以内の距離にあるものを検索します。単なるAND検索よりも文脈の強いつながりを見つけられます。

数値や日付の範囲を指定します。

クエリ	説明
bytes: [10000 TO *]	転送量が 10,000バイト以上のログを検索します（* は上限なし）。
response: [500 TO 599]	ステータスコードが 500番台 (サーバーエラー) の範囲にあるログを検索します。
bytes: {0 TO 100}	転送量が0より大きく100未満を検索します。[] は境界値を含み（以上・以下）、{} は境界値を含みません（より大きい・より小さい）。

スペルミスや表記ゆれを許容して検索します。

クエリ	説明
index:kibana_smple_dat_logs	スペルミスを許容して検索します（例: “kibana_sample_data_logs” にヒットします）。
index:kibana_smple_dat_logs~1	1文字違いまで許容します（例: 1文字までなのでkibana_sample_data_logsにヒットしません）。

💡 ポイント: ~ は単語の後ろにつけるとFuzzy（roan~）、フレーズの後ろにつけるとProximity（”foo bar”~4）として機能します。

特定の条件に合致するドキュメントの検索スコア（関連度）を高くします。

クエリ	説明
response:404^2 OR response:503	404エラーの重要度（スコア）を2倍にして検索します。関連度順に並べた際、404エラーの方が上位に来やすくなります。

複雑な条件を組み合わせます。Lucene の演算子（AND, OR, NOT）は 大文字 が必須です。小文字にすることで、特定の文字が演算子としてではなく、単語として認識されます。

クエリ	説明
NOT response: 200	ステータスコードが 200 (成功) ではない (=エラーやリダイレクト) ログをすべて表示します。
geo.src: US AND response: 404	アメリカからのアクセスかつ 404エラーだったログを検索します。
(extension: rmp OR extension:deb) AND geo.dest:GB	グループ化: 「拡張子がrmpかdeb」という条件を優先し、かつイギリスからのアクセスであるものを検索します。

Luceneクエリが思ったように動かない場合、以下の原因が考えられます。

KeywordフィールドでのFuzzy検索: keyword 型のフィールドは解析（Analyzer処理）されないため、Fuzzy検索（~）が効きません。
句読点や記号の消失: データ取り込み時に Standard Analyzer を通っている場合、記号が削除されていることがあります。「検索できない」と思ったら、元のテキストがどうトークン化されているか確認が必要です。
特殊文字のエスケープ: + – && || ! ( ) { } [ ] ^ ” ~ * ? : \ などの文字を検索値として含める場合は、直前にバックスラッシュ \ を置いてエスケープする必要があります（例：file_name:report\-2025\.pdf）。