Add query ranking expressions at query time

This is for:

Developer

A query ranking expression (QRE) is used to modify the ranking of search results. Search results that match the QRE will see their relevance either increased or decreased, depending on the specified settings. In other words, this allows you to modify the order of appearance of search results. For example, you may want to see search results that contain the word sales in their title appear first, no matter what query is executed.

Using the JavaScript Search Framework, there are essentially two ways to attach a QRE to your queries. The following sections will demonstrate both of them.

  • Typically, a better approach is to define ranking expression and featured result query pipeline rules rather than enforcing QREs in the search interface (see Use query ranking expressions).

  • A QRE in the JavaScript Search Framework is a form of query extension. For more information, see Query extension language basics and Standard query extensions.

  • A ranking modifier actually increases or decreases the relevance of search results, depending if its value is positive or negative respectively. Technically, its value can be in the range -2^31..2^31, but it’s generally set to somewhere between -100..100, as this won’t completely override the different ranking weights of search results (except for results that have the same QRE weight).

  • The QRE modifier value is correlated to the item ranking score by a 1 to 10 ratio.

    A QRE modifier value is 100. Consequently this QRE adds 1000 to the ranking score of matching items.

Attaching a QRE using the init method

  1. From the host where the JavaScript Search Framework package is deployed, using a text editor:

    1. Open your search page in a text editor.

    2. Under the node <script type="text/javascript">, replace the line $('#search').coveo('init') with the following code:

       /*
 * Creates a QRE query using the $qre query extension
 * @expression {string} query expression to use for the QRE
 * @modifier {string} ranking modifier (-100 to 100)
 * @returns {string} the QRE query
 */
 var createQre = function (expression, modifier) {
     var qre = "";
     if (expression && modifier) {
         qre = "$qre(expression:'" + expression + "', modifier:'" + modifier + "')";
     }
     return qre;
 };

 // Create the QRE
 // returns "$ qre(expression:'@title="sales report"', modifier:'75')"
 var qre = createQre("@title=\"sales report\"", "75");
 // Initialize the search interface with a hidden expression that contains the QRE
 $('#search').coveo('init', {
     SearchInterface: {
         expression: qre
     }
 });
    3. Adapt the pasted code to the desired behavior. You should only have to modify the QRE itself.
    4. Save the file.
  2. Load the modified search page in a web browser.
  3. Validate that the ranking of search results was modified in such a way that those with the string sales in their title appear first.

Attaching a QRE using an event handler

  1. From the host where the JavaScript Search Framework package is deployed, using a text editor:

    1. Open the search page HTML file.

    2. Under the node <script type="text/javascript">, replace the line $('#search').coveo('init') with the following code:

       /*
 * Creates a QRE query using the $qre query extension
 * @expression {string} query expression to use for the QRE
 * @modifier {string} ranking modifier (-100 to 100)
 * @returns {string} the QRE query
 */
 var createQre = function (expression, modifier) {
     var qre = "";
     if (expression && modifier) {
         qre = "$qre(expression:'" + expression + "', modifier:'" + modifier + "')";
     }
     return qre;
 };

 /*
 * Way to create advances qre using contextual data like the user query in this example
 */
 var setupQreOnQueryBuilt = function(e, args) {
   var queryBuilder = args.queryBuilder;
          
   var query = queryBuilder.build();
          
   var qre = createQre("@title=sales", "75");
          
   // Add the QRE query to the advanced expression
   queryBuilder.advancedExpression.add(qre);
 };

 // Attach an handler function to the doneBuldingQuery event such that a QRE is run with the query.
 $('#search').on("doneBuildingQuery", setupQreOnQueryBuilt);
 // Initialize the search interface in a standard way.
 $('#search').coveo('init');

    3. Adapt the pasted code to the desired behavior. You should only have to modify the QRE itself.

    4. Save the file.

  2. Load the modified search page in a web browser.

  3. Validate that the ranking of search results was modified in such a way that those with the string sales in their title appear first.