PromQL Parser for Python

0.8.0 · active · verified Tue Apr 14

promql-parser is a Python binding that provides a fast and robust PromQL (Prometheus Query Language) parser. It leverages a Rust-based parser for efficient conversion of PromQL queries into an Abstract Syntax Tree (AST), enabling programmatic analysis and manipulation of Prometheus queries. The current version is 0.8.0, with releases typically following updates to the underlying Rust parser.

Warnings

breaking The underlying Rust parser declares compatibility with a specific Prometheus PromQL version (e.g., v3.8 as of March 2026). Future changes to the PromQL syntax in newer Prometheus versions may lead to parsing errors or unexpected AST structures without a corresponding update to `promql-parser`.
Fix: Monitor the `messense/py-promql-parser` and `GreptimeTeam/promql-parser` GitHub repositories for updates and release notes to ensure compatibility with the PromQL version you are using. Upgrade `promql-parser` promptly when new versions are released to maintain parsing accuracy for evolving PromQL syntax.
gotcha The output of the `parse` function is an Abstract Syntax Tree (AST), which is a complex nested object structure. Understanding the exact shape of the AST for different PromQL queries requires familiarity with PromQL grammar and the parser's internal representation.
Fix: Inspect the `print(ast)` output for various query types to understand its structure. Refer to the `GreptimeTeam/promql-parser` documentation (Rust library) for details on the AST node types if deep programmatic manipulation is required, as the Python binding directly exposes this underlying structure.

Install

pip install promql-parser Install via pip

Imports

parse
```
from promql_parser import parse
```

Quickstart

Parse a PromQL query string into its Abstract Syntax Tree (AST) representation. The returned AST is a Python object that mirrors the structure of the PromQL query, allowing for detailed inspection of metric names, labels, functions, and operators.

from promql_parser import parse

query = 'rate(http_requests_total{code="200", job="prometheus"}[5m])'
ast = parse(query)
print(ast)
# Example of accessing AST components (exact structure depends on query)
# print(ast.expr.name) # For a VectorSelector, might access name
# print(ast.expr.matchers.matchers[0].name) # Accessing a matcher's name

view raw JSON →