---
title: ES|QL SAMPLE function
description: 
url: https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/149366/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>


## Syntax

![Embedded](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/149366/reference/query-languages/esql/images/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          |
| 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] |