The .Net 4 CompareTo method of strings and numerical types is translated to a case statement yielding -1|0|1 according to the result of the comparison.

Many type conversions are available. For all of them, .Net overloads with more than one argument are not supported.

Numerical types can be converted to other numerical types or parsed from strings, using following methods:

Strings can be converted to Boolean and DateTime with Convert.ToBoolean or Boolean.Parse and Convert.ToDateTime or DateTime.Parse respectively.

On all types supporting string conversion, ToString method can be called.

IList<string> catBirthDates =
    session.Query<Cat>()
        .Select(c => c.BirthDate.ToString())
        .ToList();

Equals methods taking a single argument with the same type can be used. Of course, == is supported too.

Date and time parts properties can be called on DateTime and DateTimeOffset. Those properties are:

Collections Contains methods are supported.

IList<Cat> catsWithWrongKitten =
    session.Query<Cat>()
        .Where(c => c.Kittens.Contains(c))
        .ToList();

Dictionaries Item getter are supported. This enables referencing a dictionary item value in a where condition, as it can be done with HQL expressions.

Non generic dictionary method Contains and generic dictionary method ContainsKey are translated to corresponding indices HQL expressions. Supposing Acts in following HQL example is generic,

from Eg.Show show where 'fizard' in indices(show.Acts)

it could be written with Linq:

IList<Show> shows =
    session.Query<Show>()
        .Where(s => s.Acts.ContainsKey("fizard"))
        .ToList();

The following list of mathematical functions from System.Math is handled:

On Nullable<> types, GetValueOrDefault methods, with or without a provided default value, are supported.

The following properties and methods are supported on strings:

Furthermore, a string Like extension methods allows expressing SQL like conditions.

IList<DomesticCat> cats =
    session.Query<DomesticCat>()
        .Where(c => c.Name.Like("L%l%l"))
        .ToList();

This Like extension method is a Linq to NHibernate method only. Trying to call it in another context is not supported.

If you want to avoid depending on the NHibernate.Linq namespace, you can define your own replica of the Like methods. Any 2 or 3 arguments method named Like in a class named SqlMethods will be translated.

InsertInto and InsertBuilder method extensions expect a NHibernate queryable defining the data source of the insert. This data can be entities or a projection. Then they allow specifying the target entity type to insert, and how to convert source data to those target entities. Three forms of target specification exist.

Using projection to target entity:

session.Query<Cat>()
    .Where(c => c.BodyWeight > 20)
    .InsertInto(c => new Dog { Name = c.Name + "dog", BodyWeight = c.BodyWeight });

Projections can be done with an anonymous object too, but it requires supplying explicitly the target type, which in turn requires re-specifying the source type:

session.Query<Cat>()
    .Where(c => c.BodyWeight > 20)
    .InsertInto<Cat, Dog>(c => new { Name = c.Name + "dog", BodyWeight = c.BodyWeight });

Or using assignments:

session.Query<Cat>()
    .Where(c => c.BodyWeight > 20)
    .InsertBuilder()
    .Into<Dog>()
    .Value(d => d.Name, c => c.Name + "dog")
    .Value(d => d.BodyWeight, c => c.BodyWeight)
    .Insert();

In all cases, unspecified properties are not included in the resulting SQL insert. version and timestamp properties are exceptions. If not specified, they are inserted with their seed value.

For more information on Insert limitations, please refer to Section 13.3, “DML-style operations”.

Update and UpdateBuilder method extensions expect a NHibernate queryable defining the entities to update. Then they allow specifying which properties should be updated with which values. As for insertion, three forms of target specification exist.

Using projection to updated entity:

session.Query<Cat>()
    .Where(c => c.BodyWeight > 20)
    .Update(c => new Cat { BodyWeight = c.BodyWeight / 2 });

Projections can be done with an anonymous object too:

session.Query<Cat>()
    .Where(c => c.BodyWeight > 20)
    .Update(c => new { BodyWeight = c.BodyWeight / 2 });

Or using assignments:

session.Query<Cat>()
    .Where(c => c.BodyWeight > 20)
    .UpdateBuilder()
    .Set(c => c.BodyWeight, c => c.BodyWeight / 2)
    .Update();

In all cases, unspecified properties are not included in the resulting SQL update. This could be changed for version and timestamp properties: using UpdateVersioned instead of Update allows incrementing the version. Custom version types (NHibernate.Usertype.IUserVersionType) are not supported.

When using projection to updated entity, please note that the constructed entity must have the exact same type than the underlying queryable source type. Attempting to project to any other class (anonymous projections excepted) will fail.

Delete method extension expects a queryable defining the entities to delete. It immediately deletes them.

session.Query<Cat>()
    .Where(c => c.BodyWeight > 20)
    .Delete();

NHibernate Linq provider feature a LinqExtensionMethod attribute. It allows using an arbitrary, built-in or user defined, SQL function. It should be applied on a method having the same arguments than the SQL function.

public static class CustomLinqExtensions
{
    [LinqExtensionMethod()]
    public static string Checksum(this double input)
    {
        // No need to implement it in .Net, unless you wish to call it
        // outside IQueryable context too.
        throw new NotImplementedException("This call should be translated " +
            "to SQL and run db side, but it has been run with .Net runtime");
    }
}

Then it can be used in a Linq to NHibernate query.

var rnd = (new Random()).NextDouble();
IList<Cat> cats =
    session.Query<Cat>()
        // Pseudo random order
        .OrderBy(c => (c.Id * rnd).Checksum())
        .ToList();

The function name is inferred from the method name. If needed, another name can be provided.

public static class CustomLinqExtensions
{
    [LinqExtensionMethod("dbo.aCustomFunction")]
    public static string ACustomFunction(this string input, string otherInput)
    {
        throw new NotImplementedException();
    }
}

Since NHibernate v5.0, the Linq provider will no more evaluate in-memory the method call even when it does not depend on the queried data. If you wish to have the method call evaluated before querying whenever possible, and then replaced in the query by its resulting value, specify LinqExtensionPreEvaluation.AllowPreEvaluation on the attribute.

public static class CustomLinqExtensions
{
    [LinqExtensionMethod("dbo.aCustomFunction",
        LinqExtensionPreEvaluation.AllowPreEvaluation)]
    public static string ACustomFunction(this string input, string otherInput)
    {
        // In-memory evaluation implementation.
        return input.Replace(otherInput, "blah");
    }
}

Generators are responsible for translating .Net method calls found in lambdas to the proper HQL constructs. Adding support for a new method call can be achieved by registering an additional generator in the Linq to NHibernate provider.

If the purpose of the added method is to simply call some SQL function, using Section 17.8.1, “Adding SQL functions” will be easier.

As an example, here is how to add support for an AsNullable method which would allow to call aggregates which may yield null without to explicitly cast to the nullable type of the aggregate.

public static class NullableExtensions
{
    public static T? AsNullable<T>(this T value) where T : struct
    {
        // Allow runtime use.
        // Not useful for linq-to-nhibernate, could be:
        // throw NotSupportedException();
        return value;
    }
}

Adding support in Linq to NHibernate for a custom method requires a generator. For this AsNullable method, we need a method generator, declaring statically its supported method.

public class AsNullableGenerator : BaseHqlGeneratorForMethod
{
    public AsNullableGenerator()
    {
        SupportedMethods = new[]
        {
             ReflectHelper.GetMethodDefinition(() => NullableExtensions.AsNullable(0))
        };
    }

    public override HqlTreeNode BuildHql(MethodInfo method,
        Expression targetObject,
        ReadOnlyCollection<Expression> arguments,
        HqlTreeBuilder treeBuilder,
        IHqlExpressionVisitor visitor)
    {
        // This has just to transmit the argument "as is", HQL does not need
        // a specific call for null conversion.
        return visitor.Visit(arguments[0]).AsExpression();
    }
}

There are property generators too, and the supported methods or properties can be dynamically declared. Check NHibernate NHibernate.Linq.Functions namespace classes's sources for more examples. CompareGenerator and DateTimePropertiesHqlGenerator are examples of those other cases.

For adding AsNullableGenerator in Linq to NHibernate provider, a new generators registry should be used. Derive from the default one and merge it. (Here we have a static declaration of method support case.)

public class ExtendedLinqToHqlGeneratorsRegistry :
DefaultLinqToHqlGeneratorsRegistry
{
    public ExtendedLinqToHqlGeneratorsRegistry()
        : base()
    {
        this.Merge(new AsNullableGenerator());
    }
}

In the case of dynamic declaration of method support, another call is required instead of the merge: RegisterGenerator. CompareGenerator illustrates this.

The last step is to instruct NHibernate to use this extended registry. It can be achieved through xml configuration under session-factory node, or by code before building the session factory. Use one of them.

<property name="linqtohql.generatorsregistry">
    YourNameSpace.ExtendedLinqToHqlGeneratorsRegistry, YourAssemblyName
</property>

using NHibernate.Cfg;
// ...

var cfg = new Configuration();
cfg.LinqToHqlGeneratorsRegistry<ExtendedLinqToHqlGeneratorsRegistry>();
// And build the session factory with this configuration.

Now the following query could be executed, without failing if no Max cat exists.

var oldestMaxBirthDate =
    session.Query<Cat>()
        .Where(c => c.Name == "Max")
        .Select(c => c.BirthDate.AsNullable())
        .Min();

(Of course, the same result could be obtained with (DateTime?)(c.BirthDate).)

By default, the Linq provider will try to evaluate the method call with .Net runtime whenever possible, instead of translating it to SQL. It will not do it if at least one of the parameters of the method call has its value originating from an entity, or if the method is marked with the NoPreEvaluation attribute (available since NHibernate 5.0).