Update and delete

Updatefunc (q *Query[T]) Update(ctx context.Context, a ...Assignment) (int64, error)Update applies assignments to every matching row and returns the number of rows changed. and Deletefunc (q *Query[T]) Delete(ctx context.Context) (int64, error)Delete removes every matching row and returns the number removed. write straight to the database, without loading anything, and tell you how many rows they touched. To change things you've loaded, use SaveChanges.

Update

Every assignment is explicit, so zero values and nil are written like any other.

n, err := db.Users.
	Where(ant.Eq(&U.ID, id)).
	Update(ctx, ant.Set(&U.Age, 0), ant.Set(&U.Bio, nil))

UPDATE "users" SET "age" = $1, "bio" = $2, "updated_at" = $3 WHERE "users"."id" = $4

UpdatedAt moves by itself. An explicit ant.Set(&U.UpdatedAt, t)func Set[V any](field *V, v V) AssignmentSet assigns v to field. wins.

Values from the row

Inc and Dec run in the database, so two writers can't lose each other's update. SetExpr assigns any expression, a subquery included.

_, err := db.Users.Where(ant.Eq(&U.ID, id)).Update(ctx, ant.Inc(&U.Age, 1))

_, err = db.Users.Where(ant.Eq(&U.ID, id)).Update(ctx, ant.SetExpr(&U.Email, ant.Lower(&U.Name)))

oldest := ant.SubExpr(db.Users.Where(), ant.Max(&U.Age)).Expr()

_, err = db.Users.Where(ant.Eq(&U.ID, id)).Update(ctx, ant.SetExpr(&U.Age, oldest))

Delete

n, err := db.Users.Where(ant.Lt(&U.Age, 18)).Delete(ctx)

On a model with soft deletes this marks rows instead of removing them. Conditions can use relations, which is how to delete with a join.

n, err := db.Users.Where(ant.HasNone(&U.Posts)).Delete(ctx)

One row by key is DeleteByIDfunc (t *Table[T]) DeleteByID[K comparable](ctx context.Context, key K) errorDeleteByID removes the entity with the given primary key, and stops tracking it, or returns ErrNotFound., which returns ant.ErrNotFoundvar ErrNotFound = errors.New("ant: not found")ErrNotFound reports that a query for one row matched none. if there's no such row.

err := db.Users.DeleteByID(ctx, id)

The no-condition guard

A bulk write with no condition is refused with ant.ErrNoConditionvar ErrNoCondition = errors.New("ant: bulk write has no condition")ErrNoCondition reports a bulk write with no condition., because a forgotten filter would otherwise change the whole table. Unfilteredfunc (t *Table[T]) Unfiltered() *Query[T]Unfiltered starts a query whose Update or Delete affects every row. says you really mean it.

_, err := db.Users.Query().Delete(ctx) // ant.ErrNoCondition

n, err := db.Users.Unfiltered().Delete(ctx) // every row, on purpose

The guard also sees through conditions that can't exclude a row. Those are the dangerous ones, because the code looks filtered.

var none []string

_, err := db.Users.Where(ant.And()).Delete(ctx)                  // refused
_, err = db.Users.Where(ant.NotIn(&U.Name, none...)).Delete(ctx) // refused

n, err := db.Users.Where(ant.In(&U.Name, none...)).Delete(ctx) // fine: deletes nothing

A Whenfunc (q *Query[T]) When(ok bool, f func(*Query[T]) *Query[T]) *Query[T]When applies f only if ok is true, for conditions decided at runtime. that was skipped leaves the guard on too.

Limiting a write

Limitfunc (t *Table[T]) Limit(n int) *Query[T]Limit starts a query capped at n rows. and Offsetfunc (t *Table[T]) Offset(n int) *Query[T]Offset starts a query that skips n rows. bound a bulk write, oldest first with an ordering.

n, err := db.Users.Where(ant.Lt(&U.Age, 18)).OrderBy(&U.CreatedAt).Limit(100).Delete(ctx)

Getting the rows back

UpdateReturningfunc (q *Query[T]) UpdateReturning(ctx context.Context, a ...Assignment) ([]*T, error)UpdateReturning is Update, returning the changed rows. and DeleteReturningfunc (q *Query[T]) DeleteReturning(ctx context.Context) ([]*T, error)DeleteReturning is Delete, returning the removed rows. give back what they touched. Support varies: see databases.

changed, err := db.Users.Where(ant.Gt(&U.Age, 18)).UpdateReturning(ctx, ant.Inc(&U.Age, 1))

removed, err := db.Users.Where(ant.Eq(&U.Name, "Bob")).DeleteReturning(ctx)

Reloading an entity

Reloadfunc (t *Table[T]) Reload(ctx context.Context, e *T) errorReload overwrites the columns of e with the stored row, found by e's primary key, or returns ErrNotFound. replaces an entity's columns with what is stored now, discarding unsaved changes. Relations are left alone.

_, err := db.Users.Where(ant.Eq(&U.ID, user.ID)).Update(ctx, ant.Set(&U.Age, 41))

err = db.Users.Reload(ctx, user)

Bulk writes skip the model layer

Update and Delete run no hooks and no SaveInterceptor, because they load no entities, and a bulk update doesn't touch tracked structs. They do apply global filters and timestamps.

See it tested: tests/features/writing