Skip to content

buckethead.interfaces.docs — DocStore

JSON document store (Mongo-lite) attached to BucketSQLite as bh.docs. Backed by a single bh_docs table in the in-memory SQLite, so it snapshots and branches like everything else.

bh.docs.collection("<name>") returns a Collection handle with CRUD plus a small filter DSL: $eq, $ne, $gt, $gte, $lt, $lte, $in, $exists, with dotted-path support. For anything more complex (e.g. $or, $regex, aggregation), drop to raw SQL via bh.connection.execute(...) and SQLite's json_extract.

buckethead.interfaces.docs

DocStore: unstructured JSON document interface (Mongo-lite).

Stores arbitrary JSON dicts under named collections in a single bh_docs table. Access via bh.docs.collection("name") which returns a Collection handle exposing CRUD plus a small MongoDB-flavored filter DSL ($eq, $ne, $gt/$gte/$lt/$lte, $in, $exists) with dotted-path support.

When to use what
  • KVStore — one small string/bytes value per key.
  • FileStore — opaque blobs (large, binary).
  • DocStore — structured-ish JSON documents you want to query.

Escape hatch for complex queries. The DSL intentionally omits $or, $and, $regex, array operators, and aggregation. Drop to raw SQL via bh.connection.execute(...) using SQLite's json_extract:

rows = bh.connection.execute(
    "SELECT doc FROM bh_docs WHERE collection = ? "
    "AND (json_extract(doc, '$.age') > ? OR json_extract(doc, '$.vip') = 1)",
    ("users", 30),
).fetchall()

Gotcha — JSON type coercion. json_extract returns SQLite-native types; a numeric field stored as the string "30" will not match {"age": {"$gt": 18}}. Store numbers as numbers.

Size guidance. Each update rewrites the whole row. Keep individual documents under ~1 MB, same soft ceiling as KVStore. For larger payloads use FileStore and reference the bh-key from the document.