query

Documentation

Overview

Package query provides tools for searching over structured keys.

One example of such a structured key is a Trace id. A key is simply a string, but with a very specific format. The parameters are serialized so that the parameter names appear in alphabetical order, and each name=value pair is delimited by a comma. For example, this map:

a := map[string]string{"d": "w", "a": "b", "c": "d"}

Would be serialized as this key:

,a=b,c=d,d=w,

Structured keys are a serialization of a map[string]string, so duplicate parameter names are not allowed.

Structured key parameter names and values are restricted to the following chars:

[a-zA-Z0-9._-]

Index

• Variables
• func ForceValid(m map[string]string) map[string]string
• func ForceValidWithRegex(m map[string]string, regexp *regexp.Regexp) map[string]string
• func IsValid(key string) bool
• func MakeKey(m map[string]string) (string, error)
• func MakeKeyFast(m map[string]string) (string, error)
• func ParseKey(key string) (map[string]string, error)
• func ParseKeyFast(key string) (map[string]string, error)
• func ValidateParamSet(ps paramtools.ParamSet) error
• type Query
  • func New(q url.Values) (*Query, error)
  • func NewFromString(s string) (*Query, error)
  • func (q *Query) Empty() bool
  • func (q *Query) Matches(s string) bool
  • func (q *Query) QueryPlan(ps paramtools.ReadOnlyParamSet) (paramtools.ParamSet, error)
  • func (q *Query) String() string

Variables

var (
	InvalidChar = regexp.MustCompile(`([^a-zA-Z0-9\._\-])`)

	QueryWillNeverMatch = errors.New("Query will never match.")
)

Functions

func ForceValid

func ForceValid(m map[string]string) map[string]string

ForceValid ensures that the resulting map will make a valid structured key.

func ForceValidWithRegex

func ForceValidWithRegex(m map[string]string, regexp *regexp.Regexp) map[string]string

ForceValidWithRegex ensures that the resulting map will make a valid structured key with the given regex.

func IsValid

func IsValid(key string) bool

IsValid returns true if a key is valid, i.e. if the parameter names are in alphabetical order and if the param names and values are restricted to valid values.

func MakeKey

func MakeKey(m map[string]string) (string, error)

MakeKey returns a structured key from the given map[string]string, or a non-nil error if the parameter names or values violate the structured key restrictions.

func MakeKeyFast

func MakeKeyFast(m map[string]string) (string, error)

MakeKeyFast returns a structured key from the given map[string]string. It does no validation on names or values. This is important if you are making keys from a large number of go routines, as regexp doesn't handle that case very well. See https://github.com/golang/go/issues/8232.

func ParseKey

func ParseKey(key string) (map[string]string, error)

ParseKey parses the structured key, and if valid, returns the parsed values as a map[string]string, otherwise is returns a non-nil error.

func ParseKeyFast

func ParseKeyFast(key string) (map[string]string, error)

ParseKeyFast is like ParseKey but omits much of the validation portions

func ValidateParamSet

func ValidateParamSet(ps paramtools.ParamSet) error

ValidateParamSet validates that all the keys and values in a ParamSet are restricted to the right subset of characters.

Types

type Query

type Query struct {
	// contains filtered or unexported fields
}

Query represents a query against a key, i.e. Query.Matches can return true or false if a given key matches the query. For example, this query will find all keys that have a value of 565 for 'config' and true for 'debug':

q := New(url.Values{"config": []string{"565"}, "debug": []string{"true"}})

This will find all keys that have a value of '565' or '8888':

q := New(url.Values{"config": []string{"565", "8888"}})

If the first parameter value is preceeded with an '!' then the match is negated, i.e. this query will match all keys that have a 'config' param, but whose value is not '565'.

q := New(url.Values{"config": []string{"!565"}})

If the parameter value is '*' then the match will match all keys that have that parameter name. I.e. this will match all keys that have a parameter named 'config', regardless of the value:

q := New(url.Values{"config": []string{"*"}})

If the parameter value begins with '~' then the rest of the value is interpreted as a regular expression. I.e. this will match all keys that have a parameter named 'arch' that begin with 'x':

q := New(url.Values{"arch": []string{"~^x"}})

Here is more complex example that matches all tests that have the 'name' parameter with a value of 'desk_nytimes.skp', a 'config' param that does not equal '565' or '8888', and has an 'extra_config' parameter of any value.

	  q := New(url.Values{
       "name": "desk_nytimes.skp",
       "config": []string{"!565", "8888"},
       "extra_config": []string{"*"}})

func New

func New(q url.Values) (*Query, error)

New creates a Query from the given url.Values. It represents a query to be used against keys.

func NewFromString

func NewFromString(s string) (*Query, error)

NewFromString creates a Query from the given string, which is formatted as a URL query.

func (*Query) Empty

func (q *Query) Empty() bool

Empty returns true of the Query is empty, i.e. it will match any trace.

func (*Query) Matches

func (q *Query) Matches(s string) bool

Matches returns true if the given structured key matches the query.

func (*Query) QueryPlan

func (q *Query) QueryPlan(ps paramtools.ReadOnlyParamSet) (paramtools.ParamSet, error)

QueryPlan returns a paramtools.ParamSet that can be used run a query using trace indices.

That is, if you have a Params:

Params{"config":"8888", "arch":"x86"}

And a ParamSet:

ps := &paramtools.ParamSet{
	ParamSet: paramtools.ParamSet{
	  "config": []string{"565", "8888", "gpu"},
	  "arch":   []string{"x86", "arm", "riscv"},
	  "foo":    []string{"bar"},
	},
}

It would return the ParamSet:

ParamSet{
  "config": ["8888"],
  "arch":   ["x86"],
}

Then a query of the form:

url.Values{"arch": []string{"x86", "risc-v"}, "config": []string{"*"}}

Would return:

ParamSet{
  "arch": ["x86", "risc-v"],
  "config": ["8888", "565", "gpu"],
}

func (*Query) String

func (q *Query) String() string

String returns a minimal string representation of the Query.