Document Storage API

Overview

The document storage interfaces and in-memory development implementation are grouped under the Doxygen group DocumentAPI.

Core Interfaces

DocumentStorage

class DocumentStorage

Subclassed by kadedb::InMemoryDocumentStorage

Public Functions

virtual ~DocumentStorage() = default
virtual Status createCollection(const std::string &collection, const std::optional<DocumentSchema> &schema = std::nullopt) = 0

Create a collection with an optional schema for validation.

  • Returns Status::AlreadyExists if the collection exists.

virtual Status dropCollection(const std::string &collection) = 0

Drop a collection and all of its documents.

  • Returns Status::NotFound if the collection does not exist.

virtual std::vector<std::string> listCollections() const = 0

List existing collection names.

virtual Status put(const std::string &collection, const std::string &key, const Document &doc) = 0

Put (insert or replace) a document under collection/key.

  • If a schema exists for the collection, validates the document.

  • If the collection does not exist, it will be created (MVP behavior).

  • Returns Status::InvalidArgument if schema validation fails.

  • Returns Status::FailedPrecondition on uniqueness violations per schema.

virtual Result<Document> get(const std::string &collection, const std::string &key) = 0

Get a document if present.

  • Returns Result::err(Status::NotFound) if collection/key is not found.

virtual Status erase(const std::string &collection, const std::string &key) = 0

Erase a document by key.

  • Returns Status::NotFound if collection or key is not found.

virtual Result<size_t> count(const std::string &collection) const = 0

Count documents in a collection.

  • Returns Result::err(Status::NotFound) if the collection does not exist.

virtual Result<std::vector<std::pair<std::string, Document>>> query(const std::string &collection, const std::vector<std::string> &fields, const std::optional<DocPredicate> &where = std::nullopt) = 0

Query documents with optional field projection and predicate filter.

  • fields: empty means return entire Document values.

  • where: optional single-field predicate.

  • Returns Result::err(Status::NotFound) if collection missing.

  • Returns Result::err(Status::InvalidArgument) if requested projection fields are unknown under the collection’s schema (when schema exists).

The returned vector carries pairs of (key, Document). Documents are deep copies and may be projected to only include requested fields.

In-Memory Implementation

InMemoryDocumentStorage

class InMemoryDocumentStorage : public kadedb::DocumentStorage

Public Functions

InMemoryDocumentStorage() = default
~InMemoryDocumentStorage() override = default
virtual Status createCollection(const std::string &collection, const std::optional<DocumentSchema> &schema) override

Create a collection with an optional schema for validation.

  • Returns Status::AlreadyExists if the collection exists.

virtual Status dropCollection(const std::string &collection) override

Drop a collection and all of its documents.

  • Returns Status::NotFound if the collection does not exist.

virtual std::vector<std::string> listCollections() const override

List existing collection names.

virtual Status put(const std::string &collection, const std::string &key, const Document &doc) override

Put (insert or replace) a document under collection/key.

  • If a schema exists for the collection, validates the document.

  • If the collection does not exist, it will be created (MVP behavior).

  • Returns Status::InvalidArgument if schema validation fails.

  • Returns Status::FailedPrecondition on uniqueness violations per schema.

virtual Result<Document> get(const std::string &collection, const std::string &key) override

Get a document if present.

  • Returns Result::err(Status::NotFound) if collection/key is not found.

virtual Status erase(const std::string &collection, const std::string &key) override

Erase a document by key.

  • Returns Status::NotFound if collection or key is not found.

virtual Result<size_t> count(const std::string &collection) const override

Count documents in a collection.

  • Returns Result::err(Status::NotFound) if the collection does not exist.

virtual Result<std::vector<std::pair<std::string, Document>>> query(const std::string &collection, const std::vector<std::string> &fields, const std::optional<DocPredicate> &where) override

Query documents with optional field projection and predicate filter.

  • fields: empty means return entire Document values.

  • where: optional single-field predicate.

  • Returns Result::err(Status::NotFound) if collection missing.

  • Returns Result::err(Status::InvalidArgument) if requested projection fields are unknown under the collection’s schema (when schema exists).

The returned vector carries pairs of (key, Document). Documents are deep copies and may be projected to only include requested fields.