---
title: Manage filter rules
slug: '3410'
canonical_url: https://docs.coveo.com/en/3410/
collection: tune-relevance
source_format: adoc
---
# Manage filter rules
A [query pipeline](https://docs.coveo.com/en/180/) filter is a hidden query expression that's added to queries going through the associated pipeline.
It helps define the scope of the search results displayed to users.
The **Filters** section of the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page lets members with the [required privileges](#required-privileges) create and manage filter rules.

By default, the list of filters in a pipeline is empty.
Without filters, all items matching the query are returned in the search results.
Filter rules are defined independently for each pipeline and are typically used to add a field-based expression to the [constant query expression (`cq`)](https://docs.coveo.com/en/179/).
They also permit the addition of any [query syntax](https://docs.coveo.com/en/181/) expression to any part of the query expression (`q`, `aq`, `cq`, `dq`, and `lq`).

These parameters help you customize the search experience and allow for default values for every query that matches a defined condition to be overridden.

**Example**

A support agent authenticates to a customer service [search interface](https://docs.coveo.com/en/2741/).
A query pipeline filter [rule](https://docs.coveo.com/en/236/) adds the expression `NOT @source=="Marketing"` to ensure that marketing [items](https://docs.coveo.com/en/210/) don't appear when the end user is identified as a support agent.
The `cq` is then always `NOT @source=="Marketing"` when support agents send queries.

## Prerequisites

Before creating a rule, make sure that you have the following:

* Access to a search page

You need access to a Coveo-powered [search interface](https://docs.coveo.com/en/2741/) to be able to test the [rule](https://docs.coveo.com/en/236/) that you create.

* An existing query pipeline

The queries from the search page must travel through a specific [query pipeline](https://docs.coveo.com/en/180/).

* Required privileges

You need specific [privileges to be able to add and edit rules in a query pipeline](#required-privileges).

Once you meet these requirements, you can create a rule on the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page.
To test the rule, [use the A/B test feature](https://docs.coveo.com/en/3255/) to compare the results of the rule with the results of the original pipeline.

## Access the "Filters" subtab

To manage filter rules, you must first access the **Filters** subtab in a query pipeline.

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline in which you want to manage filter rules, and then click **Edit components** in the Action bar.

. On the page that opens, select the **Advanced** tab.

. On the **Advanced** tab, on the left side of the page, select **Filters**.

## Add or edit filter rules

. [Access the **Filters** subtab](#access-the-filters-subtab) in the query pipeline you want to manage, and then do one of the following:

* To add a new filter rule, click **Add a filter rule**.

> **Note**
>
> * If you're adding a filter rule for the first time, you can click **Add rule with code** to define the rule using the appropriate [QPL syntax](#qpl-syntax).
> * If you're adding a filter rule to a list of existing rules, you can click [dots], and then click **Add rule with code**.

* To edit an existing filter rule, click the rule you want to edit, and then click **Edit** in the Action bar.

> **Note**
>
> You can also click **More**, and then select **Edit code** to edit the rule using the appropriate [QPL syntax](#qpl-syntax).

. In the **Add/Edit a filter rule** panel, under the **Query Parameter** dropdown menu, select the [query parameter](https://docs.coveo.com/en/13#tag/Search-V2/operation/searchUsingPost) in which the filter will be included in an `AND` expression.

. In the [**Content that matches**](#content-that-matches-section) section, depending on the mode, use the dropdown menus or the input to provide the desired filter expressions.

. In the **Condition** section, you can optionally select a [query pipeline condition](https://docs.coveo.com/en/2793/) in the dropdown menu or [create a new one](https://docs.coveo.com/en/1959#create-a-condition).

. Under **Description**, optionally enter information that will help you manage the rule in the future.

. Click **Add rule** or **Save**.

## Duplicate filter rules

When creating filter rules in a query pipeline, you may want to create a new rule that's similarly configured to an existing one.
An efficient way to do this is to duplicate the existing rule and then modify it as needed.

. [Access the **Filters** subtab](#access-the-filters-subtab) in the query pipeline you want to manage.

. In the **Filters** subtab, select the rules you want to duplicate within the same pipeline.

. In the **Action** bar, click **Duplicate**.

The duplicated filter rules appear at the bottom of the filters list.

## Copy filter rules to another pipeline

When you have multiple query pipelines that require similar rules, you can copy filter rules from one pipeline to another.

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline from which you want to copy query pipeline rules, and then click **Edit components** in the Action bar.

. On the page that opens, select the **Advanced** tab.

. On the **Advanced** tab, on the left side of the page, select **Filters**.

. In the **Filters** subtab, select the rules you want to copy to another pipeline.

. In the **Action** bar, click **More**, and then click **Copy to...**.

. In the dialog that appears, select the target pipeline to which you want to copy the rules, and then click **Copy**.

Your copied rules will take effect immediately in the target pipeline.

## Delete filter rules

. [Access the **Filters** subtab](#access-the-filters-subtab) in the query pipeline you want to manage.

. In the **Filters** subtab, select the rules you want to delete.

. In the **Action** bar, click **More**, and then **Delete**.

. Click **Delete** to confirm.

Your deleted rules will stop being effective immediately in the target pipeline.

> **Tip**
>
> * To avoid undesired search behaviors, delete unused query pipeline rules, as they can impact search relevance.
> 
> * Consider using the [Groups & Campaigns feature](https://docs.coveo.com/en/3283/) to make query pipeline rules only apply for a specific time period.

## Change the rule order

Query pipeline rules are executed in the order in which they appear on the page until a condition is satisfied.

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to manage the rules' execution order, and then click **Edit components** in the Action bar.

. On the page that opens, select the filter tab.

. In the filter tab, on the left side of the page, select pass:q,a[**filter**].

. In the pass:q,a[**filter**] subtab, click the rule whose position you want to change.

. In the Action bar, click **Move up** or **Move down** to change the position of the rule.

> **Note**
>
> When you move a filter rule, only the order of execution of filter rules is adjusted.
> Moving the rule doesn't affect the [order of execution](#order-of-execution) of filter rules relative to other query pipeline components.

## Leading practices

Consider the following leading practices when creating filter rules:

### Don't use filter rules to exclude sensitive information

Filters, by themselves, don't prevent the exposure of filtered content.
We strongly advise against creating a source whose content is [accessible to everyone](https://docs.coveo.com/en/1779#everyone) and using a pipeline filter to exclude sensitive information.

In the following cases, sensitive content from a source whose content is [accessible to everyone](https://docs.coveo.com/en/1779#everyone) could be exposed:

* A filter rule based on the [`aq`](https://docs.coveo.com/en/13#operation/searchUsingPost-aq) query parameter is set on a query pipeline that contains an [ART](https://docs.coveo.com/en/1013/) [model](https://docs.coveo.com/en/1012/) for which the [**Match the advanced query**](https://docs.coveo.com/en/l1ca1038#match-the-advanced-query) option is disabled.

* Using other pipelines not having a similar filter from other search interfaces or directly from the API.

* A colleague not understanding the reason for the filter could modify or remove the filter.

You can ensure security by enforcing the [search hub](https://docs.coveo.com/en/1342/) at the [search token](https://docs.coveo.com/en/1346/) level (see [Search token authentication](https://docs.coveo.com/en/56/)).
Moreover, search hubs defined on the client-side that are used as conditions in pipelines **don't** safeguard the security of the filtered content.

### Use inclusion filters

When creating filters, specify what the pipeline should _include_ rather than _exclude_ (for example, `@source==("Source 1", "Source 2")` rather than `NOT @source==("Source 3")`) to prevent new source content or content types in your organization index from appearing in search results.

If you only use an exclusion filter you must modify the filter expression whenever new content is added to your organization index.
To provide a controlled deployment of new sources into search results, use an inclusion filter, which allows content to be included in an additive manner.
This means content only appears in search results after the filter is updated, not immediately after indexing.

**Example**

You have three sources (Source 1, Source 2, Source 3) in your index and you want only Source 1 and Source 2 content to appear in the search results of a specific tab:

* An exclusion filter (for example, `NOT @source==("Source 3")`), requires you to modify the filter expression if you retrieve content from the newly created Source 4 (for example, `NOT @source==("Source 3", "Source 4")`).
* An inclusion filter (for example, `@source==("Source 1", "Source 2")`), requires no further changes even if you index Source 4 content.

### Check your source mappings

Filter rules exclude items that don't match the hidden query expression on which the rule is based.

Since you'll typically use filter rules to add a field-based expression to the `cq`, all items that fall within the scope of the filter rule must be mapped with the matching metadata values to appear in search results (see [Manage source mappings](https://docs.coveo.com/en/1640/)).
In other words, items that don't match the defined query expression won't appear in the search results.

Therefore, you should be 100% certain that all items that must match the filter expression are consistently mapped with the proper metadata.

If you're not 100% certain that the mappings are totally accurate, you should consider using [query ranking expression rules](https://docs.coveo.com/en/3234/) instead.

### Apply filter rules conditionally

Typically, filter rules should only apply when a certain [condition](https://docs.coveo.com/en/2793/) is fulfilled.

In general, you should ensure that the rule or its pipeline is associated to a global condition.

Moreover, when basing a filter rule on the value of one or more `$context` keys, you should use a condition to assert that these keys contain values.
Otherwise, you risk injecting invalid expressions in the target part of the query expression (that is, `aq`, `cq`, etc.).

## "Content that matches" section

When creating a rule, under the **Content that matches** section, you must define filter expressions to target specific content.

You can define filter expressions using either the ["Basic mode"](#basic-mode) or ["Advanced mode."](#advanced-mode)

## Basic mode

To define filter expressions using the **Basic mode**:

. [[step1]]In the **Select field** dropdown menu, use the **Filter** box to find and select the field that must be targeted by the filter expression.

. [[step2]]In the **Select a comparator** dropdown menu, select one of the [available comparators](#operators).

. If applicable, in the **Select a field value** dropdown menu, enter or select the values that must be filtered according to the field selected in [step 1](#step1).

. (Optional) Click **Add** to add another filter expression to the rule.
Note that when adding multiple filter expressions to a rule, new filter expressions are appended to the initial expression using the `and` logic, meaning that only content matching all filter expressions will be affected by the rule.

## Advanced mode

To define filter expressions using the **Advanced mode**, enter a [query expression](https://docs.coveo.com/en/2830/) using the [query syntax](https://docs.coveo.com/en/1552/).

:leveloffset!:

## Operators

## Contains

For the filter rules to modify the search results of an end user, the expression selected or entered in the **Select a field value** input must be part of the end user query.

## Does not contain

For the filter rules to modify the search results of an end user, the expression selected or entered in the **Select a field value** input must not be part of the end user query.

## Is

For the filter rules to modify the search results of an end user, the expression entered in the **Enter keyword(s)** input must be the same as the end user query.

## Is defined

For the filter rules to modify the search results of an end user, the field selected in the **Select field** dropdown menu must be defined in the end user query.

## Is not

For the filter rules to modify the search results of an end user, the expression selected or entered in the **Select a field value** input must not be the same as the end user query.

## Is not defined

For the filter rules to modify the search results of an end user, the field selected in the **Select field** dropdown menu must not be defined in the end user query.

## Since

For the filter rules to modify the search results of an end user, the date field selected in the **Select field** dropdown menu must be more recent than the date selected or entered in the **Select a field value** input.

:leveloffset!:

## QPL syntax

Use the following [query pipeline language (QPL)](https://docs.coveo.com/en/235/) syntax to define a statement expressing the `filter` feature:

```text
filter <queryExpressionPart> <expressions>
```

### `<queryExpressionPart>`

A string indicating the part of the [query expression](https://docs.coveo.com/en/2830/) to which one or more query expressions should be appended.
Must be one of:

* `aq`: The _advanced_ part
* `cq`: The _constant_ part
* `dq`: the _disjunction_ part
* `lq`: the _large_ part
* `q`: the _basic_ part

> **Notes**
>
> * The combined query expression is: `((q AND aq) OR dq) AND cq`.
> 
> * When an [Automatic Relevance Tuning (ART)](https://docs.coveo.com/en/1013/) (that is, `topClicks`) model is configured and ready in the query pipeline, the [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [Intelligent Term Detection (ITD)](https://docs.coveo.com/en/207/) feature extracts relevant keywords from the large part of the query expression (`lq`).
> Otherwise, the Search API converts `lq` to a partial match expression (see the [`lqPartialMatchKeywords`](https://docs.coveo.com/en/13#operation/searchUsingPost-lqPartialMatchKeywords) and [`lqPartialMatchThreshold`](https://docs.coveo.com/en/13#operation/searchUsingPost-lqPartialMatchThreshold) query parameters).
> In both instances, the subset of keywords processed from `lq` is ultimately injected in the basic part of the query expression (`q`).

### `<expressions>`

A comma-separated list of query expressions (for example, ``foo`, `@bar=="baz"``).
Each of these query expressions will be appended to the current value of the target `<queryExpressionPart>` using an implicit `AND` operator (that is, a whitespace character).

> **Important**
>
> The result set of the constant part (`cq`) of the combined query expression is kept in a special cache.
> 
> Consequently, you should avoid creating `filter` statements that add dynamic content to the `cq`, otherwise you risk filling the cache with useless data, which might have a negative impact on performance.

## Order of execution

The following diagram illustrates the [order of execution of query pipeline features](https://docs.coveo.com/en/1376/):


![Diagram showing order of execution | Coveo](https://docs.coveo.com/en/assets/images/tune-relevance/order-of-execution-query-pipeline-features.png)

## Required privileges

The following table indicates the [privileges](https://docs.coveo.com/en/1791#required-privileges) required to view or edit filter rules.
Learn more about the [Privilege reference](https://docs.coveo.com/en/1707/) or how to [manage privileges](https://docs.coveo.com/en/3151/).

[cols="3",options="header"]
|===
|Action
|Service - Domain
|Required access level

|View filter rules
|Organization - Organization  
Search - Query pipelines
|View

.2+|Edit filter rules using the [**Basic mode**](https://docs.coveo.com/en/3410#basic-mode)
|Organization - Organization  
Content - Fields
|View

|Search - Query pipelines
|Edit

.2+|Edit filter rules using the [**Advanced mode**](https://docs.coveo.com/en/3410#advanced-mode)
|Organization - Organization
|View

|Search - Query pipelines
|Edit
|===