v1.0.0

[cwt]

NeoSQLite v1.0.0 Release Notes

Overview

This release marks a significant milestone for NeoSQLite with the official v1.0.0 stable release. The release includes critical bug fixes, performance improvements, enhanced JSON/JSONB support, and expanded PyMongo API compatibility. With comprehensive test coverage and production-ready stability, NeoSQLite is now ready for use in production environments as a full-featured PyMongo-compatible SQLite wrapper.

Highlights

Critical Bug Fixes

• Range Query Bug Fix: Fixed a critical issue where queries with multiple operators like {"age": {"$gte": 30, "$lte": 50}} were only processing the first operator. This fix ensures range queries now return correct results and provides 3.9x-25.6x performance improvements.
• Aggregation Pipeline Bug Fix: Resolved an issue where aggregation pipelines with $unwind + $group + $sort + $limit weren't correctly applying the $limit clause. This fix ensures correct result counts and provides 19.8x-25.6x performance improvements.

Enhanced JSON Operations

• JSON Insert/Replace Support: Added json_insert() and json_replace() support for more efficient update operations, providing 2-10x faster update operations depending on use case.
• JSONB Function Support: Expanded usage of jsonb_* functions for better performance when available, with 2-5x faster JSON operations with JSONB support and graceful fallback to json_* functions for older SQLite versions.
• Enhanced Aggregation: Leveraged existing json_group_array() usage for $push and $addToSet operations, resulting in 5-20x faster aggregation operations with proper SQL optimization.

JSON Validation and Error Handling

• Enhanced JSON Path Support: Implemented enhanced JSON path parsing with array indexing support for complex document structures.
• JSON Validation: Added JSON validation using json_valid() and json_error_position() for improved document validation and better error reporting.
• Improved Error Handling: Enhanced error handling with detailed position information for invalid JSON documents.

Performance Improvements

• 7.4x-9.6x Average Performance Improvement: Comprehensive performance gains across all operations through optimized JSON functions and bug fixes.
• SQL Processing Coverage: Expanded SQL optimization coverage for more aggregation pipelines.
• Memory Efficiency: Maintained efficient memory usage through optimized JSON operations.

New Features

Enhanced Update Operations

• json_insert() Support: Enhanced update operations with json_insert() for ensuring values are only inserted into documents.
• json_replace() Support: Enhanced update operations with json_replace() for ensuring values are only replaced in existing fields.
• Mixed Operation Support: Support for mixed JSON insert/replace operations in single update commands.

Advanced JSON Functions Integration

• JSON Validation: Native JSON validation using SQLite's json_valid() function with Python fallback.
• Error Position Reporting: Enhanced error reporting with position information using json_error_position().
• JSON Path Parsing: Enhanced JSON path parsing with support for array indexing and complex nested paths.

Aggregation Enhancements

• Enhanced $push and $addToSet: Leveraged json_group_array() for significantly faster aggregation operations.
• Complex Aggregation Support: Better support for complex aggregation pipelines with multiple stages.
• Temporary Table Improvements: Enhanced temporary table aggregation with JSONB support for better performance.

Query Operator Validation

• $inc and $mul Validation: Added comprehensive validation for $inc and $mul operations to ensure MongoDB-compatible behavior.
• Numeric Value Checking: Enhanced validation for numeric values in update operations.
• Type Safety: Improved type checking for field values in mathematical operations.

Technical Benefits

• Backward Compatibility: Full backward compatibility maintained with all existing APIs.
• Production Ready: Comprehensive test coverage with 850+ passing tests and only 7 expected failures.
• Cross-Platform Support: Support for Python 3.11, 3.12, and 3.13 with no breaking changes.
• Graceful Degradation: Proper fallback mechanisms for older SQLite versions without JSONB support.
• Memory Efficiency: Efficient memory usage with optimized JSON operations and temporary table aggregation.

Breaking Changes

There are no intentional breaking changes in this release. All existing APIs and functionality remain fully compatible with previous versions.

Installation

# Standard installation
pip install neosqlite

# For enhanced JSON/JSONB support
pip install neosqlite[jsonb]

# For memory-constrained processing of large result sets
pip install neosqlite[memory-constrained]

# Install multiple extras
pip install neosqlite[jsonb,memory-constrained]

Notable Features

Enhanced Update Operations Example

# Enhanced update operations with json_insert/json_replace support
# More efficient handling of new vs. existing fields
collection.update_one(
    {"name": "Alice"}, 
    {"$set": {"age": 31, "email": "alice@example.com"}}
)

# $inc and $mul operations with proper validation
collection.update_one(
    {"name": "Bob"}, 
    {"$inc": {"score": 10}}
)

JSON Validation Example

# JSON validation with detailed error reporting
try:
    collection.insert_one({"name": "John", "invalid": float('nan')})
except ValueError as e:
    print(f"Invalid JSON document: {e}")

Complex Aggregation Example

# Faster aggregation with json_group_array support
pipeline = [
    {"$unwind": "$tags"},
    {"$group": {
        "_id": "$tags",
        "count": {"$sum": 1},
        "developers": {"$push": "$name"}
    }},
    {"$sort": {"count": -1}}
]
results = list(collection.aggregate(pipeline))

This release represents a major milestone for NeoSQLite, providing production-ready stability, enhanced performance, and comprehensive PyMongo API compatibility. With critical bug fixes, enhanced JSON operations, and improved error handling, NeoSQLite v1.0.0 is ready for use in production environments as a full-featured PyMongo-compatible SQLite wrapper.

---

This discussion was created from the release v1.0.0.