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.

This topic 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 cannot determine them automatically.

This means that if you want to generate a FacetRange based on a field generated by a query function in a search interface that relies on the Coveo JavaScript Search Framework, you must use the ranges option.

  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 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 result. This field is generated at query time and can be used as a facet or as a computed field.

Note: The field name must start with a lowercase alphabetic character and can only contain lowercase alphabetic characters, numeric characters, and/or underscore characters. Moreover, that field name must not already exist in your index.

Sample value: adjustednumberoflikes

function (string)

The mathematical expression whose result you want to store in a dynamic, temporary field.

Note: Query function expressions supports the ExprTk library syntax. However, the following statements have been disabled:

  • if/else
  • switch
  • while
  • repeat until

Tip: If your query function expression references certain numeric fields, you should ensure that the Use cahe for computed fields option is enabled for each of those fields in order to speed up evaluation (see Add or Edit Fields).

Sample value: @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 is not 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 V2, 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 wish 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 cannot 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.
People also viewed