Loading

ES|QL rules

ES|QL rules use Elasticsearch Query Language (ES|QL) to query source events and aggregate or transform data using a pipeline syntax. Query results are returned as a table where each row becomes an alert. ES|QL rules combine the flexibility of a full query pipeline with the detection capabilities of Elastic Security.

ES|QL rules are the right fit when:

  • You need aggregation, transformation, or enrichment within the query itself, such as computing statistics, renaming fields, or filtering on calculated values.
  • The detection logic requires pipe-based processing that KQL and EQL cannot express, such as STATS...BY followed by WHERE to filter aggregated results.
  • You want to create new computed fields (using EVAL) and alert on values derived from source data rather than raw field values.

ES|QL rules are not the best fit when:

  • A field-value match is sufficient. Use a custom query rule instead.
  • You need to detect ordered event sequences. Use an EQL rule instead.
  • You want anomaly detection without explicit query logic. Use a machine learning rule instead.

ES|QL rules query Elasticsearch indices directly using the FROM command. The indices must be accessible to the user who creates or last edits the rule.

ES|QL rule queries fall into two categories that affect how alerts are generated:

Aggregating queries use STATS...BY to group and count events. Alerts contain only the fields returned by the query plus any new fields created during execution.

FROM logs-*
| STATS host_count = COUNT(host.name) BY host.name
| SORT host_count DESC
| WHERE host_count > 20

This query counts events per host and alerts on hosts with more than 20 events. Use the BY clause with fields you want available for searching and filtering in the Alerts table.

Note

Aggregating queries may create duplicate alerts when events in the additional look-back time are counted in both the current and previous rule execution.

Non-aggregating queries do not use STATS...BY. Alerts contain the returned source event fields, any new fields, and all other fields from the source document.

FROM logs-* METADATA _id, _index, _version
| WHERE event.category == "process" AND event.id == "8a4f500d"
| LIMIT 10

Adding METADATA _id, _index, _version enables alert deduplication. Without it, the same source event can generate duplicate alerts across executions.

For non-aggregating queries, add METADATA _id, _index, _version after the FROM command to enable deduplication:

FROM logs-* METADATA _id, _index, _version
| WHERE event.category == "process"
| LIMIT 50

Ensure you do not DROP or filter out _id, _index, or _version in subsequent pipeline steps, or deduplication fails silently.

  • LIMIT and Max alerts per run interact. The rule uses the lower of the two values. If LIMIT is 200 but Max alerts per run is 100, only 100 alerts are created.
  • Include fields you need in BY clauses. For aggregating queries, only the BY fields appear in alerts. Fields not included are unavailable for filtering or investigation.
  • Sort non-aggregating results by @timestamp ascending when using alert suppression. This ensures proper suppression when the alert count exceeds Max alerts per run.

If your ES|QL query creates new fields that are not part of the ECS schema, they are not mapped to the alerts index. You cannot search for or filter them in the Alerts table. As a workaround, create runtime fields.

When configuring an ES|QL rule's Custom highlighted fields (in advanced settings), you can specify any fields that the query returns. This ensures returned fields are visible in the alert details flyout during investigation.

Tip

See it in practice. These patterns demonstrate ES|QL detection use cases:

  • High event count per host. An aggregating query that groups by host.name and fires when a host exceeds a threshold count. Useful for detecting noisy hosts or denial-of-service patterns.
  • Process execution with computed risk. A non-aggregating query with EVAL that computes a custom risk score from multiple fields, alerting only when the computed score exceeds a threshold.

The following settings are specific to ES|QL rules. For settings shared across all rule types, refer to Rule settings reference.

ES|QL query
The ES|QL query that defines the detection logic. Can be aggregating (with STATS...BY) or non-aggregating. Each row in the query result becomes an alert.
Suppress alerts by (optional)
Reduce repeated or duplicate alerts by grouping them on one or more fields. For details, refer to Alert suppression.
Required fields (optional)
An informational list of fields the rule needs to function. This does not affect rule execution.
Related integrations (optional)
Associate the rule with one or more Elastic integrations to indicate data dependencies and allow users to verify each integration's installation status.