Documentation
¶
Overview ¶
Package query parses and checks the list query language (where, order_by) against a collection's schema, producing backend-neutral storage conditions. Client input never reaches the database as-is: only the operators below exist, and every field and value is checked.
Index ¶
- Constants
- func Cursorable(sort []storage.SortField, fields map[string]registry.Field) (ok bool, field string)
- func EncodeCursor(sort []storage.SortField, doc storage.Document) string
- func ParseAggregate(p AggregateParams, f AggregateFields) (q storage.AggregateQuery, err error)
- func ParseCount(s string) (bool, error)
- func ParseCursor(cursor string, sort []storage.SortField, fields map[string]registry.Field) (storage.Filter, error)
- func ParseOrderBy(s string, fields map[string]registry.Field) ([]storage.SortField, error)
- func ParseWhere(where string, fields map[string]registry.Field) (storage.Filter, error)
- func ParseWhereSearch(where string, fields map[string]registry.Field) (storage.Filter, string, error)
- type AggregateFields
- type AggregateParams
- type Error
- type Errors
- type ExpandPath
Constants ¶
const ( MaxWhereBytes = 4096 // size of the raw where parameter MaxConditions = 32 // operator clauses in where MaxTextLen = 256 // value length for text operators MaxLikeWildcards = 4 // % and _ in a $like / $ilike pattern MaxSortFields = 8 // fields in order_by MaxGroupDepth = 4 // nesting of $or / $and groups )
Limits on query complexity.
const ( MaxSearchBytes = 256 MaxSearchTerms = 10 )
MaxSearchBytes and MaxSearchTerms bound the text of a $search.
const DefaultAggregateLimit = 100
DefaultAggregateLimit is the number of groups returned when `limit` isn't given.
const MaxAggregateMetrics = 10
MaxAggregateMetrics is how many metrics one aggregation may ask for.
Variables ¶
This section is empty.
Functions ¶
func Cursorable ¶ added in v0.5.0
Cursorable reports whether a cursor can follow the sort. When it can't, field names the sort field that stops it.
func EncodeCursor ¶ added in v0.5.0
EncodeCursor makes the cursor that continues after doc in this sort. The sort must be Cursorable.
func ParseAggregate ¶ added in v0.8.5
func ParseAggregate(p AggregateParams, f AggregateFields) (q storage.AggregateQuery, err error)
ParseAggregate reads and checks the parameters of an aggregation against the collection's declaration. Every problem found is returned, with the parameter it is about.
func ParseCount ¶
ParseCount parses the count parameter ("", "true" or "false").
func ParseCursor ¶ added in v0.5.0
func ParseCursor(cursor string, sort []storage.SortField, fields map[string]registry.Field) (storage.Filter, error)
ParseCursor checks a cursor against the sort it is used with, and returns the condition that selects the documents after its position. Anything else is reported as an error on the `after` parameter.
func ParseOrderBy ¶
ParseOrderBy parses a comma-separated field list with an optional "-" prefix for descending order. An "id" tiebreaker is appended unless id is already present, so pagination is stable. Empty means creation time, then id: ids chosen by clients (custom ids) have no order of their own.
func ParseWhere ¶
ParseWhere parses the where parameter (a JSON object) into a filter tree: the object's keys combine with AND, and "$or" / "$and" take an array of where objects. An empty string or object means no filter (nil). Keys are processed in sorted order, so the result is deterministic.
func ParseWhereSearch ¶ added in v0.8.5
func ParseWhereSearch(where string, fields map[string]registry.Field) (storage.Filter, string, error)
ParseWhereSearch is ParseWhere for reads that can search: a `$search` at the top level of the object is returned apart from the filter, as the text to search for. It is only allowed at the top level (the database can't combine a text search with alternatives or a negation), and its text is bounded: words, "quoted phrases" and -excluded words, at most MaxSearchBytes bytes and MaxSearchTerms terms.
Types ¶
type AggregateFields ¶ added in v0.8.5
type AggregateFields struct {
GroupBy []string // declared group_by fields
Metrics []string // declared metrics fields
// Date says whether a field is stored as a date, and so can be bucketed (and measured by
// min and max only); Numeric whether it holds numbers (sum and avg).
Date func(field string) bool
Numeric func(field string) bool
// MaxGroups is the instance's and collection's limit on groups.
MaxGroups int
}
AggregateFields tells ParseAggregate what a collection declared in `aggregate:`.
type AggregateParams ¶ added in v0.8.5
type AggregateParams struct {
GroupBy, Metrics, OrderBy, TZ, Limit string
}
AggregateParams are the raw parameters of an aggregate request.
type Errors ¶
type Errors []Error
Errors is returned when a query is invalid; it lists every problem found.
type ExpandPath ¶ added in v0.8.5
type ExpandPath struct {
// Names are the references followed, one per level.
Names []string
// Fields selects what to return of the last document; nil returns it whole.
Fields []string
// Text is the entry as written, for messages.
Text string
}
ExpandPath is one entry of an `expand` parameter: a reference name, or a chain of them (`author.company`) for a second level, with the fields to return of the last document.
func ParseExpand ¶ added in v0.8.5
func ParseExpand(s string) ([]ExpandPath, error)
ParseExpand reads the `expand` parameter: entries separated by commas, each a reference name or a dotted chain of them, optionally followed by the fields to return in parentheses: `author(name,avatar),tags(name),author.company`. An empty value is no entries. Whether the names and fields exist is checked against the collections by the caller; this only reads the syntax.
Source Files