Logical Operators

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

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

Here's an example for the in operator:

Property List Grouping

Property list grouping allows you to apply a single comparison operation across multiple properties, making it easy to search for a value in any of several fields without writing repetitive conditions.

Basic Syntax

Use parentheses with comma-separated property names followed by an operator and value:

How It Works

Property list grouping uses different logical operators depending on whether you're using positive or negative comparison operators:

Positive Operators (uses OR logic - match if found in ANY field):

• ==, @=, @=*, _=, _=*, _-=, _-=*, ^$, ^^
• Match if the condition is true for at least one property

Negative Operators (uses AND logic - match if NOT found in ALL fields):

• !=, !@=, !@=*, !_=, !_=*, !_-=, !_-=*, !^$, !^^
• Match only if the condition is true for every property

Examples

Case-insensitive search across multiple text fields:

Exact match on any of several properties:

Numeric comparison across multiple fields:

Negative operators (NOT contains):

Not equals:

Advanced Usage

Combined with other conditions:

Multiple property lists in one query:

Complex logical expressions:

Nested properties:

With numeric comparisons:

Use Cases

Property list grouping is particularly useful for:

1. Search functionality - Search across multiple text fields (name, email, title, etc.)
2. Multi-field validation - Ensure a value doesn't appear in any of several fields
3. Status checks - Check if any status field has a particular value
4. Flexible filtering - Allow users to search without knowing which specific field contains the data

Notes

• Works with all comparison operators listed in the comparison operators table
• Can include the same property multiple times if needed: (FirstName, FirstName, LastName)
• Supports any number of properties in the list
• Handles whitespace around commas gracefully: ( FirstName , LastName )
• Type safety - All properties in the list should be compatible with the comparison value type
• Nullable properties are handled automatically

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 and should be surrounded by double quotes:

  • 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

Property-to-Property Comparisons

QueryKit supports comparing one property directly to another property on the same entity. This allows for dynamic filtering where the comparison value is another field rather than a literal value:

Property-to-property comparisons work with all comparison operators and automatically handle type conversions between compatible numeric types (e.g., comparing int with decimal).

Child Property Comparisons

You can also compare child properties to root properties or other child properties:

Child property comparisons work with:

• Nested Objects: Author.Name, Email.Value
• All Operators: ==, !=, >, <, >=, <=
• Type Conversion: Automatic conversion between compatible types
• Complex Expressions: Can be combined with logical operators and parentheses

Arithmetic Expressions

QueryKit supports arithmetic expressions in filters, allowing you to perform calculations directly within your queries. This enables powerful filtering capabilities based on computed values.

Basic Arithmetic Operations

Operator Precedence

Arithmetic expressions follow standard mathematical operator precedence:

Mixing Properties and Literals

You can combine entity properties with literal numeric values:

Complex Arithmetic Expressions

Arithmetic expressions can be combined with logical operators and used in complex scenarios:

Supported Features

• All Numeric Types: int, decimal, double, float, long, short, byte and their nullable variants
• Automatic Type Conversion: Compatible numeric types are automatically converted for calculations
• Parentheses: Use parentheses to control calculation order and group expressions
• Entity Framework Translation: All arithmetic expressions are translated to efficient SQL queries
• Property-to-Property: Can mix property references with literal values in the same expression

Examples

Filtering Projections

You can also filter on queryable projections like so:

Filtering Raw SQL Projections

QueryKit can also be used with raw SQL queries via EF Core's SqlQueryRaw. This is particularly useful when you need to work with complex SQL queries that include joins, aggregations, or database-specific functions.

💡 You can use projections without using raw sql

Here's an example using a school domain:

Key Points:

• Raw SQL projections work seamlessly with QueryKit's filtering and sorting
• You can include computed fields (like StudentFullName) and nested fields from joins (like CourseStartDate)
• Property mappings allow you to use friendly query names that differ from the DTO property names
• The resulting queryable can be further filtered and sorted by QueryKit before materializing to a list

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 %:

Nested collections can also be filtered:

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:

Filtering Enums

You can filter enums with their respective integer value:

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

Derived Properties

You can also expose custom derived properties for consumption. Just be sure that Linq can handle them in a db query if you're using it that way.

Custom Operations

For more complex business logic that can't be expressed as simple derived properties, you can define custom operations. These allow you to encapsulate sophisticated filtering logic that can access related data, perform calculations, or implement domain-specific rules.

Custom Operation Features:

• Business Logic Encapsulation: Complex domain logic can be centralized and reused
• Related Data Access: Can navigate to related entities and collections (e.g., x.Orders, x.Items)
• Operator Access: The operation receives the comparison operator being used
• Type-Safe Parameters: Automatic conversion of string values to appropriate types (bool, int, decimal, DateTime, etc.)
• Entity Framework Compatible: Generated expressions translate to efficient SQL queries

Common Use Cases:

• Performance Metrics: Calculate efficiency ratios, averages, or complex aggregations
• Business Intelligence: Revenue calculations, customer scoring, inventory analysis
• Time-Based Logic: Recent activity checks, age calculations, expiration rules
• Customer Segmentation: VIP status, loyalty tiers, purchase behavior patterns
• Quality Control: Average ratings, compliance checks, threshold validations

Parameter Type Conversion:

Custom operations automatically handle common data types:

Custom operations provide a powerful way to extend QueryKit's filtering capabilities while maintaining type safety and Entity Framework compatibility.

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 QueryKit configuration depends on how you've configured the property:

Key Distinction:

• HasConversion: Use x => x.Email in QueryKit (point to parent property)
• ComplexProperty/OwnsOne: Use x => x.Email.Value in QueryKit (point to nested property)

HasConversion Support

For properties configured with EF Core's HasConversion, QueryKit provides special support that allows you to filter against the property directly without needing to access nested values. Use the HasConversion<TTarget>() configuration method:

This allows you to use Email == "value" syntax instead of Email.Value == "value" when the property is configured with HasConversion in EF Core. The HasConversion<TTarget>() method tells QueryKit what the conversion target type is so it can handle the type conversion properly.

Important: When using HasConversion in EF Core, you MUST configure the property in QueryKit using x => x.Email, not x => x.Email.Value. The conversion is on the parent property, so pointing to the nested .Value property will cause EF Core translation errors. Use x => x.Email.Value only when using ComplexProperty or OwnsOne without HasConversion.

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:

Using QueryKit on Enumerables

Since QueryKit is really just a parser for expressions, you can use it on any IEnumerable<T> as well. Just be sure to use the ApplyQueryKitFilter and ApplyQueryKitSort methods off of the enumerable.

For example

Error Handling

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

• A QueryKitException is the base class for all of the exceptions listed below. This can be caught to catch any exception thrown by QueryKit.
• A ParsingException 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.

Community Projects

• Fluent QueryKit for easy usage in javascript or typescript projects.