Documentation ¶
Index ¶
- Variables
- func ApplyValidation(set validation.RuleSet)
- func ApplyValidationRules(set *validation.Rules)
- func ConvertArgsToSafeType(args []string, dataType DataType) ([]interface{}, bool)
- func ConvertToSafeType(arg string, dataType DataType) (interface{}, bool)
- func Scope(db *gorm.DB, request *goyave.Request, dest interface{}) (*database.Paginator, *gorm.DB)
- func ScopeUnpaginated(db *gorm.DB, request *goyave.Request, dest interface{}) *gorm.DB
- type Blacklist
- type DataType
- type Filter
- type Join
- type Operator
- type Search
- type Settings
- type Sort
- type SortOrder
Constants ¶
This section is empty.
Variables ¶
var ( // DefaultPageSize the default pagination page size if the "per_page" query param // isn't provided. DefaultPageSize = 10 )
var ( // Operators definitions. The key is the query representation of the operator, (e.g. "$eq"). Operators = map[string]*Operator{ "$eq": {Function: basicComparison("="), RequiredArguments: 1}, "$ne": {Function: basicComparison("<>"), RequiredArguments: 1}, "$gt": {Function: basicComparison(">"), RequiredArguments: 1}, "$lt": {Function: basicComparison("<"), RequiredArguments: 1}, "$gte": {Function: basicComparison(">="), RequiredArguments: 1}, "$lte": {Function: basicComparison("<="), RequiredArguments: 1}, "$starts": { Function: func(tx *gorm.DB, filter *Filter, column string, dataType DataType) *gorm.DB { if dataType != DataTypeText && dataType != DataTypeEnum { return filter.Where(tx, "FALSE") } query := castEnumAsText(column, dataType) + " LIKE ?" value := sqlutil.EscapeLike(filter.Args[0]) + "%" return filter.Where(tx, query, value) }, RequiredArguments: 1, }, "$ends": { Function: func(tx *gorm.DB, filter *Filter, column string, dataType DataType) *gorm.DB { if dataType != DataTypeText && dataType != DataTypeEnum { return filter.Where(tx, "FALSE") } query := castEnumAsText(column, dataType) + " LIKE ?" value := "%" + sqlutil.EscapeLike(filter.Args[0]) return filter.Where(tx, query, value) }, RequiredArguments: 1, }, "$cont": { Function: func(tx *gorm.DB, filter *Filter, column string, dataType DataType) *gorm.DB { if dataType != DataTypeText && dataType != DataTypeEnum { return filter.Where(tx, "FALSE") } query := castEnumAsText(column, dataType) + " LIKE ?" value := "%" + sqlutil.EscapeLike(filter.Args[0]) + "%" return filter.Where(tx, query, value) }, RequiredArguments: 1, }, "$excl": { Function: func(tx *gorm.DB, filter *Filter, column string, dataType DataType) *gorm.DB { if dataType != DataTypeText && dataType != DataTypeEnum { return filter.Where(tx, "FALSE") } query := castEnumAsText(column, dataType) + " NOT LIKE ?" value := "%" + sqlutil.EscapeLike(filter.Args[0]) + "%" return filter.Where(tx, query, value) }, RequiredArguments: 1, }, "$in": {Function: multiComparison("IN"), RequiredArguments: 1}, "$notin": {Function: multiComparison("NOT IN"), RequiredArguments: 1}, "$isnull": { Function: func(tx *gorm.DB, filter *Filter, column string, dataType DataType) *gorm.DB { return filter.Where(tx, column+" IS NULL") }, RequiredArguments: 0, }, "$istrue": { Function: func(tx *gorm.DB, filter *Filter, column string, dataType DataType) *gorm.DB { if dataType != DataTypeBool { return filter.Where(tx, "FALSE") } return filter.Where(tx, column+" IS TRUE") }, RequiredArguments: 0, }, "$isfalse": { Function: func(tx *gorm.DB, filter *Filter, column string, dataType DataType) *gorm.DB { if dataType != DataTypeBool { return filter.Where(tx, "FALSE") } return filter.Where(tx, column+" IS FALSE") }, RequiredArguments: 0, }, "$notnull": { Function: func(tx *gorm.DB, filter *Filter, column string, dataType DataType) *gorm.DB { return filter.Where(tx, column+" IS NOT NULL") }, RequiredArguments: 0, }, "$between": { Function: func(tx *gorm.DB, filter *Filter, column string, dataType DataType) *gorm.DB { if dataType.IsArray() { return filter.Where(tx, "FALSE") } args, ok := ConvertArgsToSafeType(filter.Args[:2], dataType) if !ok { return filter.Where(tx, "FALSE") } query := castEnumAsText(column, dataType) + " BETWEEN ? AND ?" return filter.Where(tx, query, args...) }, RequiredArguments: 2, }, } )
var Separator = "||"
Separator the separator used when parsing the query
Functions ¶
func ApplyValidation ¶
func ApplyValidation(set validation.RuleSet)
ApplyValidation add all fields used by the filter module to the given RuleSet.
func ApplyValidationRules ¶
func ApplyValidationRules(set *validation.Rules)
ApplyValidationRules add all fields used by the filter module to the given *Rules.
func ConvertArgsToSafeType ¶ added in v0.6.0
ConvertArgsToSafeType converts a slice of string arguments to safe type that matches the column's data type in the same way as `ConvertToSafeType`. If any of the values in the given slice could not be converted, returns false.
func ConvertToSafeType ¶ added in v0.6.0
ConvertToSafeType convert the string argument to a safe type that matches the column's data type. Returns false if the input could not be converted.
Types ¶
type Blacklist ¶
type Blacklist struct { Relations map[string]*Blacklist // FieldsBlacklist prevent the fields in this list to be selected or to // be used in filters and sorts. FieldsBlacklist []string // RelationsBlacklist prevent joining the relations in this list. RelationsBlacklist []string // IsFinal if true, prevent joining any relation IsFinal bool }
Blacklist definition of blacklisted relations and fields.
type DataType ¶ added in v0.6.0
type DataType string
DataType is determined by the `filterType` struct tag (see `DataType` for available options). If not given, uses GORM's general DataType. Raw database data types are not supported so it is recommended to always specify a `filterType` in this scenario.
const ( DataTypeText DataType = "text" DataTypeTextArray DataType = "text[]" DataTypeEnum DataType = "enum" DataTypeEnumArray DataType = "enum[]" DataTypeBool DataType = "bool" DataTypeBoolArray DataType = "bool[]" DataTypeInt8 DataType = "int8" DataTypeInt8Array DataType = "int8[]" DataTypeInt16 DataType = "int16" DataTypeInt16Array DataType = "int16[]" DataTypeInt32 DataType = "int32" DataTypeInt32Array DataType = "int32[]" DataTypeInt64 DataType = "int64" DataTypeInt64Array DataType = "int64[]" DataTypeUint8 DataType = "uint8" DataTypeUint8Array DataType = "uint8[]" DataTypeUint16 DataType = "uint16" DataTypeUint16Array DataType = "uint16[]" DataTypeUint32 DataType = "uint32" DataTypeUint32Array DataType = "uint32[]" DataTypeUint64 DataType = "uint64" DataTypeUint64Array DataType = "uint64[]" DataTypeFloat32 DataType = "float32" DataTypeFloat32Array DataType = "float32[]" DataTypeFloat64 DataType = "float64" DataTypeFloat64Array DataType = "float64[]" DataTypeTime DataType = "time" DataTypeTimeArray DataType = "time[]" // DataTypeUnsupported all fields with this tag will be ignored in filters and search. DataTypeUnsupported DataType = "-" )
Supported DataTypes
type Filter ¶
Filter structured representation of a filter query.
func ParseFilter ¶
ParseFilter parse a string in format "field||$operator||value" and return a Filter struct. The filter string must satisfy the used operator's "RequiredArguments" constraint, otherwise an error is returned.
type Join ¶
Join structured representation of a join query.
type Operator ¶
type Operator struct { Function func(tx *gorm.DB, filter *Filter, column string, dataType DataType) *gorm.DB RequiredArguments uint8 }
Operator used by filters to build the SQL query. The operator function modifies the GORM statement (most of the time by adding a WHERE condition) then returns the modified statement.
Operators may need arguments (e.g. "$eq", equals needs a value to compare the field to); RequiredArguments define the minimum number of arguments a client must send in order to use this operator in a filter. RequiredArguments is checked during Filter parsing.
Operators may return the given tx without change if they don't support the given dataType or add a condition that will always be false.
type Settings ¶
type Settings struct { // FieldsSearch allows search for these fields FieldsSearch []string // SearchOperator is used by the search scope, by default it use the $cont operator SearchOperator *Operator Blacklist // DisableFields ignore the "fields" query if true. DisableFields bool // DisableFilter ignore the "filter" query if true. DisableFilter bool // DisableSort ignore the "sort" query if true. DisableSort bool // DisableJoin ignore the "join" query if true. DisableJoin bool // DisableSearch ignore the "search" query if true. DisableSearch bool }
Settings settings to disable certain features and/or blacklist fields and relations.
func (*Settings) Scope ¶
func (s *Settings) Scope(db *gorm.DB, request *goyave.Request, dest interface{}) (*database.Paginator, *gorm.DB)
Scope apply all filters, sorts and joins defined in the request's data to the given `*gorm.DB` and process pagination. Returns the resulting `*database.Paginator` and the `*gorm.DB` result, which can be used to check for database errors. The given request is expected to be validated using `ApplyValidation`.
func (*Settings) ScopeUnpaginated ¶ added in v0.5.0
func (s *Settings) ScopeUnpaginated(db *gorm.DB, request *goyave.Request, dest interface{}) *gorm.DB
ScopeUnpaginated apply all filters, sorts and joins defined in the request's data to the given `*gorm.DB` without any pagination. Returns the `*gorm.DB` result, which can be used to check for database errors. The records will be added in the given `dest` slice. The given request is expected to be validated using `ApplyValidation`.