﻿---
title: ES|QL VALUES function
description: 
url: https://www.elastic.co/elastic/docs-builder/docs/2984/reference/query-languages/esql/functions-operators/aggregation-functions/values
products:
  - Elasticsearch
---

# ES|QL VALUES function
<applies-to>
  - Elastic Stack: Preview from 8.14 to 9.3
</applies-to>


## Syntax

![Embedded](https://www.elastic.co/elastic/docs-builder/docs/2984/reference/query-languages/esql/images/functions/values.svg)


## Parameters

<definitions>
  <definition term="field">
  </definition>
</definitions>


## Description

Returns unique (deduplicated) values as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use [`MV_SORT`](https://www.elastic.co/elastic/docs-builder/docs/2984/reference/query-languages/esql/functions-operators/mv-functions/mv_sort).

## Supported types


| field           | result          |
|-----------------|-----------------|
| boolean         | boolean         |
| cartesian_point | cartesian_point |
| cartesian_shape | cartesian_shape |
| date            | date            |
| date_nanos      | date_nanos      |
| double          | double          |
| geo_point       | geo_point       |
| geo_shape       | geo_shape       |
| geohash         | geohash         |
| geohex          | geohex          |
| geotile         | geotile         |
| integer         | integer         |
| ip              | ip              |
| keyword         | keyword         |
| long            | long            |
| text            | keyword         |
| unsigned_long   | unsigned_long   |
| version         | version         |


## Example

```esql
FROM employees
| EVAL first_letter = SUBSTRING(first_name, 0, 1)
| STATS first_name = MV_SORT(VALUES(first_name)) BY first_letter
| SORT first_letter
```


| first_name:keyword                                                                                | first_letter:keyword |
|---------------------------------------------------------------------------------------------------|----------------------|
| [Alejandro, Amabile, Anneke, Anoosh, Arumugam]                                                    | A                    |
| [Basil, Berhard, Berni, Bezalel, Bojan, Breannda, Brendon]                                        | B                    |
| [Charlene, Chirstian, Claudi, Cristinel]                                                          | C                    |
| [Danel, Divier, Domenick, Duangkaew]                                                              | D                    |
| [Ebbe, Eberhardt, Erez]                                                                           | E                    |
| Florian                                                                                           | F                    |
| [Gao, Georgi, Georgy, Gino, Guoxiang]                                                             | G                    |
| [Heping, Hidefumi, Hilari, Hironobu, Hironoby, Hisao]                                             | H                    |
| [Jayson, Jungsoon]                                                                                | J                    |
| [Kazuhide, Kazuhito, Kendra, Kenroku, Kshitij, Kwee, Kyoichi]                                     | K                    |
| [Lillian, Lucien]                                                                                 | L                    |
| [Magy, Margareta, Mary, Mayuko, Mayumi, Mingsen, Mokhtar, Mona, Moss]                             | M                    |
| Otmar                                                                                             | O                    |
| [Parto, Parviz, Patricio, Prasadram, Premal]                                                      | P                    |
| [Ramzi, Remzi, Reuven]                                                                            | R                    |
| [Sailaja, Saniya, Sanjiv, Satosi, Shahaf, Shir, Somnath, Sreekrishna, Sudharsan, Sumant, Suzette] | S                    |
| [Tse, Tuval, Tzvetan]                                                                             | T                    |
| [Udi, Uri]                                                                                        | U                    |
| [Valdiodio, Valter, Vishv]                                                                        | V                    |
| Weiyi                                                                                             | W                    |
| Xinglin                                                                                           | X                    |
| [Yinghua, Yishay, Yongqiao]                                                                       | Y                    |
| [Zhongwei, Zvonko]                                                                                | Z                    |
| null                                                                                              | null                 |

<tip>
  Use [`TOP`](https://www.elastic.co/elastic/docs-builder/docs/2984/reference/query-languages/esql/functions-operators/aggregation-functions/top)
  if you need to keep repeated values.
</tip>

<warning>
  This can use a significant amount of memory and ES|QL doesn’t yet
  grow aggregations beyond memory. So this aggregation will work until
  it is used to collect more values than can fit into memory. Once it
  collects too many values it will fail the query with
  a [Circuit Breaker Error](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2984/troubleshoot/elasticsearch/circuit-breaker-errors).
</warning>