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: 25

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.