---
title: Query functions
slug: '1451'
canonical_url: https://docs.coveo.com/en/1451/
collection: build-a-search-ui
source_format: adoc
---
# Query functions

A _query function_ is a mathematical expression evaluated against each [item](https://docs.coveo.com/en/210/) returned by a [query](https://docs.coveo.com/en/231/), and whose output is stored in a dynamic, temporary [field](https://docs.coveo.com/en/200/) generated at query time.
Query function expressions are defined using the [C{plus}{plus} Mathematical Expression Toolkit Library (ExprTk)](http://www.partow.net/programming/exprtk/index.html).
They don't support loop structures, but `if` statements are supported.

This article describes the members of the structure that defines a single [query function](https://docs.coveo.com/en/232/).
You can specify an array of [query functions](https://docs.coveo.com/en/232/) in a query using the [`queryFunctions`](https://docs.coveo.com/en/13#operation/searchUsingPost-queryFunctions) top-level query parameter.

> **Note**
>
> You can use a field generated by a [query function](https://docs.coveo.com/en/232/) almost anywhere you would use a normal numeric field.
> One notable exception is automatic range generation in [Group By](https://docs.coveo.com/en/203/) operations (see the [`generateAutomaticRanges`](https://docs.coveo.com/en/13#operation/searchUsingPost-groupBy-generateAutomaticRanges) Group By parameter).
> To create ranges for a field generated by a query function, specify those ranges explicitly using the [`rangeValues`](https://docs.coveo.com/en/13#operation/searchUsingPost-groupBy-rangeValues) Group By parameter, because the index can't determine them automatically.
> 
> This implies that in a [JavaScript Search Framework](https://docs.coveo.com/en/187/) interface, to render a [`FacetRange`](https://coveo.github.io/search-ui/components/facetrange.html) component based on a field generated by a query function, you must use the [`ranges`](https://coveo.github.io/search-ui/components/facetrange.html#options.ranges) option to specify the desired ranges.

## Examples

. 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`.

```http
POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload:**

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

**200 OK response body (excerpt):**

```json
{
  ...
  "results": [
    ...
    {
      "raw": {
        ...
        "size": 1767763,
        "sizekb": 1726.3310546875,
        ...
      },
      ...
    },
    ...
  ],
  ...
}
```

. 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`.

```http
POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload:**

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

**200 OK response body (excerpt):**

```json
{
  ...
  "results": [
    ...
    {
      "raw": {
        ...
        "distance": 235762,
        "distanceinmiles": 146.495669702,
        ...
      },
      ...
    },
    ...
  ],
  ...
}
```

. You have a `@price` field on your items.
You need a `@discountedprice` field that contains the price with a 10% discount.


```http
POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload:**

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

**200 OK response body (excerpt):**

```json
{
  ...
  "results": [
    ...
    {
      "raw": {
        ...
        "price": 10,
        "discountPrice": 9,
        ...
      },
      ...
    },
    ...
  ],
  ...
}
```

## 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](https://docs.coveo.com/en/231/) that might take over a second, depending on your number of [items](https://docs.coveo.com/en/210/).

This is because [query functions](https://docs.coveo.com/en/232/) 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](https://docs.coveo.com/en/231/).

### Solve the issue in the Coveo Administration Console

For Coveo for Sitecore, follow these steps:

. Access the [Coveo Administration Console](https://platform.cloud.coveo.com/login) ([platform-ca](https://platform-ca.cloud.coveo.com/login) | [platform-eu](https://platform-eu.cloud.coveo.com/login) | [platform-au](https://platform-au.cloud.coveo.com/login)).

. Under **Content**, select **Fields**.

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

. Select your desired field, and click **Edit**.

. In the **Edit a Field** window, select **Advanced Settings**.

. 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**.

. Select **Save Field** to save your changes.

## Exceptions

A few query exceptions can be returned when using [query functions](https://docs.coveo.com/en/232/):

* `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.`