---
title: ES|QL SAMPLE function
description: 
url: https://www.elastic.co/elastic/docs-builder/docs/3601/reference/query-languages/esql/functions-operators/aggregation-functions/sample
products:
  - Elasticsearch
---

# ES|QL SAMPLE function
<applies-to>
  - Elastic Stack: Generally available since 9.1
</applies-to>

Collects sample values for a field.

## Syntax

![Embedded](https://www.elastic.co/elastic/docs-builder/docs/3601/reference/query-languages/esql/images/generated/x-pack-esql/functions/sample.svg)


## Parameters

<definitions>
  <definition term="field">
    The field to collect sample values for.
  </definition>
  <definition term="limit">
    The maximum number of values to collect.
  </definition>
</definitions>


## Description

Collects sample values for a field.

## Supported types


| field                                                     | limit   | result          |
|-----------------------------------------------------------|---------|-----------------|
| boolean                                                   | integer | boolean         |
| cartesian_point                                           | integer | cartesian_point |
| cartesian_shape                                           | integer | cartesian_shape |
| date                                                      | integer | date            |
| date_nanos                                                | integer | date_nanos      |
| double                                                    | integer | double          |
| flattened <applies-to>Elastic Stack: Planned</applies-to> | integer | flattened       |
| geo_point                                                 | integer | geo_point       |
| geo_shape                                                 | integer | geo_shape       |
| geohash                                                   | integer | geohash         |
| geohex                                                    | integer | geohex          |
| geotile                                                   | integer | geotile         |
| integer                                                   | integer | integer         |
| ip                                                        | integer | ip              |
| keyword                                                   | integer | keyword         |
| long                                                      | integer | long            |
| text                                                      | integer | keyword         |
| unsigned_long                                             | integer | unsigned_long   |
| version                                                   | integer | version         |


## Examples

```esql
FROM sample_data
| STATS sample_messages = SAMPLE(message, 3)
```


| sample_messages:keyword                                 |
|---------------------------------------------------------|
| [Connected to 10.1.0.1, Connection error, Disconnected] |

`SAMPLE` returns up to the requested number of values per group. When a group has fewer values than the limit, all values are returned. When a group has more, a multivalue array of randomly sampled values is returned.
```esql
FROM sample_data
| STATS sample_messages = SAMPLE(message, 2) BY client_ip
| SORT client_ip
```


| client_ip:ip | sample_messages:keyword                   |
|--------------|-------------------------------------------|
| 172.21.0.5   | Disconnected                              |
| 172.21.2.113 | Connected to 10.1.0.2                     |
| 172.21.2.162 | Connected to 10.1.0.3                     |
| 172.21.3.15  | [Connection error, Connected to 10.1.0.1] |