Database / No SQL

Local Manage

This is a detailed and didactic documentation of the LocalManager class, designed to serve as a guide for both users and developers who want to understand the structure of this local NoSQL data manager.

On this page

    #Overview

    LocalManager is a lightweight and efficient solution for persisting data in NoSQL format, using the local file system as storage. It emulates the behavior of modern databases (such as MongoDB), organizing information in a hierarchy of Databases (directories) and Collections (JSON files).

    It is the ideal tool for:

    • Rapid prototyping of applications.
    • Storing local configuration.
    • Test environments where you do not want to set up a complex database server.

    #Execution Flow

    The class follows a predictable cycle of file I/O handling:

    1. Initialization: The manager checks or creates the root folder (data).
    2. Mapping: When an operation is requested, it resolves the physical path: base/database/collection.json.
    3. Loading: The JSON file is read and deserialized into a list of Python dictionaries in memory.
    4. Processing: Filters, inserts or updates are applied to this list.
    5. Persistence: The resulting list is serialized back to the JSON file, ensuring data integrity.

    #Methods Summary

    MethodBrief Description
    save_payloadInserts a new record with a unique ID and timestamp.
    fetch_documentsFilters and returns documents from the collection.
    update_documentsModifies fields of existing documents based on filters.
    delete_documentsRemoves specific or multiple records from the collection.
    _get_collection_path(Internal) Resolves and creates the directory path for the database.
    _load_collection(Internal) Reads data from the JSON file with error handling.
    _save_collection(Internal) Writes data to disk with readable indentation.
    _match_filter(Internal) Compares documents with search criteria.

    #Architecture and Insights

    • ID and Time Abstraction: The system relieves the developer of generating unique IDs (uuid4) and recording creation/update times, injecting metadata automatically.
    • Write Safety: By using os.makedirs(exist_ok=True), the code avoids common "directory not found" errors during execution.
    • Search Simplicity: Filtering is based on simple equality, which makes the learning curve very low for new users.

    #LocalManager Class

    #Description

    Local persistence manager that uses JSON files to simulate a NoSQL database. It organizes data in database and collection structures inside the file system.

    #Arguments

    • base_path (str): Name of the root directory where all data will be saved. Default: "data".

    #Methods

    #1. save_payload

    Description: Adds a new document to the database. The method automatically generates a unique _id field and a _created_at field.

    Arguments:

    • database_name (str): Name of the database.
    • collection_name (str): Name of the collection.
    • payload (dict): The data you want to save.

    Returns:

    • dict: A dictionary containing the operation status and the generated ID.

    Raises:

    • Exception: Write permission errors or file system failure.

    Example:

    manager.save_payload("loja", "produtos", {"nome": "Teclado", "preco": 150.0})

    #2. fetch_documents

    Description: Retrieves a list of documents that match the given criteria.

    Arguments:

    • database_name (str): Name of the database.
    • collection_name (str): Name of the collection.
    • filter (dict, optional): Equality filter (e.g. {"status": "ativo"}).
    • limit (int): Maximum number of results (0 for unlimited).

    Returns:

    • List[Dict]: List of documents found.

    Raises:

    • json.JSONDecodeError: If the file is corrupted.

    Example:

    manager.fetch_documents("loja", "produtos", filter={"nome": "Teclado"})

    #3. update_documents

    Description: Locates documents via a filter and updates their values with a new set of data.

    Arguments:

    • database_name (str): Name of the database.
    • collection_name (str): Name of the collection.
    • filter (dict): Criterion to find the documents to be edited.
    • new_values (dict): New fields and values to be inserted/changed.
    • multi (bool): If True, updates all documents found; if False, only the first.

    Returns:

    • dict: Statistics containing matched_count and modified_count.

    Raises:

    • IOError: Error when trying to save the changes to disk.

    Example:

    manager.update_documents("loja", "produtos", {"nome": "Teclado"}, {"preco": 130.0})

    #4. delete_documents

    Description: Removes documents from the collection that match the given filter.

    Arguments:

    • database_name (str): Name of the database.
    • collection_name (str): Name of the collection.
    • filter (dict): Selection criterion for removal.
    • multi (bool): Whether to remove all matches or only the first.

    Returns:

    • dict: Confirmation with the number of deleted items (deleted_count).

    Raises:

    • Exception: Generic file access failures.

    Example:

    manager.delete_documents("loja", "produtos", {"status": "esgotado"}, multi=True)

    Source: src/database/no_relational_db/local_manager.py

    Esc
    ↑↓navigate Enteropen