Quick Search

Introduction

The GraphQL framework allows for creating custom operators for the filtering capabilities. The Suite GraphQL Module takes advantage of this feature to provide a Quick Search operator available for all queries.

Using the Quick Search on a query

Since the Quick Search capability is fully integrated with the filtering feature of Hot Chocolate, the Quick Search can be used as an operator on the where filter object. The name of the operator is quickSearch and it takes the string to be search as a parameter.

query {
    users(where: { quickSearch: "John Doe" }) {
        nodes {
            loginId
            displayName
            emailAddress
        }
    }
}

Multiple key match

When several words are used in the search string the operator will split them into separate terms and look for matches that contain one or more of the terms. For example if we search for "John Doe", the following entries will match:

• John Doe: this contains both terms.
• John Michael: this contains "John".
• Jane Doe: this contains "Doe".
• Doe Jr.: this contains "Doe"

Notice that order of appearance doesn't matter.

Exact match

If you want your search string to be matched exactly, you can surround it with double quotes "", for instance if you want to look for "John Doe" (and not other John's and other Doe's) you can use "\"John Doe\"" as search string (The example uses on as it is the most common scape character).

You can also combine both approach, for example "\"John Doe\" Michael" will match:

• John Doe: contains the exact search "John Doe".
• John Michael: contains the term "Michael".
• Jane Michael: contains the term "Michael".
• John Doe The Second: contains the exact search "John Doe".

Note

Notice how "John Doe The Second" is correctly match against "John Doe", this is because the exact match basically means "Do not split this phrase in to separate keys", it does not mean "Match the field by equality".

Quick Search Setup

Quick Search is automatically enabled on all entities exposed using the ExposeInPublicApi method on the GraphQLModuleOptions.

builder.DependsOn<GraphQLModule, GraphQLModuleOptions>(opts =>
{
    opts.ExposeInPublicApi<UserProfile, User>("users");
});

The code above will automatically enable Quick Search for all the string fields of the UserProfile entity.

Disabling Quick Search

If you want to disable the Quick Search that is otherwise automatically configured, you can do it as follows:

builder.DependsOn<GraphQLModule, GraphQLModuleOptions>(opts =>
{
    opts.ExposeInPublicApi<UserProfile, User>("users", d =>
    {
        d.ConfigureQuickSearch(false);
    });
});

As seen above, the ExposeInPublicApi method accepts a lambda expression as a second optional parameter, that allows for an explicit configuration of the Quick Search, in this case, disabling it.

Enabling Quick Search for specific fields only

You can specify what fields should be subject to the Quick Search filter, as follows:

builder.DependsOn<GraphQLModule, GraphQLModuleOptions>(opts =>
{
    opts.ExposeInPublicApi<UserProfile, User>("users", d =>
    {
        d.ConfigureQuickSearch(qs =>
        {
            qs.IncludeField(x => x.DisplayName);
        });
    });
});

Note

By specifying at least one field explicitly you are automatically disabling the implicit behavior. If you want all fields just do not specify any, and the system will automatically add all of them.

Case sensitivity

By default Quick Search terms are match as case insensitive. You can change this behavior for each field as follows:

builder.DependsOn<GraphQLModule, GraphQLModuleOptions>(opts =>
{
    opts.ExposeInPublicApi<UserProfile, User>("users", d =>
    {
        d.ConfigureQuickSearch(qs =>
        {
            qs.IncludeField(x => x.DisplayName, f =>
            {
                f.UseCaseSensitive();
            });
        });
    });
});

Important

Currently Quick Search works only for fields of type string. We are analyzing adding support for other types using implicit conversion in the future.