第13章 Hibernate Search

Hibernate Search は、さまざまなバックエンドを使用してワークのバッチを処理します。バックエンドは設定オプション default.worker.backend に制限されません。このプロパティーは、バックエンド設定の一部である BackendQueueProcessor インターフェースの実装を指定します。バックエンドをセットアップするには、JMS バックエンドなどの追加の設定が必要です。

Lucene モードでは、ノードのすべてのインデックスアップデートが、ディレクトリープロバイダーを使用した Lucene ディレクトリーに対する同じノードにより実行されます。このモードは、非クラスター環境または共有ディレクトリーストアがあるクラスター環境で使用します。

図13.1 Lucene バックエンド設定

Lucene モードは、ディレクトリーでロックストラテジーを管理する非クラスターアプリケーションまたはクラスターアプリケーションを対象とします。Lucene モードの第一の利点は、Lucene クエリーの変更の単純化と即時的な可視性です。Near Real Time (NRT) バックエンドは非クラスターおよび非共有インデックス設定向けの代替バックエンドです。

ノードのインデックスアップデートは JMS キューに送信されます。特別なリーダーがキューを処理し、マスターインデックスをアップデートします。マスターおよびスレーブパターンを確立するために、マスターインデックスはスレーブコピーに定期的に複製されます。マスターは Lucene インデックスアップデートを行います。スレーブは読み書き操作を受け取りますが、読み取り操作をローカルインデックスコピーで処理します。Lucene インデックスを更新するのはマスターだけです。また、マスターのみがアップデート操作でローカル変更を適応できます。

図13.2 JMS バックエンド設定

このモードは、スループットが重要であり、インデックスアップデートの遅延が許容されるクラスタ環境を対象とします。JMS プロバイダーにより、信頼性が保証され、ローカルインデックスコピーを変更するためにスレーブが使用されます。

shared ストラテジーを使用して、Hibernate Search は複数のクエリーおよびスレッドで該当する Lucene インデックスに対して同じ IndexReader を共有します (IndexReader がアップデートされたままの場合)。IndexReader がアップデートされない場合は、新しいものがオープンし、提供されます。各 IndexReader は複数の SegmentReaders から構成されます。shared ストラテジーは、最後のオープン後に変更または作成されたセグメントを再びオープンし、以前のインスタンスからすでにロードされたセグメントを共有します。これはデフォルトストラテジーです。

not-shared ストラテジーを使用すると、クエリーが実行されるたびに Lucene IndexReader がオープンします。IndexReader のオープンおよび起動はコストがかかる操作です。したがって、各クエリー実行で IndexReader をオープンすることは効率的なストラテジーではありません。

カスタムリーダーストラテジーは、org.hibernate.search.reader.ReaderProvider の実装を使用して記述できます。実装はスレッドセーフである必要があります。

Directory-based 実装は、デフォルトの IndexManager 実装です。高度な設定が可能であり、リーダーストラテジー、バックエンド、およびディレクトリープロバイダーに対して個別の設定を指定できます。

NRTIndexManager は、デフォルトの IndexManager の拡張であり、レイテンシーの低いインデックス書き込みに Lucene NRT (Near Real Time) 機能を使用します。ただし、lucene 以外の別のバックエンドに対する設定は無視され、Directory に対する排他的な書き込みロックが取得されます。

IndexWriter は、低いレイテンシーを提供するために各変更をディスクにフラッシュしません。クエリーは、フラッシュされていないインデックスライターバッファーからアップデートされた状態を読み取ることができます。ただし、IndexWriter が終了した場合やアプリケーションがクラッシュした場合は、アップデートが失われ、インデックスを再構築する必要があることがあります。

記載された欠点が原因でデータが制限された非クラスタ Web サイトには Near Real Time 設定が推奨されます (パフォーマンスを向上させるためにマスターノードを個別に設定できます)。

カスタマイズ IndexManager をセットアップするにはカスタム実装に完全修飾クラス名を指定します。以下のように、実装に対して引数のないコンストラクターをセットアップします。

[default|<indexname>].indexmanager = my.corp.myapp.CustomIndexManager

カスタムインデックスマネージャー実装では、デフォルト実装と同じコンポーネントが必要ありません。たとえば、Directory インターフェースを公開しないリモートインデックスサービスに委任します。

本セクションでは、マスター/スレーブ Hibernate Search アーキテクチャーの設定方法について詳しく説明します。

図13.3 JMS バックエンド設定

各インデックスアップデート操作は、JMS キューに送信されます。インデックスクエリー操作はローカルインデックスコピーで実行されます。

### slave configuration

## DirectoryProvider
# (remote) master location
hibernate.search.default.sourceBase = /mnt/mastervolume/lucenedirs/mastercopy

# local copy location
hibernate.search.default.indexBase = /Users/prod/lucenedirs

# refresh every half hour
hibernate.search.default.refresh = 1800

# appropriate directory provider
hibernate.search.default.directory_provider = filesystem-slave

## Back-end configuration
hibernate.search.default.worker.backend = jms
hibernate.search.default.worker.jms.connection_factory = /ConnectionFactory
hibernate.search.default.worker.jms.queue = queue/hibernatesearch
#optional jndi configuration (check your JMS provider for more information)

## Optional asynchronous execution strategy
# hibernate.search.default.worker.execution = async
# hibernate.search.default.worker.thread_pool.size = 2
# hibernate.search.default.worker.buffer_queue.max = 50

各インデックスアップデート操作は、JMS キューから取得され、実行されます。マスターインデックスは定期的にコピーされます。

JMS キュー内のインデックスアップデート操作が実行され、マスターインデックスが定期的にコピーされます。

### master configuration

## DirectoryProvider
# (remote) master location where information is copied to
hibernate.search.default.sourceBase = /mnt/mastervolume/lucenedirs/mastercopy

# local master location
hibernate.search.default.indexBase = /Users/prod/lucenedirs

# refresh every half hour
hibernate.search.default.refresh = 1800

# appropriate directory provider
hibernate.search.default.directory_provider = filesystem-master

## Back-end configuration
#Back-end is the default for Lucene

JMS からインデックスワークキューを処理するために、Hibernate Search フレームワーク設定以外に、メッセージ駆動 Bean を記述して、セットアップする必要があります。

@MessageDriven(activationConfig = {
      @ActivationConfigProperty(propertyName="destinationType",
                                propertyValue="javax.jms.Queue"),
      @ActivationConfigProperty(propertyName="destination",
                                propertyValue="queue/hibernatesearch"),
      @ActivationConfigProperty(propertyName="DLQMaxResent", propertyValue="1")
   } )
public class MDBSearchController extends AbstractJMSHibernateSearchController
                                 implements MessageListener {
    @PersistenceContext EntityManager em;

    //method retrieving the appropriate session
    protected Session getSession() {
        return (Session) em.getDelegate();
    }

    //potentially close the session opened in #getSession(), not needed here
    protected void cleanSessionIfNeeded(Session session)
    }
}

このサンプルは、Hibernate Search ソースコードで利用可能な抽象 JMS コントローラークラスから継承され、JavaEE MDB を実装します。この実装はサンプルとして提供され、Java EE メッセージ駆動 Bean 以外のものを使用するよう調整できます。

Hibernate Search では、基礎となる Lucene IndexWriter に渡される mergeFactor、maxMergeDocs、maxBufferedDocs などのパラメーターセットを指定して、Lucene インデックス作成パフォーマンスをチューニングできます。これらのパラメーターは、インデックスまたはシャードごとにすべてのインデックスに適用するデフォルト値として指定します。

さまざまなユースケースに対してチューニングできる複数の低レベル IndexWriter 設定があります。これらのパラメーターは、以下のように indexwriter キーワードでグループ化されます。

hibernate.search.[default|<indexname>].indexwriter.<parameter_name>

特定のシャード設定の indexwriter 値に値が設定されていない場合は、Hibernate Search がインデックスセクションをチェックし、その後でデフォルトセクションをチェックします。

以下の表の設定では、次のように Animal インデックスの 2 番目のシャードで適用される設定になります。

他のすべての値は Lucene で定義されたデフォルト値を使用します。

すべての値のデフォルトでは、Lucene の独自のデフォルトになります。このため、インデックス作成パフォーマンスと動作プロパティーのリストにリストされた値は使用している Lucene のバージョンによって異なります。示された値はバージョン 2.4 に対して相対的になります。

さまざまなユースケースに対してチューニングできる複数の低レベル IndexWriter 設定があります。これらのパラメーターは、以下のように indexwriter キーワードでグループ化されます。

default.<indexname>.indexwriter.<parameter_name>

シャード設定の indexwriter に値が設定されていない場合は、Hibernate Search がインデックスセクションをチェックし、その後でデフォルトセクションをチェックします。

以下の設定では、次のように Animal インデックスの 2 番目のシャードで適用される設定になります。

default.Animals.2.indexwriter.max_merge_docs = 10
default.Animals.2.indexwriter.merge_factor = 20
default.Animals.2.indexwriter.term_index_interval = default
default.indexwriter.max_merge_docs = 100
default.indexwriter.ram_buffer_size = 64

他のすべての値は Lucene で定義されたデフォルト値を使用します。

Lucene デフォルト値は、Hibernate Search のデフォルト設定です。したがって、以下の表にリストされた値は使用している Lucene のバージョンによって異なります。示された値はバージョン 2.4 に対して相対的になります。Lucene インデックス作成パフォーマンスの詳細については、Lucene ドキュメンテーションを参照してください。

アーキテクチャーで許可される場合は、インデックス作成の効率を向上させるために default.exclusive_index_use=true を保持します。

インデックス作成速度をチューニングする場合は、最初にオブジェクトのロードを最適化し、インデックス作成プロセスをチューニングするベースラインとして実現するタイミングを使用することが推奨されます。ワーカーバックエンドとして blackhole を設定し、インデックス作成ルーチンを開始します。このバックエンドは Hibernate Search を無効にしません。インデックスに対して必要な変更セットが生成されますが、それらの変更セットはインデックスに対してフラッシュされるのではなく破棄されます。hibernate.search.indexing_strategy を manual に設定するのとは異なり、blackhole を使用すると、データベースからより多くのデータがロードされることがあります (関連付けられたエンティティーのインデックスが再び作成されるため)。

hibernate.search.[default|<indexname>].worker.backend blackhole

以下のオプションを使用すると、作成するセグメントの最大サイズを設定できます。

//to be fairly confident no files grow above 15MB, use:
hibernate.search.default.indexwriter.ram_buffer_size = 10
hibernate.search.default.indexwriter.merge_max_optimize_size = 7
hibernate.search.default.indexwriter.merge_max_size = 7

マージ操作に対して max_size をハード制限セグメントサイズの半分未満に設定します (セグメントのマージでは 2 つのセグメントが結合されるため)。

新しいセグメントは最初に期待したものよりも大きい場合がありますが、作成されるセグメントは ram_buffer_size よりも大幅に大きくなりません。このしきい値は推定値としてチェックされます。

最初に、エンティティーのマッピングで最も一般的に使用されるアノテーションについて説明します。

Lucene ベースの Query API は、以下の一般的なアノテーションを使用してエンティティーをマップします。

最初に、永続クラスをインデックス可能であると宣言する必要があります。これを行うには、クラスに @Indexed アノテーションを付けます (@Indexedアノテーションが付いていないエンティティーはインデックス化プロセスによって無視されます)。

@Entity
@Indexed
public class Essay {
...
}

また、任意で @Indexed アノテーションの index 属性を指定して、インデックスのデフォルト名を変更することもできます。

エンティティーの各プロパティー (または属性) に対して、インデックス化する方法を記述できます。デフォルト (アノテーションなし) では、プロパティーはインデックス化プロセスで無視されます。

@Field はプロパティーをインデックス化されたプロパティーとして宣言します。また、以下の属性を 1 つまたは複数設定することにより、インデックス化プロセスの複数の側面を設定できます。

@NumericField は @Field と同種のアノテーションで、@Field または @DocumentId と同じスコープで指定できます。このアノテーションは Integer、Long、Float、および Double プロパティーに指定できます。インデックス化するときに、トライ木の構造を使用して値がインデックス化されます。プロパティーが数値のフィールドとしてインデックス化されると、効率的に範囲クエリーおよびソートを実行でき、標準の @Field プロパティーで同じクエリーを実行するよりもかなり高速に順序付けできます。@NumericField アノテーションには以下のパラメーターを使用できます。

@NumericField は Double、Long、Integer、および Float のみをサポートします。他の数値型に対して Lucene の同様の機能を利用できません。そのため、他の型はデフォルトまたはカスタムの TwoWayFieldBridge を用いた文字列のエンコーディングを使用する必要があります。

型の変換中に近似に対応できるのであればカスタムの NumericFieldBridge を使用できます。

例: カスタム NumericFieldBridge の定義

public class BigDecimalNumericFieldBridge extends NumericFieldBridge {
   private static final BigDecimal storeFactor = BigDecimal.valueOf(100);

   @Override
   public void set(String name, Object value, Document document, LuceneOptions luceneOptions) {
      if ( value != null ) {
         BigDecimal decimalValue = (BigDecimal) value;
         Long indexedValue = Long.valueOf( decimalValue.multiply( storeFactor ).longValue() );
         luceneOptions.addNumericFieldToDocument( name, indexedValue, document );
      }
   }

    @Override
    public Object get(String name, Document document) {
        String fromLucene = document.get( name );
        BigDecimal storedBigDecimal = new BigDecimal( fromLucene );
        return storedBigDecimal.divide( storeFactor );
    }

}

エンティティーの id (識別子) プロパティーは、特定のエンティティーのインデックスを一意にするために Hibernate Search によって使用される特別なプロパティーです。設計上、id は保存する必要があり、トークン化できません。プロパティーをインデックス識別子としてマーク付けするには、@DocumentId アノテーションを使用します。JPA を使用し、@Id が指定済みである場合は、@DocumentId を省略できます。選択したエンティティー識別子はドキュメント識別子としても使用されます。

Infinispan クエリーはエンティティーの id プロパティーを使用してインデックスが一意に識別されるようにします。設計上、ID は保存され、トークンに変換しないようにする必要があります。プロパティーをインデックス ID としてマークするには、@DocumentId アノテーションを使用します。

例: インデックス化されたプロパティーの指定

@Entity
@Indexed
public class Essay {
    ...
    @Id
    @DocumentId
    public Long getId() { return id; }

    @Field(name="Abstract", store=Store.YES)
    public String getSummary() { return summary; }

    @Lob
    @Field
    public String getText() { return text; }

    @Field @NumericField( precisionStep = 6)
    public float getGrade() { return grade; }
}

上記の例では、id、Abstract、text、および grade の 4 つのフィールドでインデックスを定義します。デフォルトでは、JavaBean 仕様に従ってフィールド名に大文字が使用されていないことに注意してください。grade フィールドは、デフォルトよりも若干 precision step (精度ステップ) が大きく、数値としてアノテーションが付けられます。

場合によっては、インデックスごとに若干異なるインデックス化ストラテジーでプロパティーを複数回マッピングする必要があることがあります。たとえば、フィールドでクエリーをソートするには、フィールドが分析されていない必要があります。このプロパティーで単語を基に検索し、ソートも行うには、インデックス化する必要があります (1 度分析し、1 度分析しません)。@Fields はこれを可能にします。

例: @Fields を使用してプロパティーを複数回マッピングする

@Entity
@Indexed(index = "Book" )
public class Book {
    @Fields( {
            @Field,
            @Field(name = "summary_forSort", analyze = Analyze.NO, store = Store.YES)
            } )
    public String getSummary() {
        return summary;
    }

    ...
}

この例では、フィールド summary が 2 回インデックス化されます。summary としてトークン化される方法で 1 度インデックス化され、summary_forSort として非トークン化される方法でもう 1 度インデックス化されます。

関連付けられたオブジェクトおよび埋め込みオブジェクトは、ルートエンティティーインデックスの一部としてインデックス化できます。これは、関連付けられたオブジェクトのプロパティーを基にエンティティーを検索する場合に便利です。この目的は、関連付けられた市が Atlanta (Lucene クエリーパーサー言語では address.city:Atlanta に変換されます) である場所を返すことです。場所 (place) フィールドは Place インデックスでインデックス化されます。Place インデックスドキュメントには、クエリーが可能な address.id、address.street、および address.city フィールドも含まれます。

例: アソシエーションのインデックス化

@Entity
@Indexed
public class Place {
    @Id
    @GeneratedValue
    @DocumentId
    private Long id;

    @Field
    private String name;

    @OneToOne( cascade = { CascadeType.PERSIST, CascadeType.REMOVE } )
    @IndexedEmbedded
    private Address address;
    ....
}

@Entity
public class Address {
    @Id
    @GeneratedValue
    private Long id;

    @Field
    private String street;

    @Field
    private String city;

    @ContainedIn
    @OneToMany(mappedBy="address")
    private Set<Place> places;
    ...
}

@IndexedEmbedded 技術を使用するときに Lucene インデックスでデータが非正規化されるため、Hibernate Search は Place オブジェクトと Address オブジェクトの変更を認識し、インデックスを最新の状態にする必要があります。Address の変更時に Lucene ドキュメントが確実に更新されるように、双方向の関係の逆側を @ContainedIn でマーク付けします。

これまでの説明を踏まえ、@IndexedEmbedded をネストする例を以下に示します。

@Entity
@Indexed
public class Place {
    @Id
    @GeneratedValue
    @DocumentId
    private Long id;

    @Field
    private String name;

    @OneToOne( cascade = { CascadeType.PERSIST, CascadeType.REMOVE } )
    @IndexedEmbedded
    private Address address;
    ....
}

@Entity
public class Address {
    @Id
    @GeneratedValue
    private Long id;

    @Field
    private String street;

    @Field
    private String city;

    @IndexedEmbedded(depth = 1, prefix = "ownedBy_")
    private Owner ownedBy;

    @ContainedIn
    @OneToMany(mappedBy="address")
    private Set<Place> places;
    ...
}

@Embeddable
public class Owner {
    @Field
    private String name;
   ...
}

@*ToMany、@*ToOne、および @Embedded 属性には @IndexedEmbedded アノテーションを付けることができます。その後、関連付けられたクラスの属性は主要なエンティティーインデックスへ追加されます。インデックスに以下のフィールドが含まれます。

デフォルトの接頭辞は propertyName. で、従来のオブジェクトナビゲーションの慣例に従います。これをオーバーライドするには ownedBy プロパティーで示されたように prefix 属性を使用します。

オブジェクトグラフにクラス (インスタンスではない) の循環依存関係が含まれる場合は、depth プロパティーが必要になります。Owner が Place を参照する場合がこの例になります。Hibernate Search では、想定された深さに達すると (またはオブジェクトグラフの境界に達すると)、インデックス化された埋め込み属性が含まれなくなります。自己参照を持つクラスが循環依存関係の例になります。この例では、depth が 1 に設定されているため、Owner (存在する場合) の @IndexedEmbedded 属性は無視されます。

オブジェクトアソシエーションに @IndexedEmbedded を使用すると、以下のように Lucene のクエリー構文を使用してクエリーを表現できます。

この挙動は、関係結合操作をより効率的に模擬しますが、データが重複されます。そのままの状態では Lucene インデックスにはアソシエーションの観念がなく、結合操作は存在しないことに注意してください。完全テキストのインデックス速度や機能充実の利点を活かしながらリレーショナルモデルの正規化を維持するのに役立つ可能性があります。

@IndexedEmbedded がエンティティーを参照する場合、関連付けは指向性を持つ必要があり、前述の例のように逆側には @ContainedIn アノテーションを付ける必要があります。このアノテーションを付けないと、関連付けられたエンティティーが更新されたときに Hibernate Search はルートインデックスを更新できません (前述の例では、関連付けられた Address インスタンスが更新されたときに Place インデックスドキュメントを更新する必要があります)。

場合によっては、@IndexedEmbedded アノテーションが付けられたオブジェクト型が Hibernate および Hibernate Search が対象とするオブジェクト型でないことがあります。これは、実装の代わりにインターフェースが使用される場合に特に当てはまります。このため、targetElement パラメーターを使用して Hibernate Search が対象とするオブジェクト型をオーバーライドできます。

@Entity
@Indexed
public class Address {
    @Id
    @GeneratedValue
    @DocumentId
    private Long id;

    @Field
    private String street;

    @IndexedEmbedded(depth = 1, prefix = "ownedBy_", )
    @Target(Owner.class)
    private Person ownedBy;


    ...
}

@Embeddable
public class Owner implements Person { ... }

@IndexedEmbedded アノテーションは、depth の代わりとして使用でき、depth とともに使用できる includePaths 属性も提供します。

depth のみを使用すると、埋め込まれた型のインデックス化されたフィールドすべてが同じ深さで再帰的に追加されます。このため、必要でない可能性がある他のすべてのフィールドを追加せずに特定のパスのみを選択することが難しくなります。

不必要なエンティティーのロードおよびインデックス化を回避するために、必要なパスのみを指定できます。通常のアプリケーションにはパスごとに異なる深さが必要になることがあり、以下の例で示されたようにパスを明示的に指定する必要があることがあります。

例: @IndexedEmbedded の includePaths プロパティーの使用

@Entity
@Indexed
public class Person {

   @Id
   public int getId() {
      return id;
   }

   @Field
   public String getName() {
      return name;
   }

   @Field
   public String getSurname() {
      return surname;
   }

   @OneToMany
   @IndexedEmbedded(includePaths = { "name" })
   public Set<Person> getParents() {
      return parents;
   }

   @ContainedIn
   @ManyToOne
   public Human getChild() {
      return child;
   }

    ...//other fields omitted

上記の例のようにマッピングを使用すると、name、surname、親の name、またはこれらの組み合わせで Person を検索できます。親の surname はインデックス化されないため、親の surname では検索ができませんが、インデックス化の速度が速くなり、スペースを節約でき、全体的なパフォーマンスが向上します。

@IndexedEmbeddedincludePaths には、指定されたパスと、depth の制限された値を指定して通常インデックス化するものが含まれます。includePaths を使用するときに depth を未定義にすると、depth`=0` を設定した場合と同様の挙動になり、含まれたパスのみがインデックス化されます。

例: @IndexedEmbedded の includePaths プロパティーの使用

@Entity
@Indexed
public class Human {

   @Id
   public int getId() {
      return id;
   }

   @Field
   public String getName() {
      return name;
   }

   @Field
   public String getSurname() {
      return surname;
   }

   @OneToMany
   @IndexedEmbedded(depth = 2, includePaths = { "parents.parents.name" })
   public Set<Human> getParents() {
      return parents;
   }

   @ContainedIn
   @ManyToOne
   public Human getChild() {
      return child;
   }

    ...//other fields omitted

上記の例では、各 Human の name および surname 属性がインデックス化されます。depth 属性により、親の name と surname は再帰的に 2 つ目の行までインデックス化されます。Person、Person の親、または祖父母の name または surname を使用して検索できます。第 2 レベルを越えると、もう 1 つのレベルをインデックス化しますが、name のみで surname は対象になりません。

この結果、インデックスには以下のフィールドが含まれます。

必要なクエリーを最初に定義してアプリケーションを設計すると、その時点でユースケースの実装に必要なフィールドや不必要なフィールドが分かるため、インデックス化されたパスの明示的な制御が簡単になります。

インデックス化されたクラスやプロパティーの静的なブースト値を定義するには、@Boost アノテーションを使用します。このアノテーションを @Field 内で使用するか、メソッドまたはクラスレベルで直接指定します。

例: @Boost の異なる使用方法

@Entity
@Indexed

public class Essay {
    ...

    @Id
    @DocumentId
    public Long getId() { return id; }

    @Field(name="Abstract", store=Store.YES, boost=@Boost(2f))
    @Boost(1.5f)
    public String getSummary() { return summary; }

    @Lob
    @Field(boost=@Boost(1.2f))
    public String getText() { return text; }

    @Field
    public String getISBN() { return isbn; }

}

上記の例では、Essay が検索リストの最上部に達する可能性は 1.7 倍になります。summary フィールドは isbn フィールドよりも 3.0 倍重要になります (プロパティーの @Field.boost と @Boost は累積的であるため、2 x 1.5 になります)。text フィールドは isbn フィールドよりも 1.2 倍重要になります。この説明は厳密には正しくありませんが、わかりやすく実際の感覚では現実とほぼ同じになります。

静的なインデックス時ブースティングで使用された @Boost アノテーションは静的ブースト係数を定義します。この係数は、実行時のインデックス化済みエンティティーのの状態とは関係ありません。ただし、ブースト係数がエンティティーの実際の状態に依存する可能性があるユースケースがあります。この場合は、@DynamicBoost アノテーションをカスタム BoostStrategy とともに使用できます。

例: 動的なブーストの例

public enum PersonType {
    NORMAL,
    VIP
}

@Entity
@Indexed
@DynamicBoost(impl = VIPBoostStrategy.class)
public class Person {
    private PersonType type;

    // ....
}

public class VIPBoostStrategy implements BoostStrategy {
    public float defineBoost(Object value) {
        Person person = ( Person ) value;
        if ( person.getType().equals( PersonType.VIP ) ) {
            return 2.0f;
        }
        else {
            return 1.0f;
        }
    }
}

上記の例では、VIPBoostStrategy を、インデックス化するときに使用される BoostStrategy インターフェースの実装として指定することにより、動的ブーストがクラスレベルで定義されています。@DynamicBoost はクラスまたはフィールドレベルに配置できます。エンティティー全体が defineBoost メソッドに渡されるか、またはアノテーションが付けられたフィールド/プロパティーの値のみが渡されるかはアノテーションの配置によります。渡されたオブジェクトを正しい型にキャストするのはユーザーに任されています。この例では、VIP の person のインデックス化された値はすべて普通の person の値よりも重要度が 2 倍になります。

エンティティーで @Boostアノテーションと @DynamicBoost アノテーションを組み合わせることができます。定義されたブースト係数はすべて累積的です。

トークン化されたフィールドをインデックス化するために使用されるデフォルトのアナライザークラスは、hibernate.search.analyzer プロパティーから設定可能です。このプロパティーのデフォルト値は org.apache.lucene.analysis.standard.StandardAnalyzer です。

また、エンティティー、プロパティーおよび @Field ごとにアナライザークラスを定義することもできます。@Field ごとの定義は、単一のプロパティーから複数のフィールドをインデックス化するときに便利です。

Example: Different ways of using @Analyzer

@Entity
@Indexed
@Analyzer(impl = EntityAnalyzer.class)
public class MyEntity {
    @Id
    @GeneratedValue
    @DocumentId
    private Integer id;

    @Field
    private String name;

    @Field
    @Analyzer(impl = PropertyAnalyzer.class)
    private String summary;

    @Field(analyzer = @Analyzer(impl = FieldAnalyzer.class)
    private String body;

    ...
}

この例では、トークン化されたプロパティー (name) をインデックス化するために EntityAnalyzer が使用されます。例外は summary と body であり、これらはそれぞれ PropertyAnalyzer と FieldAnalyzer によってインデックス化されます。

アナライザーの使用は非常に複雑になることがあります。そのため、Hibernate Search にはアナライザー定義の概念が導入されています。アナライザー定義は多くの @Analyzer 宣言による再使用が可能であり、以下のもので構成されます。

文字フィルターのリスト、トークナイザー、およびそれに続くフィルターのリストによってタスクが分離され、各コンポーネントの再使用が容易になり、非常に柔軟にカスタマイズされたアナライザーを構築できます (レゴブロックのように)。通常、文字フィルターが文字入力の事前処理を行った後、Tokenizer が文字入力をトークンに変換してトークン化プロセスを開始します。その後、TokenFilter によってトークンがさらに処理されます。Hibernate Search は Solr アナライザーフレームワークを使用してこのインフラストラクチャーをサポートします。

ここで、以下に示された具体的な例を確認してみましょう。最初に、文字フィルターはそのファクトリーによって定義されます。例ではマッピング文字フィルターが使用され、マッピングファイルに指定されたルールを基にして入力の文字を置き換えます。次にトークナイザーが定義されます。この例では標準のトークナイザーが使用されます。最後にフィルターのリストがファクトリーによって定義されます。この例では、専用の単語プロパティーファイルを読み取って StopFilter フィルターが構築されます。また、フィルターは大文字と小文字を区別しないことが想定されます。

例: @AnalyzerDef および Solr フレームワーク

@AnalyzerDef(name="customanalyzer",
  charFilters = {
    @CharFilterDef(factory = MappingCharFilterFactory.class, params = {
      @Parameter(name = "mapping",
        value = "org/hibernate/search/test/analyzer/solr/mapping-chars.properties")
    })
  },
  tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),
  filters = {
    @TokenFilterDef(factory = ISOLatin1AccentFilterFactory.class),
    @TokenFilterDef(factory = LowerCaseFilterFactory.class),
    @TokenFilterDef(factory = StopFilterFactory.class, params = {
      @Parameter(name="words",
        value= "org/hibernate/search/test/analyzer/solr/stoplist.properties" ),
      @Parameter(name="ignoreCase", value="true")
    })
})
public class Team {
    ...
}

トークナイザー、トークンフィルター、または文字フィルターの一部には設定またはメタデータファイルなどのリソースをロードするものがあります。これには停止フィルターと類義語フィルターが該当します。リソース文字セットが VM のデフォルトを使用しない場合、resource_charset パラメーターを追加して明示的に指定できます。

例: 特定の文字セットを使用したプロパティーファイルのロード

@AnalyzerDef(name="customanalyzer",
  charFilters = {
    @CharFilterDef(factory = MappingCharFilterFactory.class, params = {
      @Parameter(name = "mapping",
        value = "org/hibernate/search/test/analyzer/solr/mapping-chars.properties")
    })
  },
  tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),
  filters = {
    @TokenFilterDef(factory = ISOLatin1AccentFilterFactory.class),
    @TokenFilterDef(factory = LowerCaseFilterFactory.class),
    @TokenFilterDef(factory = StopFilterFactory.class, params = {
      @Parameter(name="words",
        value= "org/hibernate/search/test/analyzer/solr/stoplist.properties" ),
      @Parameter(name="resource_charset", value = "UTF-16BE"),
      @Parameter(name="ignoreCase", value="true")
  })
})
public class Team {
    ...
}

以下の例で示されているように、アナライザー定義は定義後に @Analyzer 宣言で再使用できます。

例: 名前によるアナライザーの参照

@Entity
@Indexed
@AnalyzerDef(name="customanalyzer", ... )
public class Team {
    @Id
    @DocumentId
    @GeneratedValue
    private Integer id;

    @Field
    private String name;

    @Field
    private String location;

    @Field
    @Analyzer(definition = "customanalyzer")
    private String description;
}

@AnalyzerDef によって宣言されたアナライザーインスタンスは、SearchFactory で名前を用いて使用することもできます。これはクエリーの構築時に役に立ちます。

Analyzer analyzer = fullTextSession.getSearchFactory().getAnalyzer("customanalyzer");

クエリーのフィールドは、共通の「言語」を話すよう、フィールドをインデックス化するために使用したのと同じアナライザーで分析する必要があります。クエリーとインデックス化プロセスの間では同じトークンが再使用されます。このルールには例外もありますが、ほとんどの場合に当てはまります。完全に理解して作業を行っている場合以外はこのルールに従ってください。

Solr および Lucene には便利なデフォルトの文字フィルター、トークナイザー、およびフィルターが多く含まれています。文字フィルターファクトリー、トークナイザーファクトリー、およびフィルターファクトリーの完全なリストについては、http://wiki.apache.org/solr/AnalyzersTokenizersTokenFilters を参照してください。この一部を以下に示します。

IDEの org.apache.lucene.analysis.TokenizerFactory および org.apache.lucene.analysis.TokenFilterFactory の実装をすべてチェックし、利用できる実装を確認することが推奨されます。

これまでの説明では、アナライザーを指定する方法はすべて静的でした。しかし、多言語のアプリケーションなど、インデックス化されるエンティティーの現在の状態に応じてアナライザーを選択すると便利なユースケースもあります。たとえば、BlogEntry クラスの場合、アナライザーはエントリーの言語プロパティーに依存できます。このプロパティーに応じて、実際のテキストをインデックス化するために適切な言語固有のステマーを選択する必要があります。

動的なアナライザー選択を有効にするために、Hibernate Search では AnalyzerDiscriminator アノテーションが導入されました。以下の例は、このアノテーションの使用方法を示しています。

例: @AnalyzerDiscriminator の使用方法

@Entity
@Indexed
@AnalyzerDefs({
  @AnalyzerDef(name = "en",
    tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),
    filters = {
      @TokenFilterDef(factory = LowerCaseFilterFactory.class),
      @TokenFilterDef(factory = EnglishPorterFilterFactory.class
      )
    }),
  @AnalyzerDef(name = "de",
    tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),
    filters = {
      @TokenFilterDef(factory = LowerCaseFilterFactory.class),
      @TokenFilterDef(factory = GermanStemFilterFactory.class)
    })
})
public class BlogEntry {

    @Id
    @GeneratedValue
    @DocumentId
    private Integer id;

    @Field
    @AnalyzerDiscriminator(impl = LanguageDiscriminator.class)
    private String language;

    @Field
    private String text;

    private Set<BlogEntry> references;

    // standard getter/setter
    ...
}

public class LanguageDiscriminator implements Discriminator {

    public String getAnalyzerDefinitionName(Object value, Object entity, String field) {
        if ( value == null || !( entity instanceof BlogEntry ) ) {
            return null;
        }
        return (String) value;

    }
}

@AnalyzerDiscriminator を使用する前に、動的に使用されるすべてのアナライザーを @AnalyzerDef 定義で事前に定義する必要があります。この場合は、アナライザーを動的に選択するためのクラスまたはエンティティーの特定のプロパティーに @AnalyzerDiscriminator アノテーションを配置します。AnalyzerDiscriminator の impl パラメーターを使用して、Discriminator インターフェースの具体的な実装を指定します。このインターフェースに実装を提供することはユーザーに任されています。実装しなければならない唯一のメソッドは getAnalyzerDefinitionName() であり、このメソッドは Lucene ドキュメントにフィールドが追加されるたびに呼び出されます。インデックス化されるエンティティーもインターフェースメソッドへ渡されます。AnalyzerDiscriminator がクラスレベルではなくプロパティーレベルに配置された場合のみ value パラメーターが設定されます。この場合、値はこのプロパティーの現在の値を表します。

Discriminator インターフェースの実装は、既存アナライザー定義の名前を返す必要がありますが、デフォルトのアナライザーをオーバーライドしない場合は null を返す必要があります。上記の例では、言語パラメーターが @AnalyzerDefs で指定された名前に一致する「de」または「en」のどちらかであることを仮定します。

ステミングや音声的近似などを活用するために、ドメインモデルで複数のアナライザーが使用された場合にアナライザーを読み出すことができます。この場合、同じアナライザーを使用してクエリーを構築します。この代わりに、正しいアナライザーを自動的に選択する Hibernate Search クエリー DSL を使用することもできます。

Lucene プログラム API または Lucene クエリーパーサーのいずれを使用する場合でも、指定のエンティティーのスコープ指定されたアナライザーを読み出しできます。スコープ指定されたアナライザーは、インデックス化されたフィールドに応じて適切なアナライザーを適用するアナライザーです。各フィールドで動作する各エンティティーには複数のアナライザーを定義できます。スコープ指定されたアナライザーはすべてのアナライザーをコンテキストを意識したアナライザーに統合します。この理論は若干複雑ですが、クエリーで正しいアナライザーを使用することは簡単です。

例: フルテキストのクエリー構築時におけるスコープ指定されたアナライザーの使用

org.apache.lucene.queryParser.QueryParser parser = new QueryParser(
    "title",
    fullTextSession.getSearchFactory().getAnalyzer( Song.class )
);

org.apache.lucene.search.Query luceneQuery =
    parser.parse( "title:sky Or title_stemmed:diamond" );

org.hibernate.Query fullTextQuery =
    fullTextSession.createFullTextQuery( luceneQuery, Song.class );

List result = fullTextQuery.list(); //return a list of managed objects

上記の例では、歌のタイトルが 2 つのフィールドでインデックス化されます。標準のアナライザーは title フィールドで使用され、ステミングアナライザーは title_stemmed フィールドで使用されます。検索ファクトリーによって提供されたアナライザーを使用して、クエリーは目的のフィールドに応じて適切なアナライザーを使用します。

Hibernate Search には、Java プロパティー型とそのフルテキスト表現との間のビルドインブリッジが含まれています。

@Entity
@Indexed
public class Meeting {
    @Field(analyze=Analyze.NO)

    private Date date;
    ...

場合によっては Hibernate Search のビルトインブリッジが一部のプロパティータイプに対応しなかったり、ブリッジによって使用される String 表現が要件に合わなかったりすることがあります。この問題に対応する方法を以下に説明します。

/**
 * Padding Integer bridge.
 * All numbers will be padded with 0 to match 5 digits
 *
 * @author Emmanuel Bernard
 */
public class PaddedIntegerBridge implements StringBridge {

    private int PADDING = 5;

    public String objectToString(Object object) {
        String rawInteger = ( (Integer) object ).toString();
        if (rawInteger.length() > PADDING)
            throw new IllegalArgumentException( "Try to pad on a number too big" );
        StringBuilder paddedInteger = new StringBuilder( );
        for ( int padIndex = rawInteger.length() ; padIndex < PADDING ; padIndex++ ) {
            paddedInteger.append('0');
        }
        return paddedInteger.append( rawInteger ).toString();
    }
}

@FieldBridge(impl = PaddedIntegerBridge.class)
private Integer length;

public class PaddedIntegerBridge implements StringBridge, ParameterizedBridge {

    public static String PADDING_PROPERTY = "padding";
    private int padding = 5; //default

    public void setParameterValues(Map<String,String> parameters) {
        String padding = parameters.get( PADDING_PROPERTY );
        if (padding != null) this.padding = Integer.parseInt( padding );
    }

    public String objectToString(Object object) {
        String rawInteger = ( (Integer) object ).toString();
        if (rawInteger.length() > padding)
            throw new IllegalArgumentException( "Try to pad on a number too big" );
        StringBuilder paddedInteger = new StringBuilder( );
        for ( int padIndex = rawInteger.length() ; padIndex < padding ; padIndex++ ) {
            paddedInteger.append('0');
        }
        return paddedInteger.append( rawInteger ).toString();
    }
}


//property
@FieldBridge(impl = PaddedIntegerBridge.class,
             params = @Parameter(name="padding", value="10")
            )
private Integer length;

public class PaddedIntegerBridge implements TwoWayStringBridge, ParameterizedBridge {

    public static String PADDING_PROPERTY = "padding";
    private int padding = 5; //default

    public void setParameterValues(Map parameters) {
        Object padding = parameters.get( PADDING_PROPERTY );
        if (padding != null) this.padding = (Integer) padding;
    }

    public String objectToString(Object object) {
        String rawInteger = ( (Integer) object ).toString();
        if (rawInteger.length() > padding)
            throw new IllegalArgumentException( "Try to pad on a number too big" );
        StringBuilder paddedInteger = new StringBuilder( );
        for ( int padIndex = rawInteger.length() ; padIndex < padding ; padIndex++ ) {
            paddedInteger.append('0');
        }
        return paddedInteger.append( rawInteger ).toString();
    }

    public Object stringToObject(String stringValue) {
        return new Integer(stringValue);
    }
}


//id property
@DocumentId
@FieldBridge(impl = PaddedIntegerBridge.class,
             params = @Parameter(name="padding", value="10")
private Integer id;

/**
 * Store the date in 3 different fields - year, month, day - to ease Range Query per
 * year, month or day (eg get all the elements of December for the last 5 years).
 * @author Emmanuel Bernard
 */
public class DateSplitBridge implements FieldBridge {
    private final static TimeZone GMT = TimeZone.getTimeZone("GMT");

    public void set(String name, Object value, Document document, LuceneOptions luceneOptions) {
        Date date = (Date) value;
        Calendar cal = GregorianCalendar.getInstance(GMT);
        cal.setTime(date);
        int year = cal.get(Calendar.YEAR);
        int month = cal.get(Calendar.MONTH) + 1;
        int day = cal.get(Calendar.DAY_OF_MONTH);

        // set year
        luceneOptions.addFieldToDocument(
            name + ".year",
            String.valueOf( year ),
            document );

        // set month and pad it if needed
        luceneOptions.addFieldToDocument(
            name + ".month",
            month < 10 ? "0" : "" + String.valueOf( month ),
            document );

        // set day and pad it if needed
        luceneOptions.addFieldToDocument(
            name + ".day",
            day < 10 ? "0" : "" + String.valueOf( day ),
            document );
    }
}

//property
@FieldBridge(impl = DateSplitBridge.class)
private Date date;

@Entity
@Indexed
(name="branchnetwork",
             store=Store.YES,
             impl = CatFieldsClassBridge.class,
             params = @Parameter( name="sepChar", value=" " ) )
public class Department {
    private int id;
    private String network;
    private String branchHead;
    private String branch;
    private Integer maxEmployees
    ...
}

public class CatFieldsClassBridge implements FieldBridge, ParameterizedBridge {
    private String sepChar;

    public void setParameterValues(Map parameters) {
        this.sepChar = (String) parameters.get( "sepChar" );
    }

    public void set( String name, Object value, Document document, LuceneOptions luceneOptions) {
        // In this particular class the name of the new field was passed
        // from the name field of the ClassBridge Annotation. This is not
        // a requirement. It just works that way in this instance. The
        // actual name could be supplied by hard coding it below.
        Department dep = (Department) value;
        String fieldValue1 = dep.getBranch();
        if ( fieldValue1 == null ) {
            fieldValue1 = "";
        }
        String fieldValue2 = dep.getNetwork();
        if ( fieldValue2 == null ) {
            fieldValue2 = "";
        }
        String fieldValue = fieldValue1 + sepChar + fieldValue2;
        Field field = new Field( name, fieldValue, luceneOptions.getStore(),
            luceneOptions.getIndex(), luceneOptions.getTermVector() );
        field.setBoost( luceneOptions.getBoost() );
        document.add( field );
   }
}

Lucene API では、クエリーパーサー (簡単なクエリー) または Lucene プログラム API (複雑なクエリー) を使用します。Lucene クエリーの構築は、Hibernate Search ドキュメントの範囲外になります。詳細については、オンラインの Lucene ドキュメント、Lucene in Action、または Hibernate Search in Action を参照してください。

Lucene プログラム API はフルテキストクエリーを有効にします。しかし、Lucene プログラム API を使用する場合はパラメーターを同等の文字列に変換し、さらに正しいアナライザーを適切なフィールドに適用する必要があります。たとえば、N-gram アナライザーは複数の N-gram を指定の言葉のトークンとして使用し、そのように検索する必要があります。この作業には QueryBuilder の使用が推奨されます。

Hibernate Search クエリー API は以下の特徴を持ちます。

API を使用するには、最初に指定の indexedentitytype にアタッチされるクエリービルダーを作成します。この QueryBuilder は、使用するアナライザーと適用するフィールドブリッジを認識します。複数の QueryBuilder を作成できます (クエリーのルートに関係する各エンティティー型ごと)。QueryBuilder は SearchFactory から派生します。

QueryBuilder mythQB = searchFactory.buildQueryBuilder().forEntity( Myth.class ).get();

指定のフィールドに使用するアナライザーをオーバーライドすることもできます。

QueryBuilder mythQB = searchFactory.buildQueryBuilder()
    .forEntity( Myth.class )
        .overridesForField("history","stem_analyzer_definition")
    .get();

クエリービルダーは Lucene クエリーの構築に使用されるようになりました。Lucene のクエリーパーサーを使用して生成されたカスタマイズ済みクエリーまたは Lucene プログラム API を使用してアセンブルされた Query オブジェクトは、Hibernate Search DSL とともに使用されます。

以下の例は特定の単語を検索する方法を示しています。

Query luceneQuery = mythQB.keyword().onField("history").matching("storm").createQuery();

文字列型でないプロパティーを検索します。

@Indexed
public class Myth {
  @Field(analyze = Analyze.NO)
  @DateBridge(resolution = Resolution.YEAR)
  public Date getCreationDate() { return creationDate; }
  public Date setCreationDate(Date creationDate) { this.creationDate = creationDate; }
  private Date creationDate;

  ...
}

Date birthdate = ...;
Query luceneQuery = mythQb.keyword().onField("creationDate").matching(birthdate).createQuery();

FieldBridge に objectToString メソッドがある場合 (および組み込みのすべての FieldBridge 実装にこのメソッドがある場合)、この変換はどのオブジェクトに対しても実行できます。

次の例は、N-gram アナライザーを使用するフィールドを検索します。N-gram アナライザーは単語の N-gram の連続をインデックス化します。これは、ユーザーによる誤字を防ぐのに役立ちます。たとえば、単語 hibernate の 3-gram は hib、ibe、ber、ern、rna、nat、ate になります。

@AnalyzerDef(name = "ngram",
  tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class ),
  filters = {
    @TokenFilterDef(factory = StandardFilterFactory.class),
    @TokenFilterDef(factory = LowerCaseFilterFactory.class),
    @TokenFilterDef(factory = StopFilterFactory.class),
    @TokenFilterDef(factory = NGramFilterFactory.class,
      params = {
        @Parameter(name = "minGramSize", value = "3"),
        @Parameter(name = "maxGramSize", value = "3") } )
  }
)

public class Myth {
  @Field(analyzer=@Analyzer(definition="ngram")
  public String getName() { return name; }
  public String setName(String name) { this.name = name; }
  private String name;

  ...
}

Date birthdate = ...;
Query luceneQuery = mythQb.keyword().onField("name").matching("Sisiphus")
   .createQuery();

一致する単語「Sisiphus」は小文字に変換され、3-gram (sis、isi、sip、iph、phu、hus) に分割されます。各 N-gram はクエリーの一部になります。その後、ユーザーは Sysiphus (i ではなく y) myth (シーシュポスの神話) を検索できます。ユーザーに対してすべてが透過的に行われます。

同じフィールドで可能な単語を複数検索し、すべてを一致する句に追加します。

//search document with storm or lightning in their history
Query luceneQuery =
    mythQB.keyword().onField("history").matching("storm lightning").createQuery();

複数のフィールドで同じ単語を検索するには、onFields メソッドを使用します。

Query luceneQuery = mythQB
    .keyword()
    .onFields("history","description","name")
    .matching("storm")
    .createQuery();

同じ用語を検索する場合でも、あるフィールドに対して他のフィールドとは異なる処理をする必要があることがあります。このような場合は andField() メソッドを使用します。

Query luceneQuery = mythQB.keyword()
    .onField("history")
    .andField("name")
      .boostedTo(5)
    .andField("description")
    .matching("storm")
    .createQuery();

前述の例では、フィールド名のみが 5 にブーストされます。

レーベンシュタイン距離 (Levenshtein Distance) アルゴリズムを基にしてファジークエリーを実行するには、keyword クエリーで開始して fuzzy フラグを追加します。

Query luceneQuery = mythQB
    .keyword()
      .fuzzy()
        .withThreshold( .8f )
        .withPrefixLength( 1 )
    .onField("history")
    .matching("starm")
    .createQuery();

threshold を越えると 2 つの用語の一致を考慮します。これは、0 から 1 の間の小数であり、デフォルト値は 0.5 になります。prefixLength は「ファジーの度合い」によって無視される接頭辞の長さになります。デフォルト値は 0 ですが、大量の異なる用語が含まれるインデックスではゼロ以外の値を指定することが推奨されます。

ワイルドカードクエリーは、単語の一部のみがわかる場合に便利です。? は単一の文字を表し、* は複数の文字を表します。パフォーマンス上の理由で、クエリーの最初に ? または * を使用しないことが推奨されます。

Query luceneQuery = mythQB
    .keyword()
      .wildcard()
    .onField("history")
    .matching("sto*")
    .createQuery();

これまでは、単語または単語のセットを検索しましたが、完全一致の文または近似の文を検索することも可能です。文の検索には phrase() を使用します。

Query luceneQuery = mythQB
    .phrase()
    .onField("history")
    .sentence("Thou shalt not kill")
    .createQuery();

おおよその文はスロップ (slop) 係数を追加すると検索可能になります。スロップ係数は、その文で許可される別の単語の数を表します。これは、within または near 演算子と同様に動作します。

Query luceneQuery = mythQB
    .phrase()
      .withSlop(3)
    .onField("history")
    .sentence("Thou kill")
    .createQuery();

範囲クエリーは指定の境界の間、上、または下で値を検索します。

//look for 0 <= starred < 3
Query luceneQuery = mythQB
    .range()
    .onField("starred")
    .from(0).to(3).excludeLimit()
    .createQuery();

//look for myths strictly BC
Date beforeChrist = ...;
Query luceneQuery = mythQB
    .range()
    .onField("creationDate")
    .below(beforeChrist).excludeLimit()
    .createQuery();

クエリーを集合 (組み合わせ) するとさらに複雑なクエリーを作成できます。以下の集合演算子を使用できます。

サブクエリーはブール値クエリー自体を含む Lucene クエリーです。

例: SHOULD クエリー

//look for popular myths that are preferably urban
Query luceneQuery = mythQB
    .bool()
      .should( mythQB.keyword().onField("description").matching("urban").createQuery() )
      .must( mythQB.range().onField("starred").above(4).createQuery() )
    .createQuery();

例: MUST クエリー

//look for popular urban myths
Query luceneQuery = mythQB
    .bool()
      .must( mythQB.keyword().onField("description").matching("urban").createQuery() )
      .must( mythQB.range().onField("starred").above(4).createQuery() )
    .createQuery();

例: MUST NOT クエリー

//look for popular modern myths that are not urban
Date twentiethCentury = ...;
Query luceneQuery = mythQB
    .bool()
      .must( mythQB.keyword().onField("description").matching("urban").createQuery() )
        .not()
      .must( mythQB.range().onField("starred").above(4).createQuery() )
      .must( mythQB
        .range()
        .onField("creationDate")
        .above(twentiethCentury)
        .createQuery() )
    .createQuery();

Hibernate Search クエリー DSL は簡単に使用および読み取りできるクエリー API です。Lucene クエリーを許可および作成すると、DSL によってサポートされていないクエリー型を取り入れることができます。

クエリー型およびフィールドのクエリーオプションの概要は次のとおりです。

例: クエリーオプションの組み合わせ

Query luceneQuery = mythQB
    .bool()
      .should( mythQB.keyword().onField("description").matching("urban").createQuery() )
      .should( mythQB
        .keyword()
        .onField("name")
          .boostedTo(3)
          .ignoreAnalyzer()
        .matching("urban").createQuery() )
      .must( mythQB
        .range()
          .boostedTo(5).withConstantScore()
        .onField("starred").above(4).createQuery() )
    .createQuery();

妥当な数の結果が予期され (ページネーションを使用する場合など)、すべての結果で作業を行うことが想定される場合、list() または uniqueResult() の使用が推奨されます。list() はエンティティー batch-size が適切に設定されている場合に最適です。list()、uniqueResult()、および iterate() を使用する場合は Hibernate Search がすべての Lucene Hits 要素 (ページネーション内) を処理する必要があることに注意してください。

Lucene ドキュメントのローディングを最小限にしたい場合は、scroll() の使用が適しています。ScrollableResults オブジェクトは Lucene リソースを保持するため、終了後はこのオブジェクトを閉じるようにしてください。scroll の使用が想定される場合にオブジェクトを一括してロードするには、query.setFetchSize() を使用できます。ロードされていないオブジェクトがアクセスされた場合、Hibernate Search は次の fetchSize オブジェクトを 1 度にロードします。

以下のような場合、一致するドキュメントの合計数が分かると便利です。

一致するドキュメントをすべて読み出すには大量のリソースを消費します。Hibernate Search では、ページネーションパラメーターに関係なく、一致するドキュメントの合計数を読み出しできます。さらに、オブジェクトのロードを発生させずに一致する要素の数を読み出しすることもできます。

例: クエリーの結果サイズの決定

org.hibernate.search.FullTextQuery query =
    s.createFullTextQuery( luceneQuery, Book.class );
//return the number of matching books without loading a single one
assert 3245 == ;

org.hibernate.search.FullTextQuery query =
    s.createFullTextQuery( luceneQuery, Book.class );
query.setMaxResult(10);
List results = query.list();
//return the total number of matching books regardless of pagination
assert 3245 == ;

射影の結果は Object 配列として返されます。オブジェクトに使用されたデータ構造がアプリケーションの要件と一致しない場合は、ResultTransformer を適用します。ResultTransformer はクエリーの実行後に必要なデータ構造を構築します。

射影の結果は Object 配列として返されます。オブジェクトに使用されたデータ構造がアプリケーションの要件と一致しない場合は、ResultTransformer を適用します。ResultTransformer はクエリーの実行後に必要なデータ構造を構築します。

例: 射影への ResultTransformer の使用

org.hibernate.search.FullTextQuery query =
    s.createFullTextQuery( luceneQuery, Book.class );
query.setProjection( "title", "mainAuthor.name" );

query.setResultTransformer( new StaticAliasToBeanResultTransformer( BookView.class, "title", "author" ) );
List<BookView> results = (List<BookView>) query.list();
for(BookView view : results) {
    log.info( "Book: " + view.getTitle() + ", " + view.getAuthor() );
}

ResultTransformer 実装の例は、Hibernate Core のコードベースにあります。

クエリーの結果が想定外であった場合、結果を理解するには Luke ツールを使用すると便利です。しかし、 Hibernate Search では (特定クエリーの) 結果の Lucene Explanation オブジェクトへアクセスすることもできます。このクラスは、Lucene ユーザーにとっては非常に高度なクラスですが、オブジェクトのスコアを理解するのに便利です。特定の結果の Explanation オブジェクトへアクセスする方法は 2 つあります。

最初の方法は、ドキュメント ID をパラメーターとして取り、Explanation オブジェクトを返します。ドキュメント ID は射影および FullTextQuery.DOCUMENT_ID 定数を使用して読み出しできます。

2 つ目の方法は、FullTextQuery.EXPLANATION 定数を使用して Explanation オブジェクトを射影します。

例: 射影を使用した Lucene Explanation オブジェクトの読み出し

FullTextQuery ftQuery = s.createFullTextQuery( luceneQuery, Dvd.class )
        .setProjection(
             FullTextQuery.DOCUMENT_ID,
             ,
             FullTextQuery.THIS );
@SuppressWarnings("unchecked") List<Object[]> results = ftQuery.list();
for (Object[] result : results) {
    Explanation e = (Explanation) result[1];
    display( e.toString() );
}

Explanation オブジェクトの使用で消費するリソースは Lucene クエリーを再実行するのとほぼ同じため、必要な場合のみ使用してください。

Apache Lucene には、カスタムのフィルター処理に従ってクエリーの結果をフィルターできる強力な機能が含まれています。これは、フィルターをキャッシュおよび再使用できるため、データの制限を追加で適用する大変強力な方法です。ユースケースには以下が含まれます。

Hibernate Search では、さらに、透過的にキャッシュされるパラメーター化可能な名前付きフィルターの概念が導入されます。Hibernate Core フィルターの概念を知っている場合、その API は非常に似ています

例: クエリーに対するフルテキストフィルターの有効化

fullTextQuery = s.createFullTextQuery( query, Driver.class );
fullTextQuery.enableFullTextFilter("bestDriver");
fullTextQuery.enableFullTextFilter("security").setParameter( "login", "andre" );
fullTextQuery.list(); //returns only best drivers where andre has credentials

この例では、クエリー上で 2 つのフィルターが有効になっています。フィルターは好きなだけ (有効または無効) にできます。

フィルターの宣言は、@FullTextFilterDef アノテーションから行われます。このアノテーションは、フィルターが後で適用されるクエリーに関係なく、 @Indexed エンティティーである場合があります。これは、暗黙的に、フィルター定義がグローバルであり、その名前が一意である必要があることを示します。SearchException は、同じ名前で 2 つの異なる @FullTextFilterDef アノテーションが定義された場合にスローされます。各名前付きフィルターは実際のフィルター実装を指定する必要があります。

例: フィルターの定義および実装

@FullTextFilterDefs( {
    @FullTextFilterDef(name = "bestDriver", impl = BestDriversFilter.class),
    @FullTextFilterDef(name = "security", impl = SecurityFilterFactory.class)
})
public class Driver { ... }

public class BestDriversFilter extends org.apache.lucene.search.Filter {

    public DocIdSet getDocIdSet(IndexReader reader) throws IOException {
        OpenBitSet bitSet = new OpenBitSet( reader.maxDoc() );
        TermDocs termDocs = reader.termDocs( new Term( "score", "5" ) );
        while ( termDocs.next() ) {
            bitSet.set( termDocs.doc() );
        }
        return bitSet;
    }
}

BestDriversFilter は、スコアが 5 のドライバーに結果セットを削減する単純な Lucene フィルターの例です。この例では、指定されたフィルターは org.apache.lucene.search.Filter を直接実装し、引数がないコンストラクターを含みます。

フィルターの作成で追加の手順が必要な場合、または使用するフィルターに引数がないコンストラクターが含まれない場合は、ファクトリーパターンを使用できます。

例: ファクトリーパターンを使用したフィルターの作成

@FullTextFilterDef(name = "bestDriver", impl = BestDriversFilterFactory.class)
public class Driver { ... }

public class BestDriversFilterFactory {

@Factory
    public Filter getFilter() {
        //some additional steps to cache the filter results per IndexReader
        Filter bestDriversFilter = new BestDriversFilter();
        return new CachingWrapperFilter(bestDriversFilter);
    }
}

Hibernate Search は、@Factory アノテーションが付いたメソッドを探し、そのメソッドを使用してフィルターインスタンスを構築します。ファクトリーには引数がないコンストラクターが含まれる必要があります。

Infinispan クエリーは @Factory アノテーションが付いたメソッドを使用してフィルターインスタンスを構築します。ファクトリーには引数がないコンストラクターが含まれる必要があります。

名前付きフィルターは、パラメーターをフィルターに渡す必要がある場合に便利です。たとえば、セキュリティーフィルターが、適用するセキュリティーレベルを認識する場合を考えてみます。

例: 定義されたフィルターにパラメーターを渡す

fullTextQuery = s.createFullTextQuery( query, Driver.class );
fullTextQuery.enableFullTextFilter("security").setParameter( "level", 5 );

各パラメーター名では、対象となる名前付きフィルター定義のフィルターまたはフィルターファクトリーのいずれかでセッターが関連付けられているとします。例: 実際のフィルター実装でのパラメーターの使用

public class SecurityFilterFactory {
    private Integer level;

    /**
     * injected parameter
     */
    public void setLevel(Integer level) {
        this.level = level;
    }

    @Key public FilterKey getKey() {
        StandardFilterKey key = new StandardFilterKey();
        key.addParameter( level );
        return key;
    }

    @Factory
    public Filter getFilter() {
        Query query = new TermQuery( new Term("level", level.toString() ) );
        return new CachingWrapperFilter( new QueryWrapperFilter(query) );
    }
}

@Key アノテーションが付いたメソッドは FilterKey オブジェクトを返すことに注意してください。返されたオブジェクトには特別なコントラクトがあります (キーオブジェクトは equals() / hashCode() を実装して、特定のフィルタータイプが同じであり、パラメーターセットが同じである場合のみ 2 つのキーが同じになるようにします)。つまり、2 つのフィルターキーは、キーが生成されるフィルターが交換可能である場合のみ同じになります。キーオブジェクトはキャッシュメカニズムでキーとして使用されます。

@Key メソッドは以下の場合のみ必要です。

ほとんどの場合、StandardFilterKey 実装を使用するだけで十分です。これにより、equals() / hashCode() 実装はパラメーターの各 equals および hashcode メソッドに委譲されます。

これまでに説明したように、定義されたフィルターはデフォルトでキャッシュされ、キャッシュはハード参照とソフト参照の組み合わせを使用して必要な場合にメモリーの破棄を許可します。ハード参照キャッシュは最後に使用されたフィルターを追跡し、使用頻度が最も低いフィルターを必要に応じて SoftReferences に変換します。ハード参照キャッシュのサイズを調整するには、hibernate.search.filter.cache_strategy.size (デフォルト値は 128) を使用します。フィルターキャッシュの高度な使用については、独自の FilterCachingStrategy を実装してください。クラス名は hibernate.search.filter.cache_strategy によって定義されます。

このフィルターキャッシュメカニズムを実際のフィルター結果と混同しないでください。Lucene では、CachingWrapperFilter に IndexReader を使用してフィルターをラップすることが一般的です。このラッパーは、コストがかかる再計算を回避するために getDocIdSet(IndexReader リーダー) メソッドから返された DocIdSet をキャッシュします。リーダーは開いたときのインデックスの状態を表すため、計算される DocIdSet は同じ IndexReader インスタンスに対してのみキャッシュできることに注意してください。ドキュメントリストは開いた IndexReader 内で変更できません。ただし、別の/新しい IndexReader インスタンスがドキュメントの別のセット (別のインデックスのもの、またはインデックスが変更されたため) で動作することがあります。この場合、キャッシュされた DocIdSet は再計算する必要があります。

Hibernate Search は、キャッシュのこの側面でも役に立ちます。デフォルトでは、@FullTextFilterDef の cache フラグは FilterCacheModeType.INSTANCE_AND_DOCIDSETRESULTS に設定され、フィルターインスタンスが自動的にキャッシュされ、指定されたフィルターが CachingWrapperFilter の Hibernate 固有の実装にラップされます。このクラスの Lucene のバージョンとは異なり、SoftReferences はハード参照数 (フィルターキャッシュに関する説明を参照) とともに使用されます。ハード参照数は、hibernate.search.filter.cache_docidresults.size (デフォルト値は 5) を使用して調整できます。ラップの動作は @FullTextFilterDef.cache パラメーターを使用して制御できます。このパラメーターには以下の 3 つの異なる値があります。

最後に、フィルターをキャッシュする理由について説明します。フィルターのキャッシュが必要になる状況は 2 つあります。

その状況は以下のとおりです。

シャード化された環境では、使用できるシャードのサブセットでクエリーを実行できます。これは、2 つのステップで行われます。

public class CustomerShardingStrategy implements IndexShardingStrategy {

     // stored IndexManagers in an array indexed by customerID
     private IndexManager[] indexManagers;

     public void initialize(Properties properties, IndexManager[] indexManagers) {
       this.indexManagers = indexManagers;
     }

     public IndexManager[] getIndexManagersForAllShards() {
       return indexManagers;
     }

     public IndexManager getIndexManagerForAddition(
         Class<?> entity, Serializable id, String idInString, Document document) {
       Integer customerID = Integer.parseInt(document.getFieldable("customerID").stringValue());
       return indexManagers[customerID];
     }

     public IndexManager[] getIndexManagersForDeletion(
         Class<?> entity, Serializable id, String idInString) {
       return getIndexManagersForAllShards();
     }

      /**
      * Optimization; don't search ALL shards and union the results; in this case, we
      * can be certain that all the data for a particular customer Filter is in a single
      * shard; simply return that shard by customerID.
      */
     public IndexManager[] getIndexManagersForQuery(
         FullTextFilterImplementor[] filters) {
       FullTextFilter filter = getCustomerFilter(filters, "customer");
       if (filter == null) {
         return getIndexManagersForAllShards();
       }
       else {
         return new IndexManager[] { indexManagers[Integer.parseInt(
           filter.getParameter("customerID").toString())] };
       }
     }

     private FullTextFilter getCustomerFilter(FullTextFilterImplementor[] filters, String name) {
       for (FullTextFilterImplementor filter: filters) {
         if (filter.getName().equals(name)) return filter;
       }
       return null;
     }
    }

この例では、customer という名前のフィルターが存在する場合はこのカスタマー専用のシャードのみがクエリーされます。存在しない場合はすべてのシャードが返されます。指定のシャードストラテジーはパラメーターに応じて 1 つ以上のフィルターに反応します。

2 つ目の手順では、クエリー実行時にフィルターを有効にします。クエリーの後に Lucene の結果もフィルターする通常のフィルターですが、シャードストラテジーのみへ渡される特別なフィルターを使用できます (シャードストラテジーへ渡されないと無視されます)。

この機能を使用するには、フィルターの宣言時に ShardSensitiveOnlyFilter クラスを指定します。

@Indexed
@FullTextFilterDef(name="customer", impl=ShardSensitiveOnlyFilter.class)
public class Customer {
   ...
}

FullTextQuery query = ftEm.createFullTextQuery(luceneQuery, Customer.class);
query.enableFulltextFilter("customer").setParameter("CustomerID", 5);
@SuppressWarnings("unchecked")
List<Customer> results = query.getResultList();

ShardSensitiveOnlyFilter を使用する場合、Lacene フィルターを実装する必要はありません。シャード化された環境でクエリーの実行を迅速にするために、フィルターおよびこれらにフィルターに反応するシャードストラテジーの使用が推奨されます。

ファセット検索を行うための最初の手順は FacetingRequest を作成することです。現在、離散ファセット (discrete faceting) と範囲ファセット (range faceting) の 2 つの種類のファセットリクエストがサポートされています。離散ファセットリクエストの場合、ファセット (カテゴリー化) を使用したいインデックスフィールドと、適用するファセットオプションを指定します。離散ファセットリクエストの例を以下に示します。

例: 離散ファセットリクエストの作成

QueryBuilder builder = fullTextSession.getSearchFactory()
    .buildQueryBuilder()
        .forEntity( Cd.class )
            .get();
FacetingRequest labelFacetingRequest = builder.facet()
    .name( "labelFaceting" )
    .onField( "label")
    .discrete()
    .orderedBy( FacetSortOrder.COUNT_DESC )
    .includeZeroCounts( false )
    .maxFacetCount( 1 )
    .createFacetingRequest();

このファセットリクエストを実行すると、インデックス化されたフィールド label の各離散値に対して Facet インスタンスが作成されます。Facet インスタンスは実際のフィールド値を記録します。この値には、元のクエリー結果内でこの特定のフィールド値が発生する頻度が含まれます。orderedBy、includeZeroCounts、および maxFacetCount はすべてのファセットリクエストに適用できる任意のパラメーターです。orderedBy を使用すると、作成されたファセットが返される順序を指定できます。デフォルト値は FacetSortOrder.COUNT_DESC ですが、フィールド値と範囲が指定された順番をソートすることもできます。includeZeroCount はカウント数が 0 のファセットが結果に含まれるかどうかを決定します (デフォルトでは含まれます)。maxFacetCount を使用すると返されるファセットの最大数を制限できます。

範囲ファセットリクエストの作成は離散ファセットリクエストの作成と非常に似ていますが、ファセットを使用するフィールド値の範囲を指定する必要があります。3 つの異なる価格範囲が指定されている、範囲ファセットリクエストの例を以下に示します。below および above は 1 度だけ指定できますが、from - to の範囲は何度でも指定できます。範囲の境界に excludeLimit を使用して、範囲に含まれるかどうかを指定することもできます。

QueryBuilder builder = fullTextSession.getSearchFactory()
    .buildQueryBuilder()
        .forEntity( Cd.class )
            .get();
FacetingRequest priceFacetingRequest = builder.facet()
    .name( "priceFaceting" )
    .onField( "price" )
    .range()
    .below( 1000 )
    .from( 1001 ).to( 1500 )
    .above( 1500 ).excludeLimit()
    .createFacetingRequest();

ファセットリクエストは、FullTextQuery クラスを用いて読み出しできる FacetManager クラスを使用して、クエリーに適用されます。

ファセットリクエストはいくつでも有効にでき、ファセットリクエスト名を指定して getFacets() で読み出しできます。ファセットリクエスト名を指定してそのファセットを無効にできる disableFaceting() メソッドもあります。

ファセットリクエストは、FullTextQuery を用いて読み出しできる FacetManager を使用して、クエリーに適用できます。

例: ファセットリクエストの適用

// create a fulltext query
Query luceneQuery = builder.all().createQuery(); // match all query
FullTextQuery fullTextQuery = fullTextSession.createFullTextQuery( luceneQuery, Cd.class );

// retrieve facet manager and apply faceting request
FacetManager facetManager = fullTextQuery.getFacetManager();
facetManager.enableFaceting( priceFacetingRequest );

// get the list of Cds
List<Cd> cds = fullTextQuery.list();
...

// retrieve the faceting results
List<Facet> facets = facetManager.getFacets( "priceFaceting" );
...

複数のファセットリクエストは getFacets() を使用し、ファセットリクエスト名を指定することにより読み出しできます。

disableFaceting() メソッドは、ファセットリクエスト名を指定してファセットリクエストを無効にします。

最後に、「ドリルダウン」機能を実装するために、返された Facet のいずれかを元のクエリーの追加基準として適用できます。この場合は、FacetSelection を使用できます。FacetSelection は FacetManager から利用できます。これにより、クエリー基準としてのファセットの選択 (selectFacets)、単一のファセット制限の削除 (deselectFacets)、すべてのファセット制限の消去 (clearSelectedFacets)、および現在選択されているすべてのファセットの読み出し (getSelectedFacets) が可能になります。以下にコード例を示します。

// create a fulltext query
Query luceneQuery = builder.all().createQuery(); // match all query
FullTextQuery fullTextQuery = fullTextSession.createFullTextQuery( luceneQuery, clazz );

// retrieve facet manager and apply faceting request
FacetManager facetManager = fullTextQuery.getFacetManager();
facetManager.enableFaceting( priceFacetingRequest );

// get the list of Cd
List<Cd> cds = fullTextQuery.list();
assertTrue(cds.size() == 10);

// retrieve the faceting results
List<Facet> facets = facetManager.getFacets( "priceFaceting" );
assertTrue(facets.get(0).getCount() == 2)

// apply first facet as additional search criteria
facetManager.getFacetGroup( "priceFaceting" ).selectFacets( facets.get( 0 ) );

// re-execute the query
cds = fullTextQuery.list();
assertTrue(cds.size() == 2);

Lucene インデックスの主な機能はクエリーの一致を特定することです。クエリーが実行された後、有用な情報を抽出するために結果を分析する必要があります。通常、Hibernate Search は Class タイプと主キーを抽出する必要があります。

インデックスから必要な値を抽出すると、パフォーマンスに負担がかかります。負担が大変小さくて気がつかないこともありますが、キャッシュした方がよい場合もあります。

要件は使用される射影の種類によって異なります。クエリーコンテキストなどから推測できる場合、Class 型は必要ありません。

@CacheFromIndex アノテーションを使用すると、Hibernate Search が必要とする主なメタデータフィールドの異なるキャッシュ方法を試すことができます。

import static org.hibernate.search.annotations.FieldCacheType.CLASS;
import static org.hibernate.search.annotations.FieldCacheType.ID;

@Indexed
@CacheFromIndex( { CLASS, ID } )
public class Essay {
    ...

このアノテーションを使用して Class 型および ID をキャッシュすることはできません。

FieldCache を使用するデメリットは 2 つあります。

クエリーによっては、クラス型が必要でない場合があります。このような場合、CLASS フィールドキャッシュを有効にしても使用されないことがあります。たとえば、単一のクラスを対象とする場合、戻り値はすべてその型になります (クエリーの実行ごとに評価されます)。

ID FieldCache を使用する場合、対象エンティティーの ID は (構築するすべてのブリッジとして) TwoWayFieldBridge を使用する必要があります。特定のクエリーにロードされるすべての型は ID にフィールド名を使用し、同じ型の ID を持つ必要があります (クエリーの実行ごとに評価されます）。

このストラテジーでは、既存のインデックスを削除した後、FullTextSession.purgeAll() および FullTextSession.index() を使用してすべてのエンティティーをインデックスに戻しますが、メモリーと効率性の制約があります。効率性を最大化にするために、Hibernate Search はインデックスの操作を一括してコミット時に実行します。大量のデータをインデックス化することが想定される場合は、トラザクションがコミットされるまですべてのドキュメントがキューに保持されるため、メモリーの消費に注意する必要があります。キューを周期的に空にしないと OutOfMemoryException が発生する可能性があります。キューを空にするには、fullTextSession.flushToIndexes() を使用します。fullTextSession.flushToIndexes() が呼び出されるたびに (またはトランザクションがコミットされると) バッチキューが処理され、インデックスのすべての変更が適用されます。1 度フラッシュすると変更をロールバックできないことに注意してください。

例: index() および flushToIndexes() を使用したインデックスの再構築

fullTextSession.setFlushMode(FlushMode.MANUAL);
fullTextSession.setCacheMode(CacheMode.IGNORE);
transaction = fullTextSession.beginTransaction();
//Scrollable results will avoid loading too many objects in memory
ScrollableResults results = fullTextSession.createCriteria( Email.class )
    .setFetchSize(BATCH_SIZE)
    .scroll( ScrollMode.FORWARD_ONLY );
int index = 0;
while( results.next() ) {
    index++;
    fullTextSession.index( results.get(0) ); //index each element
    if (index % BATCH_SIZE == 0) {
        fullTextSession.flushToIndexes(); //apply changes to indexes
        fullTextSession.clear(); //free memory since the queue is processed
    }
}
transaction.commit();

アプリケーションがメモリー不足にならないバッチサイズを使用するようにしてください。バッチサイズを大きくするとデータベースからオブジェクトをフェッチする速度が速くなりますが、より多くのメモリーが必要になります。

Hibernate Search の MassIndexer は複数の平行スレッドを使用してインデックスを再構築します。オプションで、リロードが必要なエンティティーを選択したり、すべてのエンティティーを再インデックス化したりできます。この方法はパフォーマンスを最大化するために最適化されますが、アプリケーションをメンテナンスモードに設定する必要があります。MassIndexer がビジー状態のときはインデックスのクエリーは推奨されません。

例: MassIndexer を使用したインデックスの再構築

fullTextSession.createIndexer().startAndWait();

これは、インデックスを再構築して削除し、データベースからすべてのエンティティーをリロードします。これは簡単に使用できますが、プロセスを迅速にするために多少の調整を行うことが推奨されます。

例: 調整された MassIndexer の使用

fullTextSession
 .createIndexer( User.class )
 .batchSizeToLoadObjects( 25 )
 .cacheMode( CacheMode.NORMAL )
 .threadsToLoadObjects( 12 )
 .idFetchSize( 150 )
 .progressMonitor( monitor ) //a MassIndexerProgressMonitor implementation
 .startAndWait();

この例では、すべての User インスタンス (およびサブタイプ) のインデックスが再構築され、クエリーごとに 25 個のオブジェクトのバッチを使用して User インスタンスをロードするために 12 個の平行スレッドが作成されます。Lucene ドキュメントを出力するために、これらの 12 個のスレッドは、インデックス化された埋め込み関係と、カスタムの FieldBridges または ClassBridges を処理する必要もあります。スレッドによって、変換の処理中に追加属性のレイジーローディングがトリガーされます。そのため、平行して動作するスレッドが大量に必要になります。実際のインデックスの書き込みを行うスレッドの数は、各インデックスのバックエンド設定によって定義されます。

インデックス化を行うほとんどの場合で、キャッシュは不必要なオーバーヘッドになるため、cacheMode を CacheMode.IGNORE (デフォルト) のままにしておくことが推奨されます。メインエントリーがインデックスに含まれる列挙に似たデータである場合は、データに応じて他の CacheMode の一部を有効にするとパフォーマンスが向上する可能性があります。

インデックス化の時間やメモリーの消費に影響するその他のパラメーターは次のとおりです。

以前のバージョンでは max_field_length を使用できましたが、これは Lucene から削除されました。LimitTokenCountAnalyzer を使用すると同様の効果を得ることができます。

.indexwriter はすべて Lucene 固有のパラメーターで、Hibernate Search はこれらのパラメーターを渡します。

MassIndexer は、前方のみスクロール可能な結果を使用して、ロードされる主キーで反復処理を行いますが、MySQL の JDBC ドライバーはメモリーのすべての値をロードします。この「最適化」が実行されないようにするには、idFetchSize を Integer.MIN_VALUE に設定します。