Document

The Document class is the core building block of coodie. It maps a Pydantic v2 model to a Cassandra / ScyllaDB table. coodie provides both synchronous and asynchronous variants.

Sync API (coodie.sync)

class coodie.sync.document.Document

Bases: BaseModel

Base class for synchronous coodie documents.

class Settings

Bases: object

name: str = ''
keyspace: str = ''
classmethod sync_table(dry_run: bool = False, drop_removed_indexes: bool = False) → list[str]

Idempotently create or update the table in the database.

Parameters:

  • dry_run – When True, return the planned CQL statements without executing them.

  • drop_removed_indexes – When True, drop secondary indexes that exist in the database but are no longer defined in the model.

Returns:

List of CQL statements that were (or would be) executed.

classmethod table_name() → str

Return the CQL table name for this model.

classmethod drop_table() → None

Drop the table for this model.

classmethod truncate() → None

Truncate (remove all rows from) the table for this model.

classmethod create(**kwargs: Any) → Document

Construct and save a new document in one step.

save(ttl: int | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None, batch: BatchQuery | None = None) → None

Insert (upsert) this document.

save_json(ttl: int | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None) → None

Insert (upsert) this document using INSERT INTO … JSON.

insert(ttl: int | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None, batch: BatchQuery | None = None) → None

Insert IF NOT EXISTS (create-only).

delete_columns(*column_names: str, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None, batch: BatchQuery | None = None, collection_elements: list[tuple[str, Any]] | None = None) → None

Set one or more non-primary-key columns to null for this document.

Generates DELETE col1, col2 FROM table WHERE pk = ?.

When collection_elements is provided, each (column, key_or_index) tuple generates DELETE "col"[?] FROM table WHERE pk = ? which removes a single map entry or list element.

Warning

This operation nullifies column values in-place and bypasses the schema-migration system. If you are removing or renaming a column, use coodie’s migration tools instead: Document.sync_table() for development environments, or coodie migrate (the CLI) for production deployments.

delete(if_exists: bool = False, if_conditions: dict[str, Any] | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None, batch: BatchQuery | None = None) → LWTResult | None

Delete this document by its primary key.

When if_exists is True the generated CQL includes IF EXISTS and a LWTResult is returned.

When if_conditions is supplied (e.g. {"name": "old"}), the CQL includes IF name = ? and a LWTResult is returned. Operator suffixes like col__ne, col__gt, col__in are supported.

update(*, if_conditions: dict[str, Any] | None = None, if_exists: bool = False, ttl: int | None = None, **kwargs: Any) → LWTResult | None

Partial update — sets only the given fields.

Supports collection operations via parse_update_kwargs (e.g. add__, remove__ prefixed keys).

When if_conditions or if_exists is supplied the generated CQL includes a lightweight-transaction clause and a LWTResult is returned.

classmethod find(**kwargs: Any) → QuerySet

Return a QuerySet filtered by kwargs.

classmethod find_one(**kwargs: Any) → Document | None

Return a single document or None.

classmethod get(**kwargs: Any) → Document

Return a single document; raise DocumentNotFound if missing.

model_config = {'arbitrary_types_allowed': True, 'populate_by_name': True, 'revalidate_instances': 'never', 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class coodie.sync.document.CounterDocument

Bases: Document

Base class for synchronous counter-column documents.

Counter tables only support increment/decrement operations. save() and insert() are forbidden.

save(ttl: int | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None) → None

Insert (upsert) this document.

insert(ttl: int | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None) → None

Insert IF NOT EXISTS (create-only).

increment(**field_deltas: int) → None

Increment counter columns by the given amounts.

Example:

page_view.increment(view_count=1, unique_visitors=1)
decrement(**field_deltas: int) → None

Decrement counter columns by the given amounts.

Example:

page_view.decrement(view_count=1)
model_config = {'arbitrary_types_allowed': True, 'populate_by_name': True, 'revalidate_instances': 'never', 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class coodie.sync.document.MaterializedView

Bases: Document

Base class for synchronous materialized view documents (read-only).

Subclasses must define Settings with:

  • __base_table__ — the base table name (required).

  • __view_columns__ — columns to select (defaults to ["*"]).

  • __where_clause__ — the WHERE clause (defaults to auto-generated IS NOT NULL for all primary-key/clustering columns).

  • __clustering_order__ — optional {column: "ASC"|"DESC"} dict.

The view name defaults to the model’s table name.

classmethod sync_view() → None

Create the materialized view in the database.

classmethod drop_view() → None

Drop the materialized view.

save(**kwargs: Any) → None

Insert (upsert) this document.

insert(**kwargs: Any) → None

Insert IF NOT EXISTS (create-only).

delete(**kwargs: Any) → LWTResult | None

Delete this document by its primary key.

When if_exists is True the generated CQL includes IF EXISTS and a LWTResult is returned.

When if_conditions is supplied (e.g. {"name": "old"}), the CQL includes IF name = ? and a LWTResult is returned. Operator suffixes like col__ne, col__gt, col__in are supported.

update(**kwargs: Any) → LWTResult | None

Partial update — sets only the given fields.

Supports collection operations via parse_update_kwargs (e.g. add__, remove__ prefixed keys).

When if_conditions or if_exists is supplied the generated CQL includes a lightweight-transaction clause and a LWTResult is returned.

model_config = {'arbitrary_types_allowed': True, 'populate_by_name': True, 'revalidate_instances': 'never', 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Async API (coodie.aio)

class coodie.aio.document.Document

Bases: BaseModel

Base class for asynchronous coodie documents.

class Settings

Bases: object

name: str = ''
keyspace: str = ''
async classmethod sync_table(dry_run: bool = False, drop_removed_indexes: bool = False) → list[str]

Idempotently create or update the table in the database.

Parameters:

  • dry_run – When True, return the planned CQL statements without executing them.

  • drop_removed_indexes – When True, drop secondary indexes that exist in the database but are no longer defined in the model.

Returns:

List of CQL statements that were (or would be) executed.

classmethod table_name() → str

Return the CQL table name for this model.

async classmethod drop_table() → None

Drop the table for this model.

async classmethod truncate() → None

Truncate (remove all rows from) the table for this model.

async classmethod create(**kwargs: Any) → Document

Construct and save a new document in one step.

async save(ttl: int | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None, batch: AsyncBatchQuery | None = None) → None

Insert (upsert) this document.

async save_json(ttl: int | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None) → None

Insert (upsert) this document using INSERT INTO … JSON.

async insert(ttl: int | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None, batch: AsyncBatchQuery | None = None) → None

Insert IF NOT EXISTS (create-only).

async delete_columns(*column_names: str, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None, batch: AsyncBatchQuery | None = None, collection_elements: list[tuple[str, Any]] | None = None) → None

Set one or more non-primary-key columns to null for this document.

Generates DELETE col1, col2 FROM table WHERE pk = ?.

When collection_elements is provided, each (column, key_or_index) tuple generates DELETE "col"[?] FROM table WHERE pk = ? which removes a single map entry or list element.

Warning

This operation nullifies column values in-place and bypasses the schema-migration system. If you are removing or renaming a column, use coodie’s migration tools instead: Document.sync_table() for development environments, or coodie migrate (the CLI) for production deployments.

async delete(if_exists: bool = False, if_conditions: dict[str, Any] | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None, batch: AsyncBatchQuery | None = None) → LWTResult | None

Delete this document by its primary key.

When if_exists is True the generated CQL includes IF EXISTS and a LWTResult is returned.

When if_conditions is supplied (e.g. {"name": "old"}), the CQL includes IF name = ? and a LWTResult is returned. Operator suffixes like col__ne, col__gt, col__in are supported.

async update(*, if_conditions: dict[str, Any] | None = None, if_exists: bool = False, ttl: int | None = None, **kwargs: Any) → LWTResult | None

Partial update — sets only the given fields.

Supports collection operations via parse_update_kwargs (e.g. add__, remove__ prefixed keys).

When if_conditions or if_exists is supplied the generated CQL includes a lightweight-transaction clause and a LWTResult is returned.

classmethod find(**kwargs: Any) → QuerySet

Return an async QuerySet filtered by kwargs.

async classmethod find_one(**kwargs: Any) → Document | None

Return a single document or None.

async classmethod get(**kwargs: Any) → Document

Return a single document; raise DocumentNotFound if missing.

model_config = {'arbitrary_types_allowed': True, 'populate_by_name': True, 'revalidate_instances': 'never', 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class coodie.aio.document.CounterDocument

Bases: Document

Base class for asynchronous counter-column documents.

Counter tables only support increment/decrement operations. save() and insert() are forbidden.

async save(ttl: int | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None) → None

Insert (upsert) this document.

async insert(ttl: int | None = None, timestamp: int | None = None, consistency: str | None = None, timeout: float | None = None) → None

Insert IF NOT EXISTS (create-only).

async increment(**field_deltas: int) → None

Increment counter columns by the given amounts.

Example:

await page_view.increment(view_count=1, unique_visitors=1)
async decrement(**field_deltas: int) → None

Decrement counter columns by the given amounts.

Example:

await page_view.decrement(view_count=1)
model_config = {'arbitrary_types_allowed': True, 'populate_by_name': True, 'revalidate_instances': 'never', 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class coodie.aio.document.MaterializedView

Bases: Document

Base class for asynchronous materialized view documents (read-only).

Subclasses must define Settings with:

  • __base_table__ — the base table name (required).

  • __view_columns__ — columns to select (defaults to ["*"]).

  • __where_clause__ — the WHERE clause (defaults to auto-generated IS NOT NULL for all primary-key/clustering columns).

  • __clustering_order__ — optional {column: "ASC"|"DESC"} dict.

The view name defaults to the model’s table name.

async classmethod sync_view() → None

Create the materialized view in the database.

async classmethod drop_view() → None

Drop the materialized view.

async save(**kwargs: Any) → None

Insert (upsert) this document.

async insert(**kwargs: Any) → None

Insert IF NOT EXISTS (create-only).

async delete(**kwargs: Any) → LWTResult | None

Delete this document by its primary key.

When if_exists is True the generated CQL includes IF EXISTS and a LWTResult is returned.

When if_conditions is supplied (e.g. {"name": "old"}), the CQL includes IF name = ? and a LWTResult is returned. Operator suffixes like col__ne, col__gt, col__in are supported.

async update(**kwargs: Any) → LWTResult | None

Partial update — sets only the given fields.

Supports collection operations via parse_update_kwargs (e.g. add__, remove__ prefixed keys).

When if_conditions or if_exists is supplied the generated CQL includes a lightweight-transaction clause and a LWTResult is returned.

model_config = {'arbitrary_types_allowed': True, 'populate_by_name': True, 'revalidate_instances': 'never', 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].