detection-rules-esql-py

Python parser and AST for ES|QL, Elasticsearch’s piped query language.

detection-rules-esql-py parses and checks ES|QL offline — syntax, stack-version feature gates, nested KQL() / EQL(), schema and type checks, and helpers for fields, sources, and rule shape — without sending the query to a cluster.

Elastic Security uses it to validate detection-rules.

Install

pip install detection-rules-esql-py

Quick start

import esql

# Prefer a Python triple-quoted string so ES|QL "..." values need no \" escapes.
tree = esql.parse_query("""
FROM logs-* METADATA _id, _version, _index
| WHERE event.category == "process"
| KEEP @timestamp, host.name, _id, _version, _index
""")
print(esql.get_from_sources(tree))
print(esql.get_unique_fields(tree))

# When the ES|QL string itself contains quotes, use ES|QL's """ delimiter
# (wrap the Python string in '''...''' so the delimiters do not collide):
tree = esql.parse_query('''ROW name = """Indiana "Indy" Jones"""''')

Documentation

Development

git clone git@github.com:elastic/detection-rules-esql-py.git
cd detection-rules-esql-py
uv sync                 # creates .venv + installs package + ruff/pytest
make ci                 # lint + check-generated + test

Grammar maintenance:

make update-window      # sync + generate + check-generated
make ci

Requires uv (brew install uv or see Astral’s install docs).

License

Elastic License 2.0 — see LICENSE.txt.