Add the minus operation

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.21.6 - 2024-05-14
+
+* Add the `minus` operation (also known as set difference, or EXCEPT in SQL).
+
 ## 0.21.5 - 2024-04-24
 
 * Add `ttl` (Time to leave) to the available options when using the bmg-redis

README.md

@@ -260,6 +260,7 @@ r.left_join(right, [:a, :b, ...], {...})     # left join with optional default r
 r.left_join(right, {:a => :x, ...}, {...})   # left join after right reversed renaming
 r.matching(right, [:a, :b, ...])             # semi join, aka where exists
 r.matching(right, :a => :x, :b => :y, ...)   # semi join, after right reversed renaming
+r.minus(right)                               # set difference
 r.not_matching(right, [:a, :b, ...])         # inverse semi join, aka where not exists
 r.not_matching(right, :a => :x, ...)         # inverse semi join, after right reversed renaming
 r.page([[:a, :asc], ...], 12, page_size: 10) # paging, using an explicit ordering
@@ -276,7 +277,7 @@ r.transform(:foo => :upcase, ...)            # specific-attrs tranformation
 r.transform([:to_s, :upcase])                # chain-transformation
 r.ungroup([:a, :b, ...])                     # ungroup relation-valued attributes within parent tuple
 r.ungroup(:a)                                # shortcut over ungroup([:a])
-r.union(right)                               # relational union
+r.union(right)                               # set union
 r.unwrap([:a, :b, ...])                      # merge tuple-valued attributes within parent tuple
 r.unwrap(:a)                                 # shortcut over unwrap([:a])
 r.where(predicate)                           # alias for restrict(predicate)

lib/bmg/algebra.rb

@@ -203,6 +203,16 @@ def _union(type, other, options)
     end
     protected :_union
 
+    def minus(other)
+      return self if other.is_a?(Relation::Empty)
+      _minus self.type.minus(other.type), other
+    end
+
+    def _minus(type, other)
+      Operator::Minus.new(type, [self, other])
+    end
+    protected :_minus
+
     def unwrap(attrs)
       _unwrap self.type.unwrap(attrs), attrs
     end

lib/bmg/operator.rb

@@ -39,6 +39,7 @@ def inspect
 require_relative 'operator/image'
 require_relative 'operator/join'
 require_relative 'operator/matching'
+require_relative 'operator/minus'
 require_relative 'operator/not_matching'
 require_relative 'operator/page'
 require_relative 'operator/project'

lib/bmg/operator/minus.rb

@@ -0,0 +1,49 @@
+module Bmg
+  module Operator
+    #
+    # Minus operator.
+    #
+    # Returns all tuples which are in the left operand but not 
+    # in the right operand.
+    #
+    # This implementation is actually a NAry-Minus, since it handles
+    # an arbitrary number of operands.
+    #
+    class Minus
+      include Operator::Nary
+
+      def initialize(type, operands)
+        @type = type
+        @operands = operands
+      end
+
+    public
+
+      def each(&bl)
+        return to_enum unless block_given?
+        initial = operands[0].to_set
+        tuples = operands.drop(1).inject(initial) do |agg, op|
+          agg - op.to_set
+        end
+        tuples.each(&bl)
+      end
+
+      def to_ast
+        [ :minus ] + operands.map(&:to_ast)
+      end
+
+    protected ### optimization
+
+      def _minus(type, other)
+        return self if other.is_a?(Relation::Empty)
+          case other
+          when Minus
+            Minus.new(type, operands + other.operands)
+          else
+            Minus.new(type, operands + [other])
+          end
+      end
+
+    end # class Union
+  end # module Operator
+end # module Bmg

lib/bmg/sql/relation.rb

@@ -191,6 +191,16 @@ def _union(type, right, options)
         end
       end
 
+      def _minus(type, right)
+        if right_expr = extract_compatible_sexpr(right)
+          expr = before_use(self.expr)
+          expr = Processor::Merge.new(:except, false, right_expr, builder).call(expr)
+          _instance(type, builder, expr)
+        else
+          super
+        end
+      end
+
       # Build a new relation instance for some new type & expression
       #
       # This method can be overriden by subclasses to provide their

lib/bmg/type.rb

@@ -288,19 +288,23 @@ def ungroup(attrlist)
     end
 
     def union(other)
-      if typechecked? && knows_attrlist? && other.knows_attrlist?
-        missing = self.attrlist - other.attrlist
-        raise TypeError, "Union incompatible: missing right attributes #{missing.join(', ')}" unless missing.empty?
-        extra = other.attrlist - self.attrlist
-        raise TypeError, "Union incompatible: missing left attributes #{extra.join(', ')}" unless extra.empty?
-      end
+      union_compatible!(other, "Union")
       dup.tap{|x|
         ### attrlist stays the same
         x.predicate = self.predicate | predicate
         x.keys      = self._keys.union(self, x, other) if knows_keys?
       }
     end
 
+    def minus(other)
+      union_compatible!(other, "Minus")
+      dup.tap{|x|
+        ### attrlist stays the same
+        x.predicate = self.predicate & predicate
+        x.keys      = self._keys.union(self, x, other) if knows_keys?
+      }
+    end
+
     def unwrap(attrlist)
       known_attributes!(attrlist) if typechecked? && knows_attrlist?
       dup.tap{|x|
@@ -338,5 +342,14 @@ def cross_join_compatible!(right)
       end
     end
 
+    def union_compatible!(other, opname)
+      if typechecked? && knows_attrlist? && other.knows_attrlist?
+        missing = self.attrlist - other.attrlist
+        raise TypeError, "#{opname} requires compatible attribute lists, but the right operand is missing the following attributes: #{missing.join(', ')}" unless missing.empty?
+        extra = other.attrlist - self.attrlist
+        raise TypeError, "#{opname} requires compatible attribute lists, but the left operand is missing the following attributes: #{extra.join(', ')}" unless extra.empty?
+      end
+    end
+
   end # class Type
 end # module Bmg

lib/bmg/version.rb

@@ -2,7 +2,7 @@ module Bmg
   module Version
     MAJOR = 0
     MINOR = 21
-    TINY  = 5
+    TINY  = 6
   end
   VERSION = "#{Version::MAJOR}.#{Version::MINOR}.#{Version::TINY}"
 end

spec/integration/sequel/base/minus.yml

@@ -0,0 +1,45 @@
+---
+- bmg: |-
+    suppliers.minus(suppliers)
+  sqlite: |-
+    SELECT
+      `t1`.`sid`,
+      `t1`.`name`,
+      `t1`.`city`,
+      `t1`.`status`
+    FROM
+      `suppliers` AS 't1'
+    EXCEPT 
+    SELECT
+      `t1`.`sid`,
+      `t1`.`name`,
+      `t1`.`city`,
+      `t1`.`status`
+    FROM
+      `suppliers` AS 't1'
+- bmg: |-
+    suppliers.minus(suppliers).minus(suppliers)
+  sqlite: |-
+    SELECT
+      `t1`.`sid`,
+      `t1`.`name`,
+      `t1`.`city`,
+      `t1`.`status`
+    FROM
+      `suppliers` AS 't1'
+    EXCEPT
+    SELECT
+      `t1`.`sid`,
+      `t1`.`name`,
+      `t1`.`city`,
+      `t1`.`status`
+    FROM
+      `suppliers` AS 't1'
+    EXCEPT
+    SELECT
+      `t1`.`sid`,
+      `t1`.`name`,
+      `t1`.`city`,
+      `t1`.`status`
+    FROM
+      `suppliers` AS 't1'

spec/unit/operator/test_minus.rb

@@ -0,0 +1,52 @@
+require 'spec_helper'
+module Bmg
+  module Operator
+    describe Minus do
+
+      let(:r1) {
+        [
+          { a: 1 },
+          { a: 2 },
+          { a: 3 },
+          { a: 4 },
+          { a: 5 },
+          { a: 6 },
+          { a: 7 },
+          { a: 8 },
+        ]
+      }
+
+      let(:r2) {
+        [
+          { a: 1 },
+          { a: 4 }
+        ]
+      }
+
+      let(:r3) {
+        [
+          { a: 3 },
+          { a: 5 }
+        ]
+      }
+
+      let(:r4) {
+        [
+          { a: 7 }
+        ]
+      }
+
+      it 'works' do
+        difference = Minus.new(Type::ANY, [r1, r2, r3, r4])
+        expect(difference.to_a).to eql(
+          [
+            { a: 2 },
+            { a: 6 },
+            { a: 8 }
+          ]
+        )
+      end
+
+    end
+  end
+end