Skip to content

v3.1.0

Choose a tag to compare

View all tags
@orhanayd orhanayd released this 29 Dec 08:53
· 15 commits to master since this release
v3.1.0
5d488d6
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

v3.1.0 (2025-12-29)

Major: Spatial Indexing + MongoDB-Style Comparison Operators

This release introduces R-tree spatial indexing for geospatial queries and MongoDB-style comparison operators for advanced filtering.

Part 1: R-tree Spatial Indexing

GeoJSON Support

Full GeoJSON geometry support:

  • Point - Single location [lon, lat]
  • LineString - Path/route
  • Polygon - Area with boundary (supports holes)
  • MultiPoint, MultiLineString, MultiPolygon
  • GeometryCollection
// Insert GeoJSON data
$db->insert("restaurants", [
    'name' => 'Ottoman Kitchen',
    'location' => [
        'type' => 'Point',
        'coordinates' => [28.9784, 41.0082]  // [longitude, latitude]
    ]
]);

Spatial Index Management

// Create R-tree index
$db->createSpatialIndex("restaurants", "location");
// Returns: ["success" => true, "indexed" => 150]

// Check if index exists
$db->hasSpatialIndex("restaurants", "location");  // true/false

// List all spatial indexes
$db->getSpatialIndexes("restaurants");  // ["location"]

// Drop index
$db->dropSpatialIndex("restaurants", "location");

// Rebuild index
$db->rebuildSpatialIndex("restaurants", "location");

Spatial Query Methods

All distance parameters and results are in meters.

// Find within radius
$nearby = $db->withinDistance("restaurants", "location", 28.97, 41.00, 5000);  // 5000 meters

// Find in bounding box
$inArea = $db->withinBBox("restaurants", "location", 28.97, 41.00, 29.00, 41.03);

// Find K nearest
$closest = $db->nearest("restaurants", "location", 28.97, 41.00, 10);

// Find within polygon
$inPolygon = $db->withinPolygon("restaurants", "location", $polygon);

Query Builder Integration

$results = $db->query("restaurants")
    ->withinDistance('location', 28.97, 41.00, 5000)  // 5000 meters
    ->where(['open_now' => true])
    ->withDistance('location', 28.97, 41.00)  // _distance field in meters
    ->sort('_distance', 'asc')
    ->limit(10)
    ->get();

Spatial Index File Structure

hash-dbname.nonedb.sidx.location      # R-tree spatial index
hash-dbname.nonedb.gsidx.location     # Global spatial index (sharded)

Part 2: MongoDB-Style Comparison Operators

Operator Reference

Operator Description Example
$gt Greater than ['age' => ['$gt' => 18]]
$gte Greater than or equal ['price' => ['$gte' => 100]]
$lt Less than ['stock' => ['$lt' => 10]]
$lte Less than or equal ['rating' => ['$lte' => 5]]
$eq Equal (explicit) ['status' => ['$eq' => 'active']]
$ne Not equal ['role' => ['$ne' => 'guest']]
$in Value in array ['category' => ['$in' => ['a', 'b']]]
$nin Value not in array ['tag' => ['$nin' => ['spam']]]
$exists Field exists ['email' => ['$exists' => true]]
$like Pattern match ['name' => ['$like' => '^John']]
$regex Regular expression ['email' => ['$regex' => '@gmail.com$']]
$contains Array/string contains ['tags' => ['$contains' => 'featured']]

Usage Examples

// Range query
$results = $db->query("products")
    ->where([
        'price' => ['$gte' => 100, '$lte' => 500],
        'stock' => ['$gt' => 0]
    ])
    ->get();

// Multiple operators
$results = $db->query("users")
    ->where([
        'role' => ['$in' => ['admin', 'moderator']],
        'status' => ['$ne' => 'banned'],
        'email' => ['$exists' => true]
    ])
    ->get();

// Combined with spatial queries
$results = $db->query("restaurants")
    ->withinDistance('location', 28.97, 41.00, 5000)  // 5000 meters
    ->where([
        'rating' => ['$gte' => 4.0],
        'cuisine' => ['$in' => ['turkish', 'italian']]
    ])
    ->get();

Part 3: R-tree Performance Optimizations

Optimization Description
Parent Pointer Map O(1) parent lookup instead of O(n) tree scan
Linear Split Algorithm O(n) seed selection instead of O(n²) quadratic split
Dirty Flag Pattern Single disk write per batch instead of n writes
Distance Memoization Cached Haversine distance calculations
Centroid Caching Cached geometry centroid calculations
Node Size 32 Fewer tree levels and splits (increased from 16)
Adaptive nearest() Exponential radius expansion for efficient k-NN

Performance Results

Operation 100 1K 5K
createSpatialIndex 2.4 ms 81 ms 423 ms
withinDistance (10km) 3 ms 32 ms 166 ms
withinBBox 0.7 ms 7 ms 38 ms
nearest(10) 2 ms 2 ms 2.4 ms

Comparison Operator Performance

Operator 100 1K 5K
$gt, $gte, $lt, $lte 0.7 ms 6-7 ms 33-38 ms
$in, $nin 0.7 ms 6.5-7 ms 36-37 ms
$like, $regex 0.7 ms 7 ms 39 ms
Complex (4 operators) 0.7 ms 7.5 ms 43 ms

New Methods

Spatial Index Methods (noneDB)

  • createSpatialIndex($dbname, $field) - Create R-tree index
  • hasSpatialIndex($dbname, $field) - Check if index exists
  • getSpatialIndexes($dbname) - List all spatial indexes
  • dropSpatialIndex($dbname, $field) - Remove index
  • rebuildSpatialIndex($dbname, $field) - Rebuild index
  • withinDistance($dbname, $field, $lon, $lat, $meters) - Find within radius (meters)
  • withinBBox($dbname, $field, $minLon, $minLat, $maxLon, $maxLat) - Find in bbox
  • nearest($dbname, $field, $lon, $lat, $k) - Find K nearest
  • withinPolygon($dbname, $field, $polygon) - Find in polygon
  • validateGeoJSON($geometry) - Validate GeoJSON

Query Builder Methods (noneDBQuery)

  • withinDistance($field, $lon, $lat, $meters) - Spatial: within radius (meters)
  • withinBBox($field, $minLon, $minLat, $maxLon, $maxLat) - Spatial: within bbox
  • nearest($field, $lon, $lat, $k) - Spatial: K nearest
  • withinPolygon($field, $polygon) - Spatial: within polygon
  • withDistance($field, $lon, $lat) - Add _distance field to results (meters)

Comparison Operators in where()

  • $gt, $gte, $lt, $lte - Numeric comparisons
  • $eq, $ne - Equality comparisons
  • $in, $nin - Array membership
  • $exists - Field existence
  • $like - Pattern matching (case-insensitive)
  • $regex - Regular expression matching
  • $contains - Array/string contains

Test Results

  • 970 tests, 3079 assertions (all passing)
  • 42 new comparison operator tests
  • 24 new spatial + operator combination tests
  • 48 new query documentation tests
  • Full sharded spatial index support verified

Documentation

New documentation files in docs/:

  • QUERY.md - Complete query builder reference
  • SPATIAL.md - Spatial indexing guide
  • CONFIGURATION.md - Configuration options
  • API.md - Complete API reference
  • BENCHMARKS.md - Performance benchmarks

Breaking Changes

None. Spatial indexing is a new feature in v3.1.0.

Note: All spatial distance parameters and results use meters as the unit:

  • withinDistance() - distance parameter in meters
  • _distance field in results is in meters
  • nearest() maxDistance option is in meters
Assets 2
Loading