[role="xpack"]
[[test-grok-pattern]]
= Test Grok pattern API

++++
<titleabbrev>Test Grok pattern</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-text_structure[Text structure APIs].
--

Tests a Grok pattern on lines of text, see also <<grok,Grokking grok>>.

[discrete]
[[test-grok-pattern-request]]
== {api-request-title}

`GET _text_structure/test_grok_pattern` +

`POST _text_structure/test_grok_pattern` +

[discrete]
[[test-grok-pattern-desc]]
== {api-description-title}

The test Grok pattern API allows you to execute a Grok pattern on one
or more lines of text. It returns whether the lines match the pattern
together with the offsets and lengths of the matched substrings.

[discrete]
[[test-grok-pattern-query-parms]]
== {api-query-parms-title}

`ecs_compatibility`::
(Optional, string) The mode of compatibility with ECS compliant Grok patterns.
Use this parameter to specify whether to use ECS Grok patterns instead of
legacy ones when the structure finder creates a Grok pattern. Valid values
are `disabled` and `v1`. The default value is `disabled`.

[discrete]
[[test-grok-pattern-request-body]]
== {api-request-body-title}

`grok_pattern`::
(Required, string)
The Grok pattern to run on the lines of text.

`text`::
(Required, array of strings)
The lines of text to run the Grok pattern on.

[discrete]
[[test-grok-pattern-example]]
== {api-examples-title}

[source,console]
--------------------------------------------------
GET _text_structure/test_grok_pattern
{
  "grok_pattern": "Hello %{WORD:first_name} %{WORD:last_name}",
  "text": [
    "Hello John Doe",
    "this does not match"
  ]
}
--------------------------------------------------

The API returns the following response:

[source,console-result]
----
{
  "matches": [
    {
      "matched": true,
      "fields": {
        "first_name": [
          {
            "match": "John",
            "offset": 6,
            "length": 4
          }
        ],
        "last_name": [
          {
            "match": "Doe",
            "offset": 11,
            "length": 3
          }
        ]
      }
    },
    {
      "matched": false
    }
  ]
}
----