README
¶
PromQL Module
The PromQL module in this package is a pruned version of the native Prometheus promql package, but extracted into a single module with fewer dependencies.
This module removes the promql engine and keeps anything related to lexing and parsing the PromQL language.
Each version of this module matches with the equivalent Prometheus version.
Example
The PromQL module can be used to parse an expression.
package main
import (
"fmt"
"github.com/influxdata/promql/v2"
)
var myExpression = `http_requests_total{job="prometheus"}[5m]`
func main() {
expr, err := promql.ParseExpr(myExpression)
if err != nil {
panic(err)
}
fmt.Println(promql.Tree(expr))
}
Contributing
Any changes to PromQL should not be made to this module as it is a pruned mirror of the original prometheus package. Changes should be submitted to the upstream Prometheus project and they will find their way into this repository when a new release happens.
The only changes that will be accepted into this repository are ones that fix a problem in the mirroring process, deviations from the upstream Prometheus, or operational changes to fulfill the primary purpose of this repository as a mirror of the promql package.
Documentation
¶
Index ¶
- Constants
- func Inspect(node Node, f inspector)
- func ParseMetric(input string) (m labels.Labels, err error)
- func ParseMetricSelector(input string) (m []*labels.Matcher, err error)
- func Tree(node Node) string
- func Walk(v Visitor, node Node, path []Node) error
- type AggregateExpr
- type BinaryExpr
- type Call
- type EvalStmt
- type Expr
- type Expressions
- type Function
- type ItemType
- type Matrix
- type MatrixSelector
- type Node
- type NumberLiteral
- type ParenExpr
- type ParseErr
- type Point
- type Pos
- type Sample
- type Scalar
- type Series
- type Statement
- type String
- type StringLiteral
- type SubqueryExpr
- type UnaryExpr
- type Value
- type ValueType
- type Vector
- type VectorMatchCardinality
- type VectorMatching
- type VectorSelector
- type Visitor
Constants ¶
const ( ValueTypeNone = "none" ValueTypeVector = "vector" ValueTypeScalar = "scalar" ValueTypeMatrix = "matrix" ValueTypeString = "string" )
The valid value types.
const LowestPrec = 0 // Non-operators.
LowestPrec is a constant for operator precedence in expressions.
Variables ¶
This section is empty.
Functions ¶
func Inspect ¶
func Inspect(node Node, f inspector)
Inspect traverses an AST in depth-first order: It starts by calling f(node, path); node must not be nil. If f returns a nil error, Inspect invokes f for all the non-nil children of node, recursively.
func ParseMetric ¶
ParseMetric parses the input into a metric
func ParseMetricSelector ¶
ParseMetricSelector parses the provided textual metric selector into a list of label matchers.
func Walk ¶
Walk traverses an AST in depth-first order: It starts by calling v.Visit(node, path); node must not be nil. If the visitor w returned by v.Visit(node, path) is not nil and the visitor returns no error, Walk is invoked recursively with visitor w for each of the non-nil children of node, followed by a call of w.Visit(nil), returning an error As the tree is descended the path of previous nodes is provided.
Types ¶
type AggregateExpr ¶
type AggregateExpr struct {
Op ItemType // The used aggregation operation.
Expr Expr // The Vector expression over which is aggregated.
Param Expr // Parameter used by some aggregators.
Grouping []string // The labels by which to group the Vector.
Without bool // Whether to drop the given labels rather than keep them.
}
AggregateExpr represents an aggregation operation on a Vector.
func (*AggregateExpr) String ¶
func (node *AggregateExpr) String() string
func (*AggregateExpr) Type ¶
func (e *AggregateExpr) Type() ValueType
type BinaryExpr ¶
type BinaryExpr struct {
Op ItemType // The operation of the expression.
LHS, RHS Expr // The operands on the respective sides of the operator.
// The matching behavior for the operation if both operands are Vectors.
// If they are not this field is nil.
VectorMatching *VectorMatching
// If a comparison operator, return 0/1 rather than filtering.
ReturnBool bool
}
BinaryExpr represents a binary expression between two child expressions.
func (*BinaryExpr) String ¶
func (node *BinaryExpr) String() string
func (*BinaryExpr) Type ¶
func (e *BinaryExpr) Type() ValueType
type Call ¶
type Call struct {
Func *Function // The function that was called.
Args Expressions // Arguments used in the call.
}
Call represents a function call.
type EvalStmt ¶
type EvalStmt struct {
Expr Expr // Expression to be evaluated.
// The time boundaries for the evaluation. If Start equals End an instant
// is evaluated.
Start, End time.Time
// Time between two evaluated instants for the range [Start:End].
Interval time.Duration
}
EvalStmt holds an expression and information on the range it should be evaluated on.
type Expr ¶
type Expr interface {
Node
// Type returns the type the expression evaluates to. It does not perform
// in-depth checks as this is done at parsing-time.
Type() ValueType
// contains filtered or unexported methods
}
Expr is a generic interface for all expression types.
type Expressions ¶
type Expressions []Expr
Expressions is a list of expression nodes that implements Node.
func (Expressions) String ¶
func (es Expressions) String() (s string)
type Function ¶
Function represents a function of the expression language and is used by function nodes.
type ItemType ¶
type ItemType int
const ( ItemError ItemType = iota // Error occurred, value is error message ItemEOF ItemComment ItemIdentifier ItemMetricIdentifier ItemLeftParen ItemRightParen ItemLeftBrace ItemRightBrace ItemLeftBracket ItemRightBracket ItemComma ItemAssign ItemColon ItemSemicolon ItemString ItemNumber ItemDuration ItemBlank ItemTimes ItemSpace // Operators. ItemSUB ItemADD ItemMUL ItemMOD ItemDIV ItemLAND ItemLOR ItemLUnless ItemEQL ItemNEQ ItemLTE ItemLSS ItemGTE ItemGTR ItemEQLRegex ItemNEQRegex ItemPOW // Aggregators. ItemAvg ItemCount ItemSum ItemMin ItemMax ItemStddev ItemStdvar ItemTopK ItemBottomK ItemCountValues ItemQuantile // Keywords. ItemOffset ItemBy ItemWithout ItemOn ItemIgnoring ItemGroupLeft ItemGroupRight ItemBool )
type Matrix ¶
type Matrix []Series
Matrix is a slice of Series that implements sort.Interface and has a String method.
func (Matrix) ContainsSameLabelset ¶
ContainsSameLabelset checks if a matrix has samples with the same labelset Such a behavior is semantically undefined https://github.com/prometheus/prometheus/issues/4562
func (Matrix) TotalSamples ¶
TotalSamples returns the total number of samples in the series within a matrix.
type MatrixSelector ¶
type MatrixSelector struct {
Name string
Range time.Duration
Offset time.Duration
LabelMatchers []*labels.Matcher
}
MatrixSelector represents a Matrix selection.
func (*MatrixSelector) String ¶
func (node *MatrixSelector) String() string
func (*MatrixSelector) Type ¶
func (e *MatrixSelector) Type() ValueType
type Node ¶
type Node interface {
// String representation of the node that returns the given node when parsed
// as part of a valid query.
String() string
}
Node is a generic interface for all nodes in an AST.
Whenever numerous nodes are listed such as in a switch-case statement or a chain of function definitions (e.g. String(), expr(), etc.) convention is to list them as follows:
- Statements
- statement types (alphabetical)
- ...
- Expressions
- expression types (alphabetical)
- ...
type NumberLiteral ¶
type NumberLiteral struct {
Val float64
}
NumberLiteral represents a number.
func (*NumberLiteral) String ¶
func (node *NumberLiteral) String() string
func (*NumberLiteral) Type ¶
func (e *NumberLiteral) Type() ValueType
type ParenExpr ¶
type ParenExpr struct {
Expr Expr
}
ParenExpr wraps an expression so it cannot be disassembled as a consequence of operator precedence.
type ParseErr ¶
ParseErr wraps a parsing error with line and position context. If the parsing input was a single line, line will be 0 and omitted from the error string.
type Point ¶
Point represents a single data point for a given timestamp.
func (Point) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
type Scalar ¶
Scalar is a data point that's explicitly not associated with a metric.
func (Scalar) MarshalJSON ¶
type Statement ¶
type Statement interface {
Node
// contains filtered or unexported methods
}
Statement is a generic interface for all statements.
type StringLiteral ¶
type StringLiteral struct {
Val string
}
StringLiteral represents a string.
func (*StringLiteral) String ¶
func (node *StringLiteral) String() string
func (*StringLiteral) Type ¶
func (e *StringLiteral) Type() ValueType
type SubqueryExpr ¶
SubqueryExpr represents a subquery.
func (*SubqueryExpr) String ¶
func (node *SubqueryExpr) String() string
func (*SubqueryExpr) Type ¶
func (e *SubqueryExpr) Type() ValueType
type UnaryExpr ¶
UnaryExpr represents a unary operation on another expression. Currently unary operations are only supported for Scalars.
type Vector ¶
type Vector []Sample
Vector is basically only an alias for model.Samples, but the contract is that in a Vector, all Samples have the same timestamp.
func (Vector) ContainsSameLabelset ¶
ContainsSameLabelset checks if a vector has samples with the same labelset Such a behavior is semantically undefined https://github.com/prometheus/prometheus/issues/4562
type VectorMatchCardinality ¶
type VectorMatchCardinality int
VectorMatchCardinality describes the cardinality relationship of two Vectors in a binary operation.
const ( CardOneToOne VectorMatchCardinality = iota CardManyToOne CardOneToMany CardManyToMany )
func (VectorMatchCardinality) String ¶
func (vmc VectorMatchCardinality) String() string
type VectorMatching ¶
type VectorMatching struct {
// The cardinality of the two Vectors.
Card VectorMatchCardinality
// MatchingLabels contains the labels which define equality of a pair of
// elements from the Vectors.
MatchingLabels []string
// On includes the given label names from matching,
// rather than excluding them.
On bool
// Include contains additional labels that should be included in
// the result from the side with the lower cardinality.
Include []string
}
VectorMatching describes how elements from two Vectors in a binary operation are supposed to be matched.
type VectorSelector ¶
VectorSelector represents a Vector selection.
func (*VectorSelector) String ¶
func (node *VectorSelector) String() string
func (*VectorSelector) Type ¶
func (e *VectorSelector) Type() ValueType
type Visitor ¶
Visitor allows visiting a Node and its child nodes. The Visit method is invoked for each node with the path leading to the node provided additionally. If the result visitor w is not nil and no error, Walk visits each of the children of node with the visitor w, followed by a call of w.Visit(nil, nil).
Source Files
Directories