coodie logo

coodie

The modern Pydantic-based ODM for Cassandra & ScyllaDB

Cassandra + Beanie (hoodie) = coodie 🧥

CI Status Docs Coverage PyPI Downloads Python License

📖 Documentation • 🚀 Quick Start • 🤝 Contributing • 📋 Changelog

Define your data models as Python classes, and coodie handles schema synchronization, serialization, and query building — with both sync and async APIs.

✨ Feature Highlights

🧬 Pydantic v2 Models — full type-checking & validation
⚡ Sync & Async — coodie.sync for blocking, coodie.aio for asyncio
🔗 Chainable QuerySet — .filter() · .limit() · .order_by()

🔄 Automatic Schema Sync — sync_table() creates & evolves tables
🏗️ Batch & LWT — BatchQuery + if_not_exists() support
🎯 Multi-Driver — scylla-driver · cassandra-driver · acsylla
🔍 Vector Search — Vector(dimensions=N) + order_by_ann() for ANN queries

🔍 How Does coodie Compare?

Feature coodie beanie cqlengine
Database Cassandra / ScyllaDB MongoDB Cassandra
Schema Definition Pydantic v2 BaseModel Pydantic v2 BaseModel Custom columns.* classes
Type Hints ✅ Native Annotated[] ✅ Native Pydantic ❌ No type hints
Async Support ✅ First-class ✅ First-class ❌ Sync only
Sync Support ✅ coodie.sync ❌ Async only ✅ Sync only
Query API Chainable QuerySet Chainable FindMany Chainable QuerySet
Schema Migration ✅ sync_table() ❌ Manual ✅ sync_table()
LWT (Compare-and-Set) ✅ if_not_exists() N/A ✅ iff()
Batch Operations ✅ BatchQuery ❌ ✅ BatchQuery
Counter Columns ✅ Counter() ❌ ✅ columns.Counter
User-Defined Types ✅ UserType ❌ ✅ UserType
TTL Support ✅ Per-save TTL ❌ ✅ Per-save TTL
Pagination ✅ Token-based PagedResult ✅ Cursor-based ❌ Manual
Multiple Drivers ✅ 3 drivers motor only cassandra-driver only
Polymorphic Models ✅ Discriminator ❌ ❌
Vector Search (ANN) ✅ Vector() + order_by_ann() ❌ ❌
Python Version 3.10+ 3.8+ 3.6+

📦 Installation

pip install coodie

Choose a driver extra for your cluster:

pip install "coodie[scylla]"      # ScyllaDB / Cassandra (recommended)
pip install "coodie[cassandra]"   # Cassandra via cassandra-driver
pip install "coodie[acsylla]"     # Async-native via acsylla

🚀 Quick Start

1. Start a local ScyllaDB (or use an existing cluster):

docker run --name scylla -d -p 9042:9042 scylladb/scylla --smp 1

# Wait for it to be ready (~30s), then create a keyspace
docker exec -it scylla cqlsh -e \
  "CREATE KEYSPACE IF NOT EXISTS my_ks
   WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};"

2. Install coodie:

pip install "coodie[scylla]"

3. Write your first script:

from coodie.sync import Document, init_coodie
from coodie.fields import PrimaryKey
from pydantic import Field
from typing import Annotated
from uuid import UUID, uuid4

# Connect
init_coodie(hosts=["127.0.0.1"], keyspace="my_ks")

# Define a model
class User(Document):
    id: Annotated[UUID, PrimaryKey()] = Field(default_factory=uuid4)
    name: str
    email: str

    class Settings:
        name = "users"

# Sync schema & insert
User.sync_table()
user = User(name="Alice", email="alice@example.com")
user.save()

# Query
print(User.find(name="Alice").allow_filtering().all())

💡 Async? Just swap coodie.sync for coodie.aio and add await — that's it!

📖 Usage

Define a Document 
from typing import Annotated
from uuid import UUID, uuid4
from pydantic import Field
from coodie import Document, PrimaryKey, ClusteringKey, Indexed

class Product(Document):
    id: Annotated[UUID, PrimaryKey()] = Field(default_factory=uuid4)
    category: Annotated[str, ClusteringKey()] = "general"
    name: str
    brand: Annotated[str, Indexed()] = "Unknown"
    price: float = 0.0

    class Settings:
        name = "products"      # table name (defaults to snake_case class name)
        keyspace = "my_ks"
Async API — coodie / coodie.aio 
import asyncio
from coodie import init_coodie
# Product defined above — same field definitions, using coodie.aio.Document

async def main():
    await init_coodie(hosts=["127.0.0.1"], keyspace="my_ks")
    await Product.sync_table()

    p = Product(name="Gadget", brand="Acme", price=9.99)
    await p.save()

    results = await Product.find(brand="Acme").limit(10).all()
    for product in results:
        print(product.name, product.price)

    gadget = await Product.get(id=p.id)
    await gadget.delete()

asyncio.run(main())
Sync API — coodie.sync 
from coodie.sync import Document, init_coodie

class Product(Document):
    ...  # same field definitions

init_coodie(hosts=["127.0.0.1"], keyspace="my_ks")
Product.sync_table()

p = Product(name="Widget", price=4.99)
p.save()

results = Product.find(brand="Acme").allow_filtering().all()
one = Product.find_one(name="Widget")
QuerySet Chaining 
# Filter, sort, and limit
products = (
    await Product.find()
    .filter(brand="Acme")
    .order_by("price")
    .limit(20)
    .all()
)

# Count
n = await Product.find(brand="Acme").allow_filtering().count()

# Async iteration
async for p in Product.find(brand="Acme"):
    print(p)

# Delete matching rows
await Product.find(brand="Discontinued").allow_filtering().delete()
Field Annotations Reference
Annotation Purpose
PrimaryKey(partition_key_index=0) Partition key column (composite keys via index)
ClusteringKey(order="ASC", clustering_key_index=0) Clustering column
Indexed(index_name=None) Secondary index
Counter() Counter column
Discriminator() Polymorphic model discriminator
Vector(dimensions=N) Vector column — maps list[float] to vector<float, N>
VectorIndex(similarity_function="COSINE") SAI vector index for ANN queries
Vector Search (ANN)

coodie supports ScyllaDB's vector<float, N> column type and ANN similarity search via VectorIndex.

class ProductEmbedding(Document):
    product_id: Annotated[UUID, PrimaryKey()] = Field(default_factory=uuid4)
    embedding: Annotated[
        list[float],
        Vector(dimensions=384),
        VectorIndex(similarity_function="COSINE"),
    ]
    ...

results = await ProductEmbedding.find().order_by_ann("embedding", query_vector).limit(10).all()

📖 Full guide: Vector Search (ANN)

📚 Learn More

Resource Link
📖 Full Documentation scylladb.github.io/coodie
🚀 Quick Start Guide Installation & Quickstart
📊 Benchmark History Performance Trends
🔄 Migrating from cqlengine Migration Guide
🤝 Contributing CONTRIBUTING.md
📋 Changelog CHANGELOG.md
🐛 Bug Reports GitHub Issues

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Israel Fruchter
💻 🤔 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

Credits

This package was created with Cookiecutter and the browniebroke/cookiecutter-pypackage project template.

Project links

Data verified by PyPI on Jun 8, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for fruch-scylladb from gravatar.com fruch-scylladb

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Israel Fruchter

GitHub Statistics

Data verified by PyPI on Jun 8, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

acsylla cassandra python-rs scylla

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

coodie-1.7.3.tar.gz (4.0 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

coodie-1.7.3-py3-none-any.whl (82.8 kB view details)

Uploaded Python 3

File details

Details for the file coodie-1.7.3.tar.gz.

File metadata

  • Download URL: coodie-1.7.3.tar.gz
  • Upload date:
  • Size: 4.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for coodie-1.7.3.tar.gz
Algorithm Hash digest
SHA256 199bd11e5e47b77c6f473fed3e248d9a95ae0515f46b2465037d35466bbc2bfd
MD5 3ce93c88c616c0a00f43c80d63522b29
BLAKE2b-256 136d8739e0a847a7eeef447b57e94f3e2c662b3790dc4d3f9386386a5f357bc9

See more details on using hashes here.

Provenance

The following attestation bundles were made for coodie-1.7.3.tar.gz:

Publisher: ci.yml on scylladb/coodie

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file coodie-1.7.3-py3-none-any.whl.

File metadata

  • Download URL: coodie-1.7.3-py3-none-any.whl
  • Upload date:
  • Size: 82.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for coodie-1.7.3-py3-none-any.whl
Algorithm Hash digest
SHA256 ac0cb94a70735133c35fbb5dd302d5f9bce31ebccdebd89e885ebfcab17f50b9
MD5 0c3652f1f4ad1bbf848588121f4391b5
BLAKE2b-256 497fa08f598743fa2dbf92b2738db26cb23b109659058ebfcbd3b937dad8d4e1

See more details on using hashes here.

Provenance

The following attestation bundles were made for coodie-1.7.3-py3-none-any.whl:

Publisher: ci.yml on scylladb/coodie

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.7.3 This release

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.0

2 files

1.5.0

2 files

1.4.0

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.0

2 files

1.1.0

2 files

1.0.1

2 files

1.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page