Skip to content

[DOCS] EQL: Document match function #56134

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 5, 2020
Merged

[DOCS] EQL: Document match function #56134

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions docs/reference/eql/functions.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ experimental::[]
* <<eql-fn-endswith>>
* <<eql-fn-indexof>>
* <<eql-fn-length>>
* <<eql-fn-match>>
* <<eql-fn-startswith>>
* <<eql-fn-string>>
* <<eql-fn-stringcontains>>
Expand Down Expand Up @@ -416,6 +417,71 @@ field datatypes:
*Returns:* integer or `null`
====

[discrete]
[[eql-fn-match]]
=== `match`

Returns `true` if a source string matches one or more provided regular
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we know which regular expression is checked first? I mean, does it matter if it's matching the second or the fourth regular expression?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure it matters from a usage point of view.

The expressions are checked using OR logic so if any of the regular expressions match, the function returns true.

The function also doesn't give any indicator of which expression matched. Only that at least one did.

match("explorer.exe", "[a-z]*?.exe", "[1-9]")
is equivalent to
match("explorer.exe", "[1-9]", "[a-z]*?.exe",)

expressions.

[%collapsible]
====
*Example*
[source,eql]
----
match("explorer.exe", "[a-z]*?.exe") // returns true
match("explorer.exe", "[a-z]*?.exe", "[1-9]") // returns true
match("explorer.exe", "[1-9]") // returns false
match("explorer.exe", "") // returns false

// process.name = "explorer.exe"
match(process.name, "[a-z]*?.exe") // returns true
match(process.name, "[a-z]*?.exe", "[1-9]") // returns true
match(process.name, "[1-9]") // returns false
match(process.name, "") // returns false

// null handling
match(null, "[a-z]*?.exe") // returns null
----

*Syntax*
[source,txt]
----
match(<source>, <reg_exp>[, ...])
----

*Parameters*

`<source>`::
+
--
(Required, string or `null`)
Source string. If `null`, the function returns `null`.

If using a field as the argument, this parameter supports only the following
field datatypes:

* <<keyword,`keyword`>>
* <<constant-keyword,`constant_keyword`>>
* <<text,`text`>> field with a <<keyword,`keyword`>> or
<<constant-keyword,`constant_keyword`>> sub-field
--

`<reg_exp>`::
+
--
(Required{multi-arg-ref}, string)
Regular expression used to match the source string. For supported syntax, see
<<regexp-syntax>>.
https://docs.oracle.com/javase/tutorial/essential/regex/pre_char_classes.html[Predefined
character classes] are not supported.

Fields are not supported as arguments.
--

*Returns:* boolean or `null`
====

[discrete]
[[eql-fn-startswith]]
=== `startsWith`
Expand Down