Skip to end of metadata
Go to start of metadata

In this topic:

This topic describes the members of the structure defining a single Query Function to perform during a request. A Query Function is a mathematical expression that you run during a request to calculate a value for each result at query time, and output its result in a dynamic field.

The Query Function syntax is: 

Example:

The @syssize field contains the search results item file size in bytes. You want to create a field that shows the value in KB. You use the following Query Function:

The field @filesizekb is created at query time and contains the calculated value. You could then use this value and show it in your search result template.

Icon

You can use Query Functions through the $qf query extension (see Standard Query Extensions) that you can quickly test in a Coveo search box.

Example:

You can also chain multiple query functions and use the result of one in another. 

Example:

You want to get the distance between two coordinates in kilometers:

Icon

You can use a query function generated field almost anywhere you would use a normal numerical field. One notable exception is automatic facet ranges in the Coveo JavaScript Search Framework (see the FacetRangecomponent). If you need to create facet ranges on a query function generated field, you must specify those ranges at query time, because the indexer cannot determine them automatically.

Parameters

The following list contains all parameters available when executing a query function using the REST Search API.

function: The function to execute

The mathematical expression that calculates the value to inject in the field.

ExprTK

The Coveo query function supports the syntax of the C++ Mathematical Expression Library ExprTk (see ExprTk Library).

Be aware that the following statements have been disabled:

  • if / else
  • while
  • repeat until
  • switch
Example:

You have a @price field on your items. You need a @discountedprice field that contains the price with a 10% discount. Your function should look like this:

dist

The dist function was added to the supported query functions, on top of the ExprTK library functions. The dist function calculates the distance as the crow flies between two sets of latitude and longitude coordinates (using the Levenshtein distance algorithm) useful in geolocalization applications (see Getting Geolocalized Results in a JavaScript Search Page.

The dist function syntax is:

The returned value is in meters. 

Example:

Your index includes geographic latitude and longitude fields for all kinds of shops. You want to calculate a distance between the current user geographic location and a restaurant location. You use the dist query function to calculate and inject a distance field at query time.

In the response, the distance field is added.

fieldName: Name of the field that will hold the results

This specifies the name of the field to be generated at query time. This field can be used as a facet or as a computed field.

Icon

The field name can only contain alphanumerical characters, and must not already exist in your index.

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 Cloud V2, for instance in a Coveo for Sitecore Cloud edition environment, follow these steps:

  1. Access the Coveo Cloud Platform.
  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.

    Icon

    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.

Solve the issue in CES

In an on-premises environment using Coveo Enterprise Search, this setting is changeable in a configuration file, where your fields can be added to the ComputedFieldsInMemory node.

Icon

You are strongly discouraged from modifying this configuration file yourself, as doing so might heavily hinder search. To safely 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.

 

  • No labels