Documentation
¶
Overview ¶
Package query provides a PostgREST-style query builder for GORM with pagination, sorting, filtering, facets, and eager-loading support.
Index ¶
- Constants
- func ApplyConditions(db *gorm.DB, conditions []Condition, config Config) *gorm.DB
- func ApplyIncludes(db *gorm.DB, includes IncludeSet, config IncludeConfig) *gorm.DB
- func ApplyIncludesFromParams(db *gorm.DB, params Params, config Config) *gorm.DB
- func ComputeFacetsWithFilters(db *gorm.DB, facetFields []string, conditions []Condition, config Config) map[string]map[string]int
- type Condition
- type Config
- type FilterQuery
- type IncludeConfig
- type IncludePath
- type IncludeSet
- type IncludeSpec
- type Operator
- type Pagination
- type Params
- type RelationType
- type Result
Constants ¶
const ( DefaultPageSize = 20 MaxPageSize = 100 )
Variables ¶
This section is empty.
Functions ¶
func ApplyConditions ¶
ApplyConditions applies conditions to a GORM query.
func ApplyIncludes ¶
func ApplyIncludes(db *gorm.DB, includes IncludeSet, config IncludeConfig) *gorm.DB
ApplyIncludes applies requested includes to a GORM query using specs from config.
func ApplyIncludesFromParams ¶
ApplyIncludesFromParams is a convenience wrapper.
Types ¶
type Condition ¶
type Condition struct {
Field string
Operator Operator
Value string
Values []string // for in, nin
}
Condition represents a single filter condition.
type Config ¶
type Config struct {
SearchFields []string
AllowedSortFields []string
AllowedFilters []string
FieldAliases map[string]string
DefaultSort string
FacetFields []string
FacetLabels map[string]string
IncludeConfig IncludeConfig
}
Config defines entity-specific query behavior.
func (Config) ResolveFacetLabel ¶
ResolveFacetLabel returns the display label for a facet field.
func (Config) ResolveField ¶
ResolveField returns the actual column name for a field, using FieldAliases if available.
type FilterQuery ¶
FilterQuery holds parsed filter conditions.
type IncludeConfig ¶
type IncludeConfig struct {
AllowedPaths []string
MaxDepth int
Specs map[string]IncludeSpec
}
IncludeConfig defines allowed includes for a resource.
func DefaultIncludeConfig ¶
func DefaultIncludeConfig() IncludeConfig
DefaultIncludeConfig returns a config with no includes allowed.
func (IncludeConfig) IsPathAllowed ¶
func (c IncludeConfig) IsPathAllowed(path string) bool
IsPathAllowed checks if a path is allowed by the config.
type IncludePath ¶
IncludePath represents a parsed include path like "service.protocols".
func (IncludePath) Child ¶
func (p IncludePath) Child() IncludePath
Child returns a new IncludePath with the first segment removed.
func (IncludePath) HasChildren ¶
func (p IncludePath) HasChildren() bool
HasChildren returns true if the path has nested segments.
type IncludeSet ¶
type IncludeSet struct {
Paths []IncludePath
ByRoot map[string][]IncludePath
}
IncludeSet holds parsed include paths grouped by root.
func ParseIncludes ¶
func ParseIncludes(includeStr string, config IncludeConfig) IncludeSet
ParseIncludes parses an include string without HTTP request context.
func ParseIncludesFromRequest ¶
func ParseIncludesFromRequest(r *http.Request, config IncludeConfig) IncludeSet
ParseIncludesFromRequest extracts _include from an HTTP request.
func (IncludeSet) ChildrenOf ¶
func (s IncludeSet) ChildrenOf(root string) []IncludePath
ChildrenOf returns include paths that are direct children of the given root.
func (IncludeSet) Has ¶
func (s IncludeSet) Has(path string) bool
Has returns true if the given path (or any parent path) is included.
func (IncludeSet) HasExact ¶
func (s IncludeSet) HasExact(path string) bool
HasExact returns true only if the exact path is included.
func (IncludeSet) IsEmpty ¶
func (s IncludeSet) IsEmpty() bool
IsEmpty returns true if no includes were requested.
type IncludeSpec ¶
type IncludeSpec struct {
Type RelationType
Relation string
Nested map[string]IncludeSpec
OrderBy string
}
IncludeSpec defines how an include path maps to GORM loading operations.
type Operator ¶
type Operator string
Operator represents filter operators matching PostgREST/Supabase format.
type Pagination ¶
type Pagination struct {
Page int `json:"page"`
PageSize int `json:"pageSize"`
Total int `json:"total"`
TotalPages int `json:"totalPages"`
}
Pagination metadata returned in paginated results.
type Params ¶
type Params struct {
Page int
PageSize int
NoPagination bool
SortBy string
SortOrder string
Query FilterQuery
Includes IncludeSet
}
Params holds parsed query parameters.
func ParseFromRequest ¶
ParseFromRequest extracts query params from an HTTP request. Supports PostgREST/Supabase filter format: field=op.value
type RelationType ¶
type RelationType string
RelationType determines how a relationship should be loaded.
const ( RelationBelongsTo RelationType = "belongs_to" RelationHasMany RelationType = "has_many" RelationHasOne RelationType = "has_one" )