Query Functions

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), but they do not support control and loop structures (e.g., if-then-else, while loop, etc.).

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.

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). If you need to create ranges for a field generated by a query function, you must 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, if you want 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.

  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,
          ...
        },
        ...
      },
      ...
    ],
    ...
  }
  1. You want to compute the distance between two coordinates in miles 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,
          ...
        },
        ...
      },
      ...
    ],
    ...
  }

Query Function Parameters

This section provides reference documentation for the available query function parameters.

fieldName (string)

The name of the dynamic, temporary field in which to store the query function expression output.

Note: The fieldName value must not correspond to an existing field in the index.

Example: numberoflikesplusone

function (string)

The mathematical expression whose output should be stored in a dynamic, temporary field.

Notes:

  • The function expression can be defined using the ExprTk library syntax, but control and loop structures (e.g., if-then-else, while loop, etc.) are not supported.
  • If the function expression references a numeric field, enable the Use cache for computed fields option on that field to speed up evaluation (see Add or Edit Fields).

Example: @numberoflikes+1

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 Cloud V2

When using Coveo Cloud, for instance in a Coveo for Sitecore Cloud edition environment, follow these steps:

  1. Access the Coveo Cloud Platform administration console.

  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.

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

  7. Select Save Field to save your changes.

Solve the Issue in Cloud V1

In a Cloud V1 environment, for instance when using Coveo for Salesforce, you can’t manually change this setting. For security reasons, the ability to change the configuration file has been limited to selected Coveo employees. To change this setting, contact Coveo Support.

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 is not a numerical field.

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

Recommended Articles