fn

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package fn is the ORM's expressions over Vuka field references, typed: each takes field references (Post.Title, Post.Author.Name) or other terms and gives an orm.Term of the Go type the database computes, so only the comparisons that make sense type-check. 

Post.Objects.Filter(fn.Lower(Post.Title).Eq("go"), fn.Year(Post.Published).Ge(2025))
Post.Objects.Annotate(fn.Count(Post.Tags).As("tags")).OrderBy(fn.Length(Post.Title).Desc())
Post.Objects.Update(ctx, orm.AssignF(Post.Views, fn.Num(Post.Views).Add(1)))

The names are the engine's (orm.Count, orm.Lower, …), which take field names as strings; this package is their Vuka form.

Deprecated: Vuka now writes a model's field as its typed field (PostFields.Title), whose Expr and Name the engine's functions take: orm.Lower(Post.Title.Expr()). Package fn goes in the next minor release.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Abs 

func Abs[T any, V Number](a orm.Arg[T, V]) orm.OrderedTerm[T, V]

Abs is a number's absolute value.

func Call 

func Call[R, T, V any](f interface{ Of(args ...any) orm.Expr }, a orm.Arg[T, V], rest ...any) orm.Term[T, R]

Call is a database function — orm.Function's, or a typed orm.Func's — called on field references and values, as a term of T typed R: 

var unaccent = orm.Function("unaccent")
fn.Str(fn.Call[string](unaccent, Post.Title)).IContains("jose")

func Cast 

func Cast[R, T, V any](a orm.Arg[T, V], t orm.CastType) orm.Term[T, R]

Cast converts to the database type t (orm.AsInt, orm.AsText, …); R is the Go type it reads as: fn.Cast[int64](Post.Code, orm.AsInt).

func Coalesce 

func Coalesce[T, V any](a orm.Arg[T, V], rest ...any) orm.Term[T, V]

Coalesce is the first of its arguments that isn't NULL; the term is of the first's type.

func CosineDistance 

func CosineDistance[T any](field orm.Arg[T, orm.Vector], v orm.Vector) orm.OrderedTerm[T, float64]

func Date 

func Date[T, V any](a orm.Arg[T, V]) orm.Term[T, string]

func Day 

func Day[T, V any](a orm.Arg[T, V]) orm.OrderedTerm[T, int64]

func Exists 

func Exists[T, R any](q orm.Query[R]) vuka.Pred[T]

Exists holds for the rows of T another model's query has a row for (with OuterEq, a related row).

func Fuse 

func Fuse[T any](orders ...orm.TermOrder[T]) orm.OrderedTerm[T, float64]

Fuse is reciprocal-rank fusion of orderings by named terms (hybrid search): order by it descending. 

rank := fn.SearchRank(doc, q).As("rank")
dist := fn.CosineDistance(Doc.Embedding, v).As("dist")
Doc.Objects.Annotate(rank, dist, fn.Fuse(rank.Desc(), dist.Asc()).As("score")).OrderBy(...)

func Headline 

func Headline[T any, V ~string](a orm.Arg[T, V], q orm.TextQuery) orm.StringTerm[T, string]

Headline is a field's text with q's matches marked.

func In 

func In[T, R, V, W any](a orm.Arg[T, V], q orm.Query[R], col orm.Arg[R, W]) vuka.Pred[T]

In holds where a field of T is among a column of another model's query (the types may differ: a key and an orm.FK to its row).

func InnerProduct 

func InnerProduct[T any](field orm.Arg[T, orm.Vector], v orm.Vector) orm.OrderedTerm[T, float64]

func L2Distance 

func L2Distance[T any](field orm.Arg[T, orm.Vector], v orm.Vector) orm.OrderedTerm[T, float64]

L2Distance, CosineDistance and InnerProduct are a vector field's distance to v.

func Length 

func Length[T any, V ~string](a orm.Arg[T, V]) orm.OrderedTerm[T, int64]

Length is a string's length in characters.

func Lit 

func Lit[T, V any](v V) orm.Term[T, V]

Lit is a value as a term of the model T: fn.Lit[Post]("PLACEMENT").

func Lower 

func Lower[T any, V ~string](a orm.Arg[T, V]) orm.StringTerm[T, V]

Lower, Upper and Trim are the string functions.

func Match 

func Match[T any](d orm.SearchDoc[T], q orm.TextQuery) vuka.Pred[T]

Match holds for the rows whose document matches q (orm.SearchQuery).

func Month 

func Month[T, V any](a orm.Arg[T, V]) orm.OrderedTerm[T, int64]

func Num 

func Num[T any, V cmp.Ordered](a orm.Arg[T, V]) orm.OrderedTerm[T, V]

Num, Str, Val and Time make a field reference (or term) a term, for arithmetic and comparisons with other fields: fn.Num(Post.Views).Add(1), fn.Num(Post.Views).GtF(Post.Likes).

func OuterEq 

func OuterEq[T, U, V, W any](inner orm.Arg[T, V], outer orm.Arg[U, W]) vuka.Pred[T]

OuterEq is the predicate of a subquery that its field equals a field of the query it stands in, Django's OuterRef: Post.Objects.Filter(fn.OuterEq(Post.Author, User.ID)).

func OuterRef 

func OuterRef[U, W any](outer orm.Arg[U, W]) orm.Expr

OuterRef is a field of the query a subquery stands in, as an expression for templates and functions.

func SQL 

func SQL[R, T, V any](template string, a orm.Arg[T, V], rest ...any) orm.Term[T, R]

SQL is a template ({0}, {1}, …) of field references, terms and values, typed R: the escape hatch for what has no function.

func SearchRank 

func SearchRank[T any](d orm.SearchDoc[T], q orm.TextQuery) orm.OrderedTerm[T, float64]

SearchRank is how well the document matches q.

func SearchVector 

func SearchVector[T any](fields ...orm.Path[T]) orm.SearchDoc[T]

SearchVector is fields as a document: orm.Search's.

func Similarity 

func Similarity[T any, V ~string](a orm.Arg[T, V], term string) orm.OrderedTerm[T, float64]

Similarity is the trigram similarity of a field's text and term.

func Str 

func Str[T any, V ~string](a orm.Arg[T, V]) orm.StringTerm[T, V]

func Subquery 

func Subquery[T, R, V any](q orm.Query[R], col orm.Arg[R, V]) orm.Term[T, V]

Subquery is a column of another model's query as a term of T: its first row's (order and limit the query). 

latest := Post.Objects.Filter(fn.OuterEq(Post.Author, User.ID)).OrderBy(Post.Published.Desc()).Limit(1)
User.Objects.Annotate(fn.Subquery[User](latest, Post.Title).As("latest"))

func Time 

func Time[T any](a orm.Arg[T, time.Time]) orm.CompareTerm[T, time.Time]

func Trim 

func Trim[T any, V ~string](a orm.Arg[T, V]) orm.StringTerm[T, V]

func Upper 

func Upper[T any, V ~string](a orm.Arg[T, V]) orm.StringTerm[T, V]

func Val 

func Val[T, V any](a orm.Arg[T, V]) orm.Term[T, V]

func Year 

func Year[T, V any](a orm.Arg[T, V]) orm.OrderedTerm[T, int64]

Year, Month and Day are parts of a time (a time.Time, *time.Time or Option[time.Time] field); Date its date.

Types

type Agg 

type Agg[T any, V cmp.Ordered] struct {
	orm.OrderedTerm[T, V]
	// contains filtered or unexported fields
}

Agg is an aggregate term: Filter and Distinct give its variants.

func Avg 

func Avg[T any, V Number](a orm.Arg[T, V]) Agg[T, float64]

func Count 

func Count[T any](p orm.Path[T]) Agg[T, int64]

Count, Sum, Avg, Min and Max aggregate a field: of the rows, of related rows through a relation (fn.Count(Post.Tags) counts tags).

func Max 

func Max[T any, V cmp.Ordered](a orm.Arg[T, V]) Agg[T, V]

func Min 

func Min[T any, V cmp.Ordered](a orm.Arg[T, V]) Agg[T, V]

func Sum 

func Sum[T any, V Number](a orm.Arg[T, V]) Agg[T, V]

func (Agg[T, V]) Distinct 

func (a Agg[T, V]) Distinct() Agg[T, V]

Distinct aggregates each distinct value once.

func (Agg[T, V]) Filter 

func (a Agg[T, V]) Filter(p vuka.Pred[T]) Agg[T, V]

Filter aggregates only the rows p holds for (Django's filter=).

type Branch 

type Branch[T, V any] struct {
	// contains filtered or unexported fields
}

Branch is a Case's: a predicate and the result where it holds.

func When 

func When[T, V any](p vuka.Pred[T], then V) Branch[T, V]

When is a Case branch: then where p holds.

type CaseTerm 

type CaseTerm[T, V any] struct {
	orm.Term[T, V]
	// contains filtered or unexported fields
}

CaseTerm is a Case: the result of its first branch whose predicate holds, else Else's, else NULL.

func Case 

func Case[T, V any](branches ...Branch[T, V]) CaseTerm[T, V]

Case is Django's Case/When, typed by its results: 

fn.Case(fn.When(Post.Views.Gt(100), "hot"), fn.When(Post.Views.Gt(10), "warm")).Else("cold")

func (CaseTerm[T, V]) Else 

func (c CaseTerm[T, V]) Else(v V) orm.Term[T, V]

Else is the result where no branch holds.

type FilteredRel 

type FilteredRel[T, R any] struct {
	// contains filtered or unexported fields
}

FilteredRel is a relation whose rows are only those a predicate holds for, Django's FilteredRelation. Name it with As, Annotate it, then read through it with Field and Count.

func FilteredRelation 

func FilteredRelation[T, R any](rel orm.Path[T], p vuka.Pred[R]) FilteredRel[T, R]

FilteredRelation is rel (a relation of T to R) with the rows p holds for. 

g := fn.FilteredRelation(Post.Tags, Tag.Name.StartsWith("g")).As("gtags")
Post.Objects.Annotate(g, g.Count().As("n"))

func (FilteredRel[T, R]) Annotation 

func (f FilteredRel[T, R]) Annotation() orm.Term[T, R]

Annotation makes it something Annotate takes.

func (FilteredRel[T, R]) As 

func (f FilteredRel[T, R]) As(name string) FilteredRel[T, R]

As names the relation.

func (FilteredRel[T, R]) Count 

func (f FilteredRel[T, R]) Count() Agg[T, int64]

Count counts the related rows.

func (FilteredRel[T, R]) Field 

func (f FilteredRel[T, R]) Field[V any](a orm.Arg[R, V]) orm.Term[T, V]

Field is a field of the related rows, read through the relation.

type Number 

type Number interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~float32 | ~float64
}

Number is what Sum and arithmetic take.

type SwitchTerm 

type SwitchTerm[T, V, R any] struct {
	orm.Term[T, R]
	// contains filtered or unexported fields
}

SwitchTerm is a Switch: a term of its results' type R.

func (SwitchTerm[T, V, R]) Case 

func (s SwitchTerm[T, V, R]) Case(v V, then R) SwitchTerm[T, V, R]

Case adds a branch; Else gives the result where no value equals.

func (SwitchTerm[T, V, R]) Else 

func (s SwitchTerm[T, V, R]) Else(r R) orm.Term[T, R]

type Switcher 

type Switcher[T, V any] struct {
	// contains filtered or unexported fields
}

Switcher is a Switch before its first Case.

func Switch 

func Switch[T, V any](a orm.Arg[T, V]) Switcher[T, V]

Switch compares a field or term with values, Case by Case: 

fn.Switch(Post.Status).Case("paid", 1).Case("refunded", -1).Else(0)

func (Switcher[T, V]) Case 

func (s Switcher[T, V]) Case[R any](v V, then R) SwitchTerm[T, V, R]

Case is the first branch: then, of type R, where the switch equals v.

Source Files

View all Source files

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.