---
title: 'Filter: Query pipeline feature'
slug: '1440'
canonical_url: https://docs.coveo.com/en/1440/
collection: tune-relevance
source_format: adoc
---
# Filter: Query pipeline feature
A [query pipeline statement](https://docs.coveo.com/en/236/) expressing the `filter` [query pipeline feature](https://docs.coveo.com/en/234/) adds one or more query expressions to the [advanced (`aq`)](https://docs.coveo.com/en/175/), [constant (`cq`)](https://docs.coveo.com/en/179/), [disjunction (`dq`)](https://docs.coveo.com/en/190/), [large (`lq`)](https://docs.coveo.com/en/214/), or [basic (`q`)](https://docs.coveo.com/en/178/) part of the query expression before the [query](https://docs.coveo.com/en/231/) is sent to the [index](https://docs.coveo.com/en/204/).

> **Leading practice**
>
> Typically, a statement expressing the `filter` feature should only apply when a certain condition is fulfilled.
> 
> In general, you should ensure that this is the case by associating such a statement, and/or the pipeline it's defined in, to a global condition.
> 
> Moreover, when basing a `filter` statement on the value of one or more `$context` keys, you should use a condition to assert that those keys contain values.
> Otherwise, you risk injecting invalid expressions in the target part of the query expression (that is,  `aq`, `cq`, etc.).
> 
> [example]
> .Example
**Condition**

```text
when $context[favoriteBookGenre] matches /*.\S.*/
```

**Statement**

```text
filter aq `@bookgenre==$context.favoriteBookGenre`
```
##### ====

> **Note**
>
> In the [Coveo Administration Console](https://docs.coveo.com/en/183/), you can manage statements expressing the `filter` feature [from the **Filters** subtab](https://docs.coveo.com/en/3410#access-the-filters-subtab).

The following diagram shows the process of a query being sent to the Search API and the order of execution of query pipeline features.


![Coveo | diagram showing order of execution](https://docs.coveo.com/en/assets/images/coveo-platform/trigger-statements-diagram.svg)

> **Important**
>
> Filters, by themselves, don't prevent the exposure of filtered content.
> We strongly advise against creating a source whose content is accessible to everyone (`"sourceVisibility": "SHARED"`) and using a pipeline filter to exclude sensitive information.
> 
> In the following cases, sensitive content from a source whose content is accessible to everyone (`"sourceVisibility": "SHARED"`) 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.

## 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 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 those 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 `cq`, otherwise you risk filling the cache with useless data, which might have a negative impact on performance.

## Example

You create a global condition with the following QPL definition:

[example.code]
#### **Global condition:**

```text
when $searchHub is "Community"
```
#### In an empty query pipeline named `Testing Filter`, you create three distinct statements, each expressing the `filter` feature, with the following QPL definitions:

[example.code]
#### **Statement 1:**

```text
filter cq `@language==en`
```
#### [example.code]
#### **Statement 2:**

```text
filter aq `@source=="Public Content"`
```
#### [example.code]
#### **Statement 3:**

```text
filter dq `@date=today`
```
#### You associate each of those three statements to the global condition you created before.

A user performs a query with the following payload:

[example.code]
#### ```json
{
  "aq": "@tags==(\"Query pipeline\", \"Search API\")",
  "context": {
    "userRole": "Developer"
  },
  "cq": "@filetype==html",
  "pipeline": "Testing Filter",
  "q": "filter statement",
  "searchHub": "Community"
}
```
#### Since this query goes through the `Testing Filter` query pipeline and satisfies the condition of each statement in that pipeline, those statements apply.
As a result, the different parts of the query expression are modified as follows:

* `cq` (that is,  `$constantQuery`) becomes `@filetype==html @language==en`.
* `aq` (that is,  `$advancedQuery`) becomes `@tags==("Query pipeline", "Search API") @source=="Public Content"`.
* `dq` (that is,  `$disjunctionQuery`) becomes `@date=today`.
* `q` (that is,  `$query`) remains `filter statement`.

The combined query expression (that is,  `((q AND aq) OR dq) AND cq`) means that to be included in the result set of this query, an [item](https://docs.coveo.com/en/210/) must mandatorily:

* Be an HTML file (because of the original `cq` query parameter).
* Be in English (because of **Statement 1**, which modifies the `cq` expression).

In addition, this item must:

* Match the `filter statement` basic query expression (because of the `q` query parameter).
* Be tagged as being about query pipelines or the Search API (because of the original `aq` query parameter).
* Reside within the source named Public Content (because of **Statement 2**, which modifies the `aq` expression).

OR

* Have been updated today (because of **Statement 3**, which modifies the `dq` expression).