astradb-nosql-design

DataStax Astra DB NoSQL Data Modeling Builder

Purpose

Expert guidance for building DataStax Astra DB NoSQL document applications — part of the IBM Cloud HCD (Hyper-Converged Database) portfolio. Generates Python 3.12 FastAPI services using astrapy SDK for non-vector document collections.

IBM Cloud Product Coverage

IBM Cloud Product	Usage
IBM HCD / DataStax Astra DB	Document API (non-vector): insert, find, update, delete
IBM Cloud IAM	(optional) — Astra DB uses its own token-based auth

Rules

• Use astrapy>=1.5.2 Data API client
• Non-vector collections: create with db.create_collection(name) — no dimension
• Filter expressions follow MongoDB operator conventions: $eq, $gt, $in, $and, $or
• Update expressions: {"$set": {...}}, {"$unset": {...}}, {"$inc": {...}}
• _id field: Astra DB auto-generates UUIDs if not provided
• Batch: use insert_many() for bulk inserts — no strict limit unlike vector collections
• Always handle AstraDBException and provide meaningful error messages

---

Scope

• Astra DB NoSQL collection creation and management
• MongoDB-style CRUD operations via Data API
• Cassandra-inspired data modeling (wide rows, partition keys)
• Bulk insert patterns
• Update and upsert operations
• Collection listing and introspection

---

Procedure

Phase 1: Astra DB Connection

from astrapy import DataAPIClient

client = DataAPIClient(token=ASTRA_DB_APPLICATION_TOKEN)
db = client.get_database(ASTRA_DB_API_ENDPOINT)

Phase 2: Create / Get Collection (Non-Vector)

# Non-vector collection — no dimension argument
collection = db.create_collection("customers")

# Get existing
collection = db.get_collection("customers")

Phase 3: Insert Documents

# Single insert
collection.insert_one({
    "_id": "cust-001",
    "name": "IBM Corp",
    "email": "[email protected]",
    "created_at": "2024-01-15",
})

# Bulk insert
result = collection.insert_many([
    {"_id": "1", "name": "Alice"},
    {"_id": "2", "name": "Bob"},
], ordered=False)
print(result.inserted_ids)