Ms Sql Server FREETEXT and CONTAINS functions are used into FullText search capabilities to querying. These functions are of course natives to this particular RDBMS and even comes a with particular structure: they don?t return a value. So far, till NH 2.0, you couldn?t do it because a little parser issue, but from NHibernate 2.1 in forward you?re enable register them.

First of all, we define the new dialect with the new functions in order that when we run a query, NHibernate can recognize those functions and can transform to native-sql, in this case, Transact-SQL.

using NHibernate.Dialect;
using NHibernate.Dialect.Function;

namespace MyCompany.Data
{
    public class MyDialect : MsSql2008Dialect
    {
        public MyDialect()
        {
            RegisterFunction("freetext", new StandardSQLFunction("freetext", null));
            RegisterFunction("contains", new StandardSQLFunction("contains", null));
        }
    }
}

Note that we are using StandardSQLFunction, we can also use SQLFunctionTemplate or implement our ISQLFunction class with all the constraints (ie: parameter number accepted) we need.

Once our new dialect is ready let?s call it from our hibernate.cfg.xml file, then NHibernate can know that this dialect will be inject. Suppose MyDialect is placed into the assembly MyCompany.Data, so the configuration file should look like this:

<?xml version="1.0" encoding="utf-8" ?>
<hibernate-configuration  xmlns="urn:nhibernate-configuration-2.2" >
    <session-factory name="NH">
        <property name="dialect">MyCompany.Data.MyDialect, MyCompany.Data</property>
        <property name="connection.connection_string">
            Data Source=(local)\sqlexpress;Initial Catalog=test;Integrated Security = true
        </property>
        <property name="proxyfactory.factory_class">NHibernate.ByteCode.LinFu.ProxyFactoryFactory, NHibernate.ByteCode.LinFu</property>
    </session-factory>
</hibernate-configuration>

Everything is ready, you just have to do this 2 steps and the functions are ready to use it, then we can query using them.

session.CreateQuery("from Documento where freetext(Texto,:keywords)")
    .SetString("keywords","hey apple car")
    .List();

Note the above query is HQL, so NHibernate knows about freetext and can operate with it.

A few days ago Oren Eini and Davy Brion were working in a new feature for NH 2.1 (no a release yet) called Future, in the ICriteria API. You can see and explanation of the job here. Now I?ve committed a complement to enable that use into the IQuery API, for those who prefer to use HQL.

What is Future Query anyway? Future are queries that are kept, waiting to be executed as a group in just one roundtrip, making use of an underlying NHibernate feature: MultiCriteria/MultiQuery.

Let?s have a look to this simple piece of code. You can see both queries sentences, and both are executed in that sentence point against the database producing 2 roundtrips to the database. Nothing weird about this, but what if we can just execute the queries in just one roundtrip?

And now, using Future we can hold the execution, in this case just two, but we can hold how many queries we need.

Where is the trick? Future method is returning a delayed enumerable implementation, that?s all. When you iterate the enumerable (with a foreach for example), it detects and execute all the queries using a NHibernate-MultiQuery command (could be a MultiCriteria, it depends what we are using). But we don?t need to know nothing about the underlying implementation, just the concept.

In other terms, this is what happens behind the scenes:

But what if we want to retrieve an entity or a scalar ? This is too simple for an IEnumerable. Thanks to Davy Brion we have another feature called FutureValue. The mechanism is the same as Future, but instead of expect a IEnumerable, we obtain a single value (an entity or a scalar).

Note: examples adapted from Davy Brion posts [1] and [2].

I know, this title sound like: “hmm?” Let me explain it with more detail.

NHibernate is a framework that use natively Xml in order to configure a mapping between objects and tables, is in charged of join these different worlds.

But now, what is going wrong with this? Many people can say that Xml files are evil, because you should write a lot of lines, and when you build your project, the compiler doesn’t know if its ok or not, you have none errors. And this is true, you should run your project and see what happen in runtime, and to get an error in runtime is just annoying.

But now, do we have another alternative to this? Yes of course. Lets go to details. NHibernate has a “compiler” too, and you can guess what it is: BuildSessionFactory() method. You don’t have to launch the whole application to know if your mapping is working well. A way to know if everything is ok is create a test like this:

Then you just need to build the project, and run this simple and fool test, if your code pass though this, your mappings are ok.

We should remember one thing, you can map into Xml not just entities, you can map queries too (and another stuff that isn’t part of this matter). To map queries into Xml it calls: Named Queries, and in this post we talk about this matter. But the main point is, mapping the queries you will know if them are well formed when BuildSessionFactory() is raised, besides another beauties discussed in that post.

Another thing you should remember is you MUST use the Xsd to validate the mapping file. This is mandatory if you’re using NHibernate and you want to spend time programming instead of dealing with mapping errors (and here they come even with not-well-formed xmls). But this is topic to an How to or another post.