query

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: May 19, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package query is the search Query DSL — filter operators, sort expressions, sparse fieldsets, includes, and pagination styles — shared by every REST + gRPC list endpoint in go/kit.

Index

Constants

View Source 
const (
	FieldNameQuery      = "query"
	FieldNamePagination = "pagination"
	FieldNameSorting    = "sorting"
	FieldNameIncludes   = "includes"
)

Variables

View Source 
var (
	ErrInvalidFilterFormat = errors.New("filter format should be filter[field][operator]")
	ErrInvalidOperator     = errors.New("invalid operator")

	//nolint:gochecknoglobals // map is used in every GET request with filters, it's more efficient to keep it global
	Operators = map[string]filter.Operator{
		"eq":       filter.OpEq,
		"ne":       filter.OpNEq,
		"gt":       filter.OpGT,
		"gte":      filter.OpGTEq,
		"lt":       filter.OpLT,
		"lte":      filter.OpLTEq,
		"in":       filter.OpIn,
		"not-in":   filter.OpNotIn,
		"is":       filter.OpIs,
		"is-not":   filter.OpIsNot,
		"like":     filter.OpLike,
		"btw":      filter.OpBetween,
		"any":      filter.OpContains,
		"any-like": filter.OpContainsLike,
	}

	//nolint:gochecknoglobals // map is used in every GET request with filters, it's more efficient to keep it global
	OperatorStrings = map[filter.Operator]string{
		filter.OpEq:           "eq",
		filter.OpNEq:          "ne",
		filter.OpGT:           "gt",
		filter.OpGTEq:         "gte",
		filter.OpLT:           "lt",
		filter.OpLTEq:         "lte",
		filter.OpIn:           "in",
		filter.OpNotIn:        "not-in",
		filter.OpIs:           "is",
		filter.OpIsNot:        "is-not",
		filter.OpLike:         "like",
		filter.OpBetween:      "btw",
		filter.OpContains:     "any",
		filter.OpContainsLike: "any-like",
	}
)

Functions

func AddFilter 

func AddFilter(q Query, operator filter.Operator, name string, val any)

func AddFilterParam 

func AddFilterParam(queryParams url.Values, fieldName string, operator filter.Operator, value interface{})

AddFilterParam is a convenience function to add a single filter parameter

func DoesInclude 

func DoesInclude(q Query, relationship string) bool

func EncodeCursor 

func EncodeCursor(createdAt time.Time, id string, params map[string]string) string

func FiltersToURLValues 

func FiltersToURLValues(filters Filters[any]) url.Values

FiltersToURLValues converts query filters to url.Values with proper JSON:API format The format follows: filter[field][operator]=value

func FormatNextURL 

func FormatNextURL[R resource.Resource](ctx context.Context, r []R, req protoreflect.ProtoMessage) (nextUrl string)

func GetFilterSingleOrArrayVal 

func GetFilterSingleOrArrayVal[T any](fName string, filters Filters[any]) []T

func GetFilterVal 

func GetFilterVal[T any](fName string, filters Filters[any]) T

func GetFilterValOrDefault 

func GetFilterValOrDefault[T any](fName string, filters Filters[any], def T) T

func MarshalOperator 

func MarshalOperator(op filter.Operator) string

func ParseOperator 

func ParseOperator(val string) filter.Operator

func UpdateFilter 

func UpdateFilter[T any](q Query, name string, updateFunc func(filter.Operator, T) (filter.Operator, string, any))

func Validate 

func Validate(q Query, opts ...ValidationOpt) error

Types

type Cursor 

type Cursor interface {
	UUID() string
	CreatedAt() time.Time
	Limit() int
}

func NewCursor 

func NewCursor(createdAt time.Time, uuid string, limit int) Cursor

type Filters 

type Filters[T any] map[string]filter.FieldFilter[T]

func (Filters[T]) Delete 

func (qf Filters[T]) Delete(key string)

func (Filters[T]) Exists 

func (qf Filters[T]) Exists(keys ...string) bool

func (Filters[T]) Get 

func (qf Filters[T]) Get(key string) filter.FieldFilter[T]

type Option 

type Option func(q *query)

func Filter 

func Filter(f filter.FieldFilter[any]) Option

func FilterBy 

func FilterBy(op filter.Operator, fieldName, val any) Option

func FilterByTriples 

func FilterByTriples(opFieldVals ...any) Option

func IncludedResourceObjects 

func IncludedResourceObjects(relationshipNames ...string) Option

func Pagination 

func Pagination(limit, offset int) Option

func ParseOptsFromHTTPReq 

func ParseOptsFromHTTPReq(r *http.Request, opts ...ParseOpt) ([]Option, error)

func ParseURLQueryOpts 

func ParseURLQueryOpts(uri *url.URL, parseOpts ...ParseOpt) ([]Option, error)

func SortBy 

func SortBy(sortParams ...any) Option

type PaginationParams 

type PaginationParams struct {
	Limit  int
	Offset int
}

func (*PaginationParams) Delete 

func (p *PaginationParams) Delete()

type ParseOpt 

type ParseOpt func(c *parseConfig)

func DefaultPagination 

func DefaultPagination(applied bool) ParseOpt

func SkipDefaultPagination 

func SkipDefaultPagination() ParseOpt

type Query 

type Query interface {
	Filters() Filters[any]
	Sorting() *SortingParams
	Merge(q Query)
	Pagination() *PaginationParams
	IncludedResourceObjects() []string
	Equal(another Query) bool
}

func New 

func New(opts ...Option) Query

type SortingDir 

type SortingDir uint
const (
	SortDirUndefined SortingDir = iota
	SortAsc
	SortDesc
)

func (SortingDir) String 

func (sd SortingDir) String() string

func (SortingDir) Valid 

func (sd SortingDir) Valid() bool

type SortingParams 

type SortingParams struct {
	// contains filtered or unexported fields
}

func (*SortingParams) Get 

func (sp *SortingParams) Get(key string) SortingDir

func (*SortingParams) Keys 

func (sp *SortingParams) Keys() []string

func (*SortingParams) Set 

func (sp *SortingParams) Set(key string, v SortingDir)

type ValidationFunc 

type ValidationFunc func(f filter.FieldFilter[any]) error

type ValidationOpt 

type ValidationOpt func(c *validator) error

func AtLeastOneFilter 

func AtLeastOneFilter() ValidationOpt

func GroupedFilters 

func GroupedFilters(fs ...string) ValidationOpt

func MandatoryFilters 

func MandatoryFilters(fs ...string) ValidationOpt

func OptionalFilters 

func OptionalFilters(fs ...string) ValidationOpt

func SortFields 

func SortFields(fs ...string) ValidationOpt

func ValidFilter 

func ValidFilter(field string, fs ...ValidationFunc) ValidationOpt

Source Files

View all Source files

Directories

Path Synopsis
Package querytest provides test helpers for query options
 Package querytest provides test helpers for query options

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.