Manage Filter Rules

Members with the required privileges can use query pipeline filters to easily define the scope of the search results displayed to your users.

Filter rules allow you to enter hidden query expressions to be added to all queries going through the related query pipeline. While this feature permits the addition of any query syntax expression to any part of the query expression (i.e., q, aq, cq, dq, or lq), query pipeline filters are typically used to add a field-based expression to the constant query expression (cq).

EXAMPLE

A support agent authenticates on a customer service search interface. A query pipeline filter rule adds the expression NOT @source=="Marketing" to ensure that marketing items 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.

The list of filters in a pipeline is empty by default. Filter rules are defined independently for each pipeline.

Create Filter Rules

  1. On the Query Pipelines page, click the query pipeline in which you want to add a rule, and then in the Action bar, click Edit Components.

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

  3. In the Advanced tab, on the left-hand side of the page, select Filters.

  4. In the upper-right corner of the page, click Add Rule to access the Add a Filter Rule [1] subpage.

  5. In the Query Parameter drop-down menu, select the query parameter in which the filter will be included in an AND expression.

  6. In the Content matching this expression input, you can either:

  7. On the right-hand side, under Condition, you can optionally select a query pipeline condition in the drop-down menu or create a new one.

  8. Under User note, optionally enter information that will help you manage the rule in the future.

  9. Click Add Rule.

Edit Filter Rules

  1. On the Query Pipelines page, click the query pipeline in which you want to edit a rule, and then in the Action bar, click Edit Components.

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

  3. In the Advanced tab, on the left-hand side of the page, select Filters.

  4. Click the rule you want to edit, and then in the Action bar, click Edit [2] to access the Edit a Filter Rule subpage.

  5. In the Query Parameter drop-down menu, select the query parameter in which the filter will be included in an AND expression.

  6. In the Content matching this expression input, you can either:

  7. On the right-hand side, under Condition, you can optionally select a query pipeline condition in the drop-down menu or create a new one.

  8. Under User note, optionally enter information that will help you manage the rule in the future.

  9. Click Save.

Duplicate Filter Rules

  1. On the Query Pipelines page, click the query pipeline for which you want to duplicate query pipeline rules, and then in the Action bar, click Edit components.

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

  3. In the Advanced tab, on the left-hand side of the page, select Filters.

  4. In the Filters subtab, click the rule you want to duplicate within the same pipeline (typically to create a slightly different rule).

  5. In the Action bar, click Duplicate.

The duplicated rule appears at the bottom of the list in the pipeline component tab.

Delete Filter Rules

  1. On the Query Pipelines page, click the query pipeline for which you want to delete query pipeline rules, and then in the Action bar, click Edit components.

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

  3. In the Advanced tab, on the left-hand side of the page, select Filters.

  4. In the Filters subtab, click the rule you want to delete.

  5. In the Action bar, click More, and then select Delete.

  6. Click Delete to confirm.

Change the Rule Order

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

  1. On the Query Pipelines page, click the query pipeline for which you want to manage the rules' execution order, and then in the Action bar, click Edit components.

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

  3. In the Advanced tab, on the left-hand side of the page, select Filters.

  4. In the Filters subtab, click the rule whose position you want to change.

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

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 protect the security of filtered content. We strongly advise against creating a source whose content is accessible to everyone and using a pipeline filter to exclude sensitive information.

EXAMPLES

In the following cases, sensitive content from a source whose content is accessible to everyone could be exposed:

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

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

You can ensure security by enforcing the search hub at the search token level (see Search Token Authentication). Moreover, search hubs defined on the client-side that are used as conditions in pipelines do not safeguard the security of your filters.

Use Inclusion Filters

When creating filters, specify what the pipeline should include rather than exclude (e.g., @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 (e.g., NOT @source==(“Source 3”)), requires you to modify the filter expression if you retrieve content from the newly created Source 4 (e.g., NOT @source==(“Source 3”, "Source 4")).

  • An inclusion filter (e.g., @source==(“Source 1”, “Source 2”)), requires no further changes even if you index Source 4 content.

Check Your Source Mappings

Filter rules filter out from the search results all items that don’t match the hidden query expression on which the rule is based.

Since you will typically use filter rules to add a field-based expression to the cq, all items that must fall within the scope of the filter rule must be mapped with the matching metadata values in order to be displayed in the search results (see Manage Source Mappings). 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 instead.

Apply Filter Rules Conditionally

Typically, filter rules should only apply when a certain condition is fulfilled.

In general, you should ensure that this is the case by associating such a rule, and/or the pipeline it’s defined in, 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 (i.e., aq, cq, etc.).

Reference

"Filter Expression Editor" Subpage

When clicking Edit, you access the Filter Expression Editor subpage to add query expressions.

In the Filter Expression Editor subpage, users can either select the "Basic Mode" or "Advanced Mode" to define query expressions.

Basic Mode

To define query expressions using the "Basic Mode":

  1. In the Select field drop-down menu, type or select the field that must be targeted by the query expression.

  2. In the Select comparator drop-down menu, select one of the available comparators.

  3. (If available [3]) In the Add a value drop-down menu, enter or select the values that must be filtered according to the field selected in step 1.

  4. Optionally, in the Add rule drop-down menu, select one of the available operators (And or Or) to add another query expression to your rule.

  5. In the right-hand section of the Filter Expression Editor subpage, you can preview the results triggered by your rule.

  6. Click Done to add the expression to the Content matching this expression.

Advanced Mode

To define query expressions using the "Advanced Mode":

  1. In the input box, enter a query expression using the Coveo Cloud query syntax.

  2. In the right-hand section of the Filter Expression Editor subpage, you can preview the results triggered by your rule.

  3. Click Done to add the expression to the Content matching this expression input.

QPL Syntax

Use the following query pipeline language (QPL) syntax to define a statement expressing the filter feature:

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

<expressions>

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

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 highlights in orange the position of filter rules in the overall order of execution of query pipeline features.

filter rules in the query pipeline order of execution

Required Privileges

By default, members of the Administrators and Relevance Managers built-in groups can view and edit elements of the Query Pipelines page.

The following table indicates the required privileges to view or edit elements of the Query Pipelines page (see Manage Privileges and Privilege Reference).

Action Service - Domain Required access level

View filter

Search - Query pipelines

View

Edit filter

Search - Query pipelines

Edit


1. (Advanced) You can click Menu, and then select Add rule with code to define the rule using the appropriate QPL syntax.
2. (Advanced) You can click More, and then select Edit code to edit the rule using the appropriate QPL syntax.
3. The Add a value drop-down menu isn’t available if the user selected the is defined or is not defined comparators in step 2.
Recommended Articles