Documentation

Overview

    Package query provides tools to query a schema defined by github.com/rs/schema.

    A query is composed of the following elements:

    * Projection to define the format of the response.
    * Predicate to define selection criteria must match to be part of the result
      set.
    * Sort to define the order of the items.
    * Window to limit slice the result set.
    

    The query package provides DLS to describe those elements as strings:

    * Projections uses a subset of GraphQL syntax. See ParseProjection for more
      info.
    * Predicate uses a subset of MongoDB query syntax. See ParsePredicate for more
      info.
    * Sort is a simple list of field separated by comas. See ParseSort for more
      info.
    

    This package is part of the rest-layer project. See http://rest-layer.io for full REST Layer documentation.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    Types

    type And

    type And []Expression

      And joins query clauses with a logical AND, returns all documents that match the conditions of both clauses.

      func (And) Match

      func (e And) Match(payload map[string]interface{}) bool

        Match implements Expression interface.

        func (*And) Prepare

        func (e *And) Prepare(validator schema.Validator) error

          Prepare implements Expression interface.

          func (And) String

          func (e And) String() string

            String implements Expression interface.

            type ElemMatch

            type ElemMatch struct {
            	Field string
            	Exps  []Expression
            }

              ElemMatch matches object values specified in an array.

              func (ElemMatch) Match

              func (e ElemMatch) Match(payload map[string]interface{}) bool

                Match implements Expression interface.

                func (*ElemMatch) Prepare

                func (e *ElemMatch) Prepare(validator schema.Validator) error

                  Prepare implements Expression interface.

                  func (ElemMatch) String

                  func (e ElemMatch) String() string

                    String implements Expression interface.

                    type Equal

                    type Equal struct {
                    	Field string
                    	Value Value
                    }

                      Equal matches all values that are equal to a specified value.

                      func (Equal) Match

                      func (e Equal) Match(payload map[string]interface{}) bool

                        Match implements Expression interface.

                        func (*Equal) Prepare

                        func (e *Equal) Prepare(validator schema.Validator) error

                          Prepare implements Expression interface.

                          func (Equal) String

                          func (e Equal) String() string

                            String implements Expression interface.

                            type Exist

                            type Exist struct {
                            	Field string
                            }

                              Exist matches all values which are present, even if nil

                              func (Exist) Match

                              func (e Exist) Match(payload map[string]interface{}) bool

                                Match implements Expression interface.

                                func (*Exist) Prepare

                                func (e *Exist) Prepare(validator schema.Validator) error

                                  Prepare implements Expression interface.

                                  func (Exist) String

                                  func (e Exist) String() string

                                    String implements Expression interface.

                                    type Expression

                                    type Expression interface {
                                    	Match(payload map[string]interface{}) bool
                                    	Prepare(validator schema.Validator) error
                                    	String() string
                                    }

                                      Expression is a query or query component that can be matched against a payload.

                                      type GreaterOrEqual

                                      type GreaterOrEqual struct {
                                      	Field string
                                      	Value Value
                                      	// contains filtered or unexported fields
                                      }

                                        GreaterOrEqual matches values that are greater than or equal to a specified value.

                                        func (GreaterOrEqual) Match

                                        func (e GreaterOrEqual) Match(payload map[string]interface{}) bool

                                          Match implements Expression interface

                                          func (*GreaterOrEqual) Prepare

                                          func (e *GreaterOrEqual) Prepare(validator schema.Validator) error

                                            Prepare implements Expression interface.

                                            func (GreaterOrEqual) String

                                            func (e GreaterOrEqual) String() string

                                              String implements Expression interface.

                                              type GreaterThan

                                              type GreaterThan struct {
                                              	Field string
                                              	Value Value
                                              	// contains filtered or unexported fields
                                              }

                                                GreaterThan matches values that are greater than a specified value.

                                                func (GreaterThan) Match

                                                func (e GreaterThan) Match(payload map[string]interface{}) bool

                                                  Match implements Expression interface.

                                                  func (*GreaterThan) Prepare

                                                  func (e *GreaterThan) Prepare(validator schema.Validator) error

                                                    Prepare implements Expression interface.

                                                    func (GreaterThan) String

                                                    func (e GreaterThan) String() string

                                                      String implements Expression interface.

                                                      type In

                                                      type In struct {
                                                      	Field  string
                                                      	Values []Value
                                                      }

                                                        In matches any of the values specified in an array.

                                                        func (In) Match

                                                        func (e In) Match(payload map[string]interface{}) bool

                                                          Match implements Expression interface.

                                                          func (*In) Prepare

                                                          func (e *In) Prepare(validator schema.Validator) error

                                                            Prepare implements Expression interface.

                                                            func (In) String

                                                            func (e In) String() string

                                                              String implements Expression interface.

                                                              type LowerOrEqual

                                                              type LowerOrEqual struct {
                                                              	Field string
                                                              	Value Value
                                                              	// contains filtered or unexported fields
                                                              }

                                                                LowerOrEqual matches values that are less than or equal to a specified value.

                                                                func (LowerOrEqual) Match

                                                                func (e LowerOrEqual) Match(payload map[string]interface{}) bool

                                                                  Match implements Expression interface.

                                                                  func (*LowerOrEqual) Prepare

                                                                  func (e *LowerOrEqual) Prepare(validator schema.Validator) error

                                                                    Prepare implements Expression interface.

                                                                    func (LowerOrEqual) String

                                                                    func (e LowerOrEqual) String() string

                                                                      String implements Expression interface.

                                                                      type LowerThan

                                                                      type LowerThan struct {
                                                                      	Field string
                                                                      	Value Value
                                                                      	// contains filtered or unexported fields
                                                                      }

                                                                        LowerThan matches values that are less than a specified value.

                                                                        func (LowerThan) Match

                                                                        func (e LowerThan) Match(payload map[string]interface{}) bool

                                                                          Match implements Expression interface.

                                                                          func (*LowerThan) Prepare

                                                                          func (e *LowerThan) Prepare(validator schema.Validator) error

                                                                            Prepare implements Expression interface.

                                                                            func (LowerThan) String

                                                                            func (e LowerThan) String() string

                                                                              String implements Expression interface.

                                                                              type NotEqual

                                                                              type NotEqual struct {
                                                                              	Field string
                                                                              	Value Value
                                                                              }

                                                                                NotEqual matches all values that are not equal to a specified value.

                                                                                func (NotEqual) Match

                                                                                func (e NotEqual) Match(payload map[string]interface{}) bool

                                                                                  Match implements Expression interface.

                                                                                  func (*NotEqual) Prepare

                                                                                  func (e *NotEqual) Prepare(validator schema.Validator) error

                                                                                    Prepare implements Expression interface.

                                                                                    func (NotEqual) String

                                                                                    func (e NotEqual) String() string

                                                                                      String implements Expression interface.

                                                                                      type NotExist

                                                                                      type NotExist struct {
                                                                                      	Field string
                                                                                      }

                                                                                        NotExist matches all values which are absent

                                                                                        func (NotExist) Match

                                                                                        func (e NotExist) Match(payload map[string]interface{}) bool

                                                                                          Match implements Expression interface.

                                                                                          func (*NotExist) Prepare

                                                                                          func (e *NotExist) Prepare(validator schema.Validator) error

                                                                                            Prepare implements Expression interface.

                                                                                            func (NotExist) String

                                                                                            func (e NotExist) String() string

                                                                                              String implements Expression interface.

                                                                                              type NotIn

                                                                                              type NotIn struct {
                                                                                              	Field  string
                                                                                              	Values []Value
                                                                                              }

                                                                                                NotIn matches none of the values specified in an array.

                                                                                                func (NotIn) Match

                                                                                                func (e NotIn) Match(payload map[string]interface{}) bool

                                                                                                  Match implements Expression interface.

                                                                                                  func (*NotIn) Prepare

                                                                                                  func (e *NotIn) Prepare(validator schema.Validator) error

                                                                                                    Prepare implements Expression interface.

                                                                                                    func (NotIn) String

                                                                                                    func (e NotIn) String() string

                                                                                                      String implements Expression interface.

                                                                                                      type Or

                                                                                                      type Or []Expression

                                                                                                        Or joins query clauses with a logical OR, returns all documents that match the conditions of either clause.

                                                                                                        func (Or) Match

                                                                                                        func (e Or) Match(payload map[string]interface{}) bool

                                                                                                          Match implements Expression interface.

                                                                                                          func (*Or) Prepare

                                                                                                          func (e *Or) Prepare(validator schema.Validator) error

                                                                                                            Prepare implements Expression interface.

                                                                                                            func (Or) String

                                                                                                            func (e Or) String() string

                                                                                                              String implements Expression interface.

                                                                                                              type Predicate

                                                                                                              type Predicate []Expression

                                                                                                                Predicate defines an expression against a schema to perform a match on schema's data.

                                                                                                                func MustParsePredicate

                                                                                                                func MustParsePredicate(query string) Predicate

                                                                                                                  MustParsePredicate parses a predicate expression and panics in case of error.

                                                                                                                  func ParsePredicate

                                                                                                                  func ParsePredicate(predicate string) (Predicate, error)

                                                                                                                    ParsePredicate parses a predicate.

                                                                                                                    func (Predicate) Match

                                                                                                                    func (e Predicate) Match(payload map[string]interface{}) bool

                                                                                                                      Match implements Expression interface.

                                                                                                                      func (Predicate) Prepare

                                                                                                                      func (e Predicate) Prepare(validator schema.Validator) error

                                                                                                                        Prepare implements Expression interface.

                                                                                                                        func (Predicate) String

                                                                                                                        func (e Predicate) String() string

                                                                                                                          String implements Expression interface.

                                                                                                                          type Projection

                                                                                                                          type Projection []ProjectionField

                                                                                                                            Projection defines the list of fields that should be included into the returned payload, and how they should be represented. An empty Projection means all fields with no transformation.

                                                                                                                            func MustParseProjection

                                                                                                                            func MustParseProjection(projection string) Projection

                                                                                                                              MustParseProjection parses a projection expression and panics in case of error.

                                                                                                                              func ParseProjection

                                                                                                                              func ParseProjection(projection string) (Projection, error)

                                                                                                                                ParseProjection recursively parses a projection expression.

                                                                                                                                Projection expression syntax allows to list fields that must be kept in the response hierarchically.

                                                                                                                                A field is an alphanum + - and _ separated by comas:

                                                                                                                                field1,field2

                                                                                                                                When a document has sub-fields, sub-resources or sub-connections, the sub-element's fields can be specified as well by enclosing them between braces:

                                                                                                                                field1{sub-field1,sub-field2},field2

                                                                                                                                Fields can get some some parameters which can be passed to field filters to transform the value. Parameters are passed as key:value pairs enclosed in parenthesizes, with value being either a quotted string or a numerical value:

                                                                                                                                field1(param1:"value", param2:123),field2

                                                                                                                                You can combine field params and sub-field definition:

                                                                                                                                field1(param1:"value", param2:123){sub-field1,sub-field2},field2

                                                                                                                                Or pass params to sub-fields:

                                                                                                                                field1{sub-field1(param1:"value"),sub-field2},field2

                                                                                                                                Fields can also be renamed (aliased). This is useful when you want to have several times the same fields with different sets of parameters. To define aliases, prepend the field definition by the alias name and a colon (:):

                                                                                                                                field:alias

                                                                                                                                With params:

                                                                                                                                thumbnail_small_url:thumbnail_url(size=80),thumbnail_small_url:thumbnail_url(size=500)

                                                                                                                                With this example, the resulted document would be:

                                                                                                                                {
                                                                                                                                  "thumbnail_small_url": "the url with size 80",
                                                                                                                                  "thumbnail_large_url": "the url with size 500",
                                                                                                                                }
                                                                                                                                

                                                                                                                                func (Projection) Eval

                                                                                                                                func (p Projection) Eval(ctx context.Context, payload map[string]interface{}, rsc Resource) (map[string]interface{}, error)

                                                                                                                                  Eval evaluate the projection on the given payload with the help of the validator. The resolver is used to fetch payload of references outside of the provided payload.

                                                                                                                                  func (Projection) String

                                                                                                                                  func (p Projection) String() string

                                                                                                                                    String output the projection in its DSL form.

                                                                                                                                    func (Projection) Validate

                                                                                                                                    func (p Projection) Validate(fg schema.FieldGetter) error

                                                                                                                                      Validate validates the projection against the provided validator.

                                                                                                                                      type ProjectionField

                                                                                                                                      type ProjectionField struct {
                                                                                                                                      	// Name is the name of the field as define in the resource's schema.
                                                                                                                                      	Name string
                                                                                                                                      
                                                                                                                                      	// Alias is the wanted name in the representation.
                                                                                                                                      	Alias string
                                                                                                                                      
                                                                                                                                      	// Params defines a list of params to be sent to the field's param handler
                                                                                                                                      	// if any.
                                                                                                                                      	Params map[string]interface{}
                                                                                                                                      
                                                                                                                                      	// Children holds references to child projections if any.
                                                                                                                                      	Children Projection
                                                                                                                                      }

                                                                                                                                        ProjectionField describes how a field should be represented in the returned payload.

                                                                                                                                        func (ProjectionField) String

                                                                                                                                        func (pf ProjectionField) String() string

                                                                                                                                          String output the projection field in its DSL form.

                                                                                                                                          func (ProjectionField) Validate

                                                                                                                                          func (pf ProjectionField) Validate(fg schema.FieldGetter) error

                                                                                                                                            Validate validates the projection field against the provided validator.

                                                                                                                                            type Query

                                                                                                                                            type Query struct {
                                                                                                                                            	// Projection is the list of fields from the items of the result that should
                                                                                                                                            	// be included in the query response. A projected field can be aliased or
                                                                                                                                            	// given parameters to be passed to per field transformation filters. A
                                                                                                                                            	// projection is hierarchical allow projection of deep structures.
                                                                                                                                            	//
                                                                                                                                            	// A DSL can be used to build the projection structure.
                                                                                                                                            	Projection Projection
                                                                                                                                            
                                                                                                                                            	// Predicate defines the criteria an item must meet in order to be
                                                                                                                                            	// considered for inclusion in the result set.
                                                                                                                                            	//
                                                                                                                                            	// A DLS can be used to build a predicate from a MongoDB like expressions.
                                                                                                                                            	Predicate Predicate
                                                                                                                                            
                                                                                                                                            	// Sort is a list of fields or sub-fields to use for sorting the result set.
                                                                                                                                            	Sort Sort
                                                                                                                                            
                                                                                                                                            	// Window defines result set windowing using an offset and a limit. When
                                                                                                                                            	// nil, the full result-set should be returned.
                                                                                                                                            	Window *Window
                                                                                                                                            }

                                                                                                                                              Query defines the criteria of a query to be applied on a resource validated by a schema.Schema.

                                                                                                                                              func New

                                                                                                                                              func New(projection, predicate, sort string, window *Window) (*Query, error)

                                                                                                                                                New creates a query from a projection, predicate and sort queries using their respective DSL notations. An optional window can be provided.

                                                                                                                                                Example:

                                                                                                                                                New("foo{bar},baz:b", `{baz: "bar"}`, "foo.bar,-baz", Page(1, 10, 0))
                                                                                                                                                

                                                                                                                                                Select items with the foo field equal to bar, including only the foo.bar and baz fields in the result set, with the baz field aliased to b. The result is then sorted by the foo.bar field ascending and baz descending. The result is windowed on page 1 with 10 items per page, skiping no result.

                                                                                                                                                func (*Query) Validate

                                                                                                                                                func (q *Query) Validate(validator schema.Validator) error

                                                                                                                                                  Validate validates the query against the provided validator.

                                                                                                                                                  type Regex

                                                                                                                                                  type Regex struct {
                                                                                                                                                  	Field string
                                                                                                                                                  	Value *regexp.Regexp
                                                                                                                                                  }

                                                                                                                                                    Regex matches values that match to a specified regular expression.

                                                                                                                                                    func (Regex) Match

                                                                                                                                                    func (e Regex) Match(payload map[string]interface{}) bool

                                                                                                                                                      Match implements Expression interface.

                                                                                                                                                      func (*Regex) Prepare

                                                                                                                                                      func (e *Regex) Prepare(validator schema.Validator) error

                                                                                                                                                        Prepare implements Expression interface.

                                                                                                                                                        func (Regex) String

                                                                                                                                                        func (e Regex) String() string

                                                                                                                                                          String implements Expression interface.

                                                                                                                                                          type Resource

                                                                                                                                                          type Resource interface {
                                                                                                                                                          	// Find executes the query and returns the matching items.
                                                                                                                                                          	Find(ctx context.Context, query *Query) ([]map[string]interface{}, error)
                                                                                                                                                          
                                                                                                                                                          	// MultiGet get some items by their id and return them in the same order. If one
                                                                                                                                                          	// or more item(s) is not found, their slot in the response is set to nil.
                                                                                                                                                          	MultiGet(ctx context.Context, ids []interface{}) ([]map[string]interface{}, error)
                                                                                                                                                          
                                                                                                                                                          	// SubResource returns the sub-resource at path. If path starts with a
                                                                                                                                                          	// dot, the lookup is performed relative to the current resource.
                                                                                                                                                          	SubResource(ctx context.Context, path string) (Resource, error)
                                                                                                                                                          
                                                                                                                                                          	// Validator returns the schema.Validator associated with the resource.
                                                                                                                                                          	Validator() schema.Validator
                                                                                                                                                          
                                                                                                                                                          	// Path returns the full path of the resource composed of names of each
                                                                                                                                                          	// intermediate resources separated by dots (i.e.: res1.res2.res3).
                                                                                                                                                          	Path() string
                                                                                                                                                          }

                                                                                                                                                            Resource represents type that can be queried by Projection.Eval.

                                                                                                                                                            type Sort

                                                                                                                                                            type Sort []SortField

                                                                                                                                                              Sort TODO

                                                                                                                                                              func MustParseSort

                                                                                                                                                              func MustParseSort(sort string) Sort

                                                                                                                                                                MustParseSort parses a sort expression and panics in case of error.

                                                                                                                                                                func ParseSort

                                                                                                                                                                func ParseSort(sort string) (Sort, error)

                                                                                                                                                                  ParseSort parses a sort expression. A sort expression is a list of fields separated by comas. A field sort is reverse if preceded by a minus sign (-).

                                                                                                                                                                  func (Sort) Validate

                                                                                                                                                                  func (s Sort) Validate(validator schema.Validator) error

                                                                                                                                                                    Validate validates the sort against the provided validator.

                                                                                                                                                                    type SortField

                                                                                                                                                                    type SortField struct {
                                                                                                                                                                    	// Name is the name of the field to sort on.
                                                                                                                                                                    	Name string
                                                                                                                                                                    
                                                                                                                                                                    	// Reversed instruct to reverse the sorting if set to true.
                                                                                                                                                                    	Reversed bool
                                                                                                                                                                    }

                                                                                                                                                                      SortField TODO

                                                                                                                                                                      type Value

                                                                                                                                                                      type Value = interface{}

                                                                                                                                                                        Value represents any kind of value to use in query.

                                                                                                                                                                        type Window

                                                                                                                                                                        type Window struct {
                                                                                                                                                                        	// Offset is the 0 based index of the item in the result set to start the
                                                                                                                                                                        	// window at.
                                                                                                                                                                        	Offset int
                                                                                                                                                                        
                                                                                                                                                                        	// Limit is the maximum number of items to return in the result set. A value
                                                                                                                                                                        	// lower than 0 means no limit.
                                                                                                                                                                        	Limit int
                                                                                                                                                                        }

                                                                                                                                                                          Window defines a view on the resulting payload.

                                                                                                                                                                          func Page

                                                                                                                                                                          func Page(page, perPage, skip int) *Window

                                                                                                                                                                            Page creates a Window using pagination.