diff --git a/documentation/src/main/docbook/devguide/en-US/Envers.xml b/documentation/src/main/docbook/devguide/en-US/Envers.xml
index a52506eff5..4f03965677 100644
--- a/documentation/src/main/docbook/devguide/en-US/Envers.xml
+++ b/documentation/src/main/docbook/devguide/en-US/Envers.xml
@@ -379,6 +379,197 @@ public class ExampleListener implements RevisionListener {
+
+
+ Queries
+
+
+ You can think of historic data as having two dimension. The first - horizontal -
+ is the state of the database at a given revision. Thus, you can
+ query for entities as they were at revision N. The second - vertical - are the
+ revisions, at which entities changed. Hence, you can query for revisions,
+ in which a given entity changed.
+
+
+
+ The queries in Envers are similar to
+ Hibernate Criteria,
+ so if you are common with them, using Envers queries will be much easier.
+
+
+
+ The main limitation of the current queries implementation is that you cannot
+ traverse relations. You can only specify constraints on the ids of the
+ related entities, and only on the "owning" side of the relation. This however
+ will be changed in future releases.
+
+
+
+ Please note, that queries on the audited data will be in many cases much slower
+ than corresponding queries on "live" data, as they involve correlated subselects.
+
+
+
+ In the future, queries will be improved both in terms of speed and possibilities, when using the valid-time
+ audit strategy, that is when storing both start and end revisions for entities. See
+ .
+
+
+
+
+ Querying for entities of a class at a given revision
+
+
+ The entry point for this type of queries is:
+
+
+
+
+
+ You can then specify constraints, which should be met by the entities returned, by
+ adding restrictions, which can be obtained using the AuditEntity
+ factory class. For example, to select only entities, where the "name" property
+ is equal to "John":
+
+
+
+
+
+ And to select only entites that are related to a given entity:
+
+
+
+
+
+ You can limit the number of results, order them, and set aggregations and projections
+ (except grouping) in the usual way.
+ When your query is complete, you can obtain the results by calling the
+ getSingleResult() or getResultList() methods.
+
+
+
+ A full query, can look for example like this:
+
+
+
+
+
+
+
+
+ Querying for revisions, at which entities of a given class changed
+
+
+ The entry point for this type of queries is:
+
+
+
+
+
+ You can add constraints to this query in the same way as to the previous one.
+ There are some additional possibilities:
+
+
+
+
+
+ using AuditEntity.revisionNumber() you can specify constraints, projections
+ and order on the revision number, in which the audited entity was modified
+
+
+
+
+ similarly, using AuditEntity.revisionProperty(propertyName) you can specify constraints,
+ projections and order on a property of the revision entity, corresponding to the revision
+ in which the audited entity was modified
+
+
+
+
+ AuditEntity.revisionType() gives you access as above to the type of
+ the revision (ADD, MOD, DEL).
+
+
+
+
+
+ Using these methods,
+ you can order the query results by revision number, set projection or constraint
+ the revision number to be greater or less than a specified value, etc. For example, the
+ following query will select the smallest revision number, at which entity of class
+ MyEntity with id entityId has changed, after revision
+ number 42:
+
+
+
+
+
+ The second additional feature you can use in queries for revisions is the ability
+ to maximalize/minimize a property. For example, if you want to select the
+ revision, at which the value of the actualDate for a given entity
+ was larger then a given value, but as small as possible:
+
+
+
+
+
+ The minimize() and maximize() methods return a criteria,
+ to which you can add constraints, which must be met by the entities with the
+ maximized/minimized properties.
+
+
+
+ You probably also noticed that there are two boolean parameters, passed when
+ creating the query. The first one, selectEntitiesOnly, is only valid when
+ you don't set an explicit projection. If true, the result of the query will be
+ a list of entities (which changed at revisions satisfying the specified
+ constraints).
+
+
+
+ If false, the result will be a list of three element arrays. The
+ first element will be the changed entity instance. The second will be an entity
+ containing revision data (if no custom entity is used, this will be an instance
+ of DefaultRevisionEntity). The third will be the type of the
+ revision (one of the values of the RevisionType enumeration:
+ ADD, MOD, DEL).
+
+
+
+ The second parameter, selectDeletedEntities, specifies if revisions,
+ in which the entity was deleted should be included in the results. If yes, such entities
+ will have the revision type DEL and all fields, except the id,
+ null.
+
+
+
+
+
+
Understanding the Envers Schema