Top - Query pipeline feature

This is for:

Developer System Administrator
In this article

A query pipeline statement expressing the top query pipeline feature increases the ranking scores of items appearing in certain query result sets by a large amount, and sets the isTopResult property to true for each of these items. It also modifies the disjunction part (dq) of the combined query expression to ensure that these items will be included in the query results.

Note

In the Coveo Administration Console, you can manage statements expressing the top feature from the Featured Results tab (see Manage Featured Result Rules).

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

Apply top statements

Syntax

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

[when <condition> [then]] top <expressions> [with <matchOptions>]

<condition>

A Boolean expression that must evaluate to true against the incoming query to apply the statement (for example, $query contains `foobar`).

Note

Statements expressing the top feature only should only apply when specific conditions are fulfilled.

Typically, you should precede the statement with a when <condition> then expression which relies on the basic part (q) of the combined query expression (that is, the $query or $originalQuery object). This allows you to limit the scope of the statement, without having to create a global condition which wouldn’t be used anywhere else.

<expressions>

A comma-separated list of query expressions whose result set items you want to feature (for example, foo`, `@bar=="baz").

Notes

  • Typically, you’ll replace <expressions> with a single query expression targeting a specific item (for example, @urihash==7Vf6bWsytplARQu3).

  • If any of your <expressions> references a field other than the standard @urihash or @permanentid:

    • Ensure that this field is included in query responses (see the fieldsToInclude option of the ResultList Coveo JavaScript Search Framework component).

    • If it’s possible for the values of this field to contain more than one term, use the == comparison operator (rather than =), and enclose the value to match between double quotes (for example, @author=="John Doe").

    • If there’s more than one field, use the AND operator to connect them (for example, @sfid=="0170b00012l2WIBAA2" AND @commonlanguage==$context.lang).

When the statement is applied:

  • For each query expression in <expressions>, a query ranking expression (QRE) with a large positive modifier is performed.

  • All of the query expressions in <expressions> are joined using OR operators. The resulting expression is then added to the disjunction part (dq) of the combined query expression using an OR operator.

  • The isTopResult property of each item matching any of the query expressions in <expressions> is set to true.

<matchOptions>

A comma-separated list of two key-value pairs which provide additional conditions that items must meet to be affected by the statement.

The only difference between these options is that one determines whether a featured item must also match the advanced part (aq) of the combined query expression to appear in the query result set, while the other must also match the basic part (q). Both are set to false by default.

matchAdvancedQuery: <true|false>

Setting this to true appends the current aq expression to the disjunction part (dq) of the combined query expression using an OR operator.

Note

In a Coveo JavaScript Search Framework page, selecting a ``Facet`` value automatically appends a query expression such as @fieldname=="field value" to the advanced part (aq) of the combined query expression.

Since a statement expressing the top feature adds one or more expressions to the disjunction part (dq) of the combined query expression, a given item doesn’t necessarily need to match the aq expression (that is, the facet selections) to be affected by such a statement. This can be confusing for end users, as a query result set could contain items which should have been filtered out by their facet selections.

You can prevent this by setting matchAdvancedQuery to true.

matchQuery: <true|false>

Setting this to true adds the current q expression to the disjunction part (dq) of the combined expression using an OR operator.

Example

In an empty query pipeline named Testing Top, you create a statement expressing the top feature with the following QPL definition:

when $query contains `top statement` then top `@urihash==7Vf6bWsytplARQu3`, `@title=="Top - Query pipeline feature"` with matchAdvancedQuery: true

A user performs a query against your index with the following payload:

{
  "aq": "@source==docs.coveo.com",
  "dq": "@language==en",
  "pipeline": "Testing Top",
  "q": "top QPL statement",
  "sortCriteria": "Relevancy"
}

This query goes through the Testing Top query pipeline and satisfies the condition established by the when expression in your statement definition, so the statement is applied. As a result:

  • dq becomes @language==en OR @source==docs.coveo.com OR @urihash==7Vf6bWsytplARQu3 OR @title=="Top - Query pipeline feature".

    An item matching either of the statement expressions will appear in the query results if it’s in English and resides within a source whose name is docs.coveo.com.

    Note

    In this example, the aq expression is added to the dq expression because the matchAdvancedQuery option is set to true in the statement definition.

    If the matchQuery option had also been set to true, the q expression would be added to the dq expression using an OR operator (that is, dq would become @language==en OR top QPL statement OR @source==docs.coveo.com OR @urihash==7Vf6bWsytplARQu3 OR @title=="Top - Query pipeline feature").

  • The following query ranking expressions are performed:

    • $qre(expression: @urihash==7Vf6bWsytplARQu3 modifier: 100000)

    • $qre(expression: @title=="Top - Query pipeline feature" modifier: 100000)

    The ranking score of any items matching one or both of these statement expressions increases significantly. Assuming that these items also match the modified disjunction query expression, they will appear at (or near) the top of the result list, since the sortCriteria parameter of the incoming query is set to Relevancy (meaning that query result items are sorted by their score values, in descending order).

  • The isTopResult property is set to true on all affected items.

    When you inspect the query results, you’ll be able to determine whether the ranking score of a given item was affected by a statement expressing the top feature.