QueryX 2.1.0

QueryX

QueryX allows performing filtering, paging and sorting to IQueryable ends using URL query strings.

Installation

Install with nuget:

Install-Package QueryX

Usage

A filter model is needed to define the properties that will be used for filtering, this model could be an specific filter class, a Dto or a Domain model object.

public class Card
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public int Priority { get; set; }
    public float EstimatedPoints { get; set; }
    public List<User> Owners { get; set; }
}

By default all properties can be used for filtering and sorting, this could be customized using fluent configuration.

Example

QueryX adds ApplyQuery extension methods to IQueryable interface to perform queries:

var filter = "priority > 1";
var result = _context.Set<Card>().ApplyQuery(filter).ToList();

Filtering

Filtering is made using operators, so a filter is defined this way: propertyName operator value.

It is possible to combine multiple filters using "and" (&) and "or" (|) logical operators:

id>1 & title=-'test' | priority|=1,2

For facilitating writing queries in URL, ; (semicolon) character can be used instead for representing the and logical operator:

id>1 ; title=-'test' | priority|=1,2

Filter grouping

Filters can be also grouped using parentheses to determine how they should be evaluated:

id>1 ; (title=-'test' | priority|=1,2)

Collection filters

It is possible to specify filters for collection properties with the following syntax:

propertyName(childPropertyName operator value)

The above code will use the Enumerable.Any method for applying the conditions.

For using the Enumerable.All method:

propertyName*(childPropertyName operator value)

An example using the Card object would be:

owners(id==1 | name=='user2')

Supported value types

Operators

Multiple values are specified this way: 0,1,2 or 'val1','val2','val3' if the values are strings

Case insensitive operator

All operators can be combined with the case insensitive operator (*) for ignoring case when comparing strings:

title ==* 'TeSt VaLuE'

This operator is intended to work only with string properties

Not Operator

The not operator (!) can be applied to any filter, collection filter or group:

!id>1 ; !title=-'test' | !priority|=1,2

id>1 ; !(title=-'test' | priority|=1,2)

!owners(id==1 | name=='user2')

Sorting and Paging

The ApplyOrderingAndPaging method allow specifying ordering.

For ascending order base on property Title:

title

For descending order:

-title

It is possible to combine multiple orderings:

id,-priority,title

Example:

var sortBy = "-estimatedPoints";
var offset = 10;
var limit = 10;
_context.Set<Card>().ApplyOrderingAndPaging(sortBy, offset, limit);

Customize filtering and sorting

It is possible to customize the filtering behavior with QueryMappingConfig class:

QueryMappingConfig.Global
    .For<Card>(cfg => 
    {
        // mapping configurations
    });

Map property name:

Allows mapping a property with a different name that will appear in the filter or sortBy string:

cfg.Property(c => c.Priority).MapFrom("queryPriority");
cfg.Property(c => c.Board.Title).MapFrom("bTitle");

Additionally, MapFrom method supports a second parameter to apply custom conversion from string to the property type:

cfg.Property(c => c.Priority).MapFrom("queryPriority", value => int.ParseInt(value));

Ignore properties:

Ignore properties from filter and sorting steps. IgnoreFilter and IgnoreSort methods exists also.

cfg.Property(c => c.Priority).Ignore();

Custom filters:

This properties are excluded as part of the filter, custom code needs to be written for doing something with the filter values. Custom filters are applied after all filters have been applied

cfg.Property(c => c.Priority).CustomFilter((source, values, op) => 
{
    // source   : IQueryable instance to apply the custom filter
    // values   : values specified in filter string
    // op       : operator for this filter
    return source.Where(c => c.Priority == values[0]);
});

Custom sort:

This properties are excluded as part of the sort behavior, custom code needs to be written to apply them. Custom filters are applied after all filters have been applied

cfg.Property(c => c.Priority).CustomSort((source, ascending, isOrdered) => 
{
    // source   : IQueryable instance to apply the custom filter
    // ascending: indicates if the sorting should be done in ascending direction
    // isOrdered: indicates if the IQueryable instace have been already ordered, if true, ThenBy and ThenByDescending methods should be used as appropriate
    return isOrdered
        ? ascending
            ? source.ThenBy(c => c.Priority)
            : source.ThenByDescending(c => c.Priority)
        : ascending
            ? source.OrderBy(c => c.Priority)
            : source.OrderByDescending(c => c.Priority);
});

Concatenate configurations:

Configurations can be concatenated as required:

cfg.Property(c => c.Priority).MapFrom("queryPriority").Ignore();
cfg.Property(c => c.Board.Title).MapFrom("bTitle").CustomFilter((source, values, op) => 
{
    // ...
});

Override global configurations

The configurations created using QueryMappingConfig.Global are applied globally. ApplyQuery and ApplyOrderingAndPaging methods accepts a QueryMappingConfig instance in case specific configuration is needed:

var config = new QueryMappingConfig();
config.For<Card>(cfg =>
{
    // set specific configurations
});

var filter = "id |= 2,4,6";
_context.Set<Card>().ApplyQuery(filter, mappingConfig: config);

Extending global configuration is also possible:

var config = QueryMappingConfig.Global.Clone()
config.For<Card>(cfg =>
{
    // set specific configurations
});

var filter = "id |= 2,4,6";
_context.Set<Card>().ApplyQuery(filter, mappingConfig: config);

QueryModel

QueryModel is a class that can be used to capture user parameters in a WebAPI endpoint, it contains Filter, SortBy, Offset and Limit properties. ApplyQuery and ApplyOrderingAndPaging methods have overloads to receive a QueryModel instance.

Query exceptions

By default invalid properties will be ignored for filtering and ordering but it is possible to change this behavior by calling ThrowQueryExceptions() when registering QueryX:

builder.Services.AddQueryX(o => o.ThrowQueryExceptions(false));

These exceptions will be thrown as appropriate:

• InvalidFilterPropertyException for filtering errors
• InvalidOrderingPropertyException for ordering errors

It is also possible set this configuration using QueryMappingConfig:

QueryMappingConfig.Global
    .SetQueryConfiguration(options => options.ThrowQueryExceptions(true));