Using Query Ranking Expressions

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.

  • A QRE in the JavaScript Search Framework is a form of query extension. For more information, refer to 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 is generally set to somewhere between -100..100, as this will not 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') by 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:'@systitle="sales report"', modifier:'75')"
       var qre = createQre("@systitle=\"sales report\"", "75");
       // Initialize the search interface with an 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 pag 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') by 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) {
         // QueryBuilder as documented on http://developers.coveo.com/display/JsSearch/QueryBuilder
         var queryBuilder = args.queryBuilder;
         // QueryObject as documented on http://developers.coveo.com/display/SearchREST/Query+Parameters
         var query = queryBuilder.build();
         var qre = createQre("@systitle=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.