Python SDK

Official Python client for jsondb.cloud — full CRUD, queries, bulk operations, and typed responses.

Installation

pip install jsondb-cloud

Quick Start

from jsondb_cloud import JsonDB

db = JsonDB(api_key="jdb_sk_live_xxxx")
users = db.collection("users")

# Create
alice = users.create({"name": "Alice", "email": "[email protected]"})
print(alice["_id"])

# Read
user = users.get(alice["_id"])

# List with filter
result = users.list(filter={"role": "admin"}, limit=10)
for doc in result.data:
    print(doc["name"])

# Update
users.update(alice["_id"], {"name": "Alice Smith", "email": "[email protected]"})

# Partial update
users.patch(alice["_id"], {"email": "[email protected]"})

# Delete
users.delete(alice["_id"])

Configuration

db = JsonDB(
    api_key="jdb_sk_live_xxxx",
    namespace="production",     # Default: "default"
    base_url="https://api.jsondb.cloud",  # Default
    max_retries=3,              # Auto-retry on 429/5xx
    timeout=30.0,               # Request timeout in seconds
)

info

You can also use the JSONDB_API_KEY and JSONDB_NAMESPACE environment variables.

Querying

# Filter with operators
result = users.list(
    filter={
        "age": {"$gte": 18},
        "status": "active",
    },
    sort="-createdAt",
    limit=20,
    offset=0,
    select=["name", "email"],
)

print(f"Found {result.meta.total} users")
for user in result.data:
    print(user["name"])

Bulk Operations

# Create multiple documents
result = users.bulk_create([
    {"name": "Alice", "role": "admin"},
    {"name": "Bob", "role": "member"},
    {"name": "Charlie", "role": "member"},
])
print(f"{result.summary['succeeded']} created")

Error Handling

from jsondb_cloud import JsonDB, NotFoundError, ValidationError, RateLimitError

db = JsonDB(api_key="jdb_sk_live_xxxx")
users = db.collection("users")

try:
    user = users.get("nonexistent")
except NotFoundError:
    print("User not found")
except ValidationError as e:
    print(f"Validation errors: {e.details}")
except RateLimitError:
    print("Slow down!")