query

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2019 License: MIT Imports: 12 Imported by: 22

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL