Dekiru.QueryFilter 2.3.0

Dynamic query filter parser

This library provides a parser for a simple query language that can be used to filter data in the form of IQueryable<T>. The main use case is to provide a simple query language for REST APIs to use with Entity Framework Core. The library is inspired by the OData query language, but only a subset of the OData query language is supported (i.e., $filter, $orderby, and $expand).

The library is available as a NuGet package: Dekiru.QueryFilter.

The two main methods are FilterDynamic and IncludeDynamic which can be used to filter and include related entities respectively. The methods are defined as extension methods on IQueryable<T>.

The methods take a string as input which is parsed and converted to an expression tree. The expression tree is then used to filter the data or define the related entities to include. The included entities may also be filtered.

Generally, all methods can be called either as a static method or as a member method. The syntax is either myMethod(SomeCollection) or SomeCollection.myMethod(). There is no functional difference between the two syntaxes, it is just a matter of preference.

Some methods may be called with a predicate, they are defined as a lamba expression:

SomeCollection.myMethod(c: c.Name eq 'John')

Nested predicates are supported:

SomeCollection.myMethod(c: c.OtherProp.Count(r: r.Name eq 'Bar') gt 5)

There is a special meta variable called $, that can be used to refer to the Entity Framework Core DbContext instance. This can be used to filter on entities that are not connected to the entity that is being queried.

Note: Null semantics, as well as case sensitivity, are determined by the underlying data source.

Operators

The following infix/prefix operators are supported:

• and - SQL AND operator
• or - SQL OR operator
• not - SQL NOT operator
• eq - SQL = operator
• ne - SQL <> operator
• gt - SQL > operator
• ge - SQL >= operator
• lt - SQL < operator
• le - SQL <= operator

Functions

• any() - Returns true if the collection contains any entries: Items.any()
• any(predicate) - Returns true if the collection contains any entries that match the predicate: Items.any(i: i.Name eq "Foo")
• all(predicate) - Returns true if all of the entries in the collection matches the predicate: Items.all(i: i.Name eq "Foo")
• startsWith(match) - Returns true if the string starts with the given value: Name.startsWith("foo")
• endsWith(match) - Returns true if the string ends with the given value: Name.endsWith("foo")
• substring(start) - Extracts characters to the end of a string, beginning at start: Name.substring(1)
• substring(start, length) - Extracts length characters from a string, beginning at start: Name.substring(1, 5)
• datepart(datePart) - Extracts a part of a date: SomeDate.datepart("day")
• dateadd(datePart, value) - Increments or decrements a date: SomeDate.dateadd("day", 1)
• tostring() - Converts a value to a string: SomeNumber.toString()
• trim() - Removes leading and trailing whitespace from a string: Name.trim()
• length() - Example: Name.length()
• contains(arg) - Example: name.Contains("foo")
• count() - Returns the number of entries in the collection: Items.count()
• count(predicate) - Returns the number of entries in the collection that matches the predicate: Items.count(i: i.Name eq "Foo")
• sum(selector) - Returns the sum of a property in all entries in the collection: Items.sum(i: i.SomeNumber)
• max(selector) - Returns the maximum value of a property in the collection: Items.max(i: i.SomeNumber)
• coalesce(alternative) - Returns the value of the property if it is not null, otherwise the supplied value will be returned: Name.coalesce("bar")
• empty() - Returns true if the property is an empty string: Name.empty()
• isnull() - Returns true if the property is null: Name.isnull()
• lower() - Converts a string to lower case: Name.lower()
• upper() - Converts a string to upper case: Name.upper()
• now() - Returns a DateTime object representing the current date and time: now()
• utcNow() - Returns a DateTime object representing the current date and time in UTC: utcNow()
• long() - Converts a value to a long: SomeProp.long()
• ulong() - Converts a value to an unsigned long: SomeProp.ulong()
• int() - Converts a value to an int: SomeProp.int()
• uint() - Converts a value to an int: SomeProp.uint()
• short() - Converts a value to a short: SomeProp.short()
• ushort() - Converts a value to an ushort: SomeProp.ushort()
• byte() - Converts a value to a byte: SomeProp.byte()
• sbyte() - Converts a value to an sbyte: SomeProp.sbyte()
• decimal() - Converts a value to a decimal: SomeProp.decimal()
• double() - Converts a value to an double: SomeProp.double()
• float() - Converts a value to an float: SomeProp.float()
• bool() - Converts a value to an bool: SomeProp.bool()

Function names are case insensitive.

Sample queries

Name eq 'John' and not Name eq 'Doe'
Name eq 'John' and Age gt 30
Name eq 'John' or Age gt 30
Name eq 'John' and (Age gt 30 or Age lt 20)

Children.any()

Children.any(c: c.Name eq 'Bar')

Children.count() gt 0

Children.count(c: c.Name eq 'Bar') gt 0

Children.all(c: c.Name eq 'Bar')

Children.count(c: c.Relatives.any(r: r.Name eq 'Bar')) gt 0

Address.Country eq 'Sweden'

Name.startswith('J')

Name.endswith('n')