torque-postgresql 4.0.1 → 4.1.1

data/lib/torque/postgresql/predicate_builder/struct_handler.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    module PredicateBuilder
+      # Turns a hash of properties into a proper set of conditions over the
+      # document that holds them, handing each of them back to the predicate
+      # builder so that the whole +where+ vocabulary works inside a struct
+      class StructHandler
+        # Properties are extracted as text, so only the ones whose type has a
+        # counterpart on the database are casted before being compared
+        PLAIN_TYPES = %i[string text].freeze
+
+        class << self
+          # Only a hash describes properties, everything else is left alone so
+          # that whole documents are still compared as documents. Without a
+          # value, a single document has properties that can be reached
+          def candidate?(type, value = nil)
+            return false if !type.is_a?(Adapter::OID::Struct) || type.is_a?(Adapter::OID::StructList)
+
+            value.nil? || value.is_a?(::Hash)
+          end
+        end
+
+        def initialize(predicate_builder)
+          @predicate_builder = predicate_builder
+        end
+
+        def call(attribute, struct, value)
+          table = table_for(attribute, struct)
+          nodes = predicate_builder.with(table).build_from_hash(value.stringify_keys)
+
+          ::Arel::Nodes::Grouping.new(nodes.reduce(:and))
+        end
+
+        # The properties of the document as the columns of a table, so that any
+        # of them can be resolved by name. A document that no class describes
+        # is open, which means any path into it is accepted, without a type
+        def table_for(attribute, struct)
+          raise ArgumentError, <<~MSG.squish if struct.is_a?(Adapter::OID::Struct) && struct.type != :jsonb
+            Unable to build a condition over "#{attribute.name}" because json
+            columns cannot be queried by their properties. Use jsonb instead.
+          MSG
+
+          @struct = struct
+          PredicateTable.new(self, attribute, Arel::Nodes::Property)
+        end
+
+        # The node for a path into the document, resolved one property at a
+        # time so that each level is typed by the class that declares it
+        def property_for(attribute, struct, path)
+          path.reduce(attribute) do |node, key|
+            struct = node.type_caster if node.is_a?(Arel::Nodes::Property)
+            table_for(node, struct)[key]
+          end
+        end
+
+        # The type of a single property, plus what it has to be casted to once
+        # it is extracted from the document as text
+        def type_of(name)
+          return [ActiveModel::Type.default_value, nil] unless @struct.is_a?(Adapter::OID::Struct)
+
+          klass = @struct.klass
+          name = name.to_s
+
+          raise ArgumentError, <<~MSG.squish if klass.strict? && !klass.attribute_names.include?(name)
+            Unable to build a condition for "#{name}" because it is not a
+            declared property of #{klass.name}.
+          MSG
+
+          type = klass.attribute_types[name]
+          [type, cast_for(type)]
+        end
+
+        private
+
+          attr_reader :predicate_builder
+
+          def cast_for(type)
+            name = type&.type
+            return if name.nil? || PLAIN_TYPES.include?(name)
+
+            ActiveRecord::Base.with_connection { |c| c.type_to_sql(name) }
+          end
+      end
+    end
+  end
+end

data/lib/torque/postgresql/predicate_builder.rb

@@ -2,6 +2,9 @@
 
 require_relative 'predicate_builder/array_handler'
 
+require_relative 'predicate_builder/composite_handler'
+require_relative 'predicate_builder/ltree_handler'
+require_relative 'predicate_builder/struct_handler'
 require_relative 'predicate_builder/regexp_handler'
 require_relative 'predicate_builder/arel_attribute_handler'
 require_relative 'predicate_builder/enumerator_lazy_handler'
@@ -11,6 +14,20 @@ module Torque
     module PredicateBuilder
       ARRAY_OID = ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array
 
+      # The handler that serves a column, either to build a condition with the
+      # given value or, without one, to resolve the parts of the column. The
+      # ltree handler is picked by the column alone, composite and struct also
+      # look at the value: a Hash means the parts, anything else the whole
+      def self.handler_for(type, value = nil)
+        if PostgreSQL.config.composite.enabled && CompositeHandler.candidate?(type, value)
+          CompositeHandler
+        elsif PostgreSQL.config.struct.enabled && StructHandler.candidate?(type, value)
+          StructHandler
+        elsif PostgreSQL.config.ltree.enabled && !value.nil? && LtreeHandler.candidate?(type)
+          LtreeHandler
+        end
+      end
+
       def initialize(*)
         super
 
@@ -28,6 +45,42 @@ module Torque
           register_handler(::Arel::Attributes::Attribute, ArelAttributeHandler.new(self))
         end
       end
+
+      # Values described as a hash of columns or properties are turned into
+      # conditions over the column that holds them. Whole values are left to
+      # the regular handlers, so that they are compared as a single value, and
+      # so is nil, which is a null check on every kind of column
+      def build(attribute, value, operator = nil)
+        return super if value.nil?
+
+        type = Adapter::OID.unwrap(table.type(attribute.name))
+        handler = PredicateBuilder.handler_for(type, value) || handler_for_path(attribute, value)
+        return super if handler.nil?
+
+        handler.new(self).call(attribute, type, value)
+      end
+
+      # A struct or composite column stands for the table of its own parts, so
+      # a Hash given to order, group or pluck reaches a part the way where does
+      def resolve_arel_attribute(table_name, column_name, &block)
+        return super unless table.has_column?(table_name)
+
+        type = Adapter::OID.unwrap(table.type(table_name))
+        handler = PredicateBuilder.handler_for(type)
+        return super if handler.nil?
+
+        handler.new(self).table_for(table.arel_table[table_name], type)[column_name]
+      end
+
+      private
+
+        # A Hash beneath a property that is not a document of its own is just
+        # a deeper path, the way jsonb reads it, which is how an entry of an
+        # array is reached
+        def handler_for_path(attribute, value)
+          return unless PostgreSQL.config.struct.enabled
+          StructHandler if attribute.is_a?(Arel::Nodes::Property) && value.is_a?(::Hash)
+        end
     end
 
     ::ActiveRecord::PredicateBuilder.prepend(PredicateBuilder)

data/lib/torque/postgresql/predicate_table.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    # Mimics ActiveRecord::TableMetadata so that the parts of a value that holds
+    # other values, like the columns of a composite type or the properties of a
+    # document, can be treated as the columns of the value they belong to. That
+    # is what allows each of them to be handed back to the predicate builder
+    #
+    # The handler is the one that knows how to resolve a name, and the node is
+    # the one that knows how to reach it
+    class PredicateTable
+      def initialize(handler, source, node)
+        @handler = handler
+        @source = source
+        @node = node
+      end
+
+      def arel_table
+        self
+      end
+
+      def [](name)
+        @node.new(@source, name, *@handler.type_of(name))
+      end
+
+      def type(name)
+        @handler.type_of(name).first
+      end
+
+      # Anything that gets here is meant to be resolved as a part of the value,
+      # which is what +type_of+ is there to accept or reject
+      def has_column?(*)
+        true
+      end
+
+      def primary_key
+        nil
+      end
+
+      # Rails 8.1 renamed this, so both names answer for the supported versions
+      def associated_with(*)
+        false
+      end
+
+      alias associated_with? associated_with
+
+      def aggregated_with?(*)
+        false
+      end
+
+      def polymorphic_association?
+        false
+      end
+
+      def through_association?
+        false
+      end
+    end
+  end
+end

data/lib/torque/postgresql/railtie.rb

@@ -30,6 +30,20 @@ module Torque
               Relation.include(Relation::Buckets)
             end
 
+            if torque_config.segments
+              require_relative 'relation/segments'
+              Relation.include(Relation::Segments)
+            end
+
+            ## Cross Join Setup
+            if torque_config.cross_join.enabled
+              require_relative 'relation/cross_join'
+              Relation.include(Relation::CrossJoin)
+
+              # TODO: delegate join_struct and join_composite once they exist
+              ActiveRecord::Base.singleton_class.delegate(:cross_join, to: :all)
+            end
+
             ## Schemas Enabled Setup
             if (config = torque_config.schemas).enabled
               require_relative 'adapter/schema_overrides'
@@ -85,6 +99,32 @@ module Torque
               end
             end
 
+            ## Struct Enabled Setup
+            if (config = torque_config.struct).enabled
+              require_relative 'adapter/oid/struct'
+              require_relative 'adapter/oid/struct_list'
+              require_relative 'adapter/oid/struct_set'
+
+              require_relative 'attributes/struct'
+
+              Attributes::Struct.include_on(ActiveRecord::Base)
+            end
+
+            ## Composite Enabled Setup
+            if (config = torque_config.composite).enabled
+              require_relative 'adapter/oid/composite'
+              require_relative 'attributes/composite'
+
+              ar_type.register(:composite, Adapter::OID::Composite, adapter: :postgresql)
+
+              config.namespace ||= ::Object.const_set('Composite', Module.new)
+
+              # Define a method to find composite classes based on the namespace
+              config.namespace.define_singleton_method(:const_missing) do |name|
+                Attributes::Composite.lookup(name)
+              end
+            end
+
             ## Geometry Enabled Setup
             if (config = torque_config.geometry).enabled
               require_relative 'adapter/oid/box'
@@ -110,6 +150,18 @@ module Torque
               ar_type.register(:interval, Adapter::OID::Interval, adapter: :postgresql)
             end
 
+            ## LTree Enabled Setup
+            if (config = torque_config.ltree).enabled
+              require_relative 'adapter/oid/ltree'
+              require_relative 'adapter/oid/lquery'
+
+              require_relative 'attributes/ltree'
+              require_relative 'attributes/lquery'
+
+              ar_type.register(:ltree,  Adapter::OID::Ltree,  adapter: :postgresql)
+              ar_type.register(:lquery, Adapter::OID::Lquery, adapter: :postgresql)
+            end
+
             ## Full Text Search Enabled Setup
             if (config = torque_config.full_text_search).enabled
               require_relative 'attributes/full_text_search'

data/lib/torque/postgresql/relation/auxiliary_statement.rb

@@ -32,11 +32,15 @@ module Torque
         # Get all auxiliary statements bound attributes and the base bound
         # attributes as well
         def bound_attributes
-          visitor = ::Arel::Visitors::PostgreSQL.new(ActiveRecord::Base.connection)
-          visitor.accept(self.arel.ast, ::Arel::Collectors::Composite.new(
+          collector = ::Arel::Collectors::Composite.new(
             ::Arel::Collectors::SQLString.new,
             ::Arel::Collectors::Bind.new,
-          )).value.last
+          )
+
+          klass.with_connection do |connection|
+            visitor = ::Arel::Visitors::PostgreSQL.new(connection)
+            visitor.accept(arel.ast, collector).value.last
+          end
         end
 
         private

data/lib/torque/postgresql/relation/buckets.rb

@@ -34,6 +34,7 @@ module Torque
           MSG
 
           count ||= 1 if values.is_a?(Range)
+          attribute = resolve_column(attribute).first if attribute.is_a?(Hash)
           attribute = arel_table[attribute] unless ::Arel.arel_node?(attribute)
           self.buckets_value = [attribute, values, count, cast, as]
           self
@@ -51,7 +52,7 @@ module Torque
 
           keys = buckets_keys
           self.group_values = [FN.group_by(build_buckets_node, :bucket)]
-          super.transform_keys { |key| keys[key - 1] }
+          super.transform_keys { |key| keys[key - 1] if key&.positive? }
         end
 
         module Initializer

data/lib/torque/postgresql/relation/cross_join.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    module Relation
+      module CrossJoin
+
+        Entry = ::Struct.new(:node, :table)
+
+        class << self
+          # Assemble the join node and the table that stands for what it
+          # exposes, which is what makes the result reachable by name
+          def build(source, as, columns, mode, with_ordinality, definitions = nil)
+            columns = columns_for(source, columns)
+            ordinality = ordinality_for(with_ordinality)
+            validate_ordinality!(ordinality, columns, definitions)
+
+            source, lateral = source_for(source, columns)
+            item = Arel::Nodes::FromItem.new(source, as, columns: columns,
+              definitions: definitions, ordinality: ordinality, lateral: lateral)
+
+            Entry.new(join_for(mode, item), ::Arel::Table.new(as.to_s))
+          end
+
+          private
+
+            # A list of documents describes its own columns, everything else
+            # has to be told what they are
+            def columns_for(source, columns)
+              return columns if columns.present? || !source.is_a?(::Array)
+
+              sample = source.first
+              sample.keys if sample.is_a?(::Hash)
+            end
+
+            # The name of the counter column, which +true+ takes from the
+            # configuration
+            def ordinality_for(value)
+              case value
+              when true then PostgreSQL.config.cross_join.ordinality_column
+              when ::Symbol, ::String then value
+              end
+            end
+
+            # PostgreSQL matches the alias list positionally, so a list that
+            # does not name every column silently renames the ones it reaches
+            # instead of naming the counter. Without knowing the columns, the
+            # only name that can be promised is the one PostgreSQL picks
+            def validate_ordinality!(ordinality, columns, definitions)
+              return if ordinality.blank? || columns.present? || definitions.present?
+              return if ordinality.to_s == 'ordinality'
+
+              raise ArgumentError, <<~MSG.squish
+                Unable to name the ordinality column "#{ordinality}" because the
+                columns of the source are unknown. Provide "columns:" so that
+                all of them can be named, or let it be called "ordinality".
+              MSG
+            end
+
+            # Only a subquery needs LATERAL, since it is a noise word in front
+            # of a function and PostgreSQL lets those see the row already
+            def source_for(source, columns)
+              case source
+              when ::ActiveRecord::Relation then [::Arel::Nodes::Grouping.new(source.arel.ast), true]
+              when ::Arel::SelectManager then [::Arel::Nodes::Grouping.new(source.ast), true]
+              when ::Array then [unnest_rows(source, columns), false]
+              when ::Arel::Nodes::Node then [source, false]
+              else
+                raise ArgumentError, <<~MSG.squish
+                  Unable to join "#{source.class}". Provide an Arel node, a
+                  relation, or an Array of rows.
+                MSG
+              end
+            end
+
+            # Rows become one array per column, which costs a single bind for
+            # each of them instead of one for every single value
+            def unnest_rows(rows, columns)
+              raise ArgumentError, 'Unable to join an empty list of rows.' if rows.empty?
+
+              raise ArgumentError, <<~MSG.squish if columns.blank?
+                Unable to name the columns of the given rows. Provide
+                "columns:" or use a Hash for each row.
+              MSG
+
+              keys = columns.map(&:to_sym)
+              values = rows.map { |row| row_values(row, keys) }
+              args = values.transpose.map { |list| ::Arel.array(list) }
+              FN.unnest(*args)
+            end
+
+            # Hash rows are read by name, so that they can be given in any
+            # order, and their keys are compared as symbols because that is
+            # not something the caller should have to match
+            def row_values(row, keys)
+              return ::Array.wrap(row) unless row.is_a?(::Hash)
+
+              row.symbolize_keys.values_at(*keys)
+            end
+
+            # A lateral reference can only be combined with an inner or a left
+            # join, and a cross join is how an inner one without a condition
+            # has to be written
+            def join_for(mode, item)
+              case mode.to_sym
+              when :cross then Arel::Nodes::CrossJoin.new(item)
+              when :left
+                on = ::Arel::Nodes::On.new(::Arel::Nodes::True.new)
+                ::Arel::Nodes::OuterJoin.new(item, on)
+              else
+                raise ArgumentError, <<~MSG.squish
+                  The "#{mode}" is not implemented as a join type. PostgreSQL
+                  only combines a lateral reference with :cross or :left.
+                MSG
+              end
+            end
+        end
+
+        # :nodoc:
+        def cross_joins_value
+          @values.fetch(:cross_joins, ::ActiveRecord::QueryMethods::FROZEN_EMPTY_HASH)
+        end
+
+        # :nodoc:
+        def cross_joins_value=(value)
+          assert_modifiable!
+          @values[:cross_joins] = value
+        end
+
+        # Joins the query against a set produced by the given source, which
+        # can be an Arel node, another relation, or a list of rows. The result
+        # is reachable by the name given to +as+. For example:
+        #
+        #   User.cross_join(FN.generate_series(1, 5), as: :sample, columns: %i[value])
+        #   # Returns 5 rows for each user
+        #
+        #   User.cross_join([{ id: 1, label: 'a' }], as: :labels)
+        #   # Returns the rows of the list combined with each user
+        def cross_join(source, **xargs)
+          spawn.cross_join!(source, **xargs)
+        end
+
+        # Like #cross_join, but modifies relation in place.
+        def cross_join!(source, as:, columns: nil, mode: :cross, with_ordinality: false)
+          entry = CrossJoin.build(source, as, columns, mode, with_ordinality)
+          self.cross_joins_value = cross_joins_value.merge(as.to_sym => entry)
+          self
+        end
+
+        private
+
+          # Hook arel build to add the joins, which is done here instead of
+          # through the join values because those are inspected by Rails for
+          # table aliases, and these sources have no table to inspect
+          def build_arel(*)
+            arel = super
+            return arel if cross_joins_value.blank?
+
+            nodes = cross_joins_value.each_value.map(&:node)
+            arel.join_sources.concat(nodes)
+            arel
+          end
+
+        # The merger is loaded with the relation, so the part that knows about
+        # this feature is coordinated from here
+        module Merger
+          def merge # :nodoc:
+            result = super
+            merge_cross_joins
+            result
+          end
+
+          private
+
+            def merge_cross_joins
+              return unless relation.is_a?(Relation::CrossJoin)
+              return if other.cross_joins_value.blank?
+
+              relation.cross_joins_value =
+                relation.cross_joins_value.merge(other.cross_joins_value)
+            end
+        end
+
+      end
+
+      ::ActiveRecord::Relation::Merger.prepend(CrossJoin::Merger)
+
+      ::ActiveRecord::Relation::SINGLE_VALUE_METHODS.push(:cross_joins)
+      ::ActiveRecord::Relation::VALUE_METHODS.push(:cross_joins)
+      ::ActiveRecord::QueryMethods::VALID_UNSCOPING_VALUES.add(:cross_joins)
+    end
+  end
+end