Spring BootでElasticsearchの特定インデックスから必要なフィールド取得

Spring BootとElasticsearchの組み合わせは、リアルタイム検索機能やログ分析機能を構築する際に非常に強力です。しかし、Elasticsearchを初めて扱う開発者の多くが直面する課題の一つが、「特定のインデックスから必要なフィールドだけをどのように取得するか？」という疑問です。

本記事では、Elasticsearchの_sourceフィルタリング機能を活用し、Spring Bootアプリケーションから@timestamp、message、agent.idなど、必要なフィールドだけを効率よく取得する方法について詳しく解説します。さらに、パフォーマンス向上やレスポンスサイズの削減、Javaコードの構造化についてもベストプラクティスを交えて紹介します。

目次

• なぜElasticsearchでフィールド選択が重要なのか？
• Spring BootとElasticsearchの基本設定
• _sourceフィールドフィルタリングの仕組み
• Spring Data Elasticsearchで特定フィールドのクエリを実装する
• @timestamp, message, agent.idを取得するコード例
• パフォーマンス最適化のポイント
• よくある問題とその対処法
• まとめ：目的に合ったクエリ設計が拡張性を生む

なぜElasticsearchでフィールド選択が重要なのか？

Elasticsearchは、検索クエリに対して通常、対象ドキュメント全体を返します。しかし、実際のアプリケーションにおいて、すべてのフィールドが常に必要とは限りません。例えば、ログを画面に表示する際には、@timestamp、message、agent.idなど一部の情報のみが必要なケースが多いでしょう。

必要なフィールドだけを取得することにより、以下のような利点が得られます：

• ネットワーク負荷の軽減：データ転送量が減るため、レスポンスが早くなります。
• 応答速度の向上：Elasticsearch側の処理負荷も減少します。
• アプリケーションのメモリ使用量削減：不要なフィールドの処理が不要になります。

このようなフィールド選択を可能にするのが、Elasticsearchの_sourceフィールドです。次のセクションでは、Spring BootとElasticsearchの接続設定について詳しく見ていきましょう。

Spring BootとElasticsearchの基本設定

Spring BootアプリケーションからElasticsearchに接続するためには、いくつかの設定が必要です。Spring Data Elasticsearchを使用することで、ネイティブクエリをJavaコード上で簡単に構築・実行することができます。このセクションでは、必要な依存関係の追加、接続設定、動作確認方法について説明します。

1. 依存関係の追加

GradleやMavenのビルドファイルに以下の依存関係を追加してください（Mavenの場合）：

  org.springframework.boot
  spring-boot-starter-data-elasticsearch

使用するSpring BootとElasticsearchのバージョンが互換性のある組み合わせであることを事前に確認しましょう。バージョン不整合はよくあるトラブルの原因です。

2. 接続情報の設定

接続情報はapplication.ymlまたはapplication.propertiesに記述します。以下はapplication.ymlの例です：

spring:
  data:
    elasticsearch:
      client:
        reactive:
          endpoints: localhost:9200

Elastic Cloudや認証付き接続を使用する場合は、追加でusername、password、sslなどの設定も必要になります。

3. 接続確認

設定が完了したら、Spring Bootアプリケーションを起動し、Elasticsearchに正しく接続できているかを確認しましょう。以下のコードでインデックスの存在確認が可能です：

@Autowired
private ElasticsearchOperations elasticsearchOperations;

@PostConstruct
public void checkIndex() {
    boolean exists = elasticsearchOperations.indexOps(IndexCoordinates.of("log-index")).exists();
    System.out.println("インデックス 'log-index' の存在: " + exists);
}

これでSpring BootとElasticsearchの連携が整いました。次のセクションでは、Elasticsearchにおける_sourceフィールドの基本と、そのフィルタリング機能について詳しく解説します。

_sourceフィールドフィルタリングの仕組み

Elasticsearchの_sourceフィールドは、インデックスに保存されたドキュメントの元のJSON構造を保持する特別なメタフィールドです。通常、クエリを実行すると、この_source全体がレスポンスとして返されますが、_sourceフィルタリングを使えば、必要なフィールドだけを指定して取得することができます。

1. _sourceフィールドとは？

Elasticsearchにデータを登録する際、元のJSONドキュメントは_sourceフィールドに保存されます。検索クエリの中で_sourceオプションを使うと、レスポンスに含めたいフィールドを明示的に制御することが可能です。

以下は、@timestamp、message、agent.idのみを取得するシンプルなクエリの例です：

GET /log-index/_search
{
  "_source": ["@timestamp", "message", "agent.id"],
  "query": {
    "match_all": {}
  }
}

このようにすることで、不要なデータを排除し、ネットワーク帯域やメモリ使用量を抑えることができます。

2. includes / excludesの活用

_sourceでは、includesやexcludesといったパラメータを使って、取得するフィールドや除外するフィールドを細かく指定することもできます。

GET /log-index/_search
{
  "_source": {
    "includes": ["@timestamp", "message", "agent.id"],
    "excludes": ["host.name"]
  },
  "query": {
    "match_all": {}
  }
}

特に大きなログや不要なメタデータが含まれている場合、これらのパラメータは非常に有効です。

3. ネストされたフィールドに注意

agent.idのようなフィールドは、オブジェクトやネスト構造の中に存在する場合があります。Elasticsearchでは、正確なパス（たとえばagent.id）を指定しなければ、正しく値を取得できません。

以下のようなJSON構造の場合：

{
  "@timestamp": "2025-04-01T12:00:00Z",
  "message": "ログイン成功",
  "agent": {
    "id": "xyz789",
    "name": "filebeat"
  }
}

agent.idと明示的にパスを指定することで、ネスト構造でも正しく値を取得できます。次のセクションでは、これらの概念をSpring Bootのコード上でどのように実装するかを詳しく紹介します。

Spring Data Elasticsearchで特定フィールドのクエリを実装する

Elasticsearchで_sourceフィルタリングを使用して特定のフィールドだけを取得するためには、Spring Bootアプリケーション内でNativeSearchQueryBuilderとFetchSourceFilterを活用するのが一般的です。このセクションでは、フィールド指定クエリの作成から、実行・DTOマッピングまでのステップを解説します。

1. NativeSearchQueryBuilderを使ったクエリ構築

以下のコードでは、@timestamp、message、agent.idのみを含むクエリを構築しています：

NativeSearchQuery searchQuery = new NativeSearchQueryBuilder()
    .withQuery(QueryBuilders.matchAllQuery())
    .withSourceFilter(new FetchSourceFilter(
        new String[] { "@timestamp", "message", "agent.id" },
        null
    ))
    .build();

このクエリは、内部的にElasticsearchに対して先述したJSON構造と同じ形式で送信されます。

2. ElasticsearchOperationsによるクエリ実行

上記で作成したクエリは、ElasticsearchOperationsまたはElasticsearchRestTemplateで実行できます。以下はElasticsearchOperationsを用いた例です：

@Autowired
private ElasticsearchOperations elasticsearchOperations;

SearchHits<LogDocument> hits = elasticsearchOperations.search(
    searchQuery,
    LogDocument.class,
    IndexCoordinates.of("log-index")
);

List<LogDocument> results = hits.stream()
    .map(SearchHit::getContent)
    .collect(Collectors.toList());

この処理により、必要なフィールドのみがLogDocumentオブジェクトにマッピングされて取得されます。

3. DTOクラスの定義

JavaのDTOクラスでは、対象となるフィールドのみを定義することで、無駄なデータ処理を省くことができます。ドット（.）を含むフィールド名はJavaの変数名として使えないため、@JsonPropertyアノテーションで明示的にマッピングを指定する必要があります。

@Data
public class LogDocument {

    @JsonProperty("@timestamp")
    private String timestamp;

    private String message;

    @JsonProperty("agent.id")
    private String agentId;
}

また、agentがオブジェクト構造である場合は、ネストされたクラスとして表現する方法もあります（詳細は次章にて紹介します）。

次のセクションでは、この構成を活用して実際にAPIとして利用できる形に統合し、完全なコード例として紹介します。

@timestamp、message、agent.idを取得するコード例

ここでは、Spring BootアプリケーションでElasticsearchから@timestamp、message、agent.idの3つのフィールドのみを取得する完全なコード構成を紹介します。DTO、サービス、コントローラーの3層で整理して実装します。

1. DTOクラスの定義

対象フィールドのみを含むシンプルなDTOクラスです。ドット記法のagent.idなどは@JsonPropertyで対応します。

@Data
@NoArgsConstructor
@AllArgsConstructor
public class LogDocument {

    @JsonProperty("@timestamp")
    private String timestamp;

    private String message;

    @JsonProperty("agent.id")
    private String agentId;
}

2. サービスクラスの実装

必要なフィールドだけを抽出するNativeSearchQueryを構築し、Elasticsearchから結果を取得します。

@Service
public class LogSearchService {

    @Autowired
    private ElasticsearchOperations elasticsearchOperations;

    public List<LogDocument> fetchLogFields() {
        NativeSearchQuery query = new NativeSearchQueryBuilder()
            .withQuery(QueryBuilders.matchAllQuery())
            .withSourceFilter(new FetchSourceFilter(
                new String[] { "@timestamp", "message", "agent.id" },
                null
            ))
            .build();

        SearchHits<LogDocument> hits = elasticsearchOperations.search(
            query,
            LogDocument.class,
            IndexCoordinates.of("log-index")
        );

        return hits.stream()
            .map(SearchHit::getContent)
            .collect(Collectors.toList());
    }
}

3. コントローラーの作成

REST APIとしてエンドポイントを公開します。これにより、クライアントアプリケーションやフロントエンドから必要なログ情報のみを取得できます。

@RestController
@RequestMapping("/logs")
public class LogController {

    @Autowired
    private LogSearchService logSearchService;

    @GetMapping("/fields")
    public ResponseEntity<List<LogDocument>> getFilteredLogs() {
        List<LogDocument> logs = logSearchService.fetchLogFields();
        return ResponseEntity.ok(logs);
    }
}

この構成により、/logs/fieldsエンドポイントにアクセスすることで、Elasticsearchのlog-indexから指定された3つのフィールドのみを含むレスポンスを取得することができます。次の章では、このような実装がパフォーマンスにもたらすメリットと、実際の最適化ポイントについて詳しく見ていきます。

パフォーマンス最適化のポイント

Elasticsearchの検索において、不要なフィールドを除外し、必要なデータだけを取得することは、単なる美学ではなく実用的なパフォーマンス最適化手法です。このセクションでは、なぜフィールドの選択が重要なのか、そしてどのようにシステム全体の効率性に寄与するのかを具体的に解説します。

1. 軽量なレスポンスは高速なアプリケーションを実現する

取得するフィールドが少ないほど、Elasticsearchのレスポンスサイズは小さくなります。それによりネットワーク帯域の使用量が抑えられ、レスポンス速度も向上します。

クエリ方式	レスポンスサイズ	備考
全フィールド取得	約150KB	多くの不要なフィールドを含む
フィールド制限付き取得	約12KB	必要最小限の情報のみ

2. DTOを活用したメモリ使用量の最小化

Javaでは、全フィールドを持つEntityクラスをそのままレスポンスとして返すと、メモリ消費が増え、ガベージコレクションや処理遅延の原因になります。必要なフィールドだけを含むDTO（Data Transfer Object）を用意することで、シリアライズとデシリアライズのコストを削減できます。

3. フィールド型の特性を意識する

Elasticsearchにおけるフィールドの型によって、検索やソート時のパフォーマンスが異なります：

• keyword型：高速なフィルタリングやソートに向いている
• text型：全文検索向けだが、パフォーマンスは劣る
• date型：範囲検索や時系列集計に適している

たとえば、messageフィールドの代わりにmessage.keywordを使うことで、分析処理を回避し、応答速度を高めることができます。

4. サイズの大きなフィールドを除外する

ログのスタックトレースやシステム情報など、サイズの大きなフィールドはレスポンスを肥大化させる主要因です。画面表示や集計に不要な場合は、明示的に除外するようにしましょう。

このような工夫により、Elasticsearchの検索処理は大幅に効率化され、結果としてアプリケーション全体のスケーラビリティとレスポンス性が向上します。次の章では、これまでの実装で開発者がよく遭遇する問題と、それに対する具体的な対処方法を紹介します。

よくある問題とその対処法

ElasticsearchとSpring Bootを連携させてフィールドを限定して取得する際、いくつかの共通した問題に遭遇することがあります。このセクションでは、現場でよく報告されるエラーやトラブルと、その具体的な解決策を紹介します。

1. 「No mapping found for field」エラー

このエラーは、クエリで指定したフィールド名が、Elasticsearchインデックスのマッピングに存在しない場合に発生します。原因としては以下のようなものがあります：

• フィールド名のスペルミス、または大文字・小文字の不一致
• ネストされた構造に対してパス指定が不完全

対処法：

• GET /index/_mappingでマッピング情報を確認する
• ネストされたフィールドはパスを完全に指定する（例：agent.id）

2. FetchSourceFilterが効かず全フィールドが返される

特定フィールドだけを取得するはずなのに、全ドキュメントが返ってくることがあります。主な原因は次の通りです：

• ElasticsearchRepositoryでは_sourceフィルタが反映されない
• Spring Data ElasticsearchのバージョンとElasticsearchの互換性問題

対処法：

• ElasticsearchOperationsまたはRestHighLevelClientを使用する
• 使用中のバージョンが対応しているか公式ドキュメントで確認する

3. ドット付きフィールド（例：agent.id）がJavaで扱えない

Javaではドット（.）を含む変数名は使用できないため、agent.idのようなフィールドはそのままではマッピングできません。

対処法：

• @JsonProperty("agent.id")で明示的にマッピングを指定
• またはネスト構造をJavaクラスでも再現する：

@Data
public class Agent {
    private String id;
}

@Data
public class LogDocument {
    @JsonProperty("@timestamp")
    private String timestamp;

    private String message;

    private Agent agent;
}

4. ネストされたフィールドのフィルタリングがうまく機能しない

object型とnested型はElasticsearchにおいて別物です。ネストされたフィールドが正しく取得できない場合、次のような対処が必要です：

対処法：

• 対象フィールドがnested型である場合は、nested queryを使用する
• _sourceでは完全なパス（例："agent.id"）を指定する

これらの対処法を適切に実践することで、Elasticsearchのフィールド指定取得を安定して運用できるようになります。次の章では、これまでの内容をまとめ、今後の活用のヒントとともに締めくくります。

まとめ：目的に合ったクエリ設計が拡張性を生む

Elasticsearchで必要なフィールドだけを選択的に取得することは、見落とされがちなテクニックですが、システムのパフォーマンスと可用性を大きく左右する重要な設計要素です。

今回の記事では、以下のようなポイントを詳しく解説しました：

• _sourceフィルタリングの基本と実装方法
• Spring BootでのNativeSearchQueryBuilderとFetchSourceFilterの活用
• DTO設計によるパフォーマンスと保守性の向上
• ネスト構造やフィールド名の問題への対処法

「不要なフィールドを返さないことは、必要なユーザー体験を守ることに等しい。」

Elasticsearchを使いこなすということは、単に検索を実行することではなく、最小限で最大限の意味を持つレスポンスを返すための設計力が求められます。

本記事で紹介した手法をベースに、次のような機能にも発展させることができます：

• ページング： fromとsizeを使った結果の分割取得
• 条件付き検索： termやrangeクエリとの組み合わせ
• 集計（Aggregation）： フィールドを限定した統計的分析

こうした実践的な知識が、スケーラブルで信頼性の高い検索機能の実装に繋がっていきます。