queryp

package module
v0.2.5 Latest Latest
Warning

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

 Go to latest Published: Dec 19, 2020 License: MIT Imports: 10 Imported by: 8

README

QueryP

NOTE: This is under development and is not yet officially released. Expect breaking changes for a bit.

This is a Go library for generating (mostly) database agnostic query parameters with:

  • Filter
  • Sort
  • Limit/Offsets

Parsing

The library also supports parsing a string with a specific format into the query parameters. It's most useful as a library for parsing GET query parameters.

For example:

field1=value1&(field2=value2|field3=value3)&limit=10&offset=10&sort=name,-description

Get all things where field1=value1 AND ( field2=value2 OR field3=value3 ) sort by name ascending, description descending limit to 10 records and skip the first 10

Supported Operators:

* &		- Logic AND (as well as splitting operators)
* |		- Logic OR

* =     - Exactly Equals
* !=    - Not Equals
* < 	- Less Than
* >		- Greater Than
* <=	- Less than or equals
* >=	- Greater than or equals
* =~	- Like (supports % wildcards)
* !=~   - Not Like (supports % wildcards)
* =~~   - Like case-insensitive (supports % wildcards)
* !=~~	- Not Like case-insensitive (supports % wildcards)
* :		- Regular Expression Match
* !:	- Not Regular Expression Match
* :~	- Regular Expression Match (case-insensitive
* !:~	- Not Regular Expression Match (case-insensitive

* ()	- Parenthesis can be use for precedence.

Drivers

Database drivers are built into the package

  • qppg - Postgres syntax driver

Usage

queryString := "field1=value1&(field2=value2|field3=value3)&limit=10&offset=10&sort=name,-description"

qp, err := queryp.ParseQuery(queryString)
if err != nil {
	log.Fatal(err)
}

var queryClause strings.Builder
var queryParams = []interface{}{}

// Fields we are allowed to filter by
filterFields := queryp.FilterFieldTypes{
	"table_name.thing_id":          queryp.FilterTypeSimple, // Simple matching good for equal/not equal
	"table_name.thing_name":        queryp.FilterTypeString, // Matching with like and regexp
	"table_name.created":           queryp.FilterTypeTime,   // Matching based on times
	"table_name.exists":            queryp.FilterTypeBool,   // Supports true/false only
	"table_name.quantity":          queryp.FilterTypeNumeric,// Supports numeric comparisons
	"someotherfield":               queryp.FilterFieldCustom{FieldName: "whoathird", FilterType: queryp.FilterTypeString}, // Use one field name in URL and another for database field
}

// Fields we are allowed to sort by
sortFields := queryp.SortFields{
	"source.source_id",
	"source.source_name",
}

// Default sort if none specified
if len(qp.Sort) == 0 {
	qp.Sort = queryp.Sort{queryp.SortTerm{Field: "source.source_name", Desc: false}}
}

// If we will filter
if len(qp.Filter) > 0 {
	queryClause.WriteString(" WHERE ")
}

// Generate the WHERE criteria for postgres
if err := qppg.FilterQuery(filterFields, qp.Filter, &queryClause, &queryParams); err != nil {
	return nil, 0, err
}

// Generate the sort criteria at the end of the query clause 
if err := qppg.SortQuery(sortFields, qp.Sort, &queryClause, &queryParams); err != nil {
	return nil, 0, err
}

// Append limit and offset if specified
if qp.Limit > 0 {
	queryClause.WriteString(" LIMIT " + strconv.Itoa(qp.Limit))
}
if qp.Offset > 0 {
	queryClause.WriteString(" OFFSET " + strconv.Itoa(qp.Offset))
}

query, err := db.Query("SELECT * FROM table_name "+queryClause.String(), queryParams...)
if err != nil {
	log.Fatal(err)
}

Thanks

Special thanks to my employer https://geneticnetworks.com for letting me work on this and open source it.

Documentation

Index

Constants

View Source 
const (
	FilterLogicSymAnd = "&"
	FilterLogicSymOr  = "|"

	ValueNeedsQuote = `&|)"`
)
View Source 
const (
	FilterOpSymEquals      = "="
	FilterOpSymNotEquals   = "!="
	FilterOpSymLessThan    = "<"
	FilterOpSymGreaterThan = ">"

	FilterOpSymLessThanEqual     = "<="
	FilterOpSymLessThanEqual2    = "=<"
	FilterOpSymGreaterThanEqual  = ">="
	FilterOpSymGreaterThanEqual2 = "=>"

	FilterOpSymLike     = "=~"
	FilterOpSymNotLike  = "!=~"
	FilterOpSymILike    = "=~~"
	FilterOpSymNotILike = "!=~~"

	FilterOpSymRegexp     = ":"
	FilterOpSymNotRegexp  = "!:"
	FilterOpSymIRegexp    = ":~"
	FilterOpSymNotIRegexp = "!:~"

	FieldNeedsQuote = `!=<>~:"`
)

Variables

View Source 
var (
	FilterOpSymToFilterOp = map[string]FilterOp{
		FilterOpSymEquals:            FilterOpEquals,
		FilterOpSymNotEquals:         FilterOpNotEquals,
		FilterOpSymLessThan:          FilterOpLessThan,
		FilterOpSymGreaterThan:       FilterOpGreaterThan,
		FilterOpSymLessThanEqual:     FilterOpLessThanEqual,
		FilterOpSymLessThanEqual2:    FilterOpLessThanEqual,
		FilterOpSymGreaterThanEqual:  FilterOpGreaterThanEqual,
		FilterOpSymGreaterThanEqual2: FilterOpGreaterThanEqual,
		FilterOpSymLike:              FilterOpLike,
		FilterOpSymNotLike:           FilterOpNotLike,
		FilterOpSymILike:             FilterOpILike,
		FilterOpSymNotILike:          FilterOpNotILike,
		FilterOpSymRegexp:            FilterOpRegexp,
		FilterOpSymNotRegexp:         FilterOpNotRegexp,
		FilterOpSymIRegexp:           FilterOpIRegexp,
		FilterOpSymNotIRegexp:        FilterOpNotIRegexp,
	}
	FilterOpToFilterOpSym = map[FilterOp]string{
		FilterOpEquals:           FilterOpSymEquals,
		FilterOpNotEquals:        FilterOpSymNotEquals,
		FilterOpLessThan:         FilterOpSymLessThan,
		FilterOpGreaterThan:      FilterOpSymGreaterThan,
		FilterOpLessThanEqual:    FilterOpSymLessThanEqual,
		FilterOpGreaterThanEqual: FilterOpSymGreaterThanEqual,
		FilterOpLike:             FilterOpSymLike,
		FilterOpNotLike:          FilterOpSymNotLike,
		FilterOpILike:            FilterOpSymILike,
		FilterOpNotILike:         FilterOpSymNotILike,
		FilterOpRegexp:           FilterOpSymRegexp,
		FilterOpNotRegexp:        FilterOpSymNotRegexp,
		FilterOpIRegexp:          FilterOpSymIRegexp,
		FilterOpNotIRegexp:       FilterOpSymNotIRegexp,
	}
)
View Source 
var (
	ErrInvalidLengthQueryp        = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowQueryp          = fmt.Errorf("proto: integer overflow")
	ErrUnexpectedEndOfGroupQueryp = fmt.Errorf("proto: unexpected end of group")
)
View Source 
var (
	FilterLogicSymToFilterLogic = map[string]FilterLogic{
		FilterLogicSymAnd: FilterLogicAnd,
		FilterLogicSymOr:  FilterLogicOr,
	}
)
View Source 
var FilterLogic_name = map[int32]string{
	0: "FilterLogicAnd",
	1: "FilterLogicOr",
}
View Source 
var FilterLogic_value = map[string]int32{
	"FilterLogicAnd": 0,
	"FilterLogicOr":  1,
}
View Source 
var FilterOp_name = map[int32]string{
	0:  "FilterOpEquals",
	1:  "FilterOpNotEquals",
	2:  "FilterOpLessThan",
	3:  "FilterOpLessThanEqual",
	4:  "FilterOpGreaterThan",
	5:  "FilterOpGreaterThanEqual",
	6:  "FilterOpLike",
	7:  "FilterOpNotLike",
	8:  "FilterOpILike",
	9:  "FilterOpNotILike",
	10: "FilterOpRegexp",
	11: "FilterOpNotRegexp",
	12: "FilterOpIRegexp",
	13: "FilterOpNotIRegexp",
}
View Source 
var FilterOp_value = map[string]int32{
	"FilterOpEquals":           0,
	"FilterOpNotEquals":        1,
	"FilterOpLessThan":         2,
	"FilterOpLessThanEqual":    3,
	"FilterOpGreaterThan":      4,
	"FilterOpGreaterThanEqual": 5,
	"FilterOpLike":             6,
	"FilterOpNotLike":          7,
	"FilterOpILike":            8,
	"FilterOpNotILike":         9,
	"FilterOpRegexp":           10,
	"FilterOpNotRegexp":        11,
	"FilterOpIRegexp":          12,
	"FilterOpNotIRegexp":       13,
}
View Source 
var FilterType_name = map[int32]string{
	0: "FilterTypeNotFound",
	1: "FilterTypeSimple",
	2: "FilterTypeString",
	3: "FilterTypeNumeric",
	4: "FilterTypeTime",
	5: "FilterTypeBool",
}
View Source 
var FilterType_value = map[string]int32{
	"FilterTypeNotFound": 0,
	"FilterTypeSimple":   1,
	"FilterTypeString":   2,
	"FilterTypeNumeric":  3,
	"FilterTypeTime":     4,
	"FilterTypeBool":     5,
}

Functions

func SafeField added in v0.2.5 

func SafeField(field string) string

SafeField will quote and escape fields if they contain op symbols or quotes

func SafeValue added in v0.2.5 

func SafeValue(value string) string

SafeValue will quote and escape values if they contain logic symbols or quotes

Types

type Field 

type Field = string

Field is just a string

type Filter 

type Filter []FilterTerm

Filter is a slice of FilterTerms that are combined to make the full filter

func (Filter) Append added in v0.2.1 

func (f Filter) Append(logic FilterLogic, field Field, op FilterOp, value interface{}) Filter

Convienience function for appending to a filter

func (Filter) String added in v0.2.5 

func (f Filter) String() string

Filter turns it into it's string representations

type FilterField added in v0.1.2 

type FilterField interface {
	GetFieldName() string
	GetFilterType() FilterType
}

FilterField is an interface used to allow specifying a filter for a particular filter type. if GetFieldName returns an empty string, it will assume the FieldName is the same as the field name specified in the map

type FilterFieldCustom added in v0.1.2 

type FilterFieldCustom struct {
	FieldName  string
	FilterType FilterType
}

FilterFieldCustom is used to have a different name for a field from what can be specified in the parsable string

func (FilterFieldCustom) GetFieldName added in v0.2.4 

func (ffc FilterFieldCustom) GetFieldName() Field

GetFieldName to return filter name from a Custom filter type

func (FilterFieldCustom) GetFilterType added in v0.2.4 

func (ffc FilterFieldCustom) GetFilterType() FilterType

GetFilterType to return the filter type from a Custom filter type

type FilterFieldTypes 

type FilterFieldTypes map[Field]FilterField

func (FilterFieldTypes) FindFilterType 

func (fft FilterFieldTypes) FindFilterType(search string) (string, FilterType)

FindFilterType search the FilterFieldTypes to find a matching field name. First it searches for exact matches and then

type FilterLogic 

type FilterLogic int32
const (
	FilterLogicAnd FilterLogic = 0
	FilterLogicOr  FilterLogic = 1
)

func (FilterLogic) EnumDescriptor added in v0.2.4 

func (FilterLogic) EnumDescriptor() ([]byte, []int)

func (FilterLogic) String 

func (logic FilterLogic) String() string

type FilterOp 

type FilterOp int32
const (
	FilterOpEquals           FilterOp = 0
	FilterOpNotEquals        FilterOp = 1
	FilterOpLessThan         FilterOp = 2
	FilterOpLessThanEqual    FilterOp = 3
	FilterOpGreaterThan      FilterOp = 4
	FilterOpGreaterThanEqual FilterOp = 5
	FilterOpLike             FilterOp = 6
	FilterOpNotLike          FilterOp = 7
	FilterOpILike            FilterOp = 8
	FilterOpNotILike         FilterOp = 9
	FilterOpRegexp           FilterOp = 10
	FilterOpNotRegexp        FilterOp = 11
	FilterOpIRegexp          FilterOp = 12
	FilterOpNotIRegexp       FilterOp = 13
)

func (FilterOp) EnumDescriptor added in v0.2.4 

func (FilterOp) EnumDescriptor() ([]byte, []int)

func (FilterOp) MarshalJSON 

func (op FilterOp) MarshalJSON() ([]byte, error)

func (FilterOp) String 

func (op FilterOp) String() string

type FilterTerm 

type FilterTerm struct {
	Logic     FilterLogic  `protobuf:"varint,1,opt,name=logic,proto3,enum=queryp.FilterLogic" json:"logic"`
	Op        FilterOp     `protobuf:"varint,2,opt,name=op,proto3,enum=queryp.FilterOp" json:"op"`
	Field     Field        `protobuf:"bytes,3,opt,name=field,proto3,casttype=Field" json:"field"`
	Value     string       `protobuf:"bytes,4,opt,name=value,proto3" json:"value"`
	SubFilter []FilterTerm `protobuf:"bytes,10,rep,name=sub_filter,json=subFilter,proto3" json:"sub_filter,omitempty"`
}

func (*FilterTerm) Descriptor added in v0.2.4 

func (*FilterTerm) Descriptor() ([]byte, []int)

func (*FilterTerm) GetField added in v0.2.4 

func (m *FilterTerm) GetField() Field

func (*FilterTerm) GetLogic added in v0.2.4 

func (m *FilterTerm) GetLogic() FilterLogic

func (*FilterTerm) GetOp added in v0.2.4 

func (m *FilterTerm) GetOp() FilterOp

func (*FilterTerm) GetSubFilter added in v0.2.4 

func (m *FilterTerm) GetSubFilter() []FilterTerm

func (*FilterTerm) GetValue added in v0.2.4 

func (m *FilterTerm) GetValue() string

func (*FilterTerm) Marshal added in v0.2.4 

func (m *FilterTerm) Marshal() (dAtA []byte, err error)

func (*FilterTerm) MarshalTo added in v0.2.4 

func (m *FilterTerm) MarshalTo(dAtA []byte) (int, error)

func (*FilterTerm) MarshalToSizedBuffer added in v0.2.4 

func (m *FilterTerm) MarshalToSizedBuffer(dAtA []byte) (int, error)

func (*FilterTerm) ProtoMessage added in v0.2.4 

func (*FilterTerm) ProtoMessage()

func (*FilterTerm) Reset added in v0.2.4 

func (m *FilterTerm) Reset()

func (*FilterTerm) Size added in v0.2.4 

func (m *FilterTerm) Size() (n int)

func (FilterTerm) String added in v0.2.4 

func (ft FilterTerm) String() string

String converts FilterTerm into it's string representation

func (*FilterTerm) Unmarshal added in v0.2.4 

func (m *FilterTerm) Unmarshal(dAtA []byte) error

func (*FilterTerm) XXX_DiscardUnknown added in v0.2.4 

func (m *FilterTerm) XXX_DiscardUnknown()

func (*FilterTerm) XXX_Marshal added in v0.2.4 

func (m *FilterTerm) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*FilterTerm) XXX_Merge added in v0.2.4 

func (m *FilterTerm) XXX_Merge(src proto.Message)

func (*FilterTerm) XXX_Size added in v0.2.4 

func (m *FilterTerm) XXX_Size() int

func (*FilterTerm) XXX_Unmarshal added in v0.2.4 

func (m *FilterTerm) XXX_Unmarshal(b []byte) error

type FilterType 

type FilterType int32
const (
	FilterTypeNotFound FilterType = 0
	FilterTypeSimple   FilterType = 1
	FilterTypeString   FilterType = 2
	FilterTypeNumeric  FilterType = 3
	FilterTypeTime     FilterType = 4
	FilterTypeBool     FilterType = 5
)

func (FilterType) EnumDescriptor added in v0.2.4 

func (FilterType) EnumDescriptor() ([]byte, []int)

func (FilterType) GetFieldName added in v0.2.4 

func (ft FilterType) GetFieldName() Field

GetFieldName returns empty field indicating it should use the same name as the filter type

func (FilterType) GetFilterType added in v0.2.4 

func (ft FilterType) GetFilterType() FilterType

GetFilterType for the default filter types

type Options 

type Options map[string]string // Just a lookup of string

func (Options) Get added in v0.2.5 

func (o Options) Get(option string) string

func (Options) Has added in v0.2.5 

func (o Options) Has(option string) bool

func (Options) Set added in v0.2.2 

func (o Options) Set(option string, value string) Options

func (Options) String added in v0.2.5 

func (o Options) String() string

type QueryParameters 

type QueryParameters struct {
	Filter  []FilterTerm `protobuf:"bytes,1,rep,name=filter,proto3,casttype=FilterTerm" json:"filter"`
	Sort    []SortTerm   `protobuf:"bytes,2,rep,name=sort,proto3,casttype=SortTerm" json:"sort"`
	Options Options      `` /* 162-byte string literal not displayed */
	Limit   int64        `protobuf:"varint,4,opt,name=limit,proto3" json:"limit"`
	Offset  int64        `protobuf:"varint,5,opt,name=offset,proto3" json:"offset"`
}

func ParseQuery 

func ParseQuery(q string) (*QueryParameters, error)

ParseQuery converts a string into query parameters This loosely follows standard HTTP URL encoding

func ParseRawQuery 

func ParseRawQuery(rq string) (*QueryParameters, error)

func (*QueryParameters) Descriptor added in v0.2.4 

func (*QueryParameters) Descriptor() ([]byte, []int)

func (*QueryParameters) GetFilter added in v0.2.4 

func (m *QueryParameters) GetFilter() []FilterTerm

func (*QueryParameters) GetLimit added in v0.2.4 

func (m *QueryParameters) GetLimit() int64

func (*QueryParameters) GetOffset added in v0.2.4 

func (m *QueryParameters) GetOffset() int64

func (*QueryParameters) GetOptions added in v0.2.4 

func (m *QueryParameters) GetOptions() Options

func (*QueryParameters) GetSort added in v0.2.4 

func (m *QueryParameters) GetSort() []SortTerm

func (*QueryParameters) Marshal added in v0.2.4 

func (m *QueryParameters) Marshal() (dAtA []byte, err error)

func (*QueryParameters) MarshalTo added in v0.2.4 

func (m *QueryParameters) MarshalTo(dAtA []byte) (int, error)

func (*QueryParameters) MarshalToSizedBuffer added in v0.2.4 

func (m *QueryParameters) MarshalToSizedBuffer(dAtA []byte) (int, error)

func (*QueryParameters) ProtoMessage added in v0.2.4 

func (*QueryParameters) ProtoMessage()

func (*QueryParameters) Reset added in v0.2.2 

func (m *QueryParameters) Reset()

func (*QueryParameters) Size added in v0.2.4 

func (m *QueryParameters) Size() (n int)

func (*QueryParameters) String 

func (qp *QueryParameters) String() string

String will turn query parameters back into a string that is equivalent to what can be parsed

func (*QueryParameters) Unmarshal added in v0.2.4 

func (m *QueryParameters) Unmarshal(dAtA []byte) error

func (*QueryParameters) XXX_DiscardUnknown added in v0.2.4 

func (m *QueryParameters) XXX_DiscardUnknown()

func (*QueryParameters) XXX_Marshal added in v0.2.4 

func (m *QueryParameters) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*QueryParameters) XXX_Merge added in v0.2.4 

func (m *QueryParameters) XXX_Merge(src proto.Message)

func (*QueryParameters) XXX_Size added in v0.2.4 

func (m *QueryParameters) XXX_Size() int

func (*QueryParameters) XXX_Unmarshal added in v0.2.4 

func (m *QueryParameters) XXX_Unmarshal(b []byte) error

type Sort 

type Sort []SortTerm

Sort is a slice of SortTerms

type SortFields 

type SortFields map[string]Field

SortFields is how you specify what fields are available to select for sorting

type SortTerm 

type SortTerm struct {
	Field Field `protobuf:"bytes,1,opt,name=field,proto3,casttype=Field" json:"field"`
	Desc  bool  `protobuf:"varint,2,opt,name=desc,proto3" json:"desc"`
}

func (*SortTerm) Descriptor added in v0.2.4 

func (*SortTerm) Descriptor() ([]byte, []int)

func (*SortTerm) GetDesc added in v0.2.4 

func (m *SortTerm) GetDesc() bool

func (*SortTerm) GetField added in v0.2.4 

func (m *SortTerm) GetField() Field

func (*SortTerm) Marshal added in v0.2.4 

func (m *SortTerm) Marshal() (dAtA []byte, err error)

func (*SortTerm) MarshalTo added in v0.2.4 

func (m *SortTerm) MarshalTo(dAtA []byte) (int, error)

func (*SortTerm) MarshalToSizedBuffer added in v0.2.4 

func (m *SortTerm) MarshalToSizedBuffer(dAtA []byte) (int, error)

func (*SortTerm) ProtoMessage added in v0.2.4 

func (*SortTerm) ProtoMessage()

func (*SortTerm) Reset added in v0.2.4 

func (m *SortTerm) Reset()

func (*SortTerm) Size added in v0.2.4 

func (m *SortTerm) Size() (n int)

func (SortTerm) String added in v0.2.4 

func (st SortTerm) String() string

func (*SortTerm) Unmarshal added in v0.2.4 

func (m *SortTerm) Unmarshal(dAtA []byte) error

func (*SortTerm) XXX_DiscardUnknown added in v0.2.4 

func (m *SortTerm) XXX_DiscardUnknown()

func (*SortTerm) XXX_Marshal added in v0.2.4 

func (m *SortTerm) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*SortTerm) XXX_Merge added in v0.2.4 

func (m *SortTerm) XXX_Merge(src proto.Message)

func (*SortTerm) XXX_Size added in v0.2.4 

func (m *SortTerm) XXX_Size() int

func (*SortTerm) XXX_Unmarshal added in v0.2.4 

func (m *SortTerm) XXX_Unmarshal(b []byte) error

Source Files

View all Source files

Directories

Path Synopsis

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.