Skip to content

Query Reference

Query

Synchronous query result with convenience methods.

Immutable — filter(), order_by(), limit() return a new Query. Reusable — each method creates a new stream.

filter 

filter(*filters: Any) -> Query[T]

Add filters to the query. Returns a new Query.

order_by 

order_by(*orders: Any) -> Query[T]

Add ordering. Accepts FieldDescriptor (ascending), Asc, or Desc.

limit 

limit(n: int) -> Query[T]

Limit the number of results. Returns a new Query.

to_list 

to_list() -> list[T]

Fetch all matching documents.

first 

first() -> T | None

Fetch the first matching document, or None.

one 

one() -> T

Fetch exactly one document. Raises if zero or more than one.

exists 

exists() -> bool

Check if any matching documents exist.

count 

count() -> int

Count matching documents using Firestore aggregation.

paginate 

paginate(page_size: int) -> Iterator[list[T]]

Iterate over pages of results.

AsyncQuery

Asynchronous query result with convenience methods.

Immutable — filter(), order_by(), limit() return a new AsyncQuery. Reusable — each method creates a new stream.

filter 

filter(*filters: Any) -> AsyncQuery[T]

Add filters to the query. Returns a new AsyncQuery.

order_by 

order_by(*orders: Any) -> AsyncQuery[T]

Add ordering. Accepts FieldDescriptor (ascending), Asc, or Desc.

limit 

limit(n: int) -> AsyncQuery[T]

Limit the number of results. Returns a new AsyncQuery.

to_list async 

to_list() -> list[T]

Fetch all matching documents.

first async 

first() -> T | None

Fetch the first matching document, or None.

one async 

one() -> T

Fetch exactly one document. Raises if zero or more than one.

exists async 

exists() -> bool

Check if any matching documents exist.

count async 

count() -> int

Count matching documents using Firestore aggregation.

paginate async 

paginate(page_size: int) -> AsyncIterator[list[T]]

Iterate over pages of results.

ProjectedQuery

Result of a projection query — iterates dict[str, Any] instead of model instances.

Returned by Query.project(). Only the projected fields are present in each dict.

to_list 

to_list() -> list[dict[str, Any]]

Fetch all matching documents as dicts.

first 

first() -> dict[str, Any] | None

Fetch the first matching document, or None.

AsyncProjectedQuery

Async result of a projection query — iterates dict[str, Any].

Returned by AsyncQuery.project(). Only the projected fields are present in each dict.

to_list async 

to_list() -> list[dict[str, Any]]

Fetch all matching documents as dicts.

first async 

first() -> dict[str, Any] | None

Fetch the first matching document, or None.

Asc

Bases: _Order

Ascending order.

Desc

Bases: _Order

Descending order.