Reading rows

A query runs when you call one of these. Which one you pick says how many rows you expect back.

All

Every matching row, as []*T. No matches means an empty result, not an error.

users, err := db.Users.Where(ant.Gt(&U.Age, 18)).All(ctx)
if err != nil {
	return err
}

for _, user := range users {
	fmt.Println(user.Name)
}

First

One row, or ant.ErrNotFoundvar ErrNotFound = errors.New("ant: not found")ErrNotFound reports that a query for one row matched none..

oldest, err := db.Users.OrderByDesc(&U.Age).First(ctx)
if errors.Is(err, ant.ErrNotFound) {
	return nil
}

Single

Exactly one row. You get ant.ErrNotFound if there's none, and ant.ErrMultipleRowsvar ErrMultipleRows = errors.New("ant: query matched more than one row")ErrMultipleRows reports that Single matched more than one row. if there's more, which suits looking up something that should be unique.

user, err := db.Users.Where(ant.Eq(&U.Email, "ada@example.com")).Single(ctx)

Find

One row by primary key, or ant.ErrNotFound. For a composite key, use FindKey.

user, err := db.Users.Find(ctx, id)

Each

Streams rows one at a time, for results too big to hold in memory. It's a Go iterator, and break releases the connection.

for user, err := range db.Users.OrderBy(&U.Name).Each(ctx) {
	if err != nil {
		return err
	}

	fmt.Println(user.Name)
}

If the query has a mistake, it arrives as the only item. Eachfunc (t *Table[T]) Each(ctx context.Context) iter.Seq2[T, error]Each streams every row. yields values, so its rows aren't tracked, and it refuses Includefunc (t *Table[T]) Include[R any](rel *[]R, shape ...func(*Query[R]) *Query[R]) *Query[T]Include starts a query that loads a one-to-many relation. because rows are still streaming in. Use Chunk for that.

Counting and checking

n, err := db.Users.Where(ant.Gt(&U.Age, 18)).Count(ctx)
found, err := db.Users.Where(ant.Eq(&U.Name, "Ada")).Exists(ctx)
missing, err := db.Users.Where(ant.Eq(&U.Name, "Ada")).DoesNotExist(ctx)

Count honors Limitfunc (t *Table[T]) Limit(n int) *Query[T]Limit starts a query capped at n rows., Offsetfunc (t *Table[T]) Offset(n int) *Query[T]Offset starts a query that skips n rows., and Distinctfunc (t *Table[T]) Distinct() *Query[T]Distinct starts a query that removes duplicate rows..

One column

ant.Pluckfunc Pluck[T, V any](ctx context.Context, q *Query[T], field *V) ([]V, error)Pluck returns one column of every matching row. reads a single column into a slice of its type. With a pointer column, NULLs stay nil.

names, err := ant.Pluck(ctx, db.Users.OrderBy(&U.Name), &U.Name)
bios, err := ant.Pluck(ctx, db.Users.Where(), &U.Bio)

Part of a row

Columnfunc (t *Table[T]) Column[V any](field *V) *Query[T]Column starts a query limited to the named column. and Omitfunc (t *Table[T]) Omit[V any](field *V) *Query[T]Omit starts a query that leaves a column out. load only some columns. The other fields keep their zero value, which is why these rows are never tracked: they can't be saved by mistake.

names, err := db.Users.Column(&U.ID).Column(&U.Name).All(ctx)
small, err := db.Users.Omit(&U.Bio).All(ctx)

Distinct

ages, err := db.Users.Column(&U.Age).Distinct().All(ctx)

Skipping the tracker

Results are tracked by default, so SaveChangesfunc (c *Context) SaveChanges(ctx context.Context) errorSaveChanges writes every change to tracked entities in one transaction: inserts and updates with parents first, then deletes with children first. can see what you change. For reads you won't change, NoTrackingfunc (t *Table[T]) NoTracking() *Query[T]NoTracking starts a query whose results are not tracked. skips the snapshot.

users, err := db.Users.NoTracking().Where(ant.Gt(&U.Age, 18)).All(ctx)

NoTrackingResolvedfunc (q *Query[T]) NoTrackingResolved() *Query[T]NoTrackingResolved is NoTracking, except that one row is one instance in the results, as it is with tracking. skips it too, but still gives each row a single instance, which helps when a read returns the same parent many times.

See it tested: tests/features/querying