Top - Query Pipeline Feature
Top - Query Pipeline Feature
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 |
The following diagram shows the process of a query being sent to the Search API and the order of execution of query pipeline features.
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 (e.g., $query contains `foobar`
).
|
Note
Statements expressing the Typically, you should precede the statement with a |
<expressions>
A comma-separated list of query expressions whose result set items you want to feature (e.g., foo`, `@bar="baz"
).
|
Notes
|
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 usingOR
operators. The resulting expression is then added to the disjunction part (dq
) of the combined query expression using anOR
operator. -
The
isTopResult
property of each item matching any of the query expressions in<expressions>
is set totrue
.
<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 Since a statement expressing the You can prevent this by setting |
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
.NoteIn this example, the
aq
expression is added to thedq
expression because thematchAdvancedQuery
option is set totrue
in the statement definition.If the
matchQuery
option had also been set totrue
, theq
expression would be added to thedq
expression using anOR
operator (i.e.,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 toRelevancy
(meaning that query result items are sorted by theirscore
values, in descending order). -
-
The
isTopResult
property is set totrue
on all affected items.When you inspect the query results, you will be able to determine whether the ranking score of a given item was affected by a statement expressing the top feature.