Skip to content

Commit de228ee

Browse files
jrodewigjrodewig
authored
[DOCS] Reorder EQL sections. Remove duplicated content. (#71477)
1 parent 51a1dcf commit de228ee

File tree

1 file changed

+167
-174
lines changed

1 file changed

+167
-174
lines changed

‎docs/reference/eql/eql.asciidoc

Lines changed: 167 additions & 174 deletions
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,7 @@ default.
4646
=== Run an EQL search
4747

4848
Use the <<eql-search-api,EQL search API>> to run a <<eql-basic-syntax,basic EQL
49-
query>>. If the {es} {security-features} are enabled, you must have the `read`
50-
<<privileges-list-indices,index privilege>> for the target data stream, index,
51-
or index alias.
49+
query>>.
5250

5351
////
5452
[source,console]
@@ -146,170 +144,6 @@ GET /my-data-stream/_eql/search
146144
----
147145
// TEST[setup:sec_logs]
148146

149-
[discrete]
150-
[[retrieve-selected-fields]]
151-
=== Retrieve selected fields
152-
153-
By default, each hit in the search response includes the document `_source`,
154-
which is the entire JSON object that was provided when indexing the document.
155-
156-
You can use the <<common-options-response-filtering,`filter_path`>> query
157-
parameter to filter the API response. For example, the following search returns
158-
only the timestamp and PID from the `_source` of each matching event.
159-
160-
[source,console]
161-
----
162-
GET /my-data-stream/_eql/search?filter_path=hits.events._source.@timestamp,hits.events._source.process.pid
163-
{
164-
"query": """
165-
process where process.name == "regsvr32.exe"
166-
"""
167-
}
168-
----
169-
// TEST[setup:sec_logs]
170-
171-
The API returns the following response.
172-
173-
[source,console-result]
174-
----
175-
{
176-
"hits": {
177-
"events": [
178-
{
179-
"_source": {
180-
"@timestamp": "2099-12-07T11:07:09.000Z",
181-
"process": {
182-
"pid": 2012
183-
}
184-
}
185-
},
186-
{
187-
"_source": {
188-
"@timestamp": "2099-12-07T11:07:10.000Z",
189-
"process": {
190-
"pid": 2012
191-
}
192-
}
193-
}
194-
]
195-
}
196-
}
197-
----
198-
199-
You can also use the `fields` parameter to retrieve and format specific fields
200-
in the response. This field is identical to the search API's
201-
<<search-fields,`fields` parameter>>.
202-
203-
204-
include::{es-repo-dir}/search/search-your-data/retrieve-selected-fields.asciidoc[tag=fields-param-desc]
205-
206-
The following EQL search uses the `fields` parameter to retrieve values for the
207-
`event.type` field, all fields starting with `process.`, and the `@timestamp`
208-
field. The request also uses the `filter_path` query parameter to exclude the
209-
`_source` of each hit.
210-
211-
[source,console]
212-
----
213-
GET /my-data-stream/_eql/search?filter_path=-hits.events._source
214-
{
215-
"query": """
216-
process where process.name == "regsvr32.exe"
217-
""",
218-
"fields": [
219-
"event.type",
220-
"process.*", <1>
221-
{
222-
"field": "@timestamp", <2>
223-
"format": "epoch_millis"
224-
}
225-
]
226-
}
227-
----
228-
// TEST[setup:sec_logs]
229-
230-
include::{es-repo-dir}/search/search-your-data/retrieve-selected-fields.asciidoc[tag=fields-param-callouts]
231-
232-
The values are returned as a flat list in the `fields` section of each hit:
233-
234-
[source,console-result]
235-
----
236-
{
237-
"is_partial": false,
238-
"is_running": false,
239-
"took": 60,
240-
"timed_out": false,
241-
"hits": {
242-
"total": {
243-
"value": 2,
244-
"relation": "eq"
245-
},
246-
"events": [
247-
{
248-
"_index": ".ds-my-data-stream-2099.12.07-000001",
249-
"_id": "OQmfCaduce8zoHT93o4H",
250-
"fields": {
251-
"process.name": [
252-
"regsvr32.exe"
253-
],
254-
"process.name.keyword": [
255-
"regsvr32.exe"
256-
],
257-
"@timestamp": [
258-
"4100324829000"
259-
],
260-
"process.command_line": [
261-
"regsvr32.exe /s /u /i:https://...RegSvr32.sct scrobj.dll"
262-
],
263-
"process.command_line.keyword": [
264-
"regsvr32.exe /s /u /i:https://...RegSvr32.sct scrobj.dll"
265-
],
266-
"process.executable.keyword": [
267-
"C:\\Windows\\System32\\regsvr32.exe"
268-
],
269-
"process.pid": [
270-
2012
271-
],
272-
"process.executable": [
273-
"C:\\Windows\\System32\\regsvr32.exe"
274-
]
275-
}
276-
},
277-
{
278-
"_index": ".ds-my-data-stream-2099.12.07-000001",
279-
"_id": "xLkCaj4EujzdNSxfYLbO",
280-
"fields": {
281-
"process.name": [
282-
"regsvr32.exe"
283-
],
284-
"process.name.keyword": [
285-
"regsvr32.exe"
286-
],
287-
"@timestamp": [
288-
"4100324830000"
289-
],
290-
"event.type": [
291-
"termination"
292-
],
293-
"process.executable.keyword": [
294-
"C:\\Windows\\System32\\regsvr32.exe"
295-
],
296-
"process.pid": [
297-
2012
298-
],
299-
"process.executable": [
300-
"C:\\Windows\\System32\\regsvr32.exe"
301-
]
302-
}
303-
}
304-
]
305-
}
306-
}
307-
----
308-
// TESTRESPONSE[s/"took": 60/"took": $body.took/]
309-
// TESTRESPONSE[s/"_index": ".ds-my-data-stream-2099.12.07-000001"/"_index": $body.hits.events.0._index/]
310-
// TESTRESPONSE[s/"_id": "OQmfCaduce8zoHT93o4H"/"_id": $body.hits.events.0._id/]
311-
// TESTRESPONSE[s/"_id": "xLkCaj4EujzdNSxfYLbO"/"_id": $body.hits.events.1._id/]
312-
313147
[discrete]
314148
[[eql-search-sequence]]
315149
=== Search for a sequence of events
@@ -534,6 +368,170 @@ GET /my-data-stream/_eql/search
534368
----
535369
// TEST[setup:sec_logs]
536370

371+
[discrete]
372+
[[retrieve-selected-fields]]
373+
=== Retrieve selected fields
374+
375+
By default, each hit in the search response includes the document `_source`,
376+
which is the entire JSON object that was provided when indexing the document.
377+
378+
You can use the <<common-options-response-filtering,`filter_path`>> query
379+
parameter to filter the API response. For example, the following search returns
380+
only the timestamp and PID from the `_source` of each matching event.
381+
382+
[source,console]
383+
----
384+
GET /my-data-stream/_eql/search?filter_path=hits.events._source.@timestamp,hits.events._source.process.pid
385+
{
386+
"query": """
387+
process where process.name == "regsvr32.exe"
388+
"""
389+
}
390+
----
391+
// TEST[setup:sec_logs]
392+
393+
The API returns the following response.
394+
395+
[source,console-result]
396+
----
397+
{
398+
"hits": {
399+
"events": [
400+
{
401+
"_source": {
402+
"@timestamp": "2099-12-07T11:07:09.000Z",
403+
"process": {
404+
"pid": 2012
405+
}
406+
}
407+
},
408+
{
409+
"_source": {
410+
"@timestamp": "2099-12-07T11:07:10.000Z",
411+
"process": {
412+
"pid": 2012
413+
}
414+
}
415+
}
416+
]
417+
}
418+
}
419+
----
420+
421+
You can also use the `fields` parameter to retrieve and format specific fields
422+
in the response. This field is identical to the search API's
423+
<<search-fields,`fields` parameter>>.
424+
425+
426+
include::{es-repo-dir}/search/search-your-data/retrieve-selected-fields.asciidoc[tag=fields-param-desc]
427+
428+
The following EQL search uses the `fields` parameter to retrieve values for the
429+
`event.type` field, all fields starting with `process.`, and the `@timestamp`
430+
field. The request also uses the `filter_path` query parameter to exclude the
431+
`_source` of each hit.
432+
433+
[source,console]
434+
----
435+
GET /my-data-stream/_eql/search?filter_path=-hits.events._source
436+
{
437+
"query": """
438+
process where process.name == "regsvr32.exe"
439+
""",
440+
"fields": [
441+
"event.type",
442+
"process.*", <1>
443+
{
444+
"field": "@timestamp", <2>
445+
"format": "epoch_millis"
446+
}
447+
]
448+
}
449+
----
450+
// TEST[setup:sec_logs]
451+
452+
include::{es-repo-dir}/search/search-your-data/retrieve-selected-fields.asciidoc[tag=fields-param-callouts]
453+
454+
The values are returned as a flat list in the `fields` section of each hit:
455+
456+
[source,console-result]
457+
----
458+
{
459+
"is_partial": false,
460+
"is_running": false,
461+
"took": 60,
462+
"timed_out": false,
463+
"hits": {
464+
"total": {
465+
"value": 2,
466+
"relation": "eq"
467+
},
468+
"events": [
469+
{
470+
"_index": ".ds-my-data-stream-2099.12.07-000001",
471+
"_id": "OQmfCaduce8zoHT93o4H",
472+
"fields": {
473+
"process.name": [
474+
"regsvr32.exe"
475+
],
476+
"process.name.keyword": [
477+
"regsvr32.exe"
478+
],
479+
"@timestamp": [
480+
"4100324829000"
481+
],
482+
"process.command_line": [
483+
"regsvr32.exe /s /u /i:https://...RegSvr32.sct scrobj.dll"
484+
],
485+
"process.command_line.keyword": [
486+
"regsvr32.exe /s /u /i:https://...RegSvr32.sct scrobj.dll"
487+
],
488+
"process.executable.keyword": [
489+
"C:\\Windows\\System32\\regsvr32.exe"
490+
],
491+
"process.pid": [
492+
2012
493+
],
494+
"process.executable": [
495+
"C:\\Windows\\System32\\regsvr32.exe"
496+
]
497+
}
498+
},
499+
{
500+
"_index": ".ds-my-data-stream-2099.12.07-000001",
501+
"_id": "xLkCaj4EujzdNSxfYLbO",
502+
"fields": {
503+
"process.name": [
504+
"regsvr32.exe"
505+
],
506+
"process.name.keyword": [
507+
"regsvr32.exe"
508+
],
509+
"@timestamp": [
510+
"4100324830000"
511+
],
512+
"event.type": [
513+
"termination"
514+
],
515+
"process.executable.keyword": [
516+
"C:\\Windows\\System32\\regsvr32.exe"
517+
],
518+
"process.pid": [
519+
2012
520+
],
521+
"process.executable": [
522+
"C:\\Windows\\System32\\regsvr32.exe"
523+
]
524+
}
525+
}
526+
]
527+
}
528+
}
529+
----
530+
// TESTRESPONSE[s/"took": 60/"took": $body.took/]
531+
// TESTRESPONSE[s/"_index": ".ds-my-data-stream-2099.12.07-000001"/"_index": $body.hits.events.0._index/]
532+
// TESTRESPONSE[s/"_id": "OQmfCaduce8zoHT93o4H"/"_id": $body.hits.events.0._id/]
533+
// TESTRESPONSE[s/"_id": "xLkCaj4EujzdNSxfYLbO"/"_id": $body.hits.events.1._id/]
534+
537535
[discrete]
538536
[[specify-a-timestamp-or-event-category-field]]
539537
=== Specify a timestamp or event category field
@@ -669,10 +667,7 @@ requests.
669667

670668
To check the progress of an async search, use the <<get-async-eql-search-api,get
671669
async EQL search API>> with the search ID. Specify how long you'd like for
672-
complete results in the `wait_for_completion_timeout` parameter. If the {es}
673-
{security-features} are enabled, only the user who first submitted the EQL
674-
search can retrieve the search using this API.
675-
670+
complete results in the `wait_for_completion_timeout` parameter.
676671
[source,console]
677672
----
678673
GET /_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=2s
@@ -753,9 +748,7 @@ GET /_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTo
753748

754749
Use the <<delete-async-eql-search-api,delete async EQL search API>> to
755750
manually delete an async EQL search before the `keep_alive` period ends. If the
756-
search is still ongoing, {es} cancels the search request. If the {es}
757-
{security-features} are enabled, only the user who first submitted the EQL
758-
search can delete the search using this API.
751+
search is still ongoing, {es} cancels the search request.
759752

760753
[source,console]
761754
----

0 commit comments

Comments
 (0)