A pure-MoonBit PromQL parser and query engine for in-memory time-series data

promql

prometheus

metrics

timeseries

query-engine

Download zip

Author

Santa968

Version

0.1.0

License

Apache-2.0

Repository

github.com/Santa968/MoonPromQL

Last updated

yesterday

Downloads

#MoonPromQL

MoonPromQL is a pure-MoonBit parser and query engine for a practical subset of PromQL. It is designed for embedded analytics, deterministic tests, edge workloads, and MoonBit applications that already have time-series data in memory.

The project does not implement a Prometheus server, TSDB, scraper, remote read/write, alerting rules, or recording rules. Its scope is the query language and its in-memory evaluation semantics.

#Features

Metric selectors and label matchers: =, !=, =~, !~.
Instant and range selectors.
Range selectors, offset, and @ timestamps.
Arithmetic and comparison operators.
and, or, and unless.
Aggregations: sum, avg, min, max, count, topk, bottomk.
by and without aggregation grouping.
Vector matching: on, ignoring, group_left, group_right.
Counter functions: rate, irate, increase, delta, idelta.
Range functions: avg_over_time, min_over_time, max_over_time, sum_over_time, count_over_time, last_over_time.
Math functions: abs, ceil, floor, round, clamp, clamp_min, clamp_max.
Utility functions: sort, sort_desc, label_join, label_replace.
Deterministic label ordering and JSON-compatible sample data.
Runs on wasm, wasm-gc, js, and native targets.

#Installation

The module is published on Mooncakes as Santa968/moonpromql:

moon add Santa968/moonpromql

#Quick Start

///|
fn main {
  let series = [
    @model.Series::new(
      "http_requests_total",
      @model.LabelSet::new([("job", "api")]),
      [{ timestamp: 0.0, value: 10.0, }, { timestamp: 60000.0, value: 20.0, }],
    ),
  ]
  let context = @eval.EvalContext::new(series, 60000.0)
  let result = @eval.query("rate(http_requests_total[2m])", context)
  println(result.to_string())
}

In a real project, import the packages in moon.pkg:

import {
  "Santa968/moonpromql/eval" @eval,
  "Santa968/moonpromql/model" @model,
}

#CLI

List commands:

moon run cmd/moonpromql -- help

Parse a query:

moon run cmd/moonpromql -- parse "sum by (job) (rate(http_requests_total[5m]))"

Evaluate a query against the built-in deterministic demo data:

moon run cmd/moonpromql -- eval "rate(http_requests_total[5m])" --at 300000

The demo data contains two http_requests_total series with job="api" and different instance labels.

Evaluate a JSON fixture:

moon run cmd/moonpromql -- eval-json "up > 0" "[{\"metric\":\"up\",\"labels\":{\"job\":\"api\"},\"samples\":[{\"timestamp\":0,\"value\":1}]}]" --at 0

Run the standalone library example:

moon run examples/basic

#Package Layout

Package	Responsibility
model	Labels, samples, series, vectors, values, and shared errors
ast	Parsed PromQL expression tree
lexer	Tokenizer
parser	Parsed expression construction
eval	Selector, binary, aggregation, and range evaluation
functions	PromQL function implementations
adapters/json	JSON time-series fixture adapter
cmd/moonpromql	Runnable demonstration CLI

#Compatibility Notes

The initial release intentionally targets a deterministic subset of PromQL. The main differences from the upstream Prometheus implementation are:

Native histograms, experimental functions, and subqueries are not yet implemented.
Counter extrapolation follows a simpler deterministic model than Prometheus.
Duplicate vector-matching series are resolved deterministically rather than reporting every upstream collision case.
Regular expressions use MoonBit's core regex syntax. Common RE2 patterns work, but \d, \w, and \s shorthand classes should be written using POSIX classes such as [[:digit:]].

Unsupported syntax fails with a positioned parse or evaluation error instead of silently returning a value.

Timestamps in fixtures, EvalContext, CLI --at, and currently the query @ modifier are milliseconds. Upstream PromQL uses seconds for @; this is a known compatibility difference. Range intervals are left-open and right-closed. Parser error positions currently use token indexes, not source line/column. Compound durations and explicit stale markers are not supported yet. The CLI currently accepts inline JSON and prints a human-readable result; file input and structured JSON output remain release work. CLI errors terminate with a nonzero exit status through the runtime error handler.

#Verification status

Validated with MoonBit 0.1.20260915. moon fmt --check, moon check --deny-warn--target all, moon build --target all, and moon test --deny-warn --targetall all pass, with 25 tests green on each of wasm, wasm-gc, js, and native.

CI runs the same checks on Linux, macOS, and Windows, and all three matrix jobs pass on the current commit.

#Sources

Semantic reference: Prometheus query documentation and operators. MoonPromQL is an independent MoonBit implementation. Runtime and library dependencies are MoonBit core packages.

#Development

Run the full local verification:

moon fmt --check
moon check --deny-warn --target all
moon test --deny-warn --target all
moon build --target all

#License

Apache-2.0. See LICENSE.

EvalContext

source

using @Santa968/moonpromql/eval { type EvalContext }

Expr

source

using @Santa968/moonpromql/ast { type Expr }

LabelSet

source

using @Santa968/moonpromql/model { type LabelSet }

Stable public facade for MoonPromQL.

Prefer importing subpackages directly when a smaller dependency surface is useful. The root package re-exports the core types and entry points.

Point

source

using @Santa968/moonpromql/model { type Point }

Stable public facade for MoonPromQL.

Prefer importing subpackages directly when a smaller dependency surface is useful. The root package re-exports the core types and entry points.

RangeSeries

source

using @Santa968/moonpromql/model { type RangeSeries }

Stable public facade for MoonPromQL.

Prefer importing subpackages directly when a smaller dependency surface is useful. The root package re-exports the core types and entry points.

Sample

source

using @Santa968/moonpromql/model { type Sample }

Stable public facade for MoonPromQL.

Prefer importing subpackages directly when a smaller dependency surface is useful. The root package re-exports the core types and entry points.

Selector

source

using @Santa968/moonpromql/ast { type Selector }

Series

source

using @Santa968/moonpromql/model { type Series }

Stable public facade for MoonPromQL.

Prefer importing subpackages directly when a smaller dependency surface is useful. The root package re-exports the core types and entry points.

Value

source

using @Santa968/moonpromql/model { type Value }

Stable public facade for MoonPromQL.

Prefer importing subpackages directly when a smaller dependency surface is useful. The root package re-exports the core types and entry points.

evaluate

source

fn evaluate(expression : @Santa968/moonpromql/ast.Expr
Expr, context : @Santa968/moonpromql/eval.EvalContext
EvalContext) -> @Santa968/moonpromql/model.Value
Value raise @Santa968/moonpromql/model.PromqlError
PromqlError

parse

source

fn parse(input : StringView) -> @Santa968/moonpromql/ast.Expr
Expr raise @Santa968/moonpromql/model.PromqlError
PromqlError

Parse a PromQL expression into an AST.

parse_series

source

fn parse_series(input : StringView) -> Array[@Santa968/moonpromql/model.Series
Series] raise @Santa968/moonpromql/model.PromqlError
PromqlError

Parse time-series fixtures from a JSON array.

query

source

fn query(input : StringView, context : @Santa968/moonpromql/eval.EvalContext
EvalContext) -> @Santa968/moonpromql/model.Value
Value raise @Santa968/moonpromql/model.PromqlError
PromqlError

Parse and evaluate one PromQL query.

Source Files

moonpromql.mbt

Site source Report issue Packages Build queue Skills Statistics

moonpromql

#MoonPromQL

#Features

#Installation

#Quick Start

#CLI

#Package Layout

#Compatibility Notes

#Verification status

#Sources

#Development

#License

#EvalContext

#Expr

#LabelSet

#Point

#RangeSeries

#Sample

#Selector

#Series

#Value

#evaluate

#parse

#parse_series

#query

Source Files

EvalContext

Expr

LabelSet

Point

RangeSeries

Sample

Selector

Series

Value

evaluate

parse

parse_series

query