Query Matcher | SaaS Custom Domains Help Center

What is the Query Matcher?

The Query matcher allows you to create rules that match requests based on query parameters in the URL. Query parameters appear after the question mark (?) in a URL and are typically used to filter content, control page behavior, or pass information between pages.

How Query Matcher Works

The Query matcher evaluates the query string portion of the URL (everything after the question mark). For example, in the URL https://example.com/products?category=shoes&color=blue, the query parameters are category=shoes and color=blue. The matcher allows you to check for query parameters' presence, absence, or specific values.

Available Operators

The Query matcher supports these comparison operators for each query parameter:

Operator	Description	Example
`is`	Exact query parameter value match	Key `category` with value `shoes` matches only when `category` equals `shoes` exactly
`is_not`	Query parameter value does not match exactly	Key `category` with value `shoes` matches when `category` is not `shoes`
`starts_with`	Query parameter value begins with specified text	Key `search` with value `prod` matches when `search` param starts with `prod`, e.g. `production`, `products` etc.
`ends_with`	Query parameter value ends with specified text	Key `search` with value `.pdf` matches when `search` param ends with `.pdf`, e.g. `file.pdf`, `document.pdf` etc.
`contains`	Query parameter value contains specified text	Key `name` with value `john` matches when `name` contains `john`, e.g. `johnson`, `john-doe`, etc.
`does_not_contain`	Query parameter value does not contain specified text	Key `name` with value `john` matches when `name` does not contain `john`, e.g. `jane`, `jane-doe`, etc.
`has_any_value`	Query parameter exists with any value	Matches when the query parameter exists.
`is_unknown`	Query parameter does not exist	Matches when query parameter does not exist.

API Reference

When working with Rules through the API, Query matchers are represented in JSON format. This is the same structure used in the API endpoints for creating and updating rules.

{
  "type": "query",
  "query_params": [
    {
      "key": "category",
      "value": "shoes",
      "operator": "is"
    },
    {
      "key": "size",
      "operator": "has_any_value"
    }
  ]
}

In API requests, this matcher would be included in the matchers array of a rule object:

{
  "name": "Shoes Category Rule",
  "active": true,
  "matchers": [
    {
      "type": "query",
      "query_params": [
        {
          "key": "category",
          "value": "shoes",
          "operator": "is"
        },
        {
          "key": "size",
          "operator": "has_any_value"
        }
      ]
    }
  ],
  "handlers": [
    // handlers would go here
  ]
}

For complete API documentation on rules, including how to create and update rules programmatically, refer to our API Documentation.

Configuration Examples

Example 1: Matching a Specific Value

This matcher will match requests where the category parameter equals "books":

In the UI:

In the API:

{
  "type": "query",
  "query_params": [
    {
      "key": "category",
      "value": "books",
      "operator": "is"
    }
  ]
}

Example 2: Checking Parameter Existence

This matcher will match requests that have a search parameter, regardless of its value:

In the UI:

In the API:

{
  "type": "query",
  "query_params": [
    {
      "key": "search",
      "operator": "has_any_value"
    }
  ]
}

Example 3: Partial Value Matching

This matcher will match requests where the product parameter contains "phone":

In the UI:

In the API:

{
  "type": "query",
  "query_params": [
    {
      "key": "product",
      "value": "phone",
      "operator": "contains"
    }
  ]
}

Example 4: Excluding Certain Content

This matcher will match requests where the mode parameter is not "admin":

In the UI:

In the API:

{
  "type": "query",
  "query_params": [
    {
      "key": "mode",
      "value": "admin",
      "operator": "is_not"
    }
  ]
}

Example 5: Multiple Parameters

This matcher will match requests that have both a category parameter equal to "electronics" and a brand parameter that exists:

In the UI:

In the API:

{
  "type": "query",
  "query_params": [
    {
      "key": "category",
      "value": "electronics",
      "operator": "is"
    },
    {
      "key": "brand",
      "operator": "has_any_value"
    }
  ]
}

Common Use Cases

Here are some popular ways to use the Query matcher:

Feature Flags and A/B Testing

Control feature visibility based on query parameters:

Create a rule with a Query matcher for your feature flag (e.g., feature=new-ui)
Add handlers to serve different content or set specific headers

Analytics and UTM Parameters

Apply special handling for marketing campaign traffic:

Create a rule with a Query matcher for UTM parameters (e.g., utm_source=newsletter)
Add handlers to track or modify the response for these specific campaigns

Language and Localization

Route users based on language preferences:

Create a rule with a Query matcher for language (e.g., lang=es)
Add handlers to rewrite the request to localized content or set appropriate headers

Access Control

Control access based on query tokens:

Create a rule with a Query matcher for access tokens (e.g., token=*)
Add handlers to validate the token and allow or deny access

Combining with Other Matchers

The Query matcher becomes especially powerful when combined with other matchers:

Query + Path: Match specific query parameters only on certain paths
Query + Method: Match query parameters only for specific HTTP methods
Query + Header: Match requests with specific query parameters and headers

Remember that when multiple matchers are used in a rule, ALL must match to apply the rule (AND logic).

Best Practices

Be aware that query parameters are case-sensitive (Size is different from size)
For parameters that might have multiple values, use contains or other flexible operators
Use has_any_value when you only need to check if a parameter exists
Use is_unknown when you want to match requests that don't have a specific parameter
Consider URL encoding issues when matching query parameter values
Remember that multiple query parameters with the same name can exist in a single URL

Troubleshooting

If your Query matcher isn't working as expected:

Check for exact spelling and case matching in parameter names and values
Verify that you've chosen the correct operator
Confirm the actual query string in requests with browser developer tools or server logs
Be aware of URL encoding (e.g., spaces might appear as %20)
Test with simplified query parameters first, then add complexity

The Query matcher provides a flexible way to create rules based on URL query parameters. By leveraging this matcher, you can implement sophisticated request handling that responds to user preferences, search terms, filters, and other dynamic aspects of your web application.

Until next time, keep building!

Need more help? Reach out via the Intercom chat widget and we'll be right with you!