Skip to main content

API Reference: YourDB Class

The YourDB class is the main entry point for interacting with your database. It manages entities (collections of objects) and provides methods for CRUD operations and database management.

from yourdb import YourDB

Initialization​

db = YourDB(db_name: str)

Creates or connects to a database instance.

  • db_name (str): The name of the database. This determines the folder name used for storage (e.g., my_app_db.yourdb).

  • Behavior: If the database directory exists, it loads existing entities and their schemas. If not, it creates the directory.

Entity Management​

create entity

db.create_entity(entity_name: str, entity_schema: dict) -> bool

Creates a new entity (similar to a table or collection) within the database.

  • entity_name (str): The name for the new entity (alphanumeric and underscores, cannot start with a number).

  • entity_schema (dict): A dictionary defining the structure and types of objects stored in this entity. Must include:

  • 'primary_key' (str): The name of the attribute serving as the unique identifier.

  • Attribute names mapped to type strings (e.g., "int", "str", "bool", "float", or the name of a @register_class-decorated class).

  • 'indexes': (Optional list of str) A list of attribute names to create indexes on for faster lookups.

  • Returns: True on success.

  • Raises: Exception if the entity name is invalid, the schema is invalid, or the entity already exists.

drop entity

db.drop_entity(entity_name: str) -> bool

Permanently deletes an entity and all its associated data files. Use with caution!

  • entity_name (str): The name of the entity to delete.

  • Returns: True on success.

  • Raises: Exception if the entity does not exist.

Data Operations​

insert_into

db.insert_into(entity_name: str, entity_object: object) -> bool

Inserts a new object record into the specified entity.

  • entity_name (str): The name of the target entity.

  • entity_object (object): An instance of a Python class (usually decorated with @register_class) whose attributes match the entity's schema. The primary key attribute must be set before calling insert.

  • ** Returns**: True on success.

  • Raises : Exception if the entity doesn't exist, the object fails schema validation (e.g., wrong type, missing primary key), or the primary key already exists.

select_from

db.select_from(entity_name: str, filter_dict: dict = None) -> list[object]

Retrieves a list of objects from an entity that match the specified filter.

  • entity_name (str): The name of the entity to query.

  • filter_dict (Optional dict): A dictionary specifying the query conditions.

    • Keys are attribute names.

    • Values are either the exact value to match or a nested dictionary with operators ($gt, $lt, $ne, etc.). See Advanced Queries.

    • If None or omitted, returns all objects in the entity.

Returns: A list of reconstructed Python objects matching the filter. Returns an empty list if no matches are found.

Raises: Exception if the entity does not exist.

update_entity

db.update_entity(entity_name: str, filter_dict: dict, update_fn: callable) -> None

Finds objects matching the filter_dict and applies the update_fn to modify them.

  • entity_name (str): The name of the entity to update.

  • filter_dict (dict): A query dictionary (like in select_from) to identify the object(s) to update.

  • update_fn (callable): A function or lambda that accepts a single argument (the retrieved object) and modifies its attributes directly in-place. The function must return the modified object.

  • Returns: None.

  • Raises: Exception if the entity does not exist.

delete_from

db.delete_from(entity_name: str, filter_dict: dict) -> None

Deletes objects from an entity that match the specified filter.

  • entity_name (str): The name of the entity to delete from.

  • filter_dict (dict): A query dictionary (like in select_from) to identify the object(s) to delete.

  • Returns: None.

  • Raises: Exception if the entity does not exist.

Optimization​

optimize_entity

db.optimize_entity(entity_name: str) -> bool

Performs an eager migration (compaction with schema upgrades) on the specified entity. Reads all data, upgrades it to the latest schema version, and writes new, clean log files containing only the latest data. This is a safe, atomic operation.

  • entity_name (str): The name of the entity to optimize.

  • Returns: True on success, False if the optimization failed (the original data remains untouched).

  • Raises: Exception if the entity does not exist.