Loading

Create an ES|QL rule in the experimental alerting system

Creating an ES|QL rule lets you write the detection query directly instead of going through the rule builder's structured inputs.

To create a rule, go to Alerting V2 Preview in the navigation menu or global search, then go to Rules. When choosing a creation path, select the one that lets you write ES|QL directly.

Once you're in that flow, there are two ways to define the rule:

  • Rule form - Fill in the step-by-step form with a live preview of results. For details on configurable rule settings and guidance on how to configure them, refer to Configure a rule.
  • YAML editor - Edit the raw rule definition directly instead of using the form. You can switch between form and YAML at any time. Invalid YAML that can't be translated to a valid form state locks you into the YAML editor until it's fixed. For a list of supported YAML fields, refer to YAML rule schema reference.
Note

Rule form and YAML editor are the names used in this documentation, not necessarily exact UI labels. Look for the equivalent options when creating or editing a rule.

The query sandbox lets you run your ES|QL query against current data and preview the results before applying them to the rule form. Use the time field selector and date picker to control the time range, then select Search (or press ⌘↵) to execute. When the results look correct, select Apply changes to populate the form.

Note

In the query sandbox, the time field selector and date picker control the query results only. They do not set the rule's schedule or lookback period.

Use the sandbox to:

  • Confirm grouping - Check that your BY clause produces the series you intend, for example, one distinct series per host or per service, not a single undifferentiated result.
  • Catch unexpected output - Verify that the query returns data in the right shape for the alert condition you plan to set. A query that returns zero rows or an unexpected field name won't behave as expected once the rule runs on a schedule.
  • Refine before committing - Edit the query and re-run it as many times as needed without leaving the rule creation form.

While the sandbox is open, switching between rule form and YAML or between rule modes (Alert and Signal) is not available. Close the sandbox first if you need to change authoring mode.

By default, applying changes in the sandbox automatically splits your query into a base query and alert condition. If you want full manual control over the split, use the toggle in the sandbox to switch to separate Base and Alert editors. If auto-split fails, a callout on the alert condition step lets you open the sandbox directly in manual split mode. For what each part of the split does, refer to ES|QL query.

  • Create a rule: Compare this creation path with the others.
  • ES|QL query patterns: Query examples ranging from a basic event filter to SLO burn rate and persistent breach detection.