query

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Mar 2, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package query provides a PostgREST-style query builder for GORM with pagination, sorting, filtering, facets, and eager-loading support.

Index

Constants

View Source
const (
	DefaultPageSize = 20
	MaxPageSize     = 100
)

Variables

This section is empty.

Functions

func ApplyConditions

func ApplyConditions(db *gorm.DB, conditions []Condition, config Config) *gorm.DB

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

func ApplyIncludesFromParams(db *gorm.DB, params Params, config Config) *gorm.DB

ApplyIncludesFromParams is a convenience wrapper.

func ComputeFacetsWithFilters

func ComputeFacetsWithFilters(
	db *gorm.DB,
	facetFields []string,
	conditions []Condition,
	config Config,
) map[string]map[string]int

ComputeFacetsWithFilters computes facet counts with cross-filtering.

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

func (c Config) ResolveFacetLabel(field string) string

ResolveFacetLabel returns the display label for a facet field.

func (Config) ResolveField

func (c Config) ResolveField(field string) string

ResolveField returns the actual column name for a field, using FieldAliases if available.

type FilterQuery

type FilterQuery struct {
	Conditions []Condition
	FreeText   string
}

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

type IncludePath struct {
	Parts []string
	Raw   string
}

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) Depth

func (p IncludePath) Depth() int

Depth returns the nesting level.

func (IncludePath) HasChildren

func (p IncludePath) HasChildren() bool

HasChildren returns true if the path has nested segments.

func (IncludePath) Root

func (p IncludePath) Root() string

Root returns the first segment.

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.

const (
	OpEq      Operator = "eq"
	OpNeq     Operator = "neq"
	OpGt      Operator = "gt"
	OpGte     Operator = "gte"
	OpLt      Operator = "lt"
	OpLte     Operator = "lte"
	OpIn      Operator = "in"
	OpNin     Operator = "nin"
	OpLike    Operator = "like"
	OpIlike   Operator = "ilike"
	OpNull    Operator = "null"
	OpNotNull Operator = "notNull"
)

func AllOperators

func AllOperators() []Operator

AllOperators returns all valid operators.

func (Operator) IsValid

func (o Operator) IsValid() bool

IsValid reports whether the operator is known.

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

func ParseFromRequest(r *http.Request, config Config) Params

ParseFromRequest extracts query params from an HTTP request. Supports PostgREST/Supabase filter format: field=op.value

func (*Params) AddCondition

func (p *Params) AddCondition(field string, op Operator, value string)

AddCondition appends a condition to the query.

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"
)

type Result

type Result[T any] struct {
	Data       []T                       `json:"data"`
	Pagination Pagination                `json:"pagination"`
	Facets     map[string]map[string]int `json:"facets,omitempty"`
}

Result is a paginated response with optional facets.

func ApplyToGorm

func ApplyToGorm[T any](db *gorm.DB, params Params, config Config) (*Result[T], error)

ApplyToGorm applies params to a GORM query and returns a paginated result.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL