## 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 discarded.
- If a field name is used more than once, a multi-valued column will be created with one value for each occurrence of the field name.

## Examples

Parsing a string with multiple data types

Parse a string containing 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
```

Type conversion for numeric fields

Convert numeric fields to specific types by appending `:type` to the semantics in the pattern. For example, `{NUMBER:num:int}` converts the `num` field to an integer:

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

Using type conversion functions

For other type conversions, use type conversion functions like `TO_DATETIME`:

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

Handling multi-valued columns

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