除服务本身外，中央服务 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 相关信息。

这两种方法都可用于扩展注册表，例如添加新的服务角色和覆盖服务，如替换服务实施。

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 类构建。

Using 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 消息传递队列。唯一的读取器处理队列并更新主索引。随后，主索引定期复制到从副本，从而建立主和从模式。主控机负责 Lucene 索引更新。slave 接受读写操作，但处理本地索引副本中的读取操作。主设备全权负责更新 Lucene 索引。仅 master 应用更新操作中的本地更改。

图 7.2. Jakarta 消息传递服务后端配置

此模式面向集群环境，其中吞吐量至关重要，并且可以节省索引更新延迟。Jakarta 消息传递供应商确保可靠性，并使用从设备更改本地索引副本。

使用 共享 策略，Hibernate Search 对给定的 Lucene 索引在多个查询和线程间共享相同的 IndexReader，但提供 IndexReader 保持更新。如果没有更新 IndexReader，则会打开并提供新的索引。每个 IndexReader 由多个 Segment Readers 组成。共享策略重新打开最后一次打开后修改或创建的片段，并共享上一实例中已加载的网段。这是默认的策略。

使用 not-shared 策略时，Lucene IndexReader 每次执行查询时都会打开。打开并启动 index Reader 是一个代价昂贵的操作。因此，为每个查询执行打开 index Reader 不是有效的策略。

您可以使用 org.hibernate.search.reader.ReaderProvider 编写自定义 reader 策略。实施必须安全进行。

基于目录 的实施是默认的 IndexManager 实施。它高度可配置，允许为 reader 策略、后端和目录提供程序进行单独的配置。

NRTIndexManager 是默认 索引管理器 的扩展，它利用 Lucene NRT、Near Real Time（低延迟索引写入）功能。但是，它会忽略 lucene 以外的备用后端的配置设置，并在 目录 上获取专用写入锁定。

IndexWriter 不会刷新磁盘的每个更改来提供低延迟。查询可以从未清空的索引写入缓冲区读取更新的状态。但是，这意味着如果 IndexWriter 被终止或应用程序崩溃，可能会丢失更新，因此必须重建索引。

由于上述缺点，建议对数据有限的非集群网站采用 Near Real Time 配置，因为可以单独配置主节点以提高性能。

为自定义实现指定完全限定类名称，以设置自定义 IndexManager。为实施设置 no-gument 构造器，如下所示：

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

自定义索引管理器实现不需要与默认实施相同的组件。例如，委派到不公开 目录 接口的远程索引服务。

这部分论述了如何配置主/从 Hibernate Search 架构。

图 7.3. Jakarta 消息传递后端配置

每个索引更新操作都会发送到 Jakarta 消息传递队列。索引查询操作在本地索引副本中执行。

### 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 消息传递队列执行并执行。主索引定期复制。

执行 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 框架配置外，还必须编写和设置消息驱动型 Bean，以便通过 Jakarta Messaging 处理索引工作队列。

@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 消息传递控制器类，并实施 Jakarta EE MDB。此实施以示例形式提供，并可通过利用非 Jakarta EE 消息驱动型 Bean 而进行调整。

Hibernate Search 用于通过指定传递给底层 Lucene IndexWriter （如 mergeFactor、 maxMergeDocs 和 maxBufferedDocs ） 的一组参数来调整 Lucene 索引性能。指定这些参数作为为所有索引应用、基于索引甚至每个分片的默认值。

有几个低级别 IndexWriter 设置可以针对不同的用例进行调整。这些参数按照 indexwriter 关键字分组：

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

如果没有在特定分片配置中为 索引写入器值 设置值，Hibernate Search 会检查 index 部分，然后在 default 部分。

下表中的配置将导致这些设置应用于 Animal 索引的第二个分片 ：

所有其他值将使用 Lucene 中定义的默认值。

所有值的默认值都是保留为 Lucene 自己的默认值。索引性能和行为属性中列出的值取决于您使用的 Lucene 版本。显示的值相对于版本 2.4。

有几个低级别 IndexWriter 设置可以针对不同的用例进行调整。这些参数按照 indexwriter 关键字分组：

default.<indexname>.indexwriter.<parameter_name>

如果没有在分片配置中为 indexwriter 设置值，Hibernate Search 会查看 index 部分，然后查看 default 部分。

以下配置将导致这些设置应用到 Animal 索引的第二个分片中 ：

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，以提高索引写入效率。

在调优索引速度时，推荐的方法首先侧重于优化对象加载，然后使用您实现的计时来调整索引过程。将 黑色设置为 worker 后端，并启动索引例程。此后端不禁用 Hibernate 搜索。它将生成必要的更改集到索引，但丢弃它们而不是将它们清空到索引。与将 hibernate.search.indexing_strategy 设置为 manual 不同，使用 黑色可能会从数据库中加载更多数据，因为相关实体也会 重新索引。

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 设置为硬限制段大小小于一半，因为合并片段将两个片段合并为一个更大的片段。

新网段最初可能比预期大小更大，但创建网段永远不会显著大于 ram_buffer_size。将此阈值检查为估计值。

让我们从最常用于映射实体的注释开始。

基于 Lucene 的查询 API 使用以下常见注解来映射实体：

最重要的是，我们必须将持久类声明为可索引。这可以通过使用 @Indexed 为类添加注解（索引流程将忽略未注释 @Indexed 的 所有实体）：

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

您可以选择指定 @Indexed 注释的 index 属性，以更改索引的默认名称。

对于实体的每个属性（或属性），您可以描述如何对其进行索引。默认（不存在）表示索引过程中会忽略该属性。

@field 确实将属性声明 为索引，并允许通过设置以下一个或多个属性来配置索引过程的多个方面：

@Field 有一个相应的注释，名为 @NumericField，其范围与 @Field 或 @DocumentId 相同。它可用于 Integer、Long、Float 和 Double 属性。在索引时，将使用 Trie 结构对该值进行索引。当属性索引为数字字段时，它实现了有效的范围查询和排序，与对标准 @Field 属性执行相同的查询相比，它实现了高效的范围查询和排序。@NumericField 注释接受以下参数：

@NumericField 仅支持 Double、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 （识别符）属性是 Hibernate Search 使用的特殊属性，用于确保给定实体的索引唯一性。按照设计，必须存储 id，且不能进行令牌化。要将属性标记为索引标识符，可使用 @DocumentId 注释。如果您使用的是 Jakarta Persistence 并且指定了 @Id，您可以省略 @DocumentId。选定的实体标识符也可用作文档标识符。

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、Abs tract、文本 和 评级。请注意，默认情况下字段名称没有大写，符合 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_forSort 索引。

可以将关联的对象和嵌入式对象作为根实体索引的一部分进行索引。如果您希望根据相关对象的属性搜索给定实体，这很有用。目标是返回相关城市为 Atlanta 的位置（在 Lucene 查询解析器语言中，语言将转换为 address.city:Atlanta）。位置字段将在位置索引中 索引。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 对象中的任何更改，以便索引保持最新。为确保在地址发生更改时 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.，遵循传统的对象导航约定。您可以使用 prefix 属性覆盖它，如 ownedBy 属性中所示。

当对象图包含类（而非实例）的循环依赖项时，需要 深度 属性。例如，如果所有者指向位置：Hibernate 搜索将在到达预期深度（或到达对象图形边界）后停止包含索引的嵌入式属性。具有自引用的类是 cyclic 依赖项示例。在我们的示例中，由于 深度 设置为 1，Owner 中的任何 @IndexedEmbedded 属性都将被忽略。

使用 @IndexedEmbedded 作为对象关联可让您表达查询（使用 Lucene 的查询语法），例如：

此行为以更有效的方式（降低数据重复的成本）模仿关系连接操作。请记住，开箱即用时 Lucene 索引没有任何关联概念，连接操作也不存在。这有助于保持关系模式规范化，同时从完整的文本索引速度和特性丰富的中受益。

当 @IndexedEmbedded 指向某一实体时，其关联必须是方向的，并且必须给另一方添加注释 @ContainedIn （如上例中所示）。如果没有，Hibernate Search 将无法在相关实体更新时更新根索引（在本示例中，相关地址实例更新时必须更新 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

使用上例中所示的映射，您可以按 名称和 /或 姓氏 搜索 Person，以及/或父 名称。它不会索引父名称 的姓氏，因此无法对父名进行搜索，但会加快索引、节省空间并提高整体性能。

@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

在上面的示例中，每个人都将拥有其名称和姓氏属性索引。父项的名称和姓氏也将进行索引，其中最多可递归为第二行，因为存在depth 属性。可以按姓名或姓氏直接搜索该人员、其父项或父项。除第二个级别外，我们还会再为一个级别编制索引，而仅索引名称，而非姓氏。

这会在索引中生成以下字段：

如果您要首先定义所需的查询（如此时您准确知道需要哪些字段）以及不需要哪些其他字段来实施您的用例，那么明确控制索引路径可能会更加简单。

若要为索引化的类或属性定义静态提升值，您可以使用 @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 字段将为 3.0(2 * 1.5)，因为属性上的 @Field.boost 和 @Boost 是累加的，比 isbn 字段更重要。文本字段将比 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;
        }
    }
}

在上例中，在将 VIPBoostStrategy 指定为要在索引时使用的 BoostStrategy 接口的实现的类级别上定义动态提升。您可以将 @DynamicBoost 放置在类或字段级别上。根据注释的放置，整个实体都传递到 defineBoost 方法，或者仅传递注解的字段/质量值。您要将传递的对象投给正确的类型。在示例中，VIP 人员的所有索引值都将与普通人的值加倍。

当然，您可以在实体中混合和匹配 @Boost 和 @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;
    ...
}

在本例中，EnityAnalyzer 用于索引令牌化属性（名称），但 摘要 和 正文 除外，它们分别使用 propertiesAnalyzer 和 FieldAnalyzer 索引。

分析器可能会变得非常复杂。因此，增加了 Hibernate 搜索分析器定义的概念。分析器定义可以被许多 @Analyzer 声明重复使用，其包含：

这种任务分离（一个 char 过滤器列表和一个跟一个过滤器列表）可轻松重复利用各个组件，并让您以非常灵活的方式（如 Lego）构建自定义分析器。通常而言，Car 过滤器在字符输入中执行一些预处理，然后令牌程序通过将字符输入转换为令牌来启动令牌化过程，然后由 TokenFilters 进一步处理。Hibernate Search 利用 Solr 分析器框架来支持此基础架构。

让我们回顾一下下面描述的一个具体示例。首先，一个 char 过滤器由工厂定义。在我们的示例中，使用了映射 char 过滤器，并将根据映射文件中指定的规则替换输入中的字符。接下来定义了令牌程序。这个示例使用标准令牌程序。最后但并非最不重要的是，一个过滤器列表由其工厂定义。在我们的示例中，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 {
    ...
}

某些令牌程序、令牌过滤器或 char 过滤器会加载资源，如配置或元数据文件。stop 过滤器和同义词过滤器就是这种情况。如果资源 charset 没有使用虚拟机默认值，您可以通过添加 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 声明的 AnalyzerDef 实例通过其名称在 SearchFactory 中也可用，该名称在构建查询时非常有用。

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

查询中的字段必须使用用于索引字段的同一分析器进行分析，以便它们使用共同"语言"：在查询和索引过程之间重复利用相同的令牌。该规则有一些例外情况，但大部分时候确实如此。尊重它，除非您知道自己正在做什么。

SOLR 和 Lucene 附带许多有用的默认 char 过滤器、令牌程序和过滤器。您可以在 http://wiki.apache.org/solr/AnalyzersTokenizersTokenFilters 找到 char 过滤器工厂、令牌方工厂和过滤工厂的完整列表。我们来看一下其中几个。

我们建议检查 IDE 中 org.apache.lucene.analysis.TokenizerFactory 和 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 参数，您可以指定特定的 Discriminator 接口实施。您要为此接口提供一个实施。您唯一需要实施的方法是 getAnalyzerDefinitionName（），它为添加到 Lucene 文档中的每个字段调用。索引化的实体也传递到 interface 方法。只有在将 AnalyzerDiscriminator 放置到属性级别而不是类级别时，才会设置 value 参数。在本例中，值表示此属性的当前值。

如果不应覆盖默认分析器，则 Discriminator 接口的实施必须返回现有分析器定义的名称或 null。上面的示例假定语言参数为 'de' 或 'en'，它与 @AnalyzerDefs 中的 指定名称匹配。

当在域模型中使用了多个分析器时，可以检索分析器，以便从医疗或手机近似中受益。在这种情况下，使用相同的分析器来构建查询。或者，使用 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

在上例中，歌曲标题按照两个字段索引：标准分析器在字段 标题中 使用，greject _stemmed 字段中则使用一个适当的 分析器。通过使用搜索工厂提供的分析器，查询会根据目标字段使用适当的分析器。

Hibernate Search 附带一组 Java 属性类型和完整文本表示法之间的内置桥接。

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

    private Date date;
    ...

有时，Hibernate Search 的内置网桥不涵盖某些属性类型，或者网桥使用的字符串表示不满足您的要求。以下段落描述了此问题的几种解决方案。

/**
 * 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 搜索文档的范围。详情请查看在线 Lucene 文档或 Lucene in Action 或 Hibernate Search in Action 的副本。

Lucene 编程 API 启用全文本查询。但是，在使用 Lucene 编程 API 时，参数必须转换为字符串等效，并且还必须将正确的分析器应用到正确的字段。例如，ngram 分析器使用多个 ngrams 作为给定词的令牌，应进行此类搜索。建议将 QueryBuilder 用于此任务。

Hibernate Search 查询 API 流畅，具有以下关键特征：

要使用 API，首先创建一个附加到给定 索引类型的 查询构建器。此 QueryBuilder 知道要使用的分析器以及要应用的字段桥接。可以创建几个 QueryBuilders（涉及查询根目录的每个实体类型一个）。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 的查询解析器或 Query 对象通过 Lucene 编程 API 生成自定义查询与 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, 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、iso、sip、iph、phu、hus。这些 ngram 各自将成为查询的一部分。然后，用户可以找到 Sysiphus 神话（使用 y）。所有操作都为用户透明地完成。

要在同一个字段中搜索多个可能的词语，请在匹配的 子句中添加它们。

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

有时，即使搜索同一术语，也要与另一个字段不同对待一个字段，为此使用 和Field（）方法。

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

在上例中，只有字段名称增加到 5。

要执行 fuzzy 查询（基于 Levenshtein 距离算法），以 关键字 查询开头并添加 fuzzy 标志。

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

阈值 是两个术语正在考虑匹配的限制。它是 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();

可以通过添加滑动因子来搜索大致句子。滑动因子表示句子中允许的换句话数：这类似于操作符内或附近的运算符。

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（） 或唯一Result( )。如果实体 批处理大小设置正确，则 list( ) 效果最佳。请注意，在使用 list（）、唯一结果（）和iterate（）时，Hibernate Search 必须 处理所有 Lucene Hits 元素（ 在分 页中 ）。

如果要最大程度减少 Lucene 文档加载，滚动（） 更为合适。完成后，不要忘记关闭 ScrollableResults 对象，因为它会保留 Lucene 资源。如果您计划使用滚动，但希望批量加载对象，您可以使用 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 实施示例可在 Hibernate 核心代码库中找到。

如果查询的结果不是您预期的，luke 工具 对了解结果很有用。但是，Hibernate Search 还允许您访问给定结果（给定查询中）的 Lucene Explanation 对象。此类对于 Lucene 用户而言比较先进，但可以很好地理解对象的评分。您可以通过两种方式访问给定结果的说明对象：

第一种方法将文档 ID 用作参数并返回说明对象。文档 ID 可使用投影和 FullTextQuery.DOCUMENT_ID 常量来检索。

在第二种方法中，您使用 FullTextQuery.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() );
}

只有在需要时才使用说明对象，因为它与再次运行 Lucene 查询的成本大致相同。

Apache Lucene 具有强大的功能，允许您根据自定义过滤流程过滤查询结果。这是应用其他数据限制的一种非常强大的方式，特别是可以缓存和重复利用过滤器。使用案例包括：

Hibernate 搜索通过引入透明缓存的可参数名称过滤器的概念来进一步推动概念。对于熟悉 Hibernate 内核过滤器概念的用户，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 实体上，无论过滤器稍后要应用到哪一个查询。这意味着过滤定义是全局的，并且它们的名称必须唯一。如果定义了两个名称相同的注释，则会抛出 SearchException，以防有两个不同的 @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 是一个简单的 Lucene 过滤器的例子，它可将结果集减少到分数为 5 的驱动程序。在本例中，指定的过滤器直接实施 org.apache.lucene.search.Filter，并且包含 no-arg 构造器。

如果您的 Filter 创建需要额外的步骤，或者您想要使用的过滤器没有 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 对象。返回的对象具有特殊合同：密钥对象必须实现等效的（）/ hashCode（），这样，只有在给定 Filter 类型相同并且参数集相同时，两个键才相等。换句话说，两个过滤器键是相等的，只有在可以交换从中生成键的过滤器时才适用。密钥对象用作缓存机制中的密钥。

只有在以下情况下才需要 @key 方法：

在大多数情况下，使用 StandardFilterKey 实现会足够好。它将等号（）/ hashCode（）实现委派到每个参数等于和 hashcode 方法。

如前文所述，定义的过滤器按默认设置进行缓存，缓存使用硬链接和软引用组合来允许在需要时处理内存。硬引用缓存跟踪最近使用的过滤器，并在需要时转换最不用于 SoftReferences 的过滤器。达到硬引用缓存的限制后，其他过滤器将缓存为 SoftReferences。要调整硬引用缓存的大小，请使用 hibernate.search.filter.cache_strategy.size （默认为 128）。如需高级使用过滤器缓存，请实现您自己的 FilterCachingStrategy。classname 由 hibernate.search.filter.cache_strategy 定义。

此过滤器缓存机制不应与缓存实际过滤器结果混淆。在 Lucene 中，通常的做法是使用 IndexReader 围绕 CachingWrapperFilter 包装过滤器。打包程序将缓存 getDocIdSet(IndexReader reader) 方法返回的 DocIdSet，以避免昂贵的重新输入。务必要提及，计算的 DocIdSet 仅适用于同一 IndexReader 实例，因为读取器在打开时有效地代表索引的状态。打开的 IndexReader 中无法更改文档列表。但是，不同的/新的 IndexReader 实例可能会在另一组文档中正常工作（可以是来自不同的索引，还是仅仅因为索引已更改），因此必须重新计算缓存的 DocIdSet。

Hibernate 搜索也有助于实现缓存的这一方面。默认情况下，@FullTextFilterDef 的 缓存 标志被设置为 FilterCacheModeType.INSTANCE_AND_DOCIDSETRESULTS，它将自动缓存过滤器实例，并将指定的过滤器围绕 CachingWrapperFilter 的 Hibernate 实施包装。与此类 SoftReferences 的 Lucene 版本和硬参考计数一起使用（请参阅关于过滤缓存）。可以使用 hibernate.search.filter.cache_docidresults.size （默认为 5）来调整硬引用计数。可以使用 @FullTextFilterDef.cache 参数控制嵌套行为。这个参数有三个不同的值：

在以下情况下，应缓存过滤器：

在分片环境中，可以对可用分片的子集执行查询。这可以通过两个步骤完成：

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 的过滤器，则只会查询专用于此客户的分片，否则将返回所有分片。给定分片策略可以响应一个或多个过滤器，并依赖于其参数。

第二步是在查询时激活过滤器。尽管过滤器可以是常规过滤器（如 中定义的），它也在查询后过滤 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。目前支持两种类型的相互竞争请求。第一种类型称为离散面，第二个类型 范围则面临请求。如果是离散的面貌请求，您可以指定您要在哪个索引字段上查看（分类）以及要应用哪些选项。以下示例中显示了离散侧面请求的示例：

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

在执行此竞争请求时，将为索引化字段 标签 的每个离散值创建 Facet 实例。Facet 实例将记录实际字段值，包括此特定字段值在原始查询结果中发生的频率。orderBy、includeZeroCounts 和 maxFacetCount 是可选参数，可在任何面临请求时应用。OrderBy 允许指定返回所创建面的顺序。默认值为 FacetSortOrder.COUNT_DESC，但您也可以根据字段值或指定范围的顺序排序。includeZeroCount 决定结果中是否包括数为 0 的面数（默认为 ），而 maxFacetCount 允许限制返回的最大面数。

范围侧面请求的创建非常相似，除非我们必须为所面对的字段值指定范围。下面列出了指定了三个不同价格范围的范围。以下 及以上 只能指定一次，但您可以根据需要 从 - 指定为 范围。对于每个范围边界，您还可以通过 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();

侧面请求通过 FacetManager 类应用到查询，该类可通过 FullTextQuery 类检索。

您可以像您一样启用任意数量的请求，并在随后通过 getFacets（）指定对象请求名称来检索它们。还有一个 disableFaceting（）方法，允许您通过指定它的名称来禁用遇到请求。

可以利用 FacetManager 对查询应用竞争请求，该请求可通过 FullTextQuery 检索。

// 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（） 并指定 faceting 请求名称来检索多个侧面请求。

disableFaceting（） 方法通过指定名称来禁用争用请求。

最后，您可以将任何返回的 Facets 应用为原始查询的额外标准，以实现"中断"功能。为此，可使用 FacetSelection。FacetSelections 可以通过 FacetManager 使用，并允许您将一个面t选为查询标准(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 搜索通常需要提取类类型和主密钥。

从索引中提取所需的值具有性能成本，在某些情况下这可能非常低且不容易，但在某些情况下，这可能是缓存的良好候选者。

要求取决于使用的 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（作为所有构建的网桥），并且特定查询中加载的所有类型都必须将 fieldname 用于 id，并且具有相同类型的 ID（每次执行查询时都会进行评估）。

此策略包括删除现有索引，然后使用 FullTextSession.purgeAll（）和 FullTextSession.index（） 将所有实体重新添加到索引中，但有一些内存和效率限制。为最大程度提高效率 Hibernate 搜索批处理索引操作，并在提交时执行它们。如果您希望为大量数据编制索引，您需要小心谨慎，因为所有文档都会保留在队列中，直到事务提交为止。如果您不定期清空队列，则可能会出现 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();

这将重新构建所有用户实例的索引（及子类型），并将创建 12 个并行线程，以在每个查询使用 25 个对象的批处理来加载用户实例。这些相同的 12 个线程还需要处理索引化的嵌入式关系和自定义 FieldBridges 或 ClassBridges，以输出 Lucene 文档。在转换过程中，线程会触发额外属性加载。因此，需要大量并行工作线程。用于实际索引写入的线程数量由每个索引的后端配置定义。

建议将 cacheMode 保留至 CacheMode.IGNORE （默认值），因为在大多数重新索引的情况下，缓存会成为无用的额外开销。根据您的数据启用一些其他缓存模型 可能会很有用，因为如果主实体与索引中包含的类似数字数据相关，可能会提高性能。

其他影响索引时间和内存消耗的参数有：

之前的版本也具有 max_field_length，但这已从 Lucene 中删除。通过使用 LimitTokenCountAnalyzer 可以获得类似的效果。

all .indexwriter 参数是特定于 Lucene 的，Hibernate 搜索通过这些参数.

MassIndexer 使用正向结果仅滚动到要加载的主键，但 MySQL 的 JDBC 驱动程序会加载内存中的所有值。为了避免这个"优化"将 idFetchSize 设置为 Integer.MIN_VALUE。