中央のサービス API はサービス自体以外に、org.hibernate.service.ServiceRegistry インターフェイスです。サービスレジストリーの主な目的は、サービスへのアクセスを保持し、管理し、提供することです。

サービスレジストリーは階層的です。あるレジストリーのサービスは、同じレジストリーのサービスや任意の親レジストリーに依存して使用できます。

org.hibernate.service.ServiceRegistryBuilder を使用して org.hibernate.service.ServiceRegistry インスタンスをビルドします。

ServiceRegistryBuilder registryBuilder =
    new ServiceRegistryBuilder( bootstrapServiceRegistry );
    ServiceRegistry serviceRegistry = registryBuilder.buildServiceRegistry();

org.hibernate.service.ServiceRegistry を構築すると、不変とみなされます。このサービス自体は再設定を受け入れる可能性がありますが、ここでの不変性はサービスの追加または置き換えを意味します。そのため、org.hibernate.service.ServiceRegistryBuilder で利用できる別のロールは、これから生成される org.hibernate.service.ServiceRegistry に含まれるサービスの調整を許可することです。

カスタムサービスについて org.hibernate.service.ServiceRegistryBuilder に指示する方法は 2 つあります。

新規サービ出力ルの追加やサービス実装の置き換えなどサービスの上書きなど、レジストリーの拡張にはいずれかのアプローチが有効です。

ServiceRegistryBuilder registryBuilder =
    new ServiceRegistryBuilder(bootstrapServiceRegistry);
registryBuilder.addService(JdbcServices.class, new MyCustomJdbcService());
ServiceRegistry serviceRegistry = registryBuilder.buildServiceRegistry();

public class MyCustomJdbcService implements JdbcServices{

   @Override
   public ConnectionProvider getConnectionProvider() {
       return null;
   }

   @Override
   public Dialect getDialect() {
       return null;
   }

   @Override
   public SqlStatementLogger getSqlStatementLogger() {
       return null;
   }

   @Override
   public SqlExceptionHelper getSqlExceptionHelper() {
       return null;
   }

   @Override
   public ExtractedDatabaseMetaData getExtractedMetaDataSupport() {
       return null;
   }

   @Override
   public LobCreator getLobCreator(LobCreationContext lobCreationContext) {
       return null;
   }

   @Override
   public ResultSetWrapper getResultSetWrapper() {
       return null;
   }
}

boot-strap レジストリーは、ほとんどの機能を機能させるために絶対に利用できるようにする必要のあるサービスを保持します。ここでの主要なサービスは、ClassLoaderService です。これは最適な例です。設定ファイルを解決する場合でも、クラスローディングサービス (例: リソース検索) へのアクセスが必要になります。これは、通常の使用時に親ではなく、ルートレジストリーです。

boot-strap レジストリーのインスタンスは、org.hibernate.service.BootstrapServiceRegistryBuilder クラスを使用して作成されます。

BootstrapServiceRegistryBuilder の使用

BootstrapServiceRegistry bootstrapServiceRegistry =
    new BootstrapServiceRegistryBuilder()
    // pass in org.hibernate.integrator.spi.Integrator instances which are not
    // auto-discovered (for whatever reason) but which should be included
    .with(anExplicitIntegrator)
    // pass in a class loader that Hibernate should use to load application classes
    .with(anExplicitClassLoaderForApplicationClasses)
    // pass in a class loader that Hibernate should use to load resources
    .with(anExplicitClassLoaderForResources)
    // see BootstrapServiceRegistryBuilder for rest of available methods
    ...
    // finally, build the bootstrap registry with all the above options
    .build();

org.hibernate.event.service.spi.EventListenerRegistry

org.hibernate.integrator.spi.Integrator の主なユースケースは、イベントリスナーを登録し、サービスを提供します。org.hibernate.integrator.spi.ServiceContributingIntegrator を参照してください。

public class MyIntegrator implements org.hibernate.integrator.spi.Integrator {

    public void integrate(
            Configuration configuration,
            SessionFactoryImplementor sessionFactory,
            SessionFactoryServiceRegistry serviceRegistry) {
        // As you might expect, an EventListenerRegistry is the thing with which event listeners are registered  It is a
        // service so we look it up using the service registry
        final EventListenerRegistry eventListenerRegistry = serviceRegistry.getService(EventListenerRegistry.class);

        // If you wish to have custom determination and handling of "duplicate" listeners, you would have to add an
        // implementation of the org.hibernate.event.service.spi.DuplicationStrategy contract like this
        eventListenerRegistry.addDuplicationStrategy(myDuplicationStrategy);

        // EventListenerRegistry defines 3 ways to register listeners:
        //     1) This form overrides any existing registrations with
        eventListenerRegistry.setListeners(EventType.AUTO_FLUSH, myCompleteSetOfListeners);
        //     2) This form adds the specified listener(s) to the beginning of the listener chain
        eventListenerRegistry.prependListeners(EventType.AUTO_FLUSH, myListenersToBeCalledFirst);
        //     3) This form adds the specified listener(s) to the end of the listener chain
        eventListenerRegistry.appendListeners(EventType.AUTO_FLUSH, myListenersToBeCalledLast);
    }
}

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

Lucene モードでは、ノードのすべてのインデックス更新は、ディレクトリープロバイダーを使用して同じノードから Lucene ディレクトリーに対して実行されます。このモードは、クラスター化されていない環境や、共有ディレクトリーストアを持つクラスター環境で使用します。

図7.1 Lucene バックエンド設定

Lucene モードは、ディレクトリーがロックストラテジーを管理するクラスター化またはクラスター化されたアプリケーションをターゲットに設定します。Lucene モードの主な利点は、Lucene クエリーの変更の単純化と即時表示です。Near Real Time (NRT) バックエンドは、クラスター化されていないインデックス設定や共有されていないインデックス設定の代替バックエンドです。

ノードのインデックス更新は Jakarta Messaging キューに送信されます。一意のリーダーはキューを処理し、マスターインデックスを更新します。マスターインデックスはその後、スレーブコピーに定期的に複製され、マスターとスレーブのパターンを確立します。マスターは Lucene インデックスの更新を行います。スレーブは読み取りおよび書き込み操作を受け入れますが、ローカルインデックスコピーの読み取り操作を処理します。マスターは Lucene インデックスの更新のみを行います。更新操作にローカルの変更を適用するのは、マスターのみです。

図7.2 Jakarta Messaging Service バックエンドの設定

このモードは、スループットが重要で、インデックス更新の遅延が許容できるクラスター化された環境をターゲットとします。Jakarta Messaging プロバイダーは信頼性を確保し、スレーブを使用してローカルインデックスコピーを変更します。

shared ストラテジーを使用すると、Hibernate Search は、IndexReader が更新され続ける場合に、複数のクエリーおよびスレッドにわたる特定の Lucene インデックスに対して同じ IndexReader を共有します。IndexReader が更新されない場合は、新しい IndexReader が開かれて提供されます。各 IndexReader は複数の SegmentReaders で設定されています。共有ストラテジーは、前回開いた後に修正または作成されたセグメントを分離し、以前のインスタンスのすでにロードされているセグメントを共有します。これはデフォルトのストラテジーです。

non-shared ストラテジーを使用すると、クエリーが実行されるたびに Lucene IndexReader が開かれます。IndexReader の開始と起動は、高価な操作です。そのため、各クエリー実行で IndexReader を開くことは効率的なストラテジーではありません。

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

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

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

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

Near Real Time 設定は、上記のデメリットとマスターノードを個別に設定できるため、データが限定されたクラスター化されていない Web サイトに対して推奨されます。

カスタム実装の完全修飾クラス名を指定して、カスタマイズされた IndexManager を設定します。以下のように、実装に no-argument コンストラクターを設定します。

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

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

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

図7.3 Jakarta Messaging バックエンドの設定

すべてのインデックス更新操作は Jakarta Messaging キューに送信されます。インデックスクエリー操作は、ローカルインデックスコピーで実行されます。

### 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 Jakarta Messaging 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

すべてのインデックス更新操作は Jakarta Messaging キューから取得され、実行されます。マスターインデックスは定期的にコピーされます。

Jakarta Messaging キューのインデックス更新操作は実行され、マスターインデックスは定期的にコピーされます。

### 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

Hibernate Search フレームワークの設定に加えて、Jakarta Messaging を介してインデックスを処理するようメッセージ駆動 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 ソースコードで利用可能な抽象 Jakarta Messaging コントローラークラスから継承し、Jakarta EE MDB を実装します。この実装は例として提供されており、Jakarta EE 以外のメッセージ駆動 Bean を利用するように調整できます。

Hibernate Search は、mergeFactor、maxMergeDocs、maxBufferedDocs など、基礎となる Lucene IndexWriter に渡される一連のパラメーターを指定することで Lucence インデクスパフォーマンスを調整するのに使用されます。これらのパラメーターは、インデックスベースまたはシャードごとに、すべてのインデックスに適用されるデフォルト値として指定します。

各種ユースケースに合わせて調整できる低レベルの IndexWriter 設定がいくつかあります。これらのパラメーターは、indexwriter キーワードでグループ化されます。

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

特定のシャード設定の indexwriter 値に値が設定されていないと、Hibernate Search は index セクションをチェックしてから default セクションをチェックします。

以下の表の設定により、Animal インデックスの 2 つ目のシャードにこれらの設定が適用されます。

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

デフォルトでは、すべての値は Lucene の独自のデフォルトのままにします。Indexing Performance and Behavior Properties に一覧表示される値は、使用している Lucene のバージョンに応じて異なります。上記の値はバージョン 2.4 に相対的です。

各種ユースケースに合わせて調整できる低レベルの IndexWriter 設定がいくつかあります。これらのパラメーターは、indexwriter キーワードでグループ化されます。

default.<indexname>.indexwriter.<parameter_name>

シャード設定で indexwriter の値が設定されていない場合、Hibernate Search は index セクションを参照し、デフォルトのセクションを探します。

以下の設定では、これらの設定が 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

マージセグメントが 2 つの大きなセグメントに結合するため、マージ操作の max_size はハード制限セグメントサイズの半分未満に設定します。

新しいセグメントは、当初は予想よりも大きくなる場合がありますが、セグメントが ram_buffer_size よりも大きく作成されることは決してありません。このしきい値は予測としてチェックされます。

エンティティーのマッピングに最も一般的に使用されるアノテーションから始めましょう。

Lucene ベースの Query API は、以下の共通アノテーションを使用してエンティティーをマッピングします。

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

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

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

エンティティーのプロパティー (または属性) ごとに、インデックス化方法を記述する機能があります。デフォルト (アノテーションなし) は、インデックスプロセスによってプロパティーが無視されることを意味します。

@Field はプロパティーをインデックスとして宣言し、以下の属性のいずれかを設定してインデックスプロセスの複数の側面を設定できます。

@Field には @NumericField というコンパニオンアノテーションがあり、@Field または @DocumentId と同じスコープで指定できます。このプロパティーは、Integer、Long、Float、および LastName プロパティーに指定できます。インデックスの作成時に、値は Trie 構造を使用してインデックス化されます。プロパティーを数字フィールドとしてインデックス化すると、標準的な @Field プロパティーに対して同じクエリーを実行するよりも、効率的な範囲クエリーとソートが可能になります。@NumericField アノテーションは以下のパラメーターを受け入れます。

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

タイプ変換中に概算を処理できると仮定した場合は、カスタムの 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 (identifier) プロパティーは、特定のエンティティーのインデックスを一意に保つために Hibernate Search で使用される特別なプロパティーです。設計上、id は保存する必要があり、トークン化しないでください。プロパティーをインデックス識別子としてマークするには、@DocumentId アノテーションを使用します。Jakarta Persistence を使用し、@Id を指定すると @DocumentId を省略できます。選択したエンティティー ID は、ドキュメント識別子として使用されます。

Infinispan Query はエンティティーの 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 のフィールドを持つインデックスを定義します。デフォルトでは、JavaBean 仕様にしたがってフィールド名は大文字では表示されないことに注意してください。Grade フィールドは、デフォルトよりも若干精度の高いステップで数字としてアノテーションが付けられます。

若干異なるインデックスストラテジーで、インデックスごとにプロパティーを複数回マップする必要がある場合があります。たとえば、フィールド別にクエリーを並び替えるには、フィールドを分析解除する必要があります。このプロパティーの単語で検索し、これをソートするには、分析後と未分析のときにインデックス付けする必要があります。これは、@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、非トークン化方式の summary_forSort で行われます。

関連オブジェクトおよび組み込みオブジェクトは、ルートエンティティーインデックスの一部としてインデックス化できます。これは、関連するオブジェクトのプロパティーに基づいて特定のエンティティーを検索する場合に役に立ちます。関連する都市が Atlanta である場所を返すことを目的としています (Lucene クエリーパーサー言語で、address.city:Atlanta に変換されます)。場所フィールドは、Place インデックスでインデックス化されます。Placement インデックスドキュメントには、クエリー可能な 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 オブジェクトの変更を認識する必要があります。Lucene ドキュメントが Address の変更時に更新されるようにするには、双方向関係の反対側に @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 プロパティーは、オブジェクトグラフにクラス (インスタンスではない) の cyclic 依存関係が含まれるときに必要になります。たとえば、Owner が Place をポイントする場合です。Hibernate Search は、予想される深さに達すると (またはオブジェクトグラフの境界に到達する)、インデックス化された組み込み属性を含まなくなります。自己参照を持つクラスは、cyclic 依存関係の例です。この例では、depth が 1 に設定されているため、Owner の @IndexedEmbedded 属性は無視されます。

オブジェクト関連付けに @IndexedEmbedded を使用すると、以下のようなクエリーを表現できます (Lucene のクエリー構文を使用)。

この動作は、より効率的な方法 (データの重複が犠牲となる) でのリレーショナルジョイン操作の操作に似ています。初期状態の Lucene インデックスには関連付けの概念がないため、join 操作が存在しないことに注意してください。これは、完全なテキストインデックスの速度と機能が充実した状態で、リレーショナルデータベースを維持するのに役立ちます。

@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 アノテーションは、属性 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 の検索 w お行うことができます。親の surname をインデックス化しないため、親の surname を検索することはできません。ただし、インデックス作成を迅速化し、スペースを節約して、全体的なパフォーマンスを向上させることができます。

@IndexedEmbeddedincludePaths には、通常はデプスの制限された値を指定するのに加え、指定されたパスが含まれます。IncludePaths を使用し、デプスを未定義のままにすると、depth=0 を設定するのと同等の動作になります。含まれるパスのみがインデックス化されます。

@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) の名前と surname 属性にインデックスが付けられます。また、depth 属性が原因で、親の名前と surname (姓) も再帰的に 2 行目にインデックス化されます。人が直接、自身の親、または親の名前で検索することができます。第 2 レベル以外では、姓 (surname) ではなく、もう 1 レベル (名前のみ) をインデックス化します。

これにより、インデックスに以下のフィールドが生成されます。

インデックス化されたパスを明示的に制御することは、必要なクエリーを最初に定義してアプリケーションを設計する場合に容易になる可能性があります。この時点では、どのフィールドが必要かを正確に把握している可能性もあります。その他のどのフィールドがユースケースを実装する必要はありません。

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

@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 重要になります (2 * 1.5。これは、isbn フィールドよりも @Field.boost および @Boost が累積的であるためです)。Text フィールドは isbn フィールドよりも 1.2 倍重要になります。この説明は、最も厳格な条件では間違っていますが、あらゆる実用的な目的において、実用性に十分に近い点に注意してください。

Static Index Time Boosting (静的インデックスの時間の改善) で使用される @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;
        }
    }
}

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

当然ながら、エンティティーで @Boost と @DynamicBoost DynamicBoost アノテーションを混在させることができます。定義されたすべてのブースター要素は累積的です。

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

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

@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;
    ...
}

この例では、EntityAnalyzer を使用して、PropertyAnalyzer と FieldAnalyzer でインデックス化される summary と body を除き トークン化されたプロパティー (name) をインデックス化します。

アナライザーの処理は非常に複雑になる可能性があります。このため、Hibernate Search にはアナライザ定義の概念が導入されました。アナライザ定義は、@Analyzer 宣言の多くで再利用でき、以下で設定されています。

タスクの分離: 文字型フィルターのリストとトークンライザー、およびフィルターの一覧が続きます。これにより、個々のコンポーネントを簡単に再利用でき、(Lego など) 非常に柔軟な方法でカスタマイズされたアナライザーを構築することができます。一般的に、文字型フィルターは文字入力で一部の事前処理を実行し、Tokenizer は、文字入力を TokenFilters によってさらに処理されるトークンに変換してトークン処理を開始します。Hibernate Search は Solr Analyzer フレームワークを使用してこのインフラストラクチャーをサポートします。

以下に記載されている具体的な例を見てみましょう。まず、文字型フィルターはファクトリーによって定義されます。この例では、マッピング文字型フィルターが使用され、マッピングファイルに指定されたルールに基づいて入力内の文字が置き換えられます。次にトークナイザーを定義します。この例では、標準トークナイザーを使用します。最後に同じように重要に、のフィルターの一覧がファクトリーによって定義されます。この例では、StopFilter フィルターは、専用の用語プロパティーファイルを読み取ります。フィルターはケースを無視することも予想されます。

@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 {
    ...
}

一部のトークナイザー、トークンフィルター、または文字型フィルターは、設定ファイルやメタデータファイルなどのリソースを読み込みます。これは、ストップフィルターと同意フィルターの例になります。リソース文字セットが仮想マシンのデフォルトを使用していない場合は、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 で宣言された Analyzer インスタンスは、SearchFactory の名前でも利用できます.これは、クエリーを構築する際に非常に便利です。

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

クエリー内のフィールドは、共通の言語を伝えるためにフィールドのインデックス作成に使用するものと同じアナライザーで分析する必要があります。クエリーとインデックス作成プロセス間で同じトークンが再利用されます。このルールには例外がありますが、ほとんどの場合に当てはまります。実際に何を実行しているのかが分からない限り、それに従ってください。

Solr および Lucene には、多くの便利なデフォルトの文字型フィルター、トークンサイザー、およびフィルターがあります。文字型フィルターファクトリー、トークン化ファクトリー、およびフィルターファクトリーの完全な一覧は、http://wiki.apache.org/solr/AnalyzersTokenizersTokenFilters にあります。それらのいくつかをチェックしてください。

IDE で org.apache.lucene.analysis.TokenizerFactory and org.apache.lucene.analysis.TokenFilterFactory のすべての実装を確認して、利用可能な実装を確認することが推奨されます。

現時点で、アナライザーを指定する方法はすべて静的でした。ただし、インデックスを作成するエンティティーの現在の状態 (たとえば多言語アプリケーション) に応じてアナライザーを選択すると便利なユースケースがあります。たとえば、BlogEntry クラスの場合、アナライザーはエントリーの言語プロパティーに依存する可能性があります。このプロパティーによっては、実際のテキストにインデックスを付けるために正しい言語固有のスチーマーを選択する必要があります。

この動的アナライザーを有効にするために、Hibernate Search で 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 パラメーターを使用すると、Dicriminator インターフェイスの具体的な実装を指定できます。このインターフェイスの実装は、ユーザー自身が提供する必要があります。実装が必要な唯一の方法は getAnalyzerDefinitionName() で、これは Lucene ドキュメントに追加された各フィールドに対して呼び出されます。インデックスを取得するエンティティーもインターフェイスメソッドに渡されます。value パラメーターは、AnalyzerDiscriminator がクラスレベルではなくプロパティーレベルに配置されている場合にのみ設定されます。この場合、値はこのプロパティーの現在の値を表します。

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

上記の例では、song タイトルが 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 を使用する場合は、パラメーターを同等の文字列に変換する必要があります。また、正しいアナライザーを正しいフィールドに適用する必要もあります。たとえば、ngram アナライザーは、特定の単語に対するトークンとして複数の ngrams を使用するため、そのように検索する必要があります。このタスクには QueryBuilder を使用することが推奨されます。

Hibernate Search のクエリー API は変動しており、以下の主要な特徴があります。

API を使用するには、まず、指定の indexedentitytype に割り当てられるクエリービルダーを作成します。この QueryBuilder は、使用するアナライザーと、適用するフィールドブリッジを認識します。複数の QueryBuilder (クエリーのルートに関連するエンティティータイプごとに 1 つ) を作成できます。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 プログラム API を使用してアセンブルされた Lucene のクエリーパーサーまたはクエリーオブジェクトを使用して生成されたカスタマイズされたクエリーは、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 実装) がある場合、すべてのオブジェクトに対して機能します。

以下の例では、ngram アナライザーを使用するフィールドを検索します。ngram アナライザーは単語の ngrams インデックスを連続させるため、ユーザーの誤字を防ぎます。たとえば、hibernate という単語の 3 グラムは 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 つのグラム (sis、isi、sip、iph、phu、hus) に分けられます。これらの各 ngram はクエリーの一部になります。ユーザーは、Sysiphus myth ( y) を見つけることができます。ユーザーに透過的に実行されます。

同一フィールドで複数の使用可能な単語を検索するには、それらすべてを一致するシーケンスに追加します。

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

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

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 距離アルゴリズムに基づく fuzzy クエリーを実行するには、keyword クエリーから始め、fuzzy フラグを追加します。

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

threshold は、両方の用語で照合が考慮される制限です。0 から 1 までの小数で、デフォルト値は 0.5 です。prefixLength は、fuzzyness で無視される接頭辞の長さです。デフォルト値は 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 係数を追加することで検索できます。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 クエリーにすることができます。

//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();

//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();

//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() の方が適しています。完了したら、Lucene リソースを保持するため、Scrollable Mission オブジェクトを閉じることを忘れないでください。スクロールを使用することが予測されても、オブジェクトを一括して読み込む必要がある場合は、query.setFetchSize() を使用できます。オブジェクトにアクセスし、読み込まれていない場合、Hibernate Search は次の fetchSize オブジェクトをパスに読み込みます。

一致するドキュメントの合計数を把握しておくと役に立つ場合があります。

当然ながら、一致するドキュメントをすべて取得することはできません。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 == ;

プロジェクション結果はオブジェクト配列として返されます。オブジェクトに使用されるデータ構造がアプリケーションの要件と一致しない場合は、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 実装の例は、ibernate Core codebase を参照してください。

クエリーの結果が適切でない場合、Luke ツールは結果を理解する際に役立ちます。ただし、Hibernate Search を使用すると、所定の結果 (特定のクエリー内) の Lucene Explanation オブジェクトにアクセスできます。このクラスは Lucene ユーザーに非常に高度なものとみなされますが、オブジェクトの性質をよく理解することができます。特定の結果について Explanation オブジェクトにアクセスするには、以下のいずれかの方法があります。

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

次の方法では、FullTextQuery.EXPLANATION 定数を使用して 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

この例では、クエリーの上に複数のフィルターを有効化しています。フィルターはいくつでも有効または無効にできます。

宣言フィルターは @FullTextFilterDef アノテーションを使用して実行されます。このアノテーションは、フィルターが後に適用されるクエリーに関係なく、@Indexed エンティティーに設定できます。これは、フィルター定義がグローバルであり、名前が一意である必要があることを意味します。同じ名前を持つ @FullTextFilterDef アノテーションが定義される場合は、SearchException が発生します。名前付きの各フィルターは、実際のフィルター実装を指定する必要があります。

@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 は簡単な Lucene フィルターの例です。これにより、スコアが 5 のドライバーに設定された結果が減少します。この例では、指定したフィルターは org.apache.lucene.search.Filter を直接実装し、no-arg コンストラクターが含まれます。

フィルターの作成に追加のステップが必要な場合や、使用するフィルターに no-arg コンストラクターがない場合は、ファクトリーパターンを使用できます。

@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 アノテーションが付けられたメソッドを検索し、そのメソッドを使用してフィルターインスタンスを作成します。ファクトリーには no-arg コンストラクターが必要です。

Infinispan Query は @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() を実装し、指定される Filter タイプが同一で、パラメーターのセットが同じである場合にのみ、両方の鍵が同じになるようにする必要があります。つまり、鍵の生成元となるフィルターが交換可能な場合、あるいは交換可能である場合にのみ、両方のフィルター鍵が同等になります。キーオブジェクトは、キャッシュメカニズムのキーとして使用されます。

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

多くの場合、StandardFilterKey 実装を使用すれば十分です。これは、equals() / hashCode() 実装をそれぞれのパラメーター equals および hashcode メソッドに委譲します。

定義されたフィルターがデフォルトのキャッシュされ、キャッシュは、必要に応じてハード参照とソフト参照の組み合わせを使用してメモリーの破損を可能にします。ハード参照キャッシュは、最近使用されたフィルターを追跡し、必要に応じて SoftReferences に最も使用されるフィルターを変換します。ハード参照キャッシュの制限に達すると、追加のフィルターが SoftReferences としてキャッシュされます。ハード参照キャッシュのサイズを調整するには、hibernate.search.filter.cache_strategy.size (デフォルトは 128 に設定) を使用します。フィルターキャッシングの高度な使用のために、独自の FilterCachingStrategy を実装します。classname は hibernate.search.filter.cache_strategy によって定義されます。

このフィルターキャッシュメカニズムは、実際のフィルター結果をキャッシュするのと混同しないようにしてください。Lucene では、CachingWrapperFilter を中心に IndexReader を使用してフィルターをラッピングすることが一般的です。ラッパーは、getDocIdSet(IndexReader reader) メソッドから返される 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 に設定) を使用して調整できます。ラッピング動作は、the@FullTextFilterDef.cache パラメーターを使用して制御できます。このパラメーターには、以下の異なる値があります。

フィルターは以下の状況でキャッシュする必要があります。

シャード化された環境では、利用可能なシャードのサブセットでクエリーを実行することができます。これを行う方法は 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;
     }
    }

この例では、custom という名前のフィルターがある場合、この顧客専用のシャードのみがクエリーされ、それ以外の場合はすべてのシャードが返されます。所定のシャード化ストラテジーは、単一または複数のフィルターに対応し、それらのパラメーターに依存します。

次のステップでは、クエリー時にフィルターをアクティブにします。フィルターは、クエリーの後に 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 を使用して Lucene フィルターを実装する必要はありません。シャード化された環境のクエリーを加速するには、これらのフィルターに対応するフィルターおよびシャード化ストラテジーを使用することが推奨されます。

ファセット検索に対する最初のステップは、FacetingRequest を作成することです。現時点では、2 種類のセッティング要求がサポートされています。最初のタイプは discrete faceting と呼ばれ、次のタイプは range faceting 要求と呼ばれます。個別のファセットリクエストの場合は、ファセット (分類) を行うインデックスフィールドと、適用するファセットオプションを指定します。個別のファセッティング要求の例は、以下の例で確認できます。

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 インスタンスは、元のクエリー結果内でこの特定のフィールドの値が発生する頻度を含む実際のフィールド値を記録します。orderdBy、includeZeroCounts および maxFacetCount は任意のオプションのパラメーターで、すべてのファセット要求に適用できます。ordersBy では、作成されたブックマークが返される順序を指定できます。デフォルトは FacetSortOrder.COUNT_DESC ですが、フィールドの値または範囲の指定順序でソートすることもできます。includeZeroCount は、結果内に含まれるブックマーク数 (デフォルトでは 0) を判断し、maxFacetCount により、返されるワイルドカードの最大数を制限できます。

一定の範囲のファセットリクエストの作成は、ブックマークするフィールド値の範囲を指定する必要がある点以外は非常に似ています。一定の範囲のファセットリクエストは、複数の異なるレート範囲が指定されている場合に以下で確認できます。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() メソッドは、名前を指定してブックマーク要求を無効にします。

最後でも重要ですが、ドルダウン機能を実装するために、元のクエリーに追加の基準として返されたすべての Facets を適用できます。そのためには、FacetSelection を使用できます。FacetSelections は FacetManager 経由で利用可能で、クエリー基準としてファセットを選択できます。(selectFacets)、ファセットの制限を削除して、すべてのファセット制限 (deselectFacets) を削除し、現在選択しているすべてのファセット (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 はクラスターイプとプライマリーキーを抽出する必要があります。

インデックスから必要な値を抽出するには、パフォーマンス負荷がかかります。パフォーマンス負荷が極めて低く、気付かない場合もありますが、キャッシュを行うのに役立つ場合もあります。

この要件は、使用されている Projections によって異なります。これは、クラスターイプがクエリーコンテキストまたは他の方法で推測される可能性があるため、クラスターイプが不要なためです。

@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 {
    ...

このアノテーションを使用してクラスターイプと ID をキャッシュできます。

FieldCache の使用は、以下の点を考慮してください。

一部のクエリーでは、クラスターイプは全く不要です。その場合、CLASS フィールドキャッシュを有効にしても使用されない可能性があります。たとえば、単一クラスをターゲットとしている場合は、返される値はすべてそのタイプのものになります (これは各クエリー実行時に評価されます)。

ID FieldCache を使用するには、ターゲットエンティティーの ID が TwoWayFieldBridge (すべてのブリッジの構築として) を使用し、特定のクエリーに読み込まれるすべてのタイプが id のフィールド名を使用し、同じタイプの ID が割り当てられている必要があります (これは各クエリー実行時に評価されます)。

このストラテジーは、既存のインデックスを削除してから、FullTextSession.purgeAll() および FullTextSession.index() を使用してすべてのエンティティーをインデックスに戻すことで設定されますが、メモリーと効率の制約があります。効率を最大限に高めるためにも、Hibernate Search はインデックス操作をバッチ処理し、コミット時に実行します。大量のデータをインデックス化する場合は、トランザクションがコミットされるまですべてのドキュメントがキューに保存されるため、メモリー消費について注意する必要があります。キューを定期的に空にしない場合は、OutOfMemoryException が発生する可能性があります。これには fullTextSession.flushToIndexes() を使用します。FullTextSession.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 がビジーな場合、インデックスのクエリーは推奨されません。

fullTextSession.createIndexer().startAndWait();

これにより、インデックスが再構築され、インデックスが削除されてから、データベースからすべてのエンティティーが再読み込みされます。簡単に使用できますが、プロセスのスピードを上げるために調整を行うことが推奨されます。

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

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

Cachemode を CacheMode.IGNORE (デフォルト) のままにすることが推奨されます。これは、ほとんどの場合でキャッシュが不要な追加オーバーヘッドになるためです。メインのエンティティーがインデックスに含まれる列挙のようなデータに関連する場合は、パフォーマンスを向上させる可能性があるため、データに応じて他の CacheMode を有効にすると便利です。

インデックス処理にかかる時間やメモリー消費量に影響を与える他のパラメーターには、以下が含まれます。

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

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

MassIndexer は、前方のみのスクロール可能な結果を使用して、読み込まれるプライマリーキーを繰り返し処理しますが、MySQL の JDBC ドライバーはメモリーのすべての値を読み込みます。この最適化を回避するには、idFetchSize を Integer.MIN_VALUE に設定します。