NoSQL Database

NonSQL is a Python-based, feature-rich NoSQL database designed for quick development and local storage needs. It supports time-based partitioning, memory caching, bloom filters, and more to provide an efficient and scalable solution for small-scale projects.

---

Features

Feature	Description
Time-Based Partitioning	Organizes data into directories based on timestamps for efficient storage.
Bloom Filter	Enables fast membership tests, minimizing unnecessary disk I/O.
LRU Cache	In-memory cache for frequently accessed documents with eviction policies.
Document Compression	Optional zlib compression for optimized storage.
Batch Operations	Support for batch inserts and updates.
Indexing	Create indexes on fields for fast lookups and queries.
TTL and Expiry	Automatically remove expired documents.
Versioning	Tracks multiple versions of documents for history retrieval.

---

Table of Contents

1. Installation
2. Usage
   • Initialization
   • Developer
   • Insert Document
   • Retrieve Document
   • Batch Insert
   • Update Document
   • Search by Tags
   • Create Index
   • Query by Index
   • Version History
   • Cleanup Expired Documents
3. CLI
4. Configuration Options
5. Examples
   • User Management System
   • Inventory Management System
   • Like Collection System
   • Real-Time Analytics System
   • Advanced Time-Series Analytics System
6. License

---

Installation

pip install nonsql

Developer

• ishan oshada - GitHub

---

Usage

Initialization

from nonsql import Database, DatabaseConfig

# Default configuration
db = Database()

# Custom configuration
config = DatabaseConfig(
     db_path="my_data",
     cache_size=2000,
     bloom_filter_size=20000,
     compression=True,
     default_ttl=3600  # Documents expire in 1 hour by default
)
db = Database(config)

Insert Document

doc_id = db.insert(key="user123", value={"name": "John", "age": 30}, tags=["user", "active"])
print("Inserted Document ID:", doc_id)

Retrieve Document

document = db.get("user123")
if document:
     print("Document:", document)
else:
     print("Document not found or expired.")

Batch Insert

documents = [
     {"key": "user124", "value": {"name": "Jane", "age": 25}, "tags": ["user"]},
     {"key": "user125", "value": {"name": "Alice", "age": 28}, "tags": ["user"]},
]
doc_ids = db.batch_insert(documents)
print("Inserted Document IDs:", doc_ids)

Update Document

doc_id = db.insert(key="user123", value={"name": "John", "age": 30})
db.batch_update([
     {"key": "user123", "value": {"age": 31, "location": "NYC"}}
])
print("Document updated")

Search by Tags

results = db.search_by_tags(["user", "active"])
for result in results:
     print(result)

Create Index

db.create_index("age")

Query by Index

results = db.query_by_index("age", 30)
for result in results:
     print(result)

Version History

history = db.get_version_history("user123")
for version in history:
     print(version)

Cleanup Expired Documents

removed_count = db.cleanup_expired()
print(f"Removed {removed_count} expired documents.")

---

Configuration Options

Parameter	Type	Default	Description
db_path	str	"nonsql_data"	Directory path for storing data.
cache_size	int	1000	Maximum number of items in memory cache.
bloom_filter_size	int	10000	Size of the Bloom filter.
compression	bool	True	Enable/disable zlib compression for documents.
default_ttl	Optional[int]	None	Default Time-to-Live for documents (in seconds).
hash_funcs	int	3	Number of hash functions for the Bloom filter.

---

CLI

The NonSQL database comes with a command-line interface for common operations.

Basic Commands

# Initialize a new database
nonsql init path/to/db --config config.yaml

# Insert a document
nonsql insert path/to/db my_key '{"name": "John"}' --tags tag1 tag2

# Retrieve a document
nonsql get path/to/db my_key

# Delete a document
nonsql delete path/to/db my_key

# Create an index
nonsql create-index path/to/db field_name

# Search by tags
nonsql search path/to/db tag1 tag2

# Remove expired documents
nonsql cleanup path/to/db

# Get document history
nonsql history path/to/db my_key

Example Config File (YAML)

db_path: "my_database"
cache_size: 1000
bloom_filter_size: 10000
compression: true
default_ttl: 3600

Examples

Example Systems

User Management System

from nonsql import Database, DatabaseConfig

# Custom configuration for user management
config = DatabaseConfig(
    db_path="user_data",
    cache_size=500,
    bloom_filter_size=5000,
    compression=True,
    default_ttl=7200  # Documents expire in 2 hours by default
)
db = Database(config)

# Insert user documents
db.insert(key="user001", value={"name": "Alice", "role": "admin"}, tags=["user", "admin"])
db.insert(key="user002", value={"name": "Bob", "role": "user"}, tags=["user", "active"])

# Retrieve a user document
user = db.get("user001")
print("User:", user)

# Update a user document
db.batch_update([{"key": "user002", "value": {"role": "moderator"}}])
print("User updated")

# Search users by tags
active_users = db.search_by_tags(["active"])
print("Active Users:", active_users)

Inventory Management System

from nonsql import Database, DatabaseConfig

# Custom configuration for inventory management
config = DatabaseConfig(
    db_path="inventory_data",
    cache_size=1000,
    bloom_filter_size=10000,
    compression=True,
    default_ttl=86400  # Documents expire in 24 hours by default
)
db = Database(config)

# Insert product documents
db.insert(key="product001", value={"name": "Laptop", "quantity": 50}, tags=["electronics", "inventory"])
db.insert(key="product002", value={"name": "Smartphone", "quantity": 200}, tags=["electronics", "inventory"])

# Retrieve a product document
product = db.get("product001")
print("Product:", product)

# Update a product document
db.batch_update([{"key": "product002", "value": {"quantity": 180}}])
print("Product updated")

# Search products by tags
electronics = db.search_by_tags(["electronics"])
print("Electronics:", electronics)

Like Collection System

from nonsql import Database, DatabaseConfig

# Custom configuration for like collection
config = DatabaseConfig(
    db_path="like_data",
    cache_size=300,
    bloom_filter_size=3000,
    compression=True,
    default_ttl=604800  # Documents expire in 7 days by default
)
db = Database(config)

# Insert like documents
db.insert(key="like001", value={"user_id": "user123", "item_id": "post456"}, tags=["like", "post"])
db.insert(key="like002", value={"user_id": "user124", "item_id": "post789"}, tags=["like", "post"])

# Retrieve a like document
like = db.get("like001")
print("Like:", like)

# Update a like document
db.batch_update([{"key": "like002", "value": {"item_id": "post101"}}])
print("Like updated")

# Search likes by tags
post_likes = db.search_by_tags(["post"])
print("Post Likes:", post_likes)

Real-Time Analytics System

from nonsql import Database, DatabaseConfig

# Custom configuration for real-time analytics
config = DatabaseConfig(
    db_path="analytics_data",
    cache_size=5000,
    bloom_filter_size=50000,
    compression=True,
    default_ttl=3600  # Documents expire in 1 hour by default
)
db = Database(config)

# Insert event documents
db.insert(key="event001", value={"user_id": "user123", "action": "click", "timestamp": 1633072800}, tags=["event", "click"])
db.insert(key="event002", value={"user_id": "user124", "action": "view", "timestamp": 1633072900}, tags=["event", "view"])

# Retrieve an event document
event = db.get("event001")
print("Event:", event)

# Update an event document
db.batch_update([{"key": "event002", "value": {"action": "click"}}])
print("Event updated")

# Search events by tags
click_events = db.search_by_tags(["click"])
print("Click Events:", click_events)

# Aggregate events by action
from collections import Counter

events = db.search_by_tags(["event"])
action_counts = Counter(event["value"]["action"] for event in events)
print("Action Counts:", action_counts)

Advanced Time-Series Analytics System

from nonsql import Database, DatabaseConfig
from datetime import datetime, timedelta
import numpy as np
from collections import defaultdict

# Configuration optimized for time-series data
config = DatabaseConfig(
    db_path="timeseries_data",
    cache_size=10000,
    bloom_filter_size=100000,
    compression=True,
    default_ttl=2592000  # 30 days retention
)
db = Database(config)

# Complex time-series data insertion with multiple metrics
def insert_metric_batch(metrics, timestamp=None):
    if timestamp is None:
        timestamp = datetime.now()
    
    batch_data = []
    for sensor_id, values in metrics.items():
        key = f"sensor_{sensor_id}_{timestamp.timestamp()}"
        processed_values = {
            "raw": values,
            "stats": {.....................

License

This project is licensed under the MIT License. See the LICENSE file for details.

Repository Views