lucene 使用的基本流程
转自：http://sin90lzc.iteye.com/blog/1106714
?
?
?
?
Querying
?
Hibernate Search的第二个很重要的能力是运行Lucene queries并通过Hibernate session获得受管理的实体。search在提供了Lucene强大的功能之外还保持着Hibernate的编程模式（给Hibernate典型的search机制提供另外的dimension：HQL,Criteria query,native SQL query）
?
预备和运行一个query由4个步骤组成：
?
你必须使用FullTextSession来访问query功能。这个具体的search session包装了一个一般的org.hibernate.Session来提供query和indexing能力。
?
Example 5.1. Creating a FullTextSession
?
Java代码??
?
当你有了FullTextSession之后，你有两种方式来生成full-text query：the Hibernate?Search query DSL 或 the native Lucene query.
?
如果你使用的是Hibernate Search query DSL，代码会像这样的：
?
Java代码??
另外，你还可以通过使用Lucene query parser或Lucene programmatic API来得到Lucene query。
?
Example 5.2. Creating a Lucene query via the QueryParser
?
Java代码??
?
Note:建立在Lucene query之上的Hibernate query是一般的org.hibernate.Query实现，这意味着你可以使用与其他Hibernate query功能（HQL,Native or Criteria）相同的模式来编程。org.hibernate.Query中的list()，uniqueResult(),iterate()和scroll()方法都可以使用。
?
你也可以使用Hibernate的Java Persistence API：
?
Example 5.3. Creating a Search query using the JPA API
?
Java代码??
?
?
Note：下面的例子中，我们只使用Hibernate API，不过也可能很容易地使用JPA来重写。
?
5.1. Building queries
Hibernate Search的query是建立在Lucene query之上，Lucene query给你最大的自由度来提供具体的Lucene query类型来运行查询。这样的话，org.hibernate.Query包装了lucene query作为你主要的操作API。
?
5.1.1.通过Lucene API来创建Lucene query(Building a Lucene query using the Lucene API)
你有多种方式来使用Lucene API。你可以使用query parser(对于简单查询来说已经足够了)或Lucene编程API(对于复杂的用例)。如何创建一个Lucene query超过了本文档的范围。具体请查阅Lucene在线文档《Lucene In Action》或《Hibernate Search in Action》
?
?
5.1.2. 使用Hibernate Search query?DSL创建一个Lucene query(Building a Lucene query with the Hibernate Search query?DSL)
使用Lucene编程API来生成query是相当复杂的。因为与生俱来的API复杂性，你必须记得转换参数到相等的字符串并确保fields应用正确的analyzer。
?
Hibernate Search query DSL使用了一种称为流畅的(fluent)API.这类API有一些关键的特征:
?
Java代码??
你也可以覆盖属性域上的analyzer。这一般都很少使用和应该避开这样的做法，除非你知道自己在做什么。
?
?
Java代码??
?
你可以使用query builder来生成query。很重要的一点是，你要认识到QueryBuilder的最终结果是一个Lucene query。基于这个原因，你可以很容易地通过Lucene query parser或Lucene编程API来生成Lucene query，并与Hibernate Search DSL一起使用。只有在DSL缺少某些功能的时候才应该去使用Lucene编程API。
?
?
5.1.2.1. 关键字查询(Keyword queries)
让我们从最常用的用例说起－搜索某个词：
?
Java代码??
keyword()方法意味着你正在尝试着去查询一个指定的词语。onField()方法指定查询哪个Lucene field。matching()方法告诉查询哪个词语。最后createQuery()方法创建Lucene query对象。除了这些方法之外，还能很多其他的方法组合来生成query。
?
下面我们看一下怎么搜索一个属性域并不是一个字符串类型的情形。
?
Java代码???
?
Note：在一般的Lucene中，你需要转换Date对象为它的字符串形式。
?
这个自动转换功能适用于所有对象，并不局限于Date，只要属性域上有对应的FieldBridge就可以了。
?
我们看一下一个高级点的例子，怎么样去搜索使用了ngram analyzer的field。ngram analyzer索引一连串的词语的ngram，ngram可以还原用户错字。例如把hibernate拆分成3-grams：hib, ibe, ber, ern,rna,nat, ate
?
?
Java代码??
?
?
搜索词"Sisiphus"会小写，并分割成3-grams:sis,isi,sip,iph,phu,hus。每个n-gram都会是query的一部分。那么我们就可以通过查询找到Sysiphus myth。所有的这些都可以自动地完成。
?
Note：对于某些原因，你可能不想某个field使用field bridge或analyzer，你可以调用?ignoreAnalyzer()方法或ignoreFieldBridge()方法。
?
如果想要在同一个field中搜索多个词，只需要简单地在matching语句中添加他们。
?
Java代码???
如果想搜索多个field，可以使用onFields方法。
?
Java代码??
?
有时候，一个field与其他field可能会被不同地对待，即使是搜索同一个term，你可以使用andField()方法来达到这种需求。
?
Java代码??
?
在上一个例子中，只有field 'name'优先级定为5。
?
5.1.2.2. 模糊查询(Fuzzy queries)
运行一个模糊查询(基于Levenshtein距离算法),像keyword查询一样，添加一个fuzzy()方法标志。
?
Java代码??
?threshold是一种限制，它定义了如何认为两个term是匹配的。它是一个0-1之间的数字，默认是0.5。prefixLength定义了模糊查询忽略前缀的长度：默认是0，如果能明确地知道前缀的话，推荐赋予一个非零值。
?
5.1.2.3. 通配符查询(Wildcard queries)
你也可以执行通配符查询(查询词中有某些部分是不确定的)。'?'代表了一个字符，*代表任何的字符串。为了性能的表现目的，推荐query不要以?或*开始。
?
Java代码??
?
Note：通配符查询是不会应用analyzer的，否则的话?和*将会很大可能被删掉。
?
5.1.2.4. Phrase queries
?
到目前为止，我们已经能查询单个或多个词语了。你也同样可以搜索精确的、接近的短句。使用phrase()方法完成这个需求。
?
?
?
Java代码??
?
你可以通过添加一个slop因子来搜索接近的短句。slop因子表示短句中词语间允许的间隔。
?
Java代码??
5.1.2.5. 范围查询(Range queries)
?
一个范围查询搜索某个范围内的值或高于(above)或是低于(below)某个界限的值。
?
Java代码??
?
5.1.2.6. 组合查询(Combining queries)
最后你还可以组合查询来形成更复杂的查询。下列的逻辑操作是允许的：
?
?
让我们看看应用了这些选项的例子：
?
Java代码??
?
5.1.3. 创建Hibernate Search查询(Building a Hibernate Search query)
到目前为止，我们只讲述了怎么样创建Lucene query的过程(see Section 5.1, “Building?queries”)。然而，这只是搜索链中的第一步。让我们看看怎么样由Lucene query建立Hibernate Search query
?
5.1.3.1. 概要（Generality）
创建了Lucene query之后，它需要包装进hibernate Query中去。如果没有指定Lucene query，query将会查询所有的indexed实体，潜在地返回所有indexed的类。
?
Example 5.4. Wrapping a Lucene query into a Hibernate Query
?
Java代码??
从性能的角度来看，推荐限制返回类型：
?
Java代码???
In ?Example 5.5, “Filtering the search result by entity type” 第一个例子只返回Customer类型的结果，第二个例子只返回Actor和Item的类型。类型约束是支持多态（例如：Customer和Salesman继承于Person，如果要求结果集能返回Customer和Salesman，只需要指定Person.class即可）。
?
?
5.1.3.2. 分页(Pagination)
出于性能的考虑，推荐约束每次查询返回的对象数量。事实上，这是一个非常普通的用例可以让用户浏览一页的数据。定义pagination与在plain HQL或Criteria query中定义分页是完全一样的。
Example 5.6. Defining pagination for a search query
?
Java代码??
Tip:fulltextQuery.getResultSize()方法可以返回所有匹配对象的总数，不管你是否应用了pagination。
?
?
5.1.3.3. Sorting
?
Apache Lucene已经提供了一个非常灵活和强大的方式去排序结果。默认的排序是relevance(按分数排序)适用于大多数的时候，不过也可以按一个或多个属性域来排序。为了达到这个目的，可以设置Lucene Sort对象来应用Lucene的sorting strategy。
?
Example 5.7. Specifying a Lucene Sort in order to sort the results
?
Java代码??
?
?
Tip：用作排序的field不能被tokenized。
?
5.1.3.4. 抓取策略(Fetching strategy)
当你限制返回类型只有一个类的时候，Hibernate Search使用一个查询语句来加载对象。该查询同样会使用域模型中定义的抓取策略。然而，也可以针对某个具体的用例来调整抓取策略。
?
Example 5.8. Specifying FetchMode on a query
?
Java代码??
?
在这个例子中，查询会返回所有的匹配luceneQuery的Books。authors集合也会使用SQL外连接在同一个查询语句中加载进来。
?
当定义一个criteria查询的时候，Hibernate Search query不需要约束返回的实体类型，该返回类型由criteria查询定义。
?
Important：如果期望的返回类型不止1个的话，不能使用setCriteriaQuery方法。
?
5.1.3.5. 投影(Projection)
对于某些用例来说，返回整个域对象（包括关联对象）会变得有点小题大做，因为只需要实体对象中小部分的属性。Hibernate Search允许只返回一部分的属性。
?
Example 5.9. Using projection instead of returning the full domain object
?
Java代码??
Hibernate Search从Lucene index中抽离出实体对象的属性并把它们向上转换成Object，最终结果返回Object[]列表。Projection避开了潜在数据库的查询(如果响应时间很重要的话，这就会很有用了)。然而，它还有一些约束条件：
?
?
?
?
Note：所有Hibernate Search内建类型都是two-way的。
?
?
?
?
Example 5.10. Using projection in order to retrieve meta data
?
?
?
Java代码??
?
你可以混合投影field和projection常量。下面列举了可用的projection常量：
?
?
?
?
?
?
5.1.3.6.自定义对象初始化策略(Customizing object initialization strategies)
?
?
?
?
默认地，Hibernate Search使用最合适的策略来初始化匹配的实体对象。它运行一个或多个查询来获取请求的实体对象。当实体对象存储在持久化上下文或二级缓存中时，默认的方法会最小程度地访问数据库，因此也是最好的方法。
?
如果大多数的实体对象缓存在二级缓存中，你可以强迫Hibernate Search先从缓存中获取对象，如果没有再访问数据库。
?
Example 5.11. Check the second-level cache before using a query
?
?
Java代码??
?
?
ObjectLookupMethod定义了一些策略去检查是否请求的对象是容易访问的（accessible），即不需要访问数据库。下面列举了其他一些选项：
?
?
Note:要应用二级缓存，首先要配置好以下几点：
?
Warning:如果不是使用EHCache或Infinispan作为二级缓存，应避免使用ObjectLookupMethod.SECOND_LEVEL_CACHE。因为其他的缓存provider实现的效果并不好。
?
你同样可以通过DatabaseRetrievalMethod定义如何从数据库中加载对象：
?
?
?
5.1.3.7. 限制查询时间(Limiting the time of a query)
在Hibernate Search有两种方式可以限制一个查询任务时间：
?
?
5.1.3.7.1. 时间到达时抛出异常(Raise an exception on time limit)
?
当查询的时间超过限制，就会抛出QueryTimeoutException异常(org.hibernate.QueryTimeoutException或javax.persistence.QueryTimeoutException，这依赖于你的编程API)
?
使用下面其中一种方法来定义时间限制：
?
Example 5.12. Defining a timeout in query execution
?
Java代码??
?
同样的，时间限制对于getResultSize(), iterate() 和scroll()来说是直到这些方法调用结束为止。这就是说Iterable方法或ScrollableResultes方法将忽略时间限制。
?
Note：时间限制不能约束explain()方法，该方法只用于调试目的，特别是用于查出一些查询会很慢的原因。
?
当使用的是JPA,简单地使用标准的方式来限制查询运行时间。
?
Example 5.13. Defining a timeout in query execution
?
?
Java代码??
Important：记住，这是一个最有效的方法，但并不能保证在指定的时间内精确地停止。
?
5.1.3.7.2.返回返回限制时间到达前获取的结果（测试中）?(Limit the number of results when the time limit is reached(EXPERIMENTAL))
另外，你可以获取在时间到达时已经读取的对象。注意，只有在查询Luene index时才受此限制。意思是说，还可以花更长的时间来获取受管状态的对象。（大概是指限制时间是查询index的时间，不包括数据库访问的时间）
?
Warning：该方法与?setTimeout方法是不兼容的。
?
使用下面的方法来定义这个限制。
?
Example 5.14. Defining a time limit in query execution
?
Java代码??
?
同样的，时间限制对于getResultSize(), iterate() 和scroll()来说是直到这些方法调用结束为止。这就是说Iterable方法或ScrollableResultes方法将忽略时间限制。
?
你可以通过调用hasPartialResults方法来确定是否加载了部分结果
?
Example 5.15. Determines when a query returns partial results
?
Java代码??
?
limitExecutionTimeTo 和 hasPartialResults方法也同样适用于JPA API.
?
?
5.2. 获取结果集（Retrieving the results）
当建立了Hibernate Search query后，运行它与运行HQL，Criteria查询没什么不同，都使用相同的编程模式和对象语义。所有普通的操作都是可用的：list(),uniqueResult(),iterate(),scroll()。
?
5.2.1.性能考虑(Performance considerations)
如果你期望返回合理数量的结果（如分页）并work on它们，list()和uniqueResult()方法是推荐使用的。如果实体的batch-size设置合适的话，list()会工作得最好。在使用list()，uniqueResult(),iterate()方法，Hibernate Search必须处理所有Lucene匹配的元素。
?
?
?
?
?
如果你想最小化加载Lucene document，scroll()方法会更合适。在你完成工作后，不要忘记关闭ScrollableResult对象，因为它保持着Lucene资源。如果你想使用scroll又想批量加载对象，你可以使用query.setFetchSize()方法。如果一个对象被访问，而它又没被加载过，Hibernate Search将会加载下一批对象。
?
Important：Pagination优于scrolling。
?
5.2.2. 结果大小(Result size)
有时候很有必要知道匹配的文档总数：
?
?
当然，获取所有匹配的document是非常消耗资源的。不管pagination参数如何，Hibernate Search都允许你获取匹配document的总数。更有趣的是，你不需要触发一个单独对象的加载就获取这个匹配元素的总量。
?
Example 5.16. Determining the result size of a query
?
Java代码??
?
Note：像Google，结果总量是一个接近数，因为index并不完全跟数据库一致（如异步集群方式）
?
5.2.3. 结果转换器(ResultTransformer)
在Section 5.1.3.5, “Projection”中看到的projection返回的结果是Object数组。这种数据结构并不总是适合应用的需要。在这种情况下，就可能需要应用一个ResultTransformer，它可以运行完查询后建立需要的数据结构。
?
Example 5.17. Using ResultTransformer in conjunction with projections
?
Java代码??
?
ResultTransformer的实现例子可以在Hibernate Core codebase中找到。
?
?
5.2.4. Understanding results
有时候你可能会因为某些查询结果而感到迷惑。Luke是一个很好的工具帮助你了解查询的结果。然而，Hibernate Search也能让你从给定的query中访问Lucene Explanation对象。这个对象对于Lucene用户来说是相当高级的，不过能为理解一个结果的分数提供很好的帮助。你有两种方式来访问结果对应的Explanation对象：
?
?
?
?
Warning：document id与实体的id是不同的。不要混淆这两个概念。
?
?
第二种方法让你使用FullTextQuery.EXPLANATION常量来投影Explanation对象。
?
Example 5.18. Retrieving the Lucene Explanation object using projection
?
Java代码??
?
小心，创建explanation对象是非常昂贵的，它大概像重新运行一次Lucene query那么地昂贵。如果你不需要这个对象就请不要创建它。
?
?
5.3.过滤器(Filters)
Apache Lucene有一个强大的过滤功能，它允许通过自定义的过滤处理来过滤查询结果。这是非常强大的方式来应用额外的数据约束，特别是filter可以被缓存和重用。下面列举了一些有趣的用例：
?
Hibernate Search把这个概念再推进了一步，称为能自动缓存的参数化命名过滤器(parameterizable named?filters)。这与大家所熟悉的Hibernate Core过滤器API是非常相似的：
?
Example 5.19. Enabling fulltext filters for a given query
?
Java代码??
?在这个例子中，我们在query之上使用了两个filter。如果你有这个需要的话，你可以使用任意数量的filter。
?
声明filter是通过@FullTextFilterDef注解完成。该注解标注在带有@Indexed注解的实体上。这暗示了filter声明是全局的和它们的名字必须是唯一的。如果两个不同的@FullTextFilterDef声明两个相同名字的filter，就会抛出SearchException。每个命名的filter必须指定它自己的filter实现。
?
Example 5.20. Defining and implementing a Filter
?
Java代码??
Java代码??
BestDriversFilter是一个简单的Lucene filter实现，它把所有'score'不为5的结果过滤掉了。在这个例子中，具体的filter直接实现了org.apache.lucene.search.Filter并包含一个无参的构造器。
?
如果你的Filter创建需要额外的步骤或Filter需要使用有参数的构造器，那么你就要使用factory模式：
?
Example 5.21. Creating a filter using the factory pattern
?
Java代码??
?
Hibernate Search 将会查找@Factory标注的方法并使用它来生成一个filter实例。该工厂类必须有无参构造器。
?
有时候需要向命名的filter传递参数。例如：一个security filter可能想要知道要应用的security level。
?
Example 5.22. Passing parameters to a defined filter
?
Java代码??每个参数名字应该与filter或filter factory中的setter方法相关联。
?
?
Example 5.23. Using parameters in the actual filter implementation
?
Java代码??
?
?
?
注意带有注解@Key的方法返回的是FilterKey对象。该对象有一个特别的条约：该对象必须实现equals()/hashCode()方法来确定两个FilterKey对象是否相等。FilterKey对象作为一个键值应用在缓存机制中。
?
@Key注解的方法只有在下面情况下是有必要的：
?
5.3.1. Using filters in a sharded environment
略
?
5.4. Faceting
Faceted search[http://en.wikipedia.org/wiki/Faceted_search]是一门能给搜索结果分类的技术。这个categorisation包括了每个分类匹配数的计算和进一步约束基于分类的搜索结果。Example 5.24, “Search for 'Hibernate Search' on Amazon”展示了一个faceting的例子。页面的主要部分显示了15个搜索结果。在左边显示浏览条目，并显示了Computers & Internet及其子分类的编排：Computer Science, ?Databases, ?Software, Web Development, ?Networking and?Home Computing。对于每个子分类右边的数字代表了全部搜索结果中需要该子分类的结果的数量。这样的一个划分Computers & Internet就是一个具体的search facet。另一种例子是平均用户审查。
?
在Hibernate Search中，QueryBuilder与FullTextQuery是faceting API的入口。前者允许创建faceting请求，而后者提供了FacetManager的访问。有了FacetManager的帮助，faceting请求可以被应用在query上，selected facet可以被加入一个存在的query来调整搜索结果。下面的章节将更详细地描述faceting过程。下面会使用Example 5.25, “Entity Cd”中定义的实体Cd作为例子
?
Example 5.25. Entity Cd
?
?
Java代码??
?
?
5.4.1. Creating a faceting request
faceted search的第一步是创建一个FacetingRequest。现在支持两种类型的faceting request。第一种类型称为discrete faceting request(离散的faceting request)，第二种类型是range faceting request。对于discrete faceting request来说，你需要指定哪个index field用于facet(categorize)并应用哪些faceting选项。Example 5.26, “Creating a discrete faceting request”就是一个discrete faceting request例子。
?
Example 5.26. Creating a discrete faceting request
?
Java代码??
?
当运行这个faceting request，将会为每个离散值（在这里是'label' field的值）创建一个Facet实例。Facet实例会记录下实际的field value，包括这个field value的值在原查询结果中出现的频率。orderedBy，includeZeroCounts和maxFacetCount是任何faceting request的可选参数。orderedBy允许指定返回的facet的顺序，默认是FacetSortOrder.COUNT_DESC，不过你也可能按field value或按指定的范围排序。includeZeroCount定义是否计数为0的facet也包含在结果中（默认是包括的）。maxFacetCount限制了最大的facet返回数。
?
?
?
Tip：应用faceting的indexed field需要满足一些先决条件。被索引的属性域必须是字符串，日期或数值类型。另外属性域必须以Index.UN_TOKENIZED方式索引，数值型的属性域必须标注为@NumericField
?
?
?
range faceting request的创建非常相似，除了我们必须为field指定一个范围值。Example 5.27,“Creating a range faceting request”是一个range faceting request的例子，它指定了三个不同的price范围。below和above只能指定一次，但你可以任意地指定from-to范围。通过excludeLimit方法定义是否包括每个范围的边界。
?
?
Example 5.27. Creating a range faceting request
?
?
Java代码??
?
5.4.2. Applying a faceting request
在5.4.1节'creating a faceting request'，我们已经看到怎么样去创建一个faceting request。现在是时候在查询时应用这个faceting request。关键在于从FulltextQuery中获取的FacetManager。(see Example 5.28, “Applying a faceting request”)
?
Example 5.28. Applying a faceting request
?
Java代码??
?
只要你有这样的需要，你可以使用添加任何数量的faceting request，并通过getFacets()和faceting request name来获取Facet。同样地，有一个disableFaceting()方法，它可以通过request name来禁用一个faceting request。
?
5.4.3. 限制查询结果(Restricting query results)
?
最后但不重要的是，你可以应用任何返回的Facet作为你原本的query的额外的criteria，这样就可以实现一个"drill-down"功能。为了这个目的，就得利用FacetSelection这个类。可以通过FacetManager来应用FacetSelection，并允许你选择一个facet作为query criteria(selectFacet)，移除一个facet restriction(deselectFacets),移除所有facet restrictions(clearSelectedFacets)并获取当前所有的selected facets(getSelectedFacets)。?Example 5.29, “Restricting query results via the application of a?FacetSelection” shows an example.
?
?
Example 5.29. Restricting query results via the application of a FacetSelection
?
Java代码??
5.5. Optimizing the query process
查询性能依赖于下面几个准则：
?
?
5.5.1. Caching index values: FieldCache
Lucene index的主要功能是鉴定与查询的匹配关系，然而查询完成后，必须分析结果并抽离有用的信息：典型地，Hibernate Search需要抽出Class type和primary key。
?
从index中抽离需要的值是一种性能消耗，这种消耗可能很低并不易让人知道，但在某些时候caching会是一种很好的实践。
?
缓存的精确需要依赖于使用Projection的类型(see Section 5.1.3.5,“Projection”)，有些时候，Class type是不需要缓存的，因为它可以通过query上下文获知。
?
使用@CacheFromIndex注解，你可以试验缓存Hibernate Search所需要的不同的主元数据field。
?
Java代码??
?
通过这个注解现在就可以缓存Class type和ID。
Note:在warmup(运行一些query)后，测量性能和内存消耗之间的影响:使用Field Cache好像能改善性能，但并不总是这样的。
?
?
使用FieldCache有两个缺点：
the id, and have ids of the same type (this is evaluated at each Query execution).
?
