Query functions

This is for:

Developer

A query function is a mathematical expression evaluated against each item returned by a query, and whose output is stored in a dynamic, temporary field generated at query time. Query function expressions are defined using the C++ Mathematical Expression Toolkit Library (ExprTk). They don’t support loop structures, but if and switch statements are supported.

This article describes the members of the structure that defines a single query function. You can specify an array of query functions in a query using the queryFunctions top-level query parameter.

Note

You can use a field generated by a query function almost anywhere you would use a normal numeric field. One notable exception is automatic range generation in Group By operations (see the generateAutomaticRanges Group By parameter). To create ranges for a field generated by a query function, specify those ranges explicitly using the rangeValues Group By parameter, because the index can’t determine them automatically.

This implies that in a JavaScript Search Framework interface, to render a FacetRange component based on a field generated by a query function, you must use the ranges option to specify the desired ranges.

Examples

  1. You want to compute the file size in kilobytes for each item at query time and store the results in a dynamically generated field called @sizekb.

    POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
    
    Content-Type: application/json
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************

    Payload:

    {
      "queryFunctions": [
        {
          "fieldName": "@sizekb",
          "function" : "@size/1024"
        }
      ]
    }

    200 OK response body (excerpt):

    {
      ...
      "results": [
        ...
        {
          "raw": {
            ...
            "size": 1767763,
            "sizekb": 1726.3310546875,
            ...
          },
          ...
        },
        ...
      ],
      ...
    }
  2. You want to compute the distance (miles) between two coordinates for each item at query time and store the results in a dynamically generated field called @distanceinmiles.

    POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
    
    Content-Type: application/json
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************

    Payload:

    {
      "queryFunctions": [
        {
          "fieldName": "@distance",
          "function" : "dist(@latitude, @longitude, 46.8167, -71.167)"
        },
        {
          "fieldName": "@distanceinmiles",
          "function": "@distance*0.000621371"
        }
      ]
    }

    200 OK response body (excerpt):

    {
      ...
      "results": [
        ...
        {
          "raw": {
            ...
            "distance": 235762,
            "distanceinmiles": 146.495669702,
            ...
          },
          ...
        },
        ...
      ],
      ...
    }
  3. You have a @price field on your items. You need a @discountedprice field that contains the price with a 10% discount.

    POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
    
    Content-Type: application/json
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************

    Payload:

    {
      "queryFunctions": [
        {
          "fieldName": "discountPrice",
          "function" : "@price*0.9"
        }
      ]
    }

    200 OK response body (excerpt):

    {
      ...
      "results": [
        ...
        {
          "raw": {
            ...
            "price": 10,
            "discountPrice": 9,
            ...
          },
          ...
        },
        ...
      ],
      ...
    }
  4. In a commerce scenario, you have two fields: @stock_status_code and @price_type_code. Both fields are populated from a dictionary field whose values vary by store or market.

    You want to compute a single @availabilitystatus field that combines both values into one of a small set of statuses, so your search interface can rely on one field.

    In this case, you need to declare intermediate var variables and branch on multiple conditions using a switch statement.

    POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
    
    Content-Type: application/json
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************

    Payload:

    {
      "dictionaryFieldContext": {
        "stock_status_code": "storeA",
        "price_type_code": "storeA"
      },
      "queryFunctions": [
        {
          "fieldName": "@availabilitystatus",
          "function": "var stock := @stock_status_code; var priceType := @price_type_code; switch { case (stock == -1) : -1; case (priceType == 0) : 0; case (priceType == 1) : 1; default : -1; };"
        }
      ]
    }

    Formatted here to ease reading:

    var stock := @stock_status_code;
    var priceType := @price_type_code;
    switch {
      case (stock == -1) : -1;
      case (priceType == 0) : 0;
      case (priceType == 1) : 1;
      default : -1;
    };

    where:

    • var stock := @stock_status_code; and var priceType := @price_type_code; store the dictionary-sourced field values in intermediate variables, so they can be reused across multiple case conditions without repeating the field reference.

    • switch { …​ } evaluates each case condition in order and returns the value of the first one that’s true. If none match, it returns the default value.

    200 OK response body (excerpt):

    {
      ...
      "results": [
        ...
        {
          "raw": {
            ...
            "stock_status_code": 1,
            "price_type_code": 0,
            "availabilitystatus": 0,
            ...
          },
          ...
        },
        ...
      ],
      ...
    }
    Note

    You can write the same logic using if/else instead of switch:

    var stock := @stock_status_code;
    var priceType := @price_type_code;
    if (stock == -1) {
      -1;
    } else {
      if (priceType == 0) {
        0;
      } else {
        if (priceType == 1) {
          1;
        } else {
          -1;
        }
      }
    };
    Note

    You can apply the same function value directly in a query expression using the $qf query extension (for example, in the aq part of a query pipeline filter rule), instead of using the queryFunctions parameter.

Performance issues

To prevent performance issues, every computed field referenced in the function must be stored in memory. Not doing so may lead to serious performance issues, with queries that might take over a second, depending on your number of items.

This is because query functions are executed on all accessible items. If the computed field isn’t stored in memory, it might have to be loaded from the disk, which can significantly slow the query.

Solve the issue in the Coveo Administration Console

For Coveo for Sitecore, follow these steps:

  1. Access the Coveo Administration Console (platform-ca | platform-eu | platform-au).

  2. Under Content, select Fields.

  3. Search for the field you want to store in cache.

  4. Select your desired field, and click Edit.

  5. In the Edit a field window, select Advanced settings.

  6. Select Use cache for numeric queries.

    Important

    If your numeric field is stored as a string, you may need to change its Type, for example to Long.

  7. Select Save to save your changes.

Exceptions

A few query exceptions can be returned when using query functions:

  • InvalidQueryFunction, Value: 40, Using the '@' character without any field name.

  • InvalidQueryFunctionField, Value: 41, Using a field that doesn’t exist in the index, nor in any prior query function.

  • InvalidQueryFunctionFieldType: Value: 42, Using a field that’s not a numeric field.

  • InvalidQueryFunctionSyntax: Value: 43, Syntax error in the expression.