From hibernate-commits at lists.jboss.org Thu May 31 10:13:25 2007 Content-Type: multipart/mixed; boundary="===============3667466106491133243==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r11603 - trunk/HibernateExt/search/doc/reference/en/modules. Date: Thu, 31 May 2007 10:13:25 -0400 Message-ID: --===============3667466106491133243== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: epbernard Date: 2007-05-31 10:13:25 -0400 (Thu, 31 May 2007) New Revision: 11603 Modified: trunk/HibernateExt/search/doc/reference/en/modules/architecture.xml trunk/HibernateExt/search/doc/reference/en/modules/mapping.xml trunk/HibernateExt/search/doc/reference/en/modules/query.xml Log: Documentation updates Modified: trunk/HibernateExt/search/doc/reference/en/modules/architecture.x= ml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/HibernateExt/search/doc/reference/en/modules/architecture.xml 200= 7-05-31 12:50:33 UTC (rev 11602) +++ trunk/HibernateExt/search/doc/reference/en/modules/architecture.xml 200= 7-05-31 14:13:25 UTC (rev 11603) @@ -188,13 +188,15 @@ Reader strategy = When executing a query, Hibernate Search interacts with the Apac= he - Lucene indexes through a reader strategy. + Lucene indexes through a reader strategy. chosing a reder strategy will + depend on the profile of the application (frequent updates, read mostl= y, + asynchronous index update etc). =
not-shared = Every time a query is executed, a Lucene IndexReader is opened. - This strategy is not the most efficient, opening and warming up an + This strategy is not the most efficient: opening and warming up an IndexReader can be a relatively expensive operation. This strategy is the default, but will be changed in the future.
@@ -202,11 +204,13 @@
shared = - Hibernate Search will share the same IndexReader for a given i= ndex - provided that the IndexReader is still up-to-date. Generally speakin= g, - this strategy provides much better performance than the previous one= . It - is especially true if the number of updates is much lower than the - read. + With this strategy, Hibernate Search will share the same + IndexReader, for a given Lucene index, across multiple queries and + threads provided that the IndexReader is still up-to-date. If the + IndexReader is not up-to-date, an new one is opened and provided. + Generally speaking, this strategy provides much better performances = than + the not-shared strategy. It is especially true if= the + number of updates is much lower than the reads.
=
Modified: trunk/HibernateExt/search/doc/reference/en/modules/mapping.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/HibernateExt/search/doc/reference/en/modules/mapping.xml 2007-05-= 31 12:50:33 UTC (rev 11602) +++ trunk/HibernateExt/search/doc/reference/en/modules/mapping.xml 2007-05-= 31 14:13:25 UTC (rev 11603) @@ -78,7 +78,7 @@ to use the index query result. For a regular Hibernate Search usage, storing is not necessary. However you might want to store some field= s to subsequently project them (see for= more - information). + information). = Whether or not you want to tokenize a property depends on whet= her you wish to search the element as is, or by the words it contains. It @@ -125,7 +125,7 @@ Embedded and associated objects = Associated objects as well as embedded objects can be indexed = as - well as part of the root entity index. + part of the root entity index. = @Entity @Indexed @@ -168,11 +168,11 @@ Place index. The Place index documents will also contain the fields address.id, address.street, and address.city - which you will be able to query from. This is done thanks to the + which you will be able to query. This is enabled by the @IndexedEmbedded annotation. = @ContainedIn is useful on embedded objects = that - are also entities (like Address in the example): = it + are also entities (like Address in this example):= it basically means that when an address entity is updated, the index document of the associated Place(s), also have to= be updated. @@ -414,8 +414,7 @@ alternative approach is to use a Filter query which will filter the result query to the appropriate range. = - Hibernate Search will sup= port - a padding mechanism + Hibernate Search will support a padding mechanism Modified: trunk/HibernateExt/search/doc/reference/en/modules/query.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/HibernateExt/search/doc/reference/en/modules/query.xml 2007-05-31= 12:50:33 UTC (rev 11602) +++ trunk/HibernateExt/search/doc/reference/en/modules/query.xml 2007-05-31= 14:13:25 UTC (rev 11603) @@ -2,12 +2,11 @@ Querying = - The second most important capability of Hibernate Sea= rch - is the ability to execute a Lucene query and retrieve - entities managed by an Hibernate session, providing the power of Lucene - without living the Hibernate paradigm, and giving another dimension to t= he - Hibernate classic search mechanisms (HQL, Criteria query, native SQL - query). + The second most important capability of Hibernate Search is the + ability to execute a Lucene query and retrieve entities managed by an + Hibernate session, providing the power of Lucene without living the + Hibernate paradigm, and giving another dimension to the Hibernate classic + search mechanisms (HQL, Criteria query, native SQL query). = To access the Hibernate Search querying facilities, you have to use an Hibernate @@ -65,9 +64,10 @@ FullTextSession fullTextSession =3D Search.createF= ullTextSession( session ); org.hibernate.Query fullTextQuery =3D fullTextSession.createFullTextQuery(= luceneQuery ); = - If not specified, the query will be applied on all indexed, - potentially returning all types of indexed classes. It is advised,= for - a performance point of view to restrict the returned types: + If not specified, the query will be executed all indexed, + potentially returning all types of indexed classes. It is advised, + from a performance point of view, to restrict the returned + types: = org.hibernate.Query fullTextQuery =3D fullTextSess= ion.createFullTextQuery( luceneQuery, Customer.class ); //or @@ -117,15 +117,15 @@ interface which is a sub interface of org.hibernate.Query. = - Fields used for sorting ust not be tokenized. + Fields used for sorting must not be tokenized.
=
Fetching strategy = When you restrict the return types to one class, Hibernate - Search load the objects and respect the static fetching strategy - defined in your domain model using a single query. + Search loads the objects using a single query. It also respects the + static fetching strategy defined in your domain model. = It is often useful, however, to refine the fetching strategy= for a specific use case. @@ -140,7 +140,8 @@ When defining a criteria query, it is not needed to restrict= the entity types returned while creating the Hibernate Search query fr= om the full text session: the type is guessed from the criteria query - itself. + itself. Only fetch mode can be adjusted, refrain from applying any + other restriction. = One cannot use setCriteriaQuery if = more than one entity type is expected to be returned. @@ -181,7 +182,8 @@ org.hibernate.search.bridge.TwoWayFieldBridge or org.hibernate.search.bridge.TwoWayStringBridge, - the latter being the simpler version + the latter being the simpler version. All Hibernate Search + built-in types are two-way. = @@ -203,7 +205,7 @@
Performance considerations = - If you expect a reasonable result number (for example using + If you expect a reasonable number of results (for example using pagination) and expect to work on all of them, list() or uniqueResult() are recommended. @@ -227,7 +229,7 @@ = - for the Google-like feature 1-10 of about 888,000,000 + for the Google-like feature 1-10 of about 888,000,000 = @@ -246,7 +248,7 @@ Hibernate Search allows you to retrieve the total number of matching documents regardless of the pagination parameters. Even more interesting, you can retrieve the number of matching elements without - even triggering a single object load. + triggering a single object load. = org.hibernate.search.FullTextQuery query =3D s.creat= eFullTextQuery( luceneQuery, Book.class ); assert 3245 =3D=3D query.getResultSize(); //return the number of matching books without loading a single one @@ -256,7 +258,11 @@ List results =3D query.list(); assert 3245 =3D=3D query.getResultSize(); //return the total number of matching books regardless of pagination = - + + Like Google, the number of results is approximative if the i= ndex + is not fully up-to-date with the database (asynchronous cluster for + example). +
= --===============3667466106491133243==--