rest-layer: github.com/rs/rest-layer/schema/query Index | Files

package query

import "github.com/rs/rest-layer/schema/query"

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

Package Files

predicate.go predicate_parser.go predicate_validator.go projection.go projection_evaluator.go projection_parser.go projection_validator.go query.go resolver.go sort.go utils.go window.go

type And Uses

type And []Expression

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

func (And) Match Uses

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

Match implements Expression interface.

func (And) String Uses

func (e And) String() string

String implements Expression interface.

func (And) Validate Uses

func (e And) Validate(validator schema.Validator) error

Validate implements Expression interface.

type Equal Uses

type Equal struct {
    Field string
    Value Value
}

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

func (Equal) Match Uses

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

Match implements Expression interface.

func (Equal) String Uses

func (e Equal) String() string

String implements Expression interface.

func (Equal) Validate Uses

func (e Equal) Validate(validator schema.Validator) error

Validate implements Expression interface.

type Exist Uses

type Exist struct {
    Field string
}

Exist matches all values which are present, even if nil

func (Exist) Match Uses

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

Match implements Expression interface.

func (Exist) String Uses

func (e Exist) String() string

String implements Expression interface.

func (Exist) Validate Uses

func (e Exist) Validate(validator schema.Validator) error

Validate implements Expression interface.

type Expression Uses

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

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

type GreaterOrEqual Uses

type GreaterOrEqual struct {
    Field string
    Value float64
}

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

func (GreaterOrEqual) Match Uses

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

Match implements Expression interface

func (GreaterOrEqual) String Uses

func (e GreaterOrEqual) String() string

String implements Expression interface.

func (GreaterOrEqual) Validate Uses

func (e GreaterOrEqual) Validate(validator schema.Validator) error

Validate implements Expression interface.

type GreaterThan Uses

type GreaterThan struct {
    Field string
    Value float64
}

GreaterThan matches values that are greater than a specified value.

func (GreaterThan) Match Uses

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

Match implements Expression interface.

func (GreaterThan) String Uses

func (e GreaterThan) String() string

String implements Expression interface.

func (GreaterThan) Validate Uses

func (e GreaterThan) Validate(validator schema.Validator) error

Validate implements Expression interface.

type In Uses

type In struct {
    Field  string
    Values []Value
}

In matches any of the values specified in an array.

func (In) Match Uses

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

Match implements Expression interface.

func (In) String Uses

func (e In) String() string

String implements Expression interface.

func (In) Validate Uses

func (e In) Validate(validator schema.Validator) error

Validate implements Expression interface.

type LowerOrEqual Uses

type LowerOrEqual struct {
    Field string
    Value float64
}

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

func (LowerOrEqual) Match Uses

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

Match implements Expression interface.

func (LowerOrEqual) String Uses

func (e LowerOrEqual) String() string

String implements Expression interface.

func (LowerOrEqual) Validate Uses

func (e LowerOrEqual) Validate(validator schema.Validator) error

Validate implements Expression interface.

type LowerThan Uses

type LowerThan struct {
    Field string
    Value float64
}

LowerThan matches values that are less than a specified value.

func (LowerThan) Match Uses

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

Match implements Expression interface.

func (LowerThan) String Uses

func (e LowerThan) String() string

String implements Expression interface.

func (LowerThan) Validate Uses

func (e LowerThan) Validate(validator schema.Validator) error

Validate implements Expression interface.

type NotEqual Uses

type NotEqual struct {
    Field string
    Value Value
}

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

func (NotEqual) Match Uses

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

Match implements Expression interface.

func (NotEqual) String Uses

func (e NotEqual) String() string

String implements Expression interface.

func (NotEqual) Validate Uses

func (e NotEqual) Validate(validator schema.Validator) error

Validate implements Expression interface.

type NotExist Uses

type NotExist struct {
    Field string
}

NotExist matches all values which are absent

func (NotExist) Match Uses

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

Match implements Expression interface.

func (NotExist) String Uses

func (e NotExist) String() string

String implements Expression interface.

func (NotExist) Validate Uses

func (e NotExist) Validate(validator schema.Validator) error

Validate implements Expression interface.

type NotIn Uses

type NotIn struct {
    Field  string
    Values []Value
}

NotIn matches none of the values specified in an array.

func (NotIn) Match Uses

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

Match implements Expression interface.

func (NotIn) String Uses

func (e NotIn) String() string

String implements Expression interface.

func (NotIn) Validate Uses

func (e NotIn) Validate(validator schema.Validator) error

Validate implements Expression interface.

type Or Uses

type Or []Expression

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

func (Or) Match Uses

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

Match implements Expression interface.

func (Or) String Uses

func (e Or) String() string

String implements Expression interface.

func (Or) Validate Uses

func (e Or) Validate(validator schema.Validator) error

Validate implements Expression interface.

type Predicate Uses

type Predicate []Expression

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

func MustParsePredicate Uses

func MustParsePredicate(query string) Predicate

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

func ParsePredicate Uses

func ParsePredicate(predicate string) (Predicate, error)

ParsePredicate parses a predicate.

func (Predicate) Match Uses

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

Match implements Expression interface.

func (Predicate) String Uses

func (e Predicate) String() string

String implements Expression interface.

func (Predicate) Validate Uses

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

Validate implements Expression interface.

type Projection Uses

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 Uses

func MustParseProjection(projection string) Projection

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

func ParseProjection Uses

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 Uses

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 Uses

func (p Projection) String() string

String output the projection in its DSL form.

func (Projection) Validate Uses

func (p Projection) Validate(validator schema.Validator) error

Validate validates the projection against the provided validator.

type ProjectionField Uses

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 Uses

func (pf ProjectionField) String() string

String output the projection field in its DSL form.

func (ProjectionField) Validate Uses

func (pf ProjectionField) Validate(validator schema.Validator) error

Validate validates the projection field against the provided validator.

type Query Uses

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 Uses

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 Uses

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

Validate validates the query against the provided validator.

type Regex Uses

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

Regex matches values that match to a specified regular expression.

func (Regex) Match Uses

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

Match implements Expression interface.

func (Regex) String Uses

func (e Regex) String() string

String implements Expression interface.

func (Regex) Validate Uses

func (e Regex) Validate(validator schema.Validator) error

Validate implements Expression interface.

type Resource Uses

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
}

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

type Sort Uses

type Sort []SortField

func MustParseSort Uses

func MustParseSort(sort string) Sort

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

func ParseSort Uses

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 Uses

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

Validate validates the sort againast the provided validator.

type SortField Uses

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
}

type Value Uses

type Value interface{}

Value represents any kind of value to use in query.

type Window Uses

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 Uses

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

Page creates a Window using pagination.

Package query imports 12 packages (graph) and is imported by 10 packages. Updated 2017-08-03. Refresh now. Tools for package owners.