Merge pull request #6 from seuros/feat/knn-spatial-search

feat: Add K-Nearest Neighbor (<->) operator for blazing fast spatial searches

Author: seuros

README.md

@@ -101,7 +101,13 @@ Location.where(
   Location.arel_table[:coordinates].st_distance(point).lt(1000)
 )
 
-# NEW: Advanced spatial predicates
+# NEW: K-Nearest Neighbor - Lightning fast "find nearest" queries
+# Uses spatial index for incredible performance!
+nearest_locations = Location
+  .order(Location.arel_table[:coordinates].distance_operator(my_position))
+  .limit(10)
+
+# Advanced spatial predicates
 # Find intersecting routes
 Route.where(Route.arel_table[:path].st_intersects(restricted_zone))
 
@@ -255,6 +261,7 @@ end
 🔍 **Spatial Query Methods**
 - Core methods: `st_distance`, `st_contains`, `st_within`, `st_length`
 - **NEW:** Advanced spatial operations:
+  - `<->` (distance_operator) - K-Nearest Neighbor search (blazing fast!)
   - `st_intersects` - Detect geometry intersections
   - `st_dwithin` - Efficient proximity queries (index-optimized!)
   - `st_buffer` - Create buffer zones around geometries

docs/COOKBOOK.md

@@ -16,6 +16,62 @@
 
 *Your starships are scattered across the galaxy like atoms in the void. Time to coordinate their movements with military precision.*
 
+### The Quantum Leap: K-Nearest Neighbor Search
+
+The `<->` operator is your secret weapon for finding the nearest anything at warp speed:
+
+```ruby
+# app/models/starship.rb
+class Starship < ApplicationRecord
+  # Find nearest starships using KNN (blazing fast with spatial index!)
+  scope :nearest_to, ->(position, limit = 10) {
+    order(arel_table[:current_coordinates].distance_operator(position))
+      .limit(limit)
+  }
+  
+  # Combine KNN with distance calculations when you need actual distances
+  scope :nearest_with_distances, ->(position, limit = 10) {
+    select(
+      "*",
+      "ST_Distance(current_coordinates, ST_GeomFromText('#{position.as_text}', 4326)) as distance_meters"
+    )
+    .order(arel_table[:current_coordinates].distance_operator(position))
+    .limit(limit)
+  }
+  
+  # Emergency protocols: Find nearest friendly ships
+  def nearest_allies(count = 5)
+    self.class
+      .where(faction: faction)
+      .where.not(id: id)
+      .order(
+        self.class.arel_table[:current_coordinates].distance_operator(current_coordinates)
+      )
+      .limit(count)
+  end
+  
+  # Tactical assessment: Nearest threats
+  def incoming_threats(scan_limit = 20)
+    HostileVessel
+      .active
+      .select(
+        "*",
+        "ST_Distance(position, ST_GeomFromText('#{current_coordinates.as_text}', 4326)) as threat_distance"
+      )
+      .order(
+        HostileVessel.arel_table[:position].distance_operator(current_coordinates)
+      )
+      .limit(scan_limit)
+      .having("threat_distance < ?", sensor_range)
+  end
+end
+
+# The Navigation AI notes:
+# "Traditional distance queries are like checking every star in the galaxy.
+#  The <-> operator is like having a sorted list already waiting for you.
+#  Always use <-> for 'find nearest' queries—your CPU will thank you."
+```
+
 ```ruby
 # app/models/starship.rb
 class Starship < ApplicationRecord

docs/SPATIAL_WARFARE.md

@@ -8,6 +8,66 @@ Welcome to the Spatial Warfare Division, pilot. You've been equipped with Active
 
 ## 🎯 The Advanced Weapons Systems
 
+### The <-> Operator - Quantum Targeting System
+
+Before we dive into the standard weapons, let me introduce you to the most powerful targeting system in the fleet: the K-Nearest Neighbor operator, `<->`. While other systems calculate distances in real-time (burning precious CPU cycles), this quantum targeting array uses spatial indexes to lock onto targets at warp speed.
+
+```ruby
+# Traditional targeting (slow, scans entire space)
+NearbyShips.order(
+  Arel.sql("ST_Distance(position, ST_GeomFromText('POINT(-73.5 40.7)', 4326))")
+).limit(10)
+
+# Quantum targeting with <-> (lightning fast, uses spatial index)
+NearbyShips.order(
+  NearbyShips.arel_table[:position].distance_operator(command_ship_position)
+).limit(10)
+
+# Even cleaner with the alias
+NearbyShips.order(
+  NearbyShips.arel_table[:position].send(:'<->', command_ship_position)
+).limit(10)
+
+# Real combat scenario: Find 5 nearest enemy vessels
+class HostileVessel < ActiveRecord::Base
+  scope :nearest_threats, ->(our_position, limit = 5) {
+    order(arel_table[:coordinates].distance_operator(our_position))
+      .limit(limit)
+  }
+  
+  # Emergency evasion: Find escape routes
+  scope :find_escape_vectors, ->(current_position) {
+    safe_zones = SpaceSector.neutral
+      .order(
+        SpaceSector.arel_table[:center_point].distance_operator(current_position)
+      )
+      .limit(3)
+  }
+end
+
+# The Tactical Computer explains:
+# "The <-> operator doesn't calculate distances—it uses the spatial index
+#  to teleport directly to the answer. It's the difference between searching
+#  every star in the galaxy versus knowing exactly which ones are closest."
+```
+
+**Critical Intelligence**: The `<->` operator returns results ordered by distance but doesn't give you the actual distance value. If you need both speed AND distance:
+
+```ruby
+# Get nearest ships with their distances
+Starship
+  .select(
+    "*", 
+    "ST_Distance(position, ST_GeomFromText('#{origin.as_text}', 4326)) as distance_meters"
+  )
+  .order(
+    arel_table[:position].distance_operator(origin)
+  )
+  .limit(10)
+```
+
+## 🎯 Standard Weapons Arsenal
+
 ### ST_Intersects - The Collision Detection Array
 
 Every good pilot knows: space is big, but not big enough when two fleets converge on the same coordinates.

lib/arel/visitors/postgis.rb

@@ -36,6 +36,13 @@ def st_area
       end
     end
     class SpatialArea < Unary; end
+    
+    # K-Nearest Neighbor distance operator
+    class SpatialDistanceOperator < Binary
+      def initialize(left, right)
+        super
+      end
+    end
 
     # Wrapper for spatial values that need special handling
     class SpatialValue < Node
@@ -76,6 +83,12 @@ def st_transform(srid)
       def st_area
         SpatialArea.new(self)
       end
+      
+      def distance_operator(other)
+        SpatialDistanceOperator.new(self, other)
+      end
+      
+      alias :'<->' :distance_operator
     end
   end
 
@@ -116,6 +129,12 @@ def st_transform(srid)
       def st_area
         Arel::Nodes::SpatialArea.new(self)
       end
+      
+      def distance_operator(other)
+        Arel::Nodes::SpatialDistanceOperator.new(self, other)
+      end
+      
+      alias :'<->' :distance_operator
     end
   end
 
@@ -211,6 +230,12 @@ def visit_Arel_Nodes_SpatialArea(node, collector)
         visit(node.expr, collector)
         collector << ")"
       end
+      
+      def visit_Arel_Nodes_SpatialDistanceOperator(node, collector)
+        visit(node.left, collector)
+        collector << " <-> "
+        visit_spatial_operand(node.right, collector)
+      end
 
       private
 

test/arel/visitors/postgis_test.rb

@@ -92,6 +92,38 @@ def test_where_clause_with_st_dwithin
         assert_sql_includes where_clause, "ST_DWithin"
         assert_sql_includes where_clause, "1000) = TRUE"
       end
+      
+      def test_knn_distance_operator
+        table = Arel::Table.new(:spatial_models)
+        query_point = factory(srid: 3785).point(1, 2)
+        
+        # Test the <-> operator
+        node = table[:location].distance_operator(query_point)
+        
+        assert_sql_includes node, '"spatial_models"."location" <-> ST_GeomFromEWKT'
+        assert_sql_includes node, "SRID=3785;POINT (1 2)"
+      end
+      
+      def test_knn_operator_alias
+        table = Arel::Table.new(:spatial_models)
+        query_point = factory(srid: 3785).point(1, 2)
+        
+        # Test the <-> alias
+        node = table[:location].send(:'<->', query_point)
+        
+        assert_sql_includes node, '"spatial_models"."location" <-> ST_GeomFromEWKT'
+      end
+      
+      def test_knn_in_order_clause
+        table = Arel::Table.new(:spatial_models)
+        query_point = factory(srid: 4326).point(-72.1, 42.1)
+        
+        # Simulate ORDER BY with KNN
+        order_node = table[:location].distance_operator(query_point).asc
+        
+        assert_sql_includes order_node, '<-> ST_GeomFromEWKT'
+        assert_sql_includes order_node, 'ASC'
+      end
 
       private