QuerySet

QuerySet is the chainable query builder returned by Document.find(). It supports filtering, ordering, limiting, and terminal operations like .all(), .first(), .count(), .delete(), and .update().

Sync API (`coodie.sync`)

class coodie.sync.query.QuerySet(doc_cls: type[Document], *, where: list[tuple[str, str, Any]] | None = None, limit_val: int | None = None, order_by_val: list[str] | None = None, allow_filtering_val: bool = False, if_not_exists_val: bool = False, if_exists_val: bool = False, ttl_val: int | None = None, timestamp_val: int | None = None, consistency_val: str | None = None, timeout_val: float | None = None, only_val: list[str] | None = None, defer_val: list[str] | None = None, values_list_val: list[str] | None = None, per_partition_limit_val: int | None = None, fetch_size_val: int | None = None, paging_state_val: bytes | None = None, distinct_val: bool = False, group_by_val: list[str] | None = None, select_token_val: list[str] | None = None, cast_val: list[tuple[str, str]] | None = None, ann_of_val: tuple[str, list[float]] | None = None, validate_val: bool | None = None)

Bases: object

Synchronous chainable query builder.

filter(**kwargs: Any) → QuerySet

limit(n: int) → QuerySet

order_by(*cols: str) → QuerySet

order_by_ann(column: str, vector: list[float]) → QuerySet

Order results by approximate nearest neighbor (ANN) similarity.

Generates ORDER BY "column" ANN OF ? in the CQL query.

Parameters:

column – The vector column name.
vector – The query vector to compare against.

allow_filtering() → QuerySet

if_not_exists() → QuerySet

if_exists() → QuerySet

ttl(seconds: int) → QuerySet

timestamp(ts: int) → QuerySet

consistency(level: str) → QuerySet

timeout(seconds: float) → QuerySet

using(*, ttl: int | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None) → QuerySet

only(*columns: str) → QuerySet

defer(*columns: str) → QuerySet

values_list(*columns: str) → QuerySet

per_partition_limit(n: int) → QuerySet

fetch_size(n: int) → QuerySet

page(paging_state: bytes | None) → QuerySet

distinct() → QuerySet

group_by(*cols: str) → QuerySet

select_token(*cols: str) → QuerySet

cast(column: str, cql_type: str) → QuerySet

is_not_null(column: str) → QuerySet

is_null(column: str) → QuerySet

validate(enabled: bool = True) → QuerySet

Enable or disable Pydantic validation when hydrating rows.

By default, rows from the database are hydrated using model_construct() which skips validation for speed. Call .validate() to switch to model_validate() which performs full type coercion and runs custom validators — useful when driver-returned types may not match model field types exactly.

all(*, lazy: bool = False) → list[Document] | list[LazyDocument] | list[tuple[Any, ...]]

paged_all() → PagedResult

Execute query returning a PagedResult with documents and paging state.

When combined with order_by_ann(), ScyllaDB ANN queries do not support cursor-based pagination and will always return a single page with paging_state=None. Use limit() to control the number of results.

first() → Document | None

count() → int

aggregate(**funcs: str) → dict[str, Any]

Execute one or more aggregate functions.

Each keyword argument maps a result name to a "func(column)" expression. Example:

result = qs.aggregate(total="sum(price)", avg_price="avg(price)")
# result == {"total": 150.0, "avg_price": 30.0}

sum(column: str) → Any

avg(column: str) → Any

min(column: str) → Any

max(column: str) → Any

json() → list[str]: Execute SELECT JSON * FROM … and return a list of JSON strings.

writetime(column: str) → Any: Execute SELECT WRITETIME("col") FROM … and return the scalar result.

column_ttl(column: str) → Any: Execute SELECT TTL("col") FROM … and return the scalar result.

delete(if_conditions: dict[str, Any] | None = None) → LWTResult | None

create(**kwargs: Any) → LWTResult | None: Insert a new document. Respects if_not_exists(), ttl(), and timestamp() chain modifiers.

update(ttl: int | None = None, if_conditions: dict[str, Any] | None = None, **kwargs: Any) → None: Bulk UPDATE matching rows. TTL may be provided as a parameter or via the ttl() chain modifier.

Async API (`coodie.aio`)

class coodie.aio.query.QuerySet(doc_cls: type[Document], *, where: list[tuple[str, str, Any]] | None = None, limit_val: int | None = None, order_by_val: list[str] | None = None, allow_filtering_val: bool = False, if_not_exists_val: bool = False, if_exists_val: bool = False, ttl_val: int | None = None, timestamp_val: int | None = None, consistency_val: str | None = None, timeout_val: float | None = None, only_val: list[str] | None = None, defer_val: list[str] | None = None, values_list_val: list[str] | None = None, per_partition_limit_val: int | None = None, fetch_size_val: int | None = None, paging_state_val: bytes | None = None, distinct_val: bool = False, group_by_val: list[str] | None = None, select_token_val: list[str] | None = None, cast_val: list[tuple[str, str]] | None = None, ann_of_val: tuple[str, list[float]] | None = None, validate_val: bool | None = None)