Logical Operators

When filtering, you can use logical operators && for and as well as || for or. For example:

Additionally, you can use ^^ for an in operator. You can add an * and use ^^* for case-insensitivity as well:

Order of Operations

You can use order of operation with parentheses like this:

Comparison Operators

There's a wide variety of comparison operators that use the same base syntax as Sieve's operators. To do a case-insensitive operation, just append a * at the end of the operator.

Sounds Like and Does Not Sound Like requires a soundex configuration on your DbContext. For more info see the docs below

Filtering Notes

• string and guid properties should be wrapped in double quotes

  • null doesn't need quotes: var input = "Title == null";

  • Double quotes can be escaped by using a similar syntax to raw-string literals introduced in C#11:

    var input = """""Title == """lamb is great on a "gee-ro" not a "gy-ro" sandwich""" """""; // OR var input = """""""""Title == """"lamb is great on a "gee-ro" not a "gy-ro" sandwich"""" """"""""";

• Dates and times use ISO 8601 format:

  • DateOnly: var filterInput = "Birthday == 2022-07-01";

  • DateTimeOffset:

    • var filterInput = "Birthday == 2022-07-01T00:00:03Z";

  • DateTime: var filterInput = "Birthday == 2022-07-01";

    • var filterInput = "Birthday == 2022-07-01T00:00:03";
    • var filterInput = "Birthday == 2022-07-01T00:00:03+01:00";

  • TimeOnly:

    • var filterInput = "Time == 12:30:00";
    • var filterInput = "Time == 12:30:00.678722";

• bool properties need to use == true, == false, or the same using the != operator. they can not be standalone properies:

  • ❌ var input = """Title == "chicken & waffles" && Favorite""";
  • ✅ var input = """Title == "chicken & waffles" && Favorite == true""";

Complex Example

Filtering Collections

You can also filter into collections with QueryKit by using most of the normal operators. For example, if I wanted to filter for recipes that only have an ingredient named salt, I could do something like this:

By default, QueryKit will use Any under the hood when building this filter, but if you want to use All, you just need to prefix the operator with a %:

🚧 At the moment, nested collections like Ingredients.Suppliers.Rating > 4 is still under active development

If you want to filter a primitve collection like List<string> you can use the Has or DoesNotHave operator (can be case insensitive with the appended *):

If you want to filter on the count of a collection, you can prefix some of the operators with a #. For example, if i wanted to get all recipes that have more than 0 ingredients:

Settings

Property Settings

Filtering is set up to create an expression using the property names you have on your entity, but you can pass in a config to customize things a bit when needed.

• HasQueryName() to create a custom alias for a property. For exmaple, we can make FirstName aliased to first.
• PreventFilter() to prevent filtering on a given property

Custom Operators

You can also add custom comparison operators to your config if you'd like:

If you want to use it globally, you can make a base implementation like this:

Note Spaces must be used around the comparison operator when using custom values. Title @@$ "titilating" ✅ Title@@$"titilating" ❌

Allow Unknown Properties

By default, QueryKit will throw an error if it doesn't recognize a property name, If you want to loosen the reigns here a bit, you can set AllowUnknownProperties to true in your config. When active, unknown properties will be ignored in the expression resolution.

Nested Objects

Say we have a nested object like this:

To actually use the nested properties, you can do something like this:

Note, with EF core, your config might look like this:

Warning EF properties configured with HasConversion are not supported at this time -- if this is a blocker for you, i'd love to hear your use case

Sorting

Sorting is a more simplistic flow. It's just an input with a comma delimited list of properties to sort by.

Rules

• use asc or desc to designate if you want it to be ascending or descending. If neither is used, QueryKit will assume asc
• You can use Sieve syntax as well by prefixing a property with - to designate it as desc
• Spaces after commas are optional

So all of these are valid:

Property Settings

Sorting is set up to create an expression using the property names you have on your entity, but you can pass in a config to customize things a bit when needed.

• Just as with filtering, HasQueryName() to create a custom alias for a property. For exmaple, we can make FirstName aliased to first.
• PreventSort() to prevent filtering on a given property

Aggregate QueryKit Application

If you want to apply filtering and sorting in one fell swoop, you can do something like this:

Error Handling

If you want to capture errors to easily throw a 400, you can add error handling around these exceptions:

• A FilterParsingException will be thrown when there is an invalid operator or bad syntax is used (e.g. not using double quotes around a string or guid).
• An UnknownFilterPropertyException will be thrown if a property is not recognized during filtering
• A SortParsingException will be thrown if a property or operation is not recognized during sorting
• A QueryKitDbContextTypeException will be thrown when trying to use a DbContext specific workflow without passing that context (e.g. SoundEx)
• A SoundsLikeNotImplementedException will be thrown when trying to use soundex on a DbContext that doesn't have it implemented.
• A QueryKitParsingException is a more generic error that will include specific details on a more granular error in the parsing pipeline.

SoundEx

The Sounds Like and Does Not Sound Like operators require a soundex configuration on any DbContext that contain your DbSet being filtered on. Something like the below should work. The SoundsLike method does not need to implement anything and is just used as a pointer to the db method.

⭐️ Note that with Postgres, something like modelBuilder.HasPostgresExtension("fuzzystrmatch"); will need to be added like the example along with a migration for adding the extension.

You can even use this on a normal IQueryable like this:

Usage

Once your DbContext is configured to allow soundex, you'll need to provide that DbContext type in your QueryKit config. This is because, as of now, there is no reliable way to get the DbContext from an IQueryable.