New

The executive guide to generative AI

Read more
About usPartnersSupport|Login

WARNING: Deprecated in 7.15.0.

The Java REST Client is deprecated in favor of the Java API Client.

« EQL APIs Using Java Builders »
Elastic Docs ›Java REST Client [7.15] ›Java High Level REST Client ›EQL APIs

EQL Search API

edit

EQL Search API

edit

Request

edit

A EqlSearchRequest allows to submit an EQL search request. Required arguments are the indices to search against and the query itself:

String indices = "my-index"; 
String query = "any where true"; 
EqlSearchRequest request = new EqlSearchRequest(indices, query);

Comma-separated list of data streams, indices, or aliases targeting the local cluster or a remote one, used to limit the request. Supports wildcards (*). To search all data streams and indices, use * or _all.

The query to execute

Optional arguments

edit

The following arguments can optionally be provided:

request.eventCategoryField("event_category"); 
request.fetchSize(50); 
request.size(15); 
request.tiebreakerField("tie"); 
request.timestampField("timestamp"); 
request.filter(QueryBuilders.matchAllQuery()); 
request.resultPosition("head"); 

List<FieldAndFormat> fields = new ArrayList<>();
fields.add(new FieldAndFormat("hostname", null));
request.fetchFields(fields); 

IndicesOptions op = IndicesOptions.fromOptions(true, true, true, false);
request.indicesOptions(op); 

Map<String, Object> settings = new HashMap<>();
settings.put("type", "keyword");
settings.put("script", "emit(doc['host.keyword'].value)");
Map<String, Object> field = new HashMap<>();
field.put("hostname", settings);
request.runtimeMappings(field); 

request.waitForCompletionTimeout(TimeValue.timeValueMinutes(1)); 
request.keepOnCompletion(true); 
request.keepAlive(TimeValue.timeValueHours(12));

Field containing the event classification. Defaults to event.category, as defined in the Elastic Common Schema (ECS).

Maximum number of events to search at a time for sequence queries (defaults to 1000).

For basic queries, the maximum number of matching events to return. For sequence queries, the maximum number of matching sequences to return. Defaults to 10.

Field used to sort hits with the same timestamp in ascending order.

Field containing the event timestamp. Defaults to @timestamp, as defined in the Elastic Common Schema (ECS).

Query, written in Query DSL, used to filter the events on which the EQL query runs.

Set of matching events or sequences to return. Accepts tail (default, return the most recent matches) or head (return the earliest matches).

Array of wildcard (*) patterns. The response returns values for field names matching these patterns in the fields property of each hit.

Value of IndicesOptions specifying various options for resolving indices names. Defaults to ignoreUnavailable = true, allowNoIndices = true, expandToOpenIndices = true, expandToClosedIndices = false.

Defines one or more runtime fields in the search request. These fields take precedence over mapped fields with the same name.

Timeout duration to wait for the request to finish. Defaults to no timeout, meaning the request waits for complete search results. If the request does not complete during this period, the search becomes an async search.

If true, the search and its results are stored on the cluster. If false, the search and its results are stored on the cluster only if the request does not complete during the period set by the waitForCompletionTimeout setting. Defaults to false.

Period for which the search and its results are stored on the cluster. Defaults to 5d (five days). When this period expires, the search and its results are deleted, even if the search is still ongoing. If the keepOnCompletion setting is false, Elasticsearch only stores async searches that do not complete within the period set by the waitForCompletionTimeout setting, regardless of this value.

Response

edit

The returned EqlSearchResponse allows to retrieve information about the executed operation as follows:

EqlSearchResponse response = client.eql().search(request, options);
response.id(); 
response.isPartial(); 
response.isRunning(); 
response.isTimeout(); 
response.took(); 
Hits hits = response.hits(); 
hits.totalHits(); 
List<Event> events = hits.events(); 
List<Sequence> sequences = hits.sequences(); 
Map<String, Object> event = events.get(0).sourceAsMap();
Map<String, DocumentField> fetchField = events.get(0).fetchFields();
fetchField.get("hostname").getValues();

The id of the async search request, null if the response isn’t stored.

true when the response contains partial results.

true when the search is still running.

true when the request timed out before completion.

Milliseconds it took Elasticsearch to execute the request.

Contains matching events and sequences. Also contains related metadata. The response will contain either `Event`s or `Sequence`s, not both, depending on the query.

Metadata about the number of matching events or sequences.

Contains events matching the query. Each object represents a matching event.

Contains event sequences matching the query. Each object represents a matching sequence.

Access the value of a runtime field.
« EQL APIs Using Java Builders »

On this page

Was this helpful?
Feedback