Skip to content

Commit a41774e

Browse files
jrodewigjrodewig
committed
[DOCS] EQL: Document EQL Search API
1 parent 1eb0047 commit a41774e

File tree

3 files changed

+318
-1
lines changed

3 files changed

+318
-1
lines changed

‎docs/reference/eql/eql-search-api.asciidoc

Lines changed: 311 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
[role="xpack"]
2+
[testenv="basic"]
3+
4+
[[eql-search-api]]
5+
=== EQL search API
6+
++++
7+
<titleabbrev>EQL search</titleabbrev>
8+
++++
9+
10+
experimental::[]
11+
12+
Returns search results for an <<eql,Event Query Language (EQL)>> query.
13+
14+
////
15+
[source,console]
16+
----
17+
PUT my_index/_bulk?refresh
18+
{"index":{"_index" : "my_index", "_id" : "1"}}
19+
{ "@timestamp": "2020-12-06T11:04:05.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
20+
{"index":{"_index" : "my_index", "_id" : "2"}}
21+
{ "@timestamp": "2020-12-06T11:04:07.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "file" }, "file": { "accessed": "2020-12-07T11:07:08.000Z", "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe", "type": "file", "size": 16384 }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
22+
{"index":{"_index" : "my_index", "_id" : "3"}}
23+
{ "@timestamp": "2020-12-07T11:06:07.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
24+
{"index":{"_index" : "my_index", "_id" : "4"}}
25+
{ "@timestamp": "2020-12-07T11:07:08.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "file" }, "file": { "accessed": "2020-12-07T11:07:08.000Z", "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe", "type": "file", "size": 16384 }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
26+
{"index":{"_index" : "my_index", "_id" : "5"}}
27+
{ "@timestamp": "2020-12-07T11:07:09.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "regsvr32.exe", "path": "C:\\Windows\\System32\\regsvr32.exe" } }
28+
----
29+
// TESTSETUP
30+
////
31+
32+
[source,console]
33+
----
34+
GET my_index/_eql/search
35+
{
36+
"query": """
37+
process where process.name = "regsvr32.exe"
38+
"""
39+
}
40+
----
41+
42+
[[eql-search-api-request]]
43+
==== {api-request-title}
44+
45+
`GET <index>/_eql/search`
46+
47+
`POST <index>/_eql/search`
48+
49+
[[eql-search-api-prereqs]]
50+
==== {api-prereq-title}
51+
52+
See <<eql-requirements,EQL requirements>>.
53+
54+
[[eql-search-api-limitations]]
55+
===== Limitations
56+
57+
See <<eql-limitations,EQL limitations>>.
58+
59+
[[eql-search-api-path-params]]
60+
==== {api-path-parms-title}
61+
62+
`<index>`::
63+
(Required, string)
64+
Comma-separated list of index names or <<indices-aliases,index aliases>> used to
65+
limit the request. Accepts wildcard expressions.
66+
+
67+
To search all indices, use `_all`.
68+
69+
[[eql-search-api-query-params]]
70+
==== {api-query-parms-title}
71+
72+
include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
73+
+
74+
Defaults to `false`.
75+
76+
include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
77+
+
78+
Defaults to `open`.
79+
80+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
81+
82+
[[eql-search-api-request-body]]
83+
==== {api-request-body-title}
84+
85+
`query`::
86+
(Required, string)
87+
<<eql-syntax,EQL>> query you wish to run.
88+
+
89+
IMPORTANT: This parameter supports a subset of EQL syntax. See
90+
<<eql-unsupported-syntax>>.
91+
92+
`event_category_field`::
93+
(Required*, string)
94+
Field containing the event classification, such as `process`, `file`, or
95+
`network`.
96+
+
97+
Defaults to `event.category`, as defined in the {ecs-ref}/ecs-event.html[Elastic
98+
Common Schema (ECS)]. If an index does not contain the `event.category` field,
99+
this value is required.
100+
101+
[[eql-search-api-timestamp-field]]
102+
`timestamp_field`::
103+
+
104+
--
105+
(Required*, string)
106+
Field containing event timestamp.
107+
108+
Defaults to `@timestamp`, as defined in the
109+
{ecs-ref}/ecs-event.html[Elastic Common Schema (ECS)]. If an index does not
110+
contain the `@timestamp` field, this value is required.
111+
112+
Events in the API response are sorted by this field's value, converted to
113+
milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], in
114+
ascending order.
115+
--
116+
117+
`implicit_join_key_field`::
118+
(Optional, string)
119+
Reserved for future use.
120+
121+
`filter`::
122+
(Optional, <<query-dsl,query DSL object>>)
123+
Query, written in query DSL, used to filter the documents on which the EQL query
124+
runs.
125+
126+
`search_after`::
127+
(Optional, string)
128+
Reserved for future use.
129+
130+
`size`::
131+
(Optional, integer)
132+
Maximum number of matching documents to return. Defaults to `50`. Values must be
133+
greater than `0`.
134+
135+
[[eql-search-api-response-body]]
136+
==== {api-response-body-title}
137+
138+
`took`::
139+
+
140+
--
141+
(integer)
142+
Milliseconds it took {es} to execute the request.
143+
144+
This value is calculated by measuring the time elapsed
145+
between receipt of a request on the coordinating node
146+
and the time at which the coordinating node is ready to send the response.
147+
148+
Took time includes:
149+
150+
* Communication time between the coordinating node and data nodes
151+
* Time the request spends in a <<modules-threadpool,thread pool>>,
152+
queued for execution
153+
* Actual execution time
154+
155+
Took time does *not* include:
156+
157+
* Time needed to send the request to {es}
158+
* Time needed to serialize the JSON response
159+
* Time needed to send the response to a client
160+
--
161+
162+
`timed_out`::
163+
(boolean)
164+
If `true`, the request timed out before completion; returned results may be
165+
partial or empty.
166+
167+
`hits`::
168+
(object)
169+
Contains returned results and metadata.
170+
171+
`hits.total.value`::
172+
(integer)
173+
Total number of returned documents.
174+
175+
`hits.total.relation`::
176+
+
177+
--
178+
(string)
179+
Indicates whether the number of documents returned is accurate or a lower bound.
180+
181+
Returned values are:
182+
183+
`eq`::: Accurate
184+
`gte`::: Lower bound, including returned documents
185+
--
186+
187+
`hits.events`::
188+
(array of objects)
189+
Contains returned documents matching the query. Each object represents a
190+
matching document.
191+
192+
`hits.events._index`::
193+
(string)
194+
Name of the index containing the returned document.
195+
196+
`hits.events._id`::
197+
(string)
198+
Unique identifier for the returned document.
199+
200+
`hits.events._score`::
201+
(float)
202+
Positive 32-bit floating point number indicating the relevance of the returned
203+
document. See <<relevance-scores>>.
204+
205+
`hits.events._source`::
206+
(object)
207+
Object containing the original JSON body passed for the document at index time.
208+
209+
`hits.events.sort`::
210+
(array)
211+
Integer used as the sort value for the event.
212+
+
213+
By default, this is the event's <<eql-search-api-timestamp-field,timestamp
214+
value>>, converted to milliseconds since the
215+
https://en.wikipedia.org/wiki/Unix_time[Unix epoch].
216+
217+
[[eql-search-api-example]]
218+
==== {api-examples-title}
219+
220+
The following EQL search request searches for events with an `event.category` of
221+
`file` that meet the following conditions:
222+
223+
* A `file.name` of `cmd.exe`
224+
* An `agent.id` that is _not_ `my_user`
225+
226+
[source,console]
227+
----
228+
GET my_index/_eql/search
229+
{
230+
"query": """
231+
file where (file.name == "cmd.exe" and agent.id != "my_user")
232+
"""
233+
}
234+
----
235+
236+
The API returns the following response. Events in the response are sorted by
237+
<<eql-search-api-timestamp-field,timestamp>>, converted to milliseconds since
238+
the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], in ascending order.
239+
240+
[source,console-result]
241+
----
242+
{
243+
"took": 6,
244+
"timed_out": false,
245+
"hits": {
246+
"total": {
247+
"value": 2,
248+
"relation": "eq"
249+
},
250+
"events": [
251+
{
252+
"_index": "my_index",
253+
"_id": "2",
254+
"_score": null,
255+
"_source": {
256+
"@timestamp": "2020-12-06T11:04:07.000Z",
257+
"agent": {
258+
"id": "8a4f500d"
259+
},
260+
"event": {
261+
"category": "file"
262+
},
263+
"file": {
264+
"accessed": "2020-12-07T11:07:08.000Z",
265+
"name": "cmd.exe",
266+
"path": "C:\\Windows\\System32\\cmd.exe",
267+
"type": "file",
268+
"size": 16384
269+
},
270+
"process": {
271+
"name": "cmd.exe",
272+
"path": "C:\\Windows\\System32\\cmd.exe"
273+
}
274+
},
275+
"sort": [
276+
1607252647000
277+
]
278+
},
279+
{
280+
"_index": "my_index",
281+
"_id": "4",
282+
"_score": null,
283+
"_source": {
284+
"@timestamp": "2020-12-07T11:07:08.000Z",
285+
"agent": {
286+
"id": "8a4f500d"
287+
},
288+
"event": {
289+
"category": "file"
290+
},
291+
"file": {
292+
"accessed": "2020-12-07T11:07:08.000Z",
293+
"name": "cmd.exe",
294+
"path": "C:\\Windows\\System32\\cmd.exe",
295+
"type": "file",
296+
"size": 16384
297+
},
298+
"process": {
299+
"name": "cmd.exe",
300+
"path": "C:\\Windows\\System32\\cmd.exe"
301+
}
302+
},
303+
"sort": [
304+
1607339228000
305+
]
306+
}
307+
]
308+
}
309+
}
310+
----
311+
// TESTRESPONSE[s/"took": 6/"took": $body.took/]

‎docs/reference/search.asciidoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,12 @@ include::search/suggesters.asciidoc[]
166166

167167
include::search/multi-search.asciidoc[]
168168

169+
ifdef::permanently-unreleased-branch[]
170+
171+
include::eql/eql-search-api.asciidoc[]
172+
173+
endif::[]
174+
169175
include::search/count.asciidoc[]
170176

171177
include::search/validate.asciidoc[]

‎x-pack/plugin/src/test/resources/rest-api-spec/api/eql.search.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"eql.search":{
33
"documentation":{
4-
"url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html"
4+
"url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/eql-search-api.html"
55
},
66
"stability": "beta",
77
"url":{

0 commit comments

Comments
 (0)