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
Constants ¶
This section is empty.
Variables ¶
var ( InvalidChar = regexp.MustCompile(`([^a-zA-Z0-9\._\-])`) QueryWillNeverMatch = errors.New("Query will never match.") )
Functions ¶
func ForceValid ¶
ForceValid ensures that the resulting map will make a valid structured key.
func ForceValidWithRegex ¶
ForceValidWithRegex ensures that the resulting map will make a valid structured key with the given regex.
func IsValid ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
New creates a Query from the given url.Values. It represents a query to be used against keys.
func NewFromString ¶
NewFromString creates a Query from the given string, which is formatted as a URL 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 := ¶mtools.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"],
}
Source Files