tagquery

type Expression interface {
	// Equals takes another expression and compares it against itself. Returns true if they are equal
	// or false otherwise
	Equals(Expression) bool

	// GetDefaultDecision defines what decision should be made if the filter has not come to a conclusive
	// decision based on a single index. When looking at more than one tag index in order of decreasing
	// priority to decide whether a metric should be part of the final result set, some operators and metric
	// combinations can come to a conclusive decision without looking at all indexes and some others can't.
	// if an expression has evaluated a metric against all indexes and has not come to a conclusive
	// decision, then the default decision gets applied.
	//
	// Example using the expression returned by `ParseExpression("anothertag!=value")`
	// metric1 has tags ["name=a.b.c", "some=value"] in the metric tag index
	// 1) expression looks at the metric tag index and it sees that metric1 does not have a tag "anothertag"
	//    with the value "value", but at this point it doesn't know if another index that will be looked
	//    at later does, so it returns the decision "none".
	// 2) expression now looks at index2 and sees again that metric1 does not have the tag and value
	//    it is looking for, so it returns "none" again.
	// 3) the expression execution sees that there are no more indexes left, so it applies the default
	//    decision for the operator != which is "pass", meaning the expression "anothertag!=value" has
	//    not filtered the metric metric1 out of the result set.
	//
	// metric2 has tags ["name=a.b.c", "anothertag=value"] according to the metric tag index and it has
	// no meta tags, we still evaluate the same expression:
	// 1) expression looks at metric tag index and see metric2 has tag "anothertag" with value "value".
	//    it directly comes to a conclusive decision that this metric needs to be filtered out of the
	//    result set and returns the filter decision "fail".
	//
	// metric3 has tags ["name=aaa", "abc=cba"] according to the metric tag index and there is a meta
	// record assigning the tag "anothertag=value" to metrics matching that query expression "abc=cba".
	// 1) expression looks at metric3 and sees it does not have the tag & value it's looking for, so
	//    it returns the filter decision "none" because it cannot know for sure whether another index
	//    will assign "anothertag=value" to metric3.
	// 2) expression looks at the meta tag index and it sees that there are meta records matching the
	//    tag "anothertag" and the value "value", so it retrieves the according filter functions of
	//    of these meta records and passes metric3's tag set into them.
	// 3) the filter function of the meta record for the query set "abc=cba" returns true, indicating
	//    that its meta tag gets applied to metric3.
	// 4) based on that the tag expression comes to the decision that metric3 should not be part of
	//    final result set, so it returns "fail".
	GetDefaultDecision() FilterDecision

	// GetKey returns tag to who's values this expression get's applied to
	// example:
	// in the expression "tag1=value" GetKey() would return "tag1"
	GetKey() string

	// GetValue returns the value part of the expression
	// example:
	// in the expression "abc!=cba" this would return "cba"
	GetValue() string

	// GetOperator returns the operator of this expression
	GetOperator() ExpressionOperator

	// GetOperatorCost returns a value which should roughly reflect the cost of this operator compared
	// to other operators. F.e. = is cheaper than =~. Keep in mind that this is only a very rough
	// estimate and will never be accurate.
	GetOperatorCost() uint32

	// OperatesOnTag returns whether this expression operators on the tag key
	// (if not, it operates on the value).
	// Expressions such has expressionHasTag, expressionMatchTag, expressionPrefixTag would return true,
	// because in order to make a decision regarding whether a metric should be part of the result set
	// they need to look at a metric's tags, as opposed to looking at the values associated with some
	// specified tag.
	// If this returns true, then tags shall be passed into ValuePasses(), other values associated with
	// the tag returned by GetKey() shall be passed into ValuePasses().
	OperatesOnTag() bool

	// RequiresNonEmptyValue returns whether this expression requires a non-empty value.
	// Every valid query must have at least one expression requiring a non-empty value.
	RequiresNonEmptyValue() bool

	// ResultIsSmallerWhenInverted returns a bool indicating whether the result set after evaluating
	// this expression will likely be bigger than half of the tested index entries or smaller.
	// This is never guaranteed to actually be correct, it is only an assumption based on which we
	// can optimize performance.
	// F.e. operators = / =~ / __tag=   would return false
	//      operators != / !=~          would return true
	ResultIsSmallerWhenInverted() bool

	// Matches takes a string which should either be a tag key or value depending on the return
	// value of OperatesOnTag(), then it returns whether the given string satisfies this expression
	Matches(string) bool

	// MatchesExactly returns a bool to indicate whether the key / value of this expression (depending
	// on OperatesOnTag()) needs to be an exact match with the key / value of the metrics it evaluates
	// F.e:
	// in the case of the expression "tag1=value1" we're only looking for metrics where the value
	// associated with tag key "tag1" is exactly "value1", so a simple string comparison is sufficient.
	// in other cases like "tag1=~val.*" or "tag^=val" this isn't the case, a simple string comparison
	// is not sufficient to decide whether a metric should be part of the result set or not.
	// since simple string comparisons are cheaper than other comparison methods, whenever possible we
	// want to use string comparison.
	MatchesExactly() bool

	// GetMetricDefinitionFilter returns a MetricDefinitionFilter
	// The MetricDefinitionFilter takes a metric definition, looks at its tags and returns a decision
	// regarding this query expression applied to its tags
	GetMetricDefinitionFilter(lookup IdTagLookup) MetricDefinitionFilter

	// StringIntoWriter takes a string writer and writes a representation of this expression into it
	StringIntoWriter(writer io.Writer)
}

type ExpressionOperator uint16

type Expressions []Expression

type FilterDecision uint8

type IdTagLookup func(id schema.MKey, tag, value string) bool

type InvalidExpressionError string

type MetaTagRecord struct {
	MetaTags    Tags        `json:"metaTags"`
	Expressions Expressions `json:"expressions"`
}

type MetricDefinitionFilter func(id schema.MKey, name string, tags []string) FilterDecision

type Query struct {
	// clause that operates on LastUpdate field
	From int64

	// slice of expressions sorted by the estimated cost of their operators
	Expressions Expressions
	// contains filtered or unexported fields
}

type Tag struct {
	Key   string
	Value string
}

type Tags []Tag