HomeDev GuideRecipesAPI ReferenceGraphQL
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

Filters are typically used to narrow down search results, for example limiting a free-text search for books to a specific category, or for database-like queries.

Search requests consist primarily of queries and filters. Queries and filters are similar. Filters provide better performance but do not affect scoring (sorting by relevance).

The .NET client API supports most filter types supported by the REST API, and a fluent API for common filtering operations.

Assume a `BlogPost` class with a `Title` string property. The following code finds all `BlogPosts` titled "Find."

The `Search<TSource>` method returns an instance of `ITypeSearch<TSource>`, which acts as a builder class for a search request. Using the `Filter` extension method, you can add a filter to the search request by supplying an expression that returns an instance of the `Filter` class. The client API has several extension methods for value types and strings that return filters, such as the `Match` method above.

## Group filters

You can group filters using Boolean operators. For example, the following code finds blog posts titled _Find_ or _Search_.

Assuming the `BlogPost` class has a `Tag` property, the following code finds blog posts titled _Search_ and tagged with _Find_, or titled _Find_ (with no requirements for tags).

## Call Filter multiple times

You can call the `filter` method multiple times, which is useful if filters you want to apply are determined at runtime, such as filters that depend on user input. For example, you can modify the first part of the filter expression above as follows.

## OrFilter method

If you invoke the `Filter` method multiple times, the latter invocations' filters are combined with previous invocations' filters using **AND**. To combine them using **OR**, use the following code.

If the `OrFilter` method is called _before_ the `Filter` method, it is the same as calling the `Filter` method, since there is no existing filter with which to **OR**-group it.

## Complex and dynamically created filters

Sometimes, the `Filter` and `OrFilter` methods are not enough. For example, you build complex search queries dynamically at runtime based on user input. While the methods can handle most scenarios at compile time, creating multiple grouped `Orfilters` at runtime is tricky and results in complex code. To build filters without regard to other filters and apply them to a search query, using the `IClient` extension method `BuildFilter`.

The `BuildFilter` method requires a generic type parameter to which you apply the filter. The method returns an object of type `FilterBuilder`. The `FilterBuilder` class has **And** and **Or** methods, which you use to can add filter expressions like the `Filter` and `OrFilter` methods. The `FilterBuilder` class is implicitly convertible to the Filter class, so you can pass instances of it as arguments to the `Filter` and `OrFilter` methods and in filter expressions.

For example, you manage a restaurant search that uses two variables: cuisines and countries, both of type `IEnumerable<string>`. Both may be null, but if either is not, you want to add a filter so that search results return only restaurants matching those cuisines or countries. Use the `BuildFilter` method to accomplish this.

## Filter methods

When filtering with the `Filter` method, you provide an expression that returns a filter. To do so, use extension methods for properties that return filters. The above examples used the `Match` extension method, but several other methods exist.

  • Filter methods for:

    • [Strings](🔗)

    • [Numerical](🔗) fields (int, int?, double etc)

    • [DateTime](🔗) fields

    • [Boolean](🔗) fields

    • [Enum](🔗) fields

    • [Complex objects](🔗)

    • GeoLocation fields

You can also create [custom extension methods to enhance the filtering functionality](🔗).