v1.14.1

[cwt]

NeoSQLite v1.14.1 Release Notes

TL;DR

NeoSQLite v1.14.1 is a correctness and compatibility release that eliminates major limitations in the SQL evaluation tier. It introduces Static Type Inference to perfectly match MongoDB BSON type semantics even for computed expressions and provides full SQL-tier support for the $type operator.

Critical Fix: This release resolves a functional issue where $expr queries returning strings (like $type or $concat) would return zero results in find() filters. They now correctly follow MongoDB truthiness rules.

• Upgrade if you use: $isNumber, $toBool, $type, or string-based expressions within $expr.
• Result Correctness: Achieved 100% compatibility in API comparison reports for type-checking and truthiness evaluation.

---

Overview

This release focuses on "Tier-1 SQL" correctness, ensuring that database-native evaluation perfectly matches MongoDB's BSON semantics:

• Static Type Inference — Implemented a system to predict operator return types (e.g., $add returns a number, $eq returns a boolean) during SQL generation.
• Perfect BSON Type Matching — Fixed $isNumber to correctly identify that booleans are NOT numbers, even when computed or passed as literals.
• SQL-Tier $type Support — Full database-level support for the $type operator, including detection of NeoSQLite-encoded Binary and ObjectId.
• MongoDB Truthiness Wrapper — Wrapped $expr results in an optimized COALESCE logic to ensure that strings and objects are correctly treated as truthy in filter predicates.
• Parameter Binding Fix — Resolved "Incorrect number of bindings" errors caused by optimized-away expression operands.

---

High Severity Fixes

Corrected $expr Truthiness in Filters

Problem: In MongoDB, strings (including empty ones) and objects are truthy. In SQLite WHERE clauses, strings are falsy. This caused $expr filters returning strings to match zero documents.

Solution: Wrapped top-level SQL expressions in COALESCE(({expr}), 0) != 0. This efficiently maps MongoDB truthiness to SQLite boolean logic while evaluating the expression only once and avoiding parameter duplication.

Perfect Type Detection for $isNumber

Problem: SQLite's typeof() cannot distinguish between booleans and integers (both are 0/1). This caused {"$isNumber": True} to incorrectly return True.

Solution: Combined json_type() for field references with Static Type Inference for expressions and literal checking for constants. The system now knows True is a boolean before it generates the SQL.

---

Medium Severity Enhancements

Full SQL-Tier $type Implementation

Optimization: The $type operator now runs entirely in SQL. It maps SQLite types to BSON type strings ('int', 'double', 'bool', etc.) and uses json_extract to detect encoded binData and objectId shapes within JSON strings.

Optimized Parameter Binding

Bug Fix: Fixed a regression where operands optimized to constants (e.g., isNumber(True) -> 0) would leave behind unused SQL parameters, causing ProgrammingError during execution.

---

Test Statistics

Unit Tests

Metric	Result
Total Tests	2,542
Passed	2,542
XFailed	0
Failed	0
Code Coverage	80%

API Comparison Tests

NeoSQLite vs MongoDB

Metric	v1.14.1
Total Tests	386
Passed	368
Skipped	18
Failed	0
Compatibility	100.0%

---

Installation

pip install neosqlite
# or
poetry install

---

Migration Guide

Upgrading from v1.14.0

This is a non-breaking patch release. Users are encouraged to upgrade immediately to fix potential silent filter failures in $expr queries.

---

Credits

Type system enhancements and compatibility fixes developed as part of the NeoSQLite project.

---

NeoSQLite v1.14.1 — Static Type Inference, $type SQL Optimization, and Truthiness Correctness.

---

This discussion was created from the release v1.14.1.