Metadata-Version: 2.4
Name: detection-rules-esql-py
Version: 0.1.0
Summary: Offline ES|QL parser and AST for Elastic Security detection-rules
Author: Elastic
License-Expression: Elastic-2.0
Project-URL: Repository, https://github.com/elastic/detection-rules-esql-py
Project-URL: Issues, https://github.com/elastic/detection-rules-esql-py/issues
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: NOTICE.txt
License-File: licenses/ANTLR4-BSD-3-CLAUSE.txt
License-File: licenses/ELASTIC-LICENSE-2.0.txt
Requires-Dist: antlr4-python3-runtime==4.13.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff==0.16.8; extra == "dev"
Requires-Dist: pip-licenses>=5.0; extra == "dev"
Dynamic: license-file

# detection-rules-esql-py

[![CI](https://github.com/elastic/detection-rules-esql-py/actions/workflows/ci.yml/badge.svg)](https://github.com/elastic/detection-rules-esql-py/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Version](https://img.shields.io/badge/version-0.1.0-green.svg)](pyproject.toml)
[![License](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](LICENSE.txt)

Python parser and AST for [ES|QL](https://www.elastic.co/docs/reference/query-languages/esql), 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](https://github.com/elastic/detection-rules).

## Install

```console
pip install detection-rules-esql-py
```

## Quick start

```python
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

| Doc | Contents |
| --- | --- |
| [docs/maintaining.md](docs/maintaining.md) | Grammar and definitions sync |
| [docs/detection-rules-integration.md](docs/detection-rules-integration.md) | How Elastic Security detection-rules uses the package |
| [CHANGELOG.md](CHANGELOG.md) | Release notes |
| [SUPPORT.md](SUPPORT.md) | How to get help |
| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Elastic Community Code of Conduct |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup and PR checklist |

## Development

```bash
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:

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

Requires [uv](https://docs.astral.sh/uv/) (`brew install uv` or see Astral’s install docs).

## License

Elastic License 2.0 — see [LICENSE.txt](LICENSE.txt).
