query

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: May 25, 2026 License: MIT Imports: 18 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,
		"like":     filter.OpLike,
		"not-like": filter.OpNotLike,
		"btw":      filter.OpBetween,
		"any":      filter.OpContains,
		"any-like": filter.OpContainsLike,
		"is-null":  filter.OpIsNull,
		"not-null": filter.OpNotNull,
	}

	//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.OpLike:         "like",
		filter.OpNotLike:      "not-like",
		filter.OpBetween:      "btw",
		filter.OpContains:     "any",
		filter.OpContainsLike: "any-like",
		filter.OpIsNull:       "is-null",
		filter.OpNotNull:      "not-null",
	}
)

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 AggregationsToURLValues added in v0.1.1 

func AggregationsToURLValues(aggs []Aggregation) url.Values

func BucketToURLValue added in v0.1.1 

func BucketToURLValue(d time.Duration) string

func DecodePositionCursor 

func DecodePositionCursor(encoded string) (time.Time, string)

DecodePositionCursor reverses EncodePositionCursor. Returns the zero values when the cursor is empty or malformed; callers should treat a zero return as "no cursor".

func DoesInclude 

func DoesInclude(q Query, relationship string) bool

func EncodePositionCursor 

func EncodePositionCursor(createdAt time.Time, id string) string

EncodePositionCursor builds the opaque page[after] / page[before] value: base64(`<RFC3339Nano>|<uuid>`). Position only — filters and sort travel as their own query params, never inside the cursor.

func FiltersToURLValues 

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

func FormatNextURL 

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

FormatNextURL builds the JSON:API §Pagination `links.next` URL for the supplied result page. It preserves every filter / sort / include / fields[] param that came in on req and adds (or replaces) `page[after]=<opaqueCursor>` plus `page[size]=<limit>`.

Returns "" when the result set is empty, when the request was a fetch-by-id (no pagination needed), or when the gRPC metadata doesn't contain the forwarded host / path.

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 GroupToURLValue added in v0.1.1 

func GroupToURLValue(group []string) string

func MarshalOperator 

func MarshalOperator(op filter.Operator) string

func OrGroupsToURLValues added in v0.1.1 

func OrGroupsToURLValues(groups []Filters[any]) url.Values

func PaginationToURLValues 

func PaginationToURLValues(p *PaginationParams) url.Values

func ParseOperator 

func ParseOperator(val string) filter.Operator

func SortingToURLValue 

func SortingToURLValue(sp *SortingParams) string

func SparseFieldsetsToURLValues 

func SparseFieldsetsToURLValues(fields SparseFieldsets) url.Values

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 AggOp added in v0.1.1 

type AggOp uint
const (
	AggUndefined AggOp = iota
	AggCount
	AggSum
	AggAvg
	AggMin
	AggMax
)

func (AggOp) String added in v0.1.1 

func (op AggOp) String() string

func (AggOp) Valid added in v0.1.1 

func (op AggOp) Valid() bool

type Aggregation added in v0.1.1 

type Aggregation struct {
	Alias    string
	Operator AggOp
	Field    string
}

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 Aggregate added in v0.1.1 

func Aggregate(alias string, op AggOp, field string) Option

func Bucket added in v0.1.1 

func Bucket(d time.Duration) Option

func CursorPagination 

func CursorPagination(before, after string, size int) Option

func Fields 

func Fields(resourceType string, names ...string) Option

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 Group added in v0.1.1 

func Group(dimensions ...string) Option

func IncludedResourceObjects 

func IncludedResourceObjects(relationshipNames ...string) Option

func OrGroup added in v0.1.1 

func OrGroup(opts ...Option) 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
	Before string
	After  string
	Size   int
}

func (*PaginationParams) Delete 

func (p *PaginationParams) Delete()

func (*PaginationParams) IsCursor 

func (p *PaginationParams) IsCursor() bool

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]
	OrGroups() []Filters[any]
	Sorting() *SortingParams
	Merge(q Query)
	Pagination() *PaginationParams
	IncludedResourceObjects() []string
	Fields() SparseFieldsets
	Group() []string
	Aggregations() []Aggregation
	Bucket() time.Duration
	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 SparseFieldsets 

type SparseFieldsets map[string][]string

type ValidationFunc 

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

type ValidationOpt 

type ValidationOpt func(c *validator) error

func AggregationFields added in v0.1.1 

func AggregationFields(fs ...string) ValidationOpt

func AtLeastOneFilter 

func AtLeastOneFilter() ValidationOpt

func GroupFields added in v0.1.1 

func GroupFields(fs ...string) 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.