CRUD Operations: Working with Documents in OxiDB

OxiDB provides a familiar, MongoDB-inspired API for working with documents. Every document is a JSON object stored in a collection, and every document gets an auto-generated _id field.

Inserting Documents

Insert a single document into a collection. The collection is created automatically if it doesn't exist:

from oxidb import OxiDbClient

db = OxiDbClient("127.0.0.1", 4444)

# Single insert
doc_id = db.insert("products", {
    "name": "Mechanical Keyboard",
    "price": 149.99,
    "category": "peripherals",
    "tags": ["keyboard", "mechanical", "rgb"],
    "in_stock": True,
    "specs": {
        "switches": "Cherry MX Blue",
        "layout": "TKL",
        "backlight": "RGB"
    }
})
print(f"Inserted: {doc_id}")

OxiDB supports nested objects, arrays, numbers, strings, booleans, and null values — any valid JSON structure.

Finding Documents

Use find() to query documents with filters, sorting, skip, and limit:

# Find all products in a category
products = db.find("products", {"category": "peripherals"})

# Find with sorting (1 = ascending, -1 = descending)
products = db.find("products", {}, sort={"price": -1})

# Pagination with skip and limit
page_2 = db.find("products", {}, sort={"name": 1}, skip=10, limit=10)

# Find a single document
keyboard = db.find_one("products", {"name": "Mechanical Keyboard"})

Updating Documents

OxiDB supports powerful update operators:

# $set — set field values
db.update("products", {"category": "peripherals"}, {
    "$set": {"on_sale": True, "discount": 0.15}
})

# $inc — increment numeric fields
db.update_one("products", {"name": "Mechanical Keyboard"}, {
    "$inc": {"views": 1, "price": -10}
})

# $unset — remove fields
db.update_one("products", {"name": "Mechanical Keyboard"}, {
    "$unset": {"discount": ""}
})

# $push — add to arrays
db.update_one("products", {"name": "Mechanical Keyboard"}, {
    "$push": {"tags": "hot-deal"}
})

# $pull — remove from arrays
db.update_one("products", {"name": "Mechanical Keyboard"}, {
    "$pull": {"tags": "rgb"}
})

All Update Operators

Operator	Description
`$set`	Set field values (supports dot notation for nested fields)
`$unset`	Remove fields from documents
`$inc`	Increment numeric fields
`$mul`	Multiply numeric fields
`$min` / `$max`	Update only if new value is less/greater than current
`$rename`	Rename a field
`$currentDate`	Set field to current date/time
`$push`	Append to an array
`$pull`	Remove matching values from an array
`$addToSet`	Add to array only if not already present
`$pop`	Remove first or last element from an array

Deleting Documents

# Delete all matching documents
db.delete("products", {"in_stock": False})

# Delete a single document
db.delete_one("products", {"name": "Old Product"})

# Count remaining documents
count = db.count("products", {})
print(f"Products remaining: {count}")

OxiDB uses soft-delete internally — the status byte is flipped in the append-only storage file. This means deletes are O(1) and don't require data compaction.