AsyncQueryBuilder

Async fluent query API returned by AsyncSqliterDB.select().

results = await db.select(User).filter(active=True).fetch_all()

Source: sqliter/asyncio/query.py

See also: Guide -- Asyncio Support

Construction

Instances are created by:

query = db.select(User)

Do not instantiate AsyncQueryBuilder directly.

Chain-Building Methods

These methods mirror the sync query builder and return self for chaining:

• filter(**conditions)
• fields(fields)
• exclude(fields)
• only(field)
• order(field, reverse=False)
• limit(count)
• offset(count)
• bypass_cache()
• cache_ttl(ttl)
• group_by(*fields)
• annotate(**aggregates)
• having(**conditions)
• select_related(*paths)
• prefetch_related(*paths)
• with_count(path, alias="count", distinct=False)

only() accepts exactly one field, matching the sync query builder.

Async Terminal Methods

These methods execute SQL and must be awaited:

fetch_all()

async def fetch_all(self) -> list[T]:

fetch_one()

async def fetch_one(self) -> T | None:

fetch_first()

async def fetch_first(self) -> T | None:

fetch_last()

async def fetch_last(self) -> T | None:

fetch_dicts()

For projection and aggregate queries:

async def fetch_dicts(self) -> list[dict[str, object]]:

count()

async def count(self) -> int:

exists()

async def exists(self) -> bool:

update()

Bulk update matching rows:

async def update(self, values: dict[str, Any]) -> int:

Relationship traversal filters, such as author__name="Ada", are not supported for bulk updates. Filter on fields from the model being updated.

delete()

Bulk delete matching rows:

async def delete(self) -> int:

Relationship traversal filters, such as author__name="Ada", are not supported for bulk deletes. Filter on fields from the model being deleted.

Example

report = await (
    db.select(User)
    .group_by("status")
    .annotate(total=func.count())
    .fetch_dicts()
)

Relationship Loading

AsyncQueryBuilder supports the same eager loading features as the sync query builder:

• select_related() for forward foreign keys
• prefetch_related() for reverse relationships and many-to-many
• with_count() for relationship counts

When async ORM models are used, these return async-compatible relationship wrappers on the fetched instances.