filter

type Bindings ¶

type Bindings map[string]any

Bindings provides runtime values for CEL variables which are not schema fields.

These values are used when rendering SQL placeholders and when evaluating compiled conditions in-memory.

type Column ¶

type Column struct {
	Table string
	Name  string
}

Column identifies the backing table column.

type ComparisonCondition ¶

type ComparisonCondition struct {
	Left     ValueExpr
	Operator ComparisonOperator
	Right    ValueExpr
}

ComparisonCondition represents a binary comparison.

type ComparisonOperator ¶

type ComparisonOperator string

ComparisonOperator lists supported comparison operators.

const (
	CompareEq  ComparisonOperator = "="
	CompareNeq ComparisonOperator = "!="
	CompareLt  ComparisonOperator = "<"
	CompareLte ComparisonOperator = "<="
	CompareGt  ComparisonOperator = ">"
	CompareGte ComparisonOperator = ">="
)

type CompileHook ¶

type CompileHook func(schema Schema, filter string, ast *cel.Ast, cond Condition) (Condition, error)

CompileHook can rewrite or replace the compiled condition tree.

Hooks run after CEL parsing/type-checking and IR building, but before the resulting Program is returned.

Returning (nil, nil) keeps the current condition unchanged.

type ComprehensionKind ¶

type ComprehensionKind string

ComprehensionKind enumerates the supported comprehension macros.

const (
	ComprehensionExists ComprehensionKind = "exists"
)

type Condition ¶

type Condition interface {
	// contains filtered or unexported methods
}

Condition represents a boolean expression derived from the CEL filter.

func CondAnd(c ...Condition) Condition

func CondOr(c ...Condition) Condition

type ConstantCondition ¶

type ConstantCondition struct {
	Value bool
}

ConstantCondition captures a literal boolean outcome.

type ContainsCondition ¶

type ContainsCondition struct {
	Field string
	Value ValueExpr
}

ContainsCondition models the <field>.contains(<value>) call.

type ContainsPredicate ¶

type ContainsPredicate struct {
	Substring ValueExpr
}

ContainsPredicate represents t.contains(substring).

type DialectName ¶

type DialectName string

DialectName enumerates supported SQL dialects.

const (
	DialectSQLite   DialectName = "sqlite"
	DialectMySQL    DialectName = "mysql"
	DialectPostgres DialectName = "postgres"
	// DialectPostgresNamedArgs renders Postgres SQL using named arguments (`@name`).
	//
	// The generated statement uses `Statement.NamedArgs` instead of positional `Statement.Args`.
	DialectPostgresNamedArgs DialectName = "postgres_pgx"
)

type DialectSQL ¶

type DialectSQL struct {
	Default  string
	SQLite   string
	MySQL    string
	Postgres string
}

DialectSQL stores dialect-specific SQL templates.

Templates are SQL fragments used in a WHERE clause and must evaluate to a boolean expression in the target dialect.

Placeholders:

• `{{field_name}}` is replaced with the schema column expression for that field.
• `?` are replaced with dialect placeholders and populated from condition args.

type ElementInCondition ¶

type ElementInCondition struct {
	Element ValueExpr
	Field   string
}

ElementInCondition represents the CEL syntax `"value" in field`.

This is primarily used for JSON list membership checks.

type EndsWithCondition ¶

type EndsWithCondition struct {
	Field string
	Value ValueExpr
}

EndsWithCondition models the <field>.endsWith(<value>) call.

type EndsWithPredicate ¶

type EndsWithPredicate struct {
	Suffix ValueExpr
}

EndsWithPredicate represents t.endsWith(suffix).

type Engine ¶

type Engine struct {
	// contains filtered or unexported fields
}

Engine parses CEL filters into a dialect-agnostic condition tree.

func NewEngine(schema Schema, opts ...EngineOption) (*Engine, error)

func (e *Engine) Compile(filter string) (*Program, error)

func (e *Engine) CompileToStatement(filter string, bindings Bindings, opts RenderOptions) (Statement, error)

func (e *Engine) ExtraFilterCEL() string

func (e *Engine) IsCondGranted(filter string, vars map[string]any) (bool, error)

type EngineOption ¶

type EngineOption func(*engineConfig)

EngineOption customizes Engine construction.

func WithCompileHook(hook CompileHook) EngineOption

func WithEnvOptions(opts ...cel.EnvOption) EngineOption

func WithExtraFilterCEL(expr string) EngineOption

func WithMacros(macros ...cel.Macro) EngineOption

func WithSQLPredicate(name string, pred SQLPredicate) EngineOption

type EvalOptions ¶

type EvalOptions struct {
}

EvalOptions configures in-memory evaluation.

Dialect is optional, but when set it will try to mirror renderer semantics for a few dialect-sensitive operations (e.g. Postgres ILIKE for contains()).

type Field ¶

type Field struct {
	Name                 string
	Kind                 FieldKind
	Type                 FieldType
	Column               Column
	JSONPath             []string
	AliasFor             string
	SupportsContains     bool
	Expressions          map[DialectName]string
	AllowedComparisonOps map[ComparisonOperator]bool
}

Field captures the schema metadata for an exposed CEL identifier.

type FieldKind ¶

type FieldKind string

FieldKind describes how a field is stored.

const (
	FieldKindScalar       FieldKind = "scalar"
	FieldKindBoolColumn   FieldKind = "bool_column"
	FieldKindJSONBool     FieldKind = "json_bool"
	FieldKindJSONList     FieldKind = "json_list"
	FieldKindVirtualAlias FieldKind = "virtual_alias"
)

type FieldPredicateCondition ¶

type FieldPredicateCondition struct {
	Field string
}

FieldPredicateCondition asserts that a boolean field evaluates to true.

type FieldRef ¶

type FieldRef struct {
	Name string
}

FieldRef references a named schema field.

type FieldType ¶

type FieldType string

FieldType represents the logical type of a field.

const (
	FieldTypeString    FieldType = "string"
	FieldTypeInt       FieldType = "int"
	FieldTypeBool      FieldType = "bool"
	FieldTypeTimestamp FieldType = "timestamp"
)

type FunctionValue ¶

type FunctionValue struct {
	Name string
	Args []ValueExpr
}

FunctionValue captures simple function calls like size(tags).

type InCondition ¶

type InCondition struct {
	Left   ValueExpr
	Values []ValueExpr
}

InCondition represents an IN predicate.

Values can be:

• individual literals/params (e.g. id in [1,2,3])
• a single list param (e.g. id in project_ids)

type ListComprehensionCondition ¶

type ListComprehensionCondition struct {
	Kind      ComprehensionKind
	Field     string
	IterVar   string
	Predicate PredicateExpr
}

ListComprehensionCondition represents CEL macros like exists().

type LiteralValue ¶

type LiteralValue struct {
	Value any
}

LiteralValue holds a literal scalar.

type LogicalCondition ¶

type LogicalCondition struct {
	Operator LogicalOperator
	Left     Condition
	Right    Condition
}

LogicalCondition composes two conditions with a logical operator.

type LogicalOperator ¶

type LogicalOperator string

LogicalOperator enumerates the supported logical operators.

const (
	LogicalAnd LogicalOperator = "AND"
	LogicalOr  LogicalOperator = "OR"
)

type NotCondition ¶

type NotCondition struct {
	Expr Condition
}

NotCondition negates a child condition.

type ParamRef ¶

type ParamRef struct {
	Name string
}

ParamRef references a named CEL variable which is not a schema field.

Values are supplied at runtime via bindings (SQL rendering) or vars (in-memory evaluation).

type PredicateExpr ¶

type PredicateExpr interface {
	// contains filtered or unexported methods
}

PredicateExpr represents predicates used in comprehensions.

type Program ¶

type Program struct {
	// contains filtered or unexported fields
}

Program stores a compiled filter condition.

func NewProgramFromCondition(schema Schema, cond Condition) *Program

func (p *Program) ConditionTree() Condition

func (p *Program) IsCondGranted(vars map[string]any, opts ...EvalOptions) (bool, error)

func (p *Program) RenderSQL(bindings Bindings, opts RenderOptions) (Statement, error)

func (p *Program) Schema() Schema

type RenderOptions ¶

type RenderOptions struct {
	Dialect           DialectName
	PlaceholderOffset int
	// TableAliases maps schema column table names to SQL qualifiers (usually aliases).
	//
	// This is useful when the schema was defined against a concrete table name but
	// the actual query uses a table alias:
	//
	//   schema column: {Table: "project", Name: "id"}
	//   query: FROM project p
	//   opts: TableAliases{"project": "p"} -> renders "p.id"
	//
	// A mapped empty string disables qualification for that table.
	TableAliases map[string]string
	// OmitTableQualifier disables table qualification for all columns, rendering
	// "id" instead of "t.id".
	//
	// This is useful when composing fragments into queries that use different
	// aliases (or no alias).
	OmitTableQualifier bool
}

RenderOptions configure SQL rendering.

type SQLPredicate ¶

type SQLPredicate struct {
	SQL  DialectSQL
	Eval SQLPredicateEval
}

SQLPredicate defines a custom predicate which renders to dialect-specific SQL.

type SQLPredicateCondition ¶

type SQLPredicateCondition struct {
	Name string
	SQL  DialectSQL
	Args []ValueExpr
	Eval SQLPredicateEval
}

SQLPredicateCondition represents a custom predicate rendered as SQL.

Instances are produced by `sql("<name>")` or `sql("<name>", [...])`. See SQLPredicate / WithSQLPredicate for registration.

type SQLPredicateEval ¶

type SQLPredicateEval func(schema Schema, vars map[string]any, args []any, opts EvalOptions) (bool, error)

SQLPredicateEval evaluates a custom predicate in-memory.

The args slice contains resolved argument values (literals / param values). vars contains the full evaluation var map (schema fields and params).

Returning an error will fail evaluation.

type Schema ¶

type Schema struct {
	Name       string
	Fields     map[string]*Field
	EnvOptions []cel.EnvOption
}

Schema collects CEL environment options and field metadata.

func SchemaFromStruct(name, table string, model any) (Schema, error)

func (s Schema) Field(name string) (*Field, bool)

func (s Schema) ResolveAlias(name string) (*Field, bool)

type StartsWithCondition ¶

type StartsWithCondition struct {
	Field string
	Value ValueExpr
}

StartsWithCondition models the <field>.startsWith(<value>) call.

type StartsWithPredicate ¶

type StartsWithPredicate struct {
	Prefix ValueExpr
}

StartsWithPredicate represents t.startsWith(prefix).

type Statement ¶

type Statement struct {
	SQL  string
	Args []any
	// NamedArgs is populated when rendering with DialectPostgresNamedArgs.
	//
	// It is intended to be passed to pgx as `pgx.NamedArgs(stmt.NamedArgs)`:
	// `conn.Query(ctx, "SELECT ... WHERE "+stmt.SQL, pgx.NamedArgs(stmt.NamedArgs))`
	NamedArgs Bindings
}

Statement contains the rendered SQL fragment and its args.

func RenderCondition(schema Schema, cond Condition, bindings Bindings, opts RenderOptions) (Statement, error)

type ValueExpr ¶

type ValueExpr interface {
	// contains filtered or unexported methods
}

ValueExpr models scalar expressions whose result feeds a comparison.