query_queryover.xml

<chapter id="queryqueryover">
    <title>QueryOver Queries</title>

    <para>
        The ICriteria API
        is NHibernate's implementation of Query Object.
        NHibernate 3.0 introduces the QueryOver API, which combines the use of
        Extension Methods
        and
        Lambda Expressions
        (both new in .Net 3.5) to provide a statically type-safe wrapper round the ICriteria API.
    </para>
    <para>
        QueryOver uses Lambda Expressions to provide some extra
        syntax to remove the 'magic strings' from your ICriteria queries.
    </para>
    <para>
        So, for example:
    </para>
    <programlisting><![CDATA[.Add(Expression.Eq("Name", "Smith"))]]></programlisting>
    <para>becomes:</para>
    <programlisting><![CDATA[.Where<Person>(p => p.Name == "Smith")]]></programlisting>
    <para>
        With this kind of syntax there are no 'magic strings', and refactoring tools like
        'Find All References', and 'Refactor-&gt;Rename' work perfectly.
    </para>
    <para>
        Note: QueryOver is intended to remove the references to 'magic strings'
        from the ICriteria API while maintaining it's opaqueness.  It is <emphasis role="underline">not</emphasis> a LINQ provider;
        NHibernate has a built-in <link linkend="querylinq">Linq provider</link> for this.
    </para>

    <sect1 id="queryqueryover-querystructure">
        <title>Structure of a Query</title>
        
        <para>
            Queries are created from an ISession using the syntax:
        </para>
        <programlisting><![CDATA[IList<Cat> cats =
    session.QueryOver<Cat>()
        .Where(c => c.Name == "Max")
        .List();]]></programlisting>
        <para>&nbsp;</para>
        <para>
            Detached QueryOver (analogous to DetachedCriteria) can be created, and then used with an ISession using:
        </para>
        <programlisting><![CDATA[QueryOver<Cat> query =
    QueryOver.Of<Cat>()
        .Where(c => c.Name == "Paddy");
        
IList<Cat> cats =
    query.GetExecutableQueryOver(session)
        .List();]]></programlisting>

        <para>
            Queries can be built up to use restrictions, projections, and ordering using
            a fluent inline syntax:    
        </para>
        <programlisting><![CDATA[var catNames =
    session.QueryOver<Cat>()
        .WhereRestrictionOn(c => c.Age).IsBetween(2).And(8)
        .Select(c => c.Name)
        .OrderBy(c => c.Name).Asc
        .List<string>();]]></programlisting>
        
    </sect1>

    <sect1 id="queryqueryover-simpleexpressions">
        <title>Simple Expressions</title>
        
        <para>
            The Restrictions class (used by ICriteria) has been extended to include overloads
            that allow Lambda Expression syntax.  The Where() method works for simple expressions (&lt;, &lt;=, ==, !=, &gt;, &gt;=)
            so instead of:
        </para>
        <programlisting><![CDATA[ICriterion equalCriterion = Restrictions.Eq("Name", "Max")]]></programlisting>
        <para>
            You can write:
        </para>
        <programlisting><![CDATA[ICriterion equalCriterion = Restrictions.Where<Cat>(c => c.Name == "Max")]]></programlisting>
        <para>&nbsp;</para>
        <para>
            Since the QueryOver class (and IQueryOver interface) is generic and knows the type of the query,
            there is an inline syntax for restrictions that does not require the additional qualification
            of class name.  So you can also write:
        </para>
        <programlisting><![CDATA[var cats =
    session.QueryOver<Cat>()
        .Where(c => c.Name == "Max")
        .And(c => c.Age > 4)
        .List();]]></programlisting>
        <para>
            Note, the methods Where() and And() are semantically identical; the And() method is purely to allow
            QueryOver to look similar to HQL/SQL.
        </para>
        <para>&nbsp;</para>
        <para>
            Boolean comparisons can be made directly instead of comparing to true/false:
        </para>
        <programlisting><![CDATA[        .Where(p => p.IsParent)
        .And(p => !p.IsRetired)]]></programlisting>
        <para>&nbsp;</para>
        <para>
            Simple expressions can also be combined using the || and &amp;&amp; operators.  So ICriteria like:
        </para>
        <programlisting><![CDATA[        .Add(Restrictions.And(
                Restrictions.Eq("Name", "test name"),
                Restrictions.Or(
                    Restrictions.Gt("Age", 21),
                    Restrictions.Eq("HasCar", true))))]]></programlisting>
        <para>
            Can be written in QueryOver as:
        </para>
        <programlisting><![CDATA[        .Where(p => p.Name == "test name" && (p.Age > 21 || p.HasCar))]]></programlisting>
        <para>&nbsp;</para>
        <para>
            Each of the corresponding overloads in the QueryOver API allows the use of regular ICriterion
            to allow access to private properties.
        </para>
        <programlisting><![CDATA[        .Where(Restrictions.Eq("Name", "Max"))]]></programlisting>
        <para>&nbsp;</para>
        <para>
            It is worth noting that the QueryOver API is built on top of the ICriteria API.  Internally the structures are the same, so at runtime
            the statement below, and the statement above, are stored as exactly the same ICriterion.  The actual Lambda Expression is not stored
            in the query.
        </para>
        <programlisting><![CDATA[        .Where(c => c.Name == "Max")]]></programlisting>

    </sect1>
    
    <sect1 id="queryqueryover-additionalrestrictions">
        <title>Additional Restrictions</title>

        <para>
            Some SQL operators/functions do not have a direct equivalent in C#.
            (e.g., the SQL <literal>where name like '%anna%'</literal>).
            These operators have overloads for QueryOver in the Restrictions class, so you can write:
        </para>
        <programlisting><![CDATA[        .Where(Restrictions.On<Cat>(c => c.Name).IsLike("%anna%"))]]></programlisting>
        <para>
            There is also an inline syntax to avoid the qualification of the type:
        </para>
        <programlisting><![CDATA[        .WhereRestrictionOn(c => c.Name).IsLike("%anna%")]]></programlisting>
        <para>&nbsp;</para>
        <para>
            While simple expressions (see above) can be combined using the || and &amp;&amp; operators, this is not possible with the other
            restrictions.  So this ICriteria:
        </para>
        <programlisting><![CDATA[        .Add(Restrictions.Or(
            Restrictions.Gt("Age", 5)
            Restrictions.In("Name", new string[] { "Max", "Paddy" })))]]></programlisting>
        <para>
            Would have to be written as:
        </para>
        <programlisting><![CDATA[        .Add(Restrictions.Or(
            Restrictions.Where<Cat>(c => c.Age > 5)
            Restrictions.On<Cat>(c => c.Name).IsIn(new string[] { "Max", "Paddy" })))]]></programlisting>

        <para>
            However, in addition to the additional restrictions factory methods, there are extension methods to allow
            a more concise inline syntax for some of the operators.  So this:
        </para>
        <programlisting><![CDATA[        .WhereRestrictionOn(c => c.Name).IsLike("%anna%")]]></programlisting>
        <para>
            May also be written as:
        </para>
        <programlisting><![CDATA[        .Where(c => c..Name.IsLike("%anna%"))]]></programlisting>
            
    </sect1>

    <sect1 id="queryqueryover-associations">
        <title>Associations</title>

        <para>
            QueryOver can navigate association paths using JoinQueryOver() (analogous to ICriteria.CreateCriteria() to create sub-criteria).
        </para>
        <para>
            The factory method QuerOver&lt;T&gt;() on ISession returns an IQueryOver&lt;T&gt;.
            More accurately, it returns an IQueryOver&lt;T,T&gt; (which inherits from IQueryOver&lt;T&gt;).
        </para>
        <para>
            An IQueryOver has two types of interest; the root type (the type of entity that the query returns),
            and the type of the 'current' entity being queried.  For example, the following query uses
            a join to create a sub-QueryOver (analogous to creating sub-criteria in the ICriteria API):
        </para>
        <programlisting><![CDATA[IQueryOver<Cat,Kitten> catQuery =
    session.QueryOver<Cat>()
        .JoinQueryOver(c => c.Kittens)
            .Where(k => k.Name == "Tiddles");]]></programlisting>
        <para>
            The JoinQueryOver returns a new instance of the IQueryOver than has its root at the Kittens collection.
            The default type for restrictions is now Kitten (restricting on the name 'Tiddles' in the above example),
            while calling .List() will return an IList&lt;Cat&gt;.  The type IQueryOver&lt;Cat,Kitten&gt; inherits from IQueryOver&lt;Cat&gt;.
        </para>
        <para>
            Note, the overload for JoinQueryOver takes an IEnumerable&lt;T&gt;, and the C# compiler infers the type from that.
            If your collection type is not IEnumerable&lt;T&gt;, then you need to qualify the type of the sub-criteria:
        </para>
        <programlisting>IQueryOver&lt;Cat,Kitten&gt; catQuery =
    session.QueryOver&lt;Cat&gt;()
        .JoinQueryOver&lt;<emphasis>Kitten</emphasis>&gt;(c =&gt; c.Kittens)
            .Where(k =&gt; k.Name == "Tiddles");</programlisting>
        <para>&nbsp;</para>
        <para>
            The default join is an inner-join.  Each of the additional join types can be specified using
            the methods <code>.Inner, .Left, .Right,</code> or <code>.Full</code>.
            For example, to left outer-join on Kittens use:
        </para>
        <programlisting><![CDATA[IQueryOver<Cat,Kitten> catQuery =
    session.QueryOver<Cat>()
        .Left.JoinQueryOver(c => c.Kittens)
            .Where(k => k.Name == "Tiddles");]]></programlisting>
    
    </sect1>

    <sect1 id="queryqueryover_entityjoin">
      <title>Join entities without association (Entity joins or ad hoc joins)</title>
      <para>
        In QueryOver you have the ability to define a join to any entity, not just through a mapped association.
        To achieve it, use <literal>JoinEntityAlias</literal> and <literal>JoinEntityQueryOver</literal>. By example:
      </para>

      <programlisting><![CDATA[Cat cat = null;
Cat joinedCat = null;

var uniquelyNamedCats = sess.QueryOver<Cat>(() => cat)
    .JoinEntityAlias(
        () => joinedCat,
        () => cat.Name == joinedCat.Name && cat.Id != joinedCat.Id,
        JoinType.LeftOuterJoin)
    .Where(() => joinedCat.Id == null)
    .List();]]></programlisting>
    </sect1>

    <sect1 id="queryqueryover-aliases">
        <title>Aliases</title>

        <para>
            In the traditional ICriteria interface aliases are assigned using 'magic strings', however their value
            does not correspond to a name in the object domain.  For example, when an alias is assigned using
            <code>.CreateAlias("Kitten", "kittenAlias")</code>, the string "kittenAlias" does not correspond
            to a property or class in the domain.
        </para>
        <para>
            In QueryOver, aliases are assigned using an empty variable.
            The variable can be declared anywhere (but should
            be <code>null</code> at runtime).  The compiler can then check the syntax against the variable is
            used correctly, but at runtime the variable is not evaluated (it's just used as a placeholder for
            the alias).
        </para>
        <para>
            Each Lambda Expression function in QueryOver has a corresponding overload to allow use of aliases,
            and a .JoinAlias function to traverse associations using aliases without creating a sub-QueryOver.
        </para>
        <programlisting><![CDATA[Cat catAlias = null;
Kitten kittenAlias = null;

IQueryOver<Cat,Cat> catQuery =
    session.QueryOver<Cat>(() => catAlias)
        .JoinAlias(() => catAlias.Kittens, () => kittenAlias)
        .Where(() => catAlias.Age > 5)
        .And(() => kittenAlias.Name == "Tiddles");]]></programlisting>

    </sect1>

    <sect1 id="queryqueryover-projections">
        <title>Projections</title>

        <para>
            Simple projections of the properties of the root type can be added using the <code>.Select</code> method
            which can take multiple Lambda Expression arguments:
        </para>
        <programlisting><![CDATA[var selection =
    session.QueryOver<Cat>()
        .Select(
            c => c.Name,
            c => c.Age)
        .List<object[]>();]]></programlisting>
        <para>
            Because this query no longer returns a Cat, the return type must be explicitly specified.
            If a single property is projected, the return type can be specified using:
        </para>
        <programlisting><![CDATA[IList<int> ages =
    session.QueryOver<Cat>()
        .Select(c => c.Age)
        .List<int>();]]></programlisting>
        <para>
            However, if multiple properties are projected, then the returned list will contain
            object arrays, as per a projection
            in ICriteria.  This could be fed into an anonymous type using:
        </para>
        <programlisting><![CDATA[var catDetails =
    session.QueryOver<Cat>()
        .Select(
            c => c.Name,
            c => c.Age)
        .List<object[]>()
        .Select(properties => new {
            CatName = (string)properties[0],
            CatAge = (int)properties[1],
            });
            
Console.WriteLine(catDetails[0].CatName);
Console.WriteLine(catDetails[0].CatAge);]]></programlisting>
        <para>
            Note that the second <code>.Select</code> call in this example is an extension method on IEnumerable&lt;T&gt; supplied in System.Linq;
            it is not part of NHibernate.
        </para>
        <para>&nbsp;</para>
        <para>
            QueryOver allows arbitrary IProjection to be added (allowing private properties to be projected).  The Projections factory
            class also has overloads to allow Lambda Expressions to be used:
        </para>
        <programlisting><![CDATA[var selection =
    session.QueryOver<Cat>()
        .Select(Projections.ProjectionList()
            .Add(Projections.Property<Cat>(c => c.Name))
            .Add(Projections.Avg<Cat>(c => c.Age)))
        .List<object[]>();]]></programlisting>
        <para>&nbsp;</para>
        <para>
            In addition there is an inline syntax for creating projection lists that does not require the explicit class qualification:
        </para>
        <programlisting><![CDATA[var selection =
    session.QueryOver<Cat>()
        .SelectList(list => list
            .Select(c => c.Name)
            .SelectAvg(c => c.Age))
        .List<object[]>();]]></programlisting>
        <para>&nbsp;</para>
        <para>
            Projections can also have arbitrary aliases assigned to them to allow result transformation.
            If there is a CatSummary DTO class defined as:
        </para>
        <programlisting><![CDATA[public class CatSummary
{
    public string Name { get; set; }
    public int AverageAge { get; set; }
}]]></programlisting>
        <para>
            ... then aliased projections can be used with the AliasToBean&lt;T&gt; transformer:
        </para>
        <programlisting><![CDATA[CatSummary summaryDto = null;
IList<CatSummary> catReport =
    session.QueryOver<Cat>()
        .SelectList(list => list
            .SelectGroup(c => c.Name).WithAlias(() => summaryDto.Name)
            .SelectAvg(c => c.Age).WithAlias(() => summaryDto.AverageAge))
        .TransformUsing(Transformers.AliasToBean<CatSummary>())
        .List<CatSummary>();]]></programlisting>

    </sect1>

    <sect1 id="queryqueryover-projectionfunctions">
        <title>Projection Functions</title>

        <para>
            In addition to projecting properties, there are extension methods to allow certain common dialect-registered
            functions to be applied.  For example you can write the following to get 3 letters named people.
        </para>
        <programlisting><![CDATA[        .Where(p => p.FirstName.StrLength() == 3)]]></programlisting>
        
        <para>
            The functions can also be used inside projections:
        </para>
        <programlisting><![CDATA[        .Select(
            p => Projections.Concat(p.LastName, ", ", p.FirstName),
            p => p.Height.Abs())]]></programlisting>

    </sect1>

    <sect1 id="queryqueryover-projectionentities">
      <title>Entities Projection</title>

      <para>
        You can add entity projections via the <literal>AsEntity()</literal> extension.
      </para>

      <programlisting><![CDATA[Cat mate = null;

var catAndMateNameList = sess.QueryOver<Cat>()
    .JoinAlias(c => c.Mate, () => mate)
    .Select(c => c.AsEntity(), c => mate.Name)
    .List<object[]>();]]></programlisting>

      <para>
        Or it can be done via the <literal>Projections.RootEntity</literal> and <literal>Projections.Entity</literal> methods
        if more control over loaded entities is required. For instance, entity projections can be lazy loaded
        or fetched with lazy properties:
      </para>
      <programlisting><![CDATA[.Select(
    Projections.Entity(() => alias1).SetLazy(true),
    Projections.Entity(() => alias2).SetFetchLazyProperties(true),
    Projections.RootEntity()
        )]]></programlisting>
    </sect1>

    <sect1 id="queryqueryover-subqueries">
        <title>Sub-queries</title>

        <para>
            The Sub-queries factory class has overloads to allow Lambda Expressions to express sub-query
            restrictions.  For example:
        </para>
        <programlisting><![CDATA[QueryOver<Cat> maximumAge =
    QueryOver.Of<Cat>()
        .SelectList(p => p.SelectMax(c => c.Age));

IList<Cat> oldestCats =
    session.QueryOver<Cat>()
        .Where(Subqueries.WhereProperty<Cat>(c => c.Age).Eq(maximumAge))
        .List();]]></programlisting>
        <para>&nbsp;</para>
        <para>
            The inline syntax allows you to use sub-queries without re-qualifying the type:
        </para>
        <programlisting><![CDATA[IList<Cat> oldestCats =
    session.QueryOver<Cat>()
        .WithSubquery.WhereProperty(c => c.Age).Eq(maximumAge)
        .List();]]></programlisting>
        <para>&nbsp;</para>
        <para>
            There is an extension method <code>As()</code> on (a detached) QueryOver that allows you to cast it to any type.
            This is used in conjunction with the overloads <code>Where(), WhereAll(),</code> and <code>WhereSome()</code>
            to allow use of the built-in C# operators for comparison, so the above query can be written as:
        </para>
        <programlisting><![CDATA[IList<Cat> oldestCats =
    session.QueryOver<Cat>()
        .WithSubquery.Where(c => c.Age == maximumAge.As<int>())
        .List();]]></programlisting>

    </sect1>

</chapter>