Built a Fluent, Strongly-Typed Query Builder for NHibernate (NHQueryBuilder) — Looking for feedback!

[pdesai84]

I’ve been working on an open-source tool called NHQueryBuilder, designed specifically for NHibernate developers who build complex criteria queries and want a more fluent, strongly-typed, discoverable API.

Instead of chaining a bunch of CreateAlias, Restrictions., Projections., etc., you can build queries with a LINQ-style fluent syntax — while still generating classic NHibernate ICriteria under the hood.

Why I built it

NHibernate is still heavily used in many enterprise and legacy systems, but writing advanced queries with Criteria API gets verbose quickly. So NHQueryBuilder tries to make it:

• Strongly typed
• Fluent and expressive
• Less error-prone
• Easier to read/maintain
• Still fully compatible with NHibernate ISession

Old way:

var criteria = session.CreateCriteria<ObjectLink>("Author")
    .CreateAlias("Aurthor.Attachment", "Attachment")
    .CreateAlias("Attachment.Type", "attachmentType")
    .Add(Restrictions.In("attachmentType.Code", new[] { "PDF", "Q" }))
    .SetProjection(Projections.Property("Attachment.Type.Code"))
    .SetFirstResult(10)
    .SetMaxResults(10);

var result = criteria.List<string>();

NHQueryBuilder way:

var c = new FluentConditions<Author>()
    .IsIn(x => x.Attachment.Type.Code, new[] { "PDF", "Q" })
    .Select(x => x.Attachment.Type.Code)
    .Skip(10)
    .Take(10);
var result = session.GetProjectedList(c);

GitHub

Source code, full README, examples, and documentation:
https://github.com/pdesai84/NHQueryBuilder

NuGet

Package is available here:
https://www.nuget.org/packages/NHQueryBuilder

Feedback

I’d love your feedback!

Since people have begun using it, I’d really appreciate feedback from the community:

• Is this useful?
• What features should be added?
• Any limitations or improvements you’d like?

If you try it out and have ideas, please share them in GitHub Discussions:
https://github.com/pdesai84/NHQueryBuilder/discussions

Or report an issue here:
https://github.com/pdesai84/NHQueryBuilder/issues

Thanks!

[fredericDelaporte]

It looks to me you are reinventing QueryOver.

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.

But I have not used any of them much, so, I cannot tell why would QueryOver not match your goals.

[pdesai84]

For a simple query QueryOver is fine. However, when you would like to condition over the multiple columns over the multiple tables, the QueryOver gets complicated. You have to add lot of alias and Fetch conditions. However, in my example, you can just skip all these complexities. If you like to I can give you complex example.

[pdesai84]

Look at the following complexity:

var queryResult = session.QueryOver<Author>()
    .JoinQueryOver(x => x.Attachment)
    .JoinQueryOver(x => x.Type)
    .Where(x => x.Code.IsIn(new[] { "PDF", "Q" }))
    .JoinQueryOver(x => x.Book)
    .Where(x => x != null)
    .JoinQueryOver(x => x.BookType)
    .Where(x => x.Code == "Fantasy" || x.Code == "FairtTale")
    .JoinQueryOver(x => x.Borrower)
    .SelectList(list => list
    .Select(x => x.Borrower.Code)
    .Select(x => x.Borrower.Name)
    )
    .Skip(10)
    .Take(10);

Using NHQueryBuilder:

var queryResult = new FluentConditions<Author>()
           .IsIn(x => x.Attachment.Type.Code, new[] { "PDF", "Q" })
           .IsNotNull(x => x.Book)
           .Equal(x => x.Book.BookType.Code, "Fantasy").OR.Equal(x => x.Book.BookType.Code, "FairtTale")
           .Select(x => new { x.Borrower.Code, x.Borrower.Name })
           .Skip(10)
           .Take(10);
var result = session.GetProjectedList(authorCond);