EQL Search API

Request

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 »