# GROK

The GROK command is used to extract structured data from a string. It matches the string against patterns based on regular expressions and extracts the specified patterns as columns.

## Syntax

`GROK input "pattern"`

### Parameters

#### input

The column containing the string you want to structure. If the column has multiple values, GROK will process each value.

#### pattern

A grok pattern. If a field name conflicts with an existing column, the existing column is dropped. If a field name is used more than once, a multi-valued column is created with one value per each occurrence of the field name.

## Examples

The following example parses a string that contains a timestamp, an IP address, an email address, and a number:

```esql
ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 some.email@foo.com 42"
| GROK a "%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num}"
| KEEP date, ip, email, num
```

By default, GROK outputs keyword string columns. `int` and `float` types can be converted by appending `:type` to the semantics in the pattern. For example `{NUMBER:num:int}`:

```esql
ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 some.email@foo.com 42"
| GROK a "%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num:int}"
| KEEP date, ip, email, num
```

For other type conversions, use Type conversion functions:

```esql
ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 some.email@foo.com 42"
| GROK a "%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num:int}"
| KEEP date, ip, email, num
| EVAL date = TO_DATETIME(date)
```

If a field name is used more than once, GROK creates a multi-valued column:

```esql
FROM addresses
| KEEP city.name, zip_code
| GROK zip_code "%{WORD:zip_parts} %{WORD:zip_parts}"
```

### Limitations

- If a field name conflicts with an existing column, the existing column is discarded.
- If a field name is used more than once, a multi-valued column will be created with one value per each occurrence of the field name.
- The `GROK` command does not support configuring custom patterns or multiple patterns.
- The `GROK` command is not subject to Grok watchdog settings.
