Query Matcher

The Query matcher allows a rule to match requests based on URL query parameters. It is the primary way to create behavior that depends on search terms, filters, feature flags, UTM tracking codes, or any other data passed in the query string.

The Query matcher only determines whether a rule should run. Once a request matches, the rule’s configured handlers execute.

To learn how rules work, see Hostgrid Rules.

The Query matcher evaluates the query string portion of the incoming request URL (everything after the ?).

For the URL:

https://example.com/products?category=shoes&color=blue

The components are:

Only the specified query parameter is evaluated by this matcher. The host, path, headers, and HTTP method are matched using their own matcher types.

You configure the matcher by providing the parameter name (the key) and the condition its value must satisfy.

The Query matcher supports the following comparison operators.

These operators perform string comparisons against the decoded query parameter value. Choose the operator that most closely matches the requests you want the rule to affect.

To match requests where the category is exactly “electronics”:

Parameter: category
Operator: is equal to
Value: electronics

API representation:

{
    "type": "query",
    "params": {
        "items": [
            {
                "name": "category",
                "operator": "equal",
                "value": "electronics"
            }
        ]
    }
}

To match any search query containing the word “phone”:

Parameter: q
Operator: contains
Value: phone

API representation:

{
    "type": "query",
    "params": {
        "items": [
            {
                "name": "q",
                "operator": "contains",
                "value": "phone"
            }
        ]
    }
}

This matches ?q=smartphone, ?q=phones, and ?q=phone-case.

To match requests where the mode parameter is anything other than “admin”:

Parameter: mode
Operator: is not equal to
Value: admin

API representation:

{
    "type": "query",
    "params": {
        "items": [
            {
                "name": "mode",
                "operator": "not_equal",
                "value": "admin"
            }
        ]
    }
}

This matches ?mode=user, ?mode=guest, and requests that have no mode parameter at all.

A single Query matcher can include conditions for more than one query parameter.

When multiple parameter conditions are added to the same matcher, all of them must match before the rule executes.

For example, a single Query matcher with these conditions:

category is equal to electronics
brand is equal to acme

Only matches requests that satisfy both conditions, such as ?category=electronics&brand=acme.

This behaves identically to adding two separate Query matchers to the same rule. Use whichever approach keeps your rule configuration clearer.

A rule can contain matchers of different types. When multiple matchers are configured, all of them must match before the rule executes.

Similarly, you can combine the Query matcher with:

• Path Matcher
• Method Matcher
• Header Matcher

The Query matcher is most effective when paired with a handler that takes a different action based on the query parameters in the request.

• Be aware of URL encoding. Query parameter values are often URL-encoded (e.g., spaces appear as %20 or +). The matcher evaluates the decoded value, so you should use the unencoded string in your configuration (e.g., use red shoes, not red%20shoes).
• Parameter names and values are case-sensitive. ?Category=Shoes does not match a matcher looking for category equal to shoes.
• Use contains for flexible matching. If a parameter can have multiple valid formats or variations, contains is more resilient than exact matching.
• Consider parameter order. The order of query parameters in a URL does not matter. ?a=1&b=2 is treated the same as ?b=2&a=1.
• Be cautious with sensitive data. Query parameters are visible in URLs, browser history, and server logs. Avoid routing or handling sensitive tokens exclusively via query matchers when possible.

If a rule with a Query matcher is not matching as expected:

• Check parameter name spelling. Verify the exact key used in the URL (e.g., utm_source vs UTM_Source vs utm-source).
• Inspect the actual query string. Use browser developer tools (Network tab) to see the exact parameter names and values being sent.
• Review URL encoding. If your match fails on values with spaces or special characters, ensure you are comparing against the decoded value.
• Review operator selection. is not equal to admin matches requests with ?mode=user, but it also matches requests that have no mode parameter at all.
• Confirm matcher combinations. If the rule has multiple matchers, every one must evaluate to true. A Path matcher that does not match will prevent the rule from running even if the Query matcher does.
• Consider rule order. If an earlier rule contains a Redirect or Static Response handler, later rules will not execute for that request.

For more information about rule evaluation, see Hostgrid Rules.

• Hostgrid Rules
• Path Matcher
• Method Matcher
• Header Matcher
• Rule Handlers