activecypher 0.14.2 → 0.15.2

data/lib/active_cypher/connection_adapters/abstract_bolt_adapter.rb

@@ -98,9 +98,9 @@ module ActiveCypher
       #
       # @yieldparam session [Bolt::Session] The session to use
       # @return [Object] The result of the block
-      def with_session(**kw, &block)
+      def with_session(**kw, &)
         connect
-        @driver.with_session(**kw, &block)
+        @driver.with_session(**kw, &)
       end
 
       # Asynchronously yields a Session from the connection pool.
@@ -108,9 +108,9 @@ module ActiveCypher
       #
       # @yieldparam session [Bolt::Session] The session to use
       # @return [Async::Task] A task that resolves to the block's result
-      def async_with_session(**kw, &block)
+      def async_with_session(**kw, &)
         connect
-        @driver.async_with_session(**kw, &block)
+        @driver.async_with_session(**kw, &)
       end
 
       # Runs a Cypher query via Bolt session.
@@ -169,26 +169,24 @@ module ActiveCypher
 
           begin
             result = Sync do
+              # Try to execute a simple query first
+              session = Bolt::Session.new(@connection)
+              session.run('RETURN 1 AS check', {})
+              session.close
+              true
+            rescue StandardError => e
+              # Query failed, need to reset the connection
+              logger.debug { "Connection needs reset: #{e.message}" }
+
+              # Send RESET message directly
               begin
-                # Try to execute a simple query first
-                session = Bolt::Session.new(@connection)
-                session.run('RETURN 1 AS check', {})
-                session.close
-                true
-              rescue StandardError => e
-                # Query failed, need to reset the connection
-                logger.debug { "Connection needs reset: #{e.message}" }
-
-                # Send RESET message directly
-                begin
-                  @connection.write_message(Bolt::Messaging::Reset.new)
-                  response = @connection.read_message
-                  logger.debug { "Reset response: #{response.class}" }
-                  response.is_a?(Bolt::Messaging::Success)
-                rescue StandardError => reset_error
-                  logger.error { "Reset failed: #{reset_error.message}" }
-                  false
-                end
+                @connection.write_message(Bolt::Messaging::Reset.new)
+                response = @connection.read_message
+                logger.debug { "Reset response: #{response.class}" }
+                response.is_a?(Bolt::Messaging::Success)
+              rescue StandardError => reset_error
+                logger.error { "Reset failed: #{reset_error.message}" }
+                false
               end
             end
           rescue StandardError => e

data/lib/active_cypher/connection_adapters/memgraph_adapter.rb

@@ -63,6 +63,10 @@ module ActiveCypher
         self.class
       end
 
+      def id_type_conversion(incoming)
+        incoming.to_i
+      end
+
       # Memgraph uses different constraint syntax than Neo4j
       def ensure_schema_migration_constraint
         execute_ddl(<<~CYPHER)
@@ -200,30 +204,6 @@ module ActiveCypher
         metadata.compact
       end
 
-      # Hydrates attributes from a Memgraph record
-      # @param record [Hash] The raw record from Memgraph
-      # @param node_alias [Symbol] The alias used for the node in the query
-      # @return [Hash] The hydrated attributes
-      def hydrate_record(record, node_alias)
-        attrs = {}
-        node_data = record[node_alias] || record[node_alias.to_s]
-
-        if node_data.is_a?(Array) && node_data.length >= 2
-          properties_container = node_data[1]
-          if properties_container.is_a?(Array) && properties_container.length >= 3
-            properties = properties_container[2]
-            properties.each { |k, v| attrs[k.to_sym] = v } if properties.is_a?(Hash)
-          end
-        elsif node_data.is_a?(Hash)
-          node_data.each { |k, v| attrs[k.to_sym] = v }
-        elsif node_data.respond_to?(:properties)
-          attrs = node_data.properties.symbolize_keys
-        end
-
-        attrs[:internal_id] = record[:internal_id] || record['internal_id']
-        attrs
-      end
-
       protected
 
       def parse_schema(rows)

data/lib/active_cypher/connection_adapters/neo4j_adapter.rb

@@ -130,30 +130,6 @@ module ActiveCypher
         metadata.compact
       end
 
-      # Hydrates attributes from a Neo4j record
-      # @param record [Hash] The raw record from Neo4j
-      # @param node_alias [Symbol] The alias used for the node in the query
-      # @return [Hash] The hydrated attributes
-      def hydrate_record(record, node_alias)
-        attrs = {}
-        node_data = record[node_alias] || record[node_alias.to_s]
-
-        if node_data.is_a?(Array) && node_data.length >= 2
-          properties_container = node_data[1]
-          if properties_container.is_a?(Array) && properties_container.length >= 3
-            properties = properties_container[2]
-            properties.each { |k, v| attrs[k.to_sym] = v } if properties.is_a?(Hash)
-          end
-        elsif node_data.is_a?(Hash)
-          node_data.each { |k, v| attrs[k.to_sym] = v }
-        elsif node_data.respond_to?(:properties)
-          attrs = node_data.properties.symbolize_keys
-        end
-
-        attrs[:internal_id] = record[:internal_id] || record['internal_id']
-        attrs
-      end
-
       module Persistence
         include PersistenceMethods
 

data/lib/active_cypher/migration.rb

@@ -92,14 +92,13 @@ module ActiveCypher
     end
 
     def create_uniqueness_constraint(label, *props, if_not_exists: true, name: nil)
+      props_clause = props.map { |p| "n.#{p}" }.join(', ')
       cypher = if connection.vendor == :memgraph
                  # Memgraph syntax: CREATE CONSTRAINT ON (n:Label) ASSERT n.prop IS UNIQUE
                  # Note: Memgraph doesn't support IF NOT EXISTS or named constraints
-                 props_clause = props.map { |p| "n.#{p}" }.join(', ')
                  "CREATE CONSTRAINT ON (n:#{label}) ASSERT #{props_clause} IS UNIQUE"
                else
                  # Neo4j syntax
-                 props_clause = props.map { |p| "n.#{p}" }.join(', ')
                  c = +'CREATE CONSTRAINT'
                  c << " #{name}" if name
                  c << ' IF NOT EXISTS' if if_not_exists
@@ -113,7 +112,7 @@ module ActiveCypher
       cypher = if connection.vendor == :memgraph
                  # Memgraph TEXT INDEX syntax (requires --experimental-enabled='text-search')
                  # Memgraph only supports single property per text index, so create one per prop
-                 props.map.with_index do |p, i|
+                 props.map.with_index do |p, _i|
                    index_name = props.size > 1 ? "#{name}_#{p}" : name.to_s
                    "CREATE TEXT INDEX #{index_name} ON :#{label}(#{p})"
                  end

data/lib/active_cypher/model/connection_owner.rb

@@ -7,7 +7,6 @@ module ActiveCypher
     module ConnectionOwner
       extend ActiveSupport::Concern
       include ActiveCypher::Logging
-      include ActiveCypher::Model::ConnectionHandling
 
       def self.db_key_for(mapping, role)
         return nil unless mapping.is_a?(Hash)
@@ -66,7 +65,7 @@ module ActiveCypher
         # Always dynamically fetch the connection for the current db_key
         def connection
           handler = connection_handler
-          mapping = connects_to_mappings if respond_to?(:connects_to_mappings)
+          mapping = connects_to_mappings
           role = ActiveCypher::RuntimeRegistry.current_role || :writing
           db_key = ConnectionOwner.db_key_for(mapping, role)
           db_key = db_key.to_sym if db_key.respond_to?(:to_sym)

data/lib/active_cypher/model/core.rb

@@ -36,6 +36,14 @@ module ActiveCypher
           clear_changes_information
         end
       end
+
+      def ==(other)
+        # Compares by class and internal graph id only.
+        # Note: an unsaved modification will still compare equal to the persisted version.
+        return false unless other.instance_of?(self.class)
+
+        internal_id == other.internal_id
+      end
     end
   end
 end

data/lib/active_cypher/railtie.rb

@@ -44,8 +44,8 @@ module ActiveCypher
       # Find all abstract node base classes with connects_to mappings
       ObjectSpace.each_object(Class) do |klass|
         next unless klass < ActiveCypher::Base
-        next unless klass.respond_to?(:abstract_class?) && klass.abstract_class?
-        next unless klass.respond_to?(:connects_to_mappings) && klass.connects_to_mappings.present?
+        next unless klass.abstract_class?
+        next if klass.connects_to_mappings.empty?
 
         # Register pools for each role in connects_to mapping
         klass.connects_to_mappings.each_value do |conn_name|

data/lib/active_cypher/relation.rb

@@ -164,8 +164,8 @@ module ActiveCypher
         # 1. Pull out the node payload and the elementId string
         # ------------------------------------------------------------
         if row.is_a?(Hash)
-          node_payload = row[:n] || row['n'] || row
-          element_id   = row[:internal_id] || row['internal_id']
+          node_payload = row[:n] || row['n'] || row[:target] || row['target'] || row
+          element_id   = row[:internal_id] || row['internal_id'] || node_payload&.dig(1, 0)
         else # Array row: [node, id]
           node_payload, element_id = row
         end
@@ -176,6 +176,7 @@ module ActiveCypher
         # ------------------------------------------------------------
         if node_payload.is_a?(Array) && node_payload.first == 78
           # Re‑use the adapter's private helper for consistency
+          # why is it private? This seems to be the only place it's called
           node_payload = model_class.connection
                                     .send(:process_node, node_payload)
         end

data/lib/active_cypher/relationship.rb

@@ -29,9 +29,6 @@ require 'active_support/core_ext/hash/indifferent_access'
 
 module ActiveCypher
   class Relationship
-    # Define connects_to_mappings as a class attribute to match ActiveCypher::Base
-    class_attribute :connects_to_mappings, default: {}
-
     # --------------------------------------------------------------
     # Mix‑ins
     # --------------------------------------------------------------
@@ -44,7 +41,6 @@ module ActiveCypher
     include Model::ConnectionOwner
     include Logging
     include Model::Abstract
-    include Model::ConnectionHandling
     include Model::Callbacks
     include Model::Countable
 
@@ -203,22 +199,24 @@ module ActiveCypher
 
         rel_type = relationship_type
 
+        id_func = connection.class::ID_FUNCTION
+
         # Build WHERE conditions for the attributes
         conditions = []
         params = {}
 
-        attributes.each_with_index do |(key, value), index|
-          param_name = :"p#{index + 1}"
-          conditions << "r.#{key} = $#{param_name}"
-          params[param_name] = value
+        if attributes.key?(:internal_id)
+          where_clause = "#{id_func}(r) = $p1"
+          params['p1'] = attributes[:internal_id]
+        else
+          attributes.each_with_index do |(key, value), index|
+            param_name = :"p#{index + 1}"
+            conditions << "r.#{key} = $#{param_name}"
+            params[param_name] = value
+          end
+          where_clause = conditions.join(' AND ')
         end
 
-        where_clause = conditions.join(' AND ')
-
-        # Determine ID function based on adapter type
-        adapter_class = connection.class
-        id_func = adapter_class.const_defined?(:ID_FUNCTION) ? adapter_class::ID_FUNCTION : 'id'
-
         cypher = <<~CYPHER
           MATCH ()-[r:#{rel_type}]-()
           WHERE #{where_clause}
@@ -234,6 +232,12 @@ module ActiveCypher
         # Extract relationship data and instantiate
         rel_data = row[:r] || row['r']
         rid = row[:rid] || row['rid']
+        from_node_id = (row[:from_node] || row['from_node'])&.dig(1, 0)
+        to_node_id   = (row[:to_node]   || row['to_node'])&.dig(1, 0)
+
+        # this is extra queries, but easier than navigating instantiation from the row data
+        from_node = Object.const_get(from_class).find(from_node_id)
+        to_node = Object.const_get(to_class).find(to_node_id)
 
         # Extract properties from the relationship data
         # Memgraph returns relationships wrapped as [type_code, [actual_data]]
@@ -256,7 +260,7 @@ module ActiveCypher
         attrs = attrs.transform_keys(&:to_sym)
         attrs[:internal_id] = rid if rid
 
-        instantiate(attrs)
+        instantiate(attrs, from_node: from_node, to_node: to_node)
       end
 
       # Find the first relationship or raise an exception

data/lib/active_cypher/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveCypher
-  VERSION = '0.14.2'
+  VERSION = '0.15.2'
 
   def self.gem_version
     Gem::Version.new VERSION

data/lib/cyrel/clause/create.rb

@@ -9,11 +9,7 @@ module Cyrel
       # @param pattern [Cyrel::Pattern::Path, Cyrel::Pattern::Node, Cyrel::Pattern::Relationship]
       #   The pattern to create. Typically a Path or Node.
       def initialize(pattern)
-        # Ensure pattern is a valid type for CREATE
-        unless pattern.is_a?(Cyrel::Pattern::Path) || pattern.is_a?(Cyrel::Pattern::Node) || pattern.is_a?(Cyrel::Pattern::Relationship)
-          raise ArgumentError,
-                "CREATE pattern must be a Cyrel::Pattern::Path, Node, or Relationship, got #{pattern.class}"
-        end
+        Cyrel::Pattern.assert_pattern!(pattern, 'CREATE')
 
         # NOTE: Creating relationships between existing nodes requires coordination.
         # The pattern itself should reference existing aliases defined in a preceding MATCH/MERGE.

data/lib/cyrel/clause/match.rb

@@ -12,13 +12,7 @@ module Cyrel
       # @param path_variable [Symbol, String, nil] An optional variable to assign to the matched path.
       def initialize(pattern, optional: false, path_variable: nil)
         super() # Call super for Base initialization
-        # Ensure pattern is a valid type
-        unless pattern.is_a?(Cyrel::Pattern::Path) ||
-               pattern.is_a?(Cyrel::Pattern::Node) ||
-               pattern.is_a?(Cyrel::Pattern::Relationship)
-          raise ArgumentError,
-                "Match pattern must be a Cyrel::Pattern::Path, Node, or Relationship, got #{pattern.class}"
-        end
+        Cyrel::Pattern.assert_pattern!(pattern, 'Match')
 
         @pattern = pattern
         @optional = optional

data/lib/cyrel/clause/merge.rb

@@ -12,11 +12,7 @@ module Cyrel
       # @param pattern [Cyrel::Pattern::Path, Cyrel::Pattern::Node, Cyrel::Pattern::Relationship]
       #   The pattern to merge. Typically a Path or Node.
       def initialize(pattern)
-        # Ensure pattern is a valid type for MERGE
-        unless pattern.is_a?(Cyrel::Pattern::Path) || pattern.is_a?(Cyrel::Pattern::Node) || pattern.is_a?(Cyrel::Pattern::Relationship)
-          raise ArgumentError,
-                "MERGE pattern must be a Cyrel::Pattern::Path, Node, or Relationship, got #{pattern.class}"
-        end
+        Cyrel::Pattern.assert_pattern!(pattern, 'MERGE')
 
         @pattern = pattern
       end

data/lib/cyrel/expression/exists.rb

@@ -13,10 +13,7 @@ module Cyrel
       # @param pattern [Cyrel::Pattern::Path, Cyrel::Pattern::Node, Cyrel::Pattern::Relationship]
       #   The pattern to check for existence.
       def initialize(pattern)
-        unless pattern.is_a?(Cyrel::Pattern::Path) || pattern.is_a?(Cyrel::Pattern::Node) || pattern.is_a?(Cyrel::Pattern::Relationship)
-          raise ArgumentError,
-                "EXISTS pattern must be a Cyrel::Pattern::Path, Node, or Relationship, got #{pattern.class}"
-        end
+        Cyrel::Pattern.assert_pattern!(pattern, 'EXISTS')
 
         @pattern = pattern
       end

data/lib/cyrel/expression/pattern_comprehension.rb

@@ -13,10 +13,7 @@ module Cyrel
       # @param projection_expression [Cyrel::Expression::Base, Object]
       #   The expression evaluated for each match of the pattern.
       def initialize(pattern, projection_expression)
-        unless pattern.is_a?(Cyrel::Pattern::Path) || pattern.is_a?(Cyrel::Pattern::Node) || pattern.is_a?(Cyrel::Pattern::Relationship)
-          raise ArgumentError,
-                "Pattern Comprehension pattern must be a Path, Node, or Relationship, got #{pattern.class}"
-        end
+        Cyrel::Pattern.assert_pattern!(pattern, 'Pattern Comprehension')
 
         @pattern = pattern
         @projection_expression = Expression.coerce(projection_expression)

data/lib/cyrel/pattern/node.rb

@@ -12,7 +12,7 @@ module Cyrel
 
       attribute :alias_name, Cyrel::Types::SymbolType.new
       attribute :labels,     array: :string, default: []
-      attribute :or_labels,  array: :string, default: []  # Memgraph 3.2+: (n:Label1|Label2)
+      attribute :or_labels,  array: :string, default: [] # Memgraph 3.2+: (n:Label1|Label2)
       attribute :properties, Cyrel::Types::HashType.new, default: -> { {} }
 
       validates :alias_name, presence: true

data/lib/cyrel/pattern.rb

@@ -4,5 +4,15 @@ module Cyrel
   # Namespace for classes representing structural components of Cypher patterns
   # (nodes, relationships, paths).
   module Pattern
+    # Validates that the given object is a usable pattern (Path, Node, or Relationship).
+    # @param pattern [Object] The object to validate.
+    # @param context [String] Label used in the error message (e.g. "CREATE", "MATCH").
+    # @raise [ArgumentError] When the object is not a pattern.
+    def self.assert_pattern!(pattern, context)
+      return pattern if pattern.is_a?(Path) || pattern.is_a?(Node) || pattern.is_a?(Relationship)
+
+      raise ArgumentError,
+            "#{context} pattern must be a Cyrel::Pattern::Path, Node, or Relationship, got #{pattern.class}"
+    end
   end
 end

data/lib/cyrel/query.rb

@@ -136,13 +136,7 @@ module Cyrel
       # ------------------------------------------------------------------
       processed_conditions = conditions.flat_map do |cond|
         if cond.is_a?(Hash)
-          cond.map do |key, value|
-            Expression::Comparison.new(
-              Expression::PropertyAccess.new(@current_alias || infer_alias, key),
-              :'=',
-              value
-            )
-          end
+          hash_to_conditions(cond)
         else
           cond # already an expression (or coercible)
         end
@@ -155,7 +149,7 @@ module Cyrel
       # ------------------------------------------------------------------
       # 2. Merge with an existing WHERE (if any)
       # ------------------------------------------------------------------
-      existing_where_index = @clauses.find_index { |c| c.is_a?(Clause::Where) || (c.is_a?(AST::ClauseAdapter) && c.ast_node.is_a?(AST::WhereNode)) }
+      existing_where_index = find_clause_index(Clause::Where, AST::WhereNode)
 
       if existing_where_index
         existing_clause = @clauses[existing_where_index]
@@ -258,7 +252,7 @@ module Cyrel
       ast_clause = AST::ClauseAdapter.new(set_node)
 
       # Check for existing SET clause to merge with
-      existing_set_index = @clauses.find_index { |c| c.is_a?(Clause::Set) || (c.is_a?(AST::ClauseAdapter) && c.ast_node.is_a?(AST::SetNode)) }
+      existing_set_index = find_clause_index(Clause::Set, AST::SetNode)
 
       if existing_set_index
         existing_clause = @clauses[existing_set_index]
@@ -321,58 +315,19 @@ module Cyrel
     # @return [self]
     # Because sometimes you want to pass things along, and sometimes you just want to pass the buck.
     def with(*items, distinct: false, where: nil)
-      # Process items similar to existing Return clause
-      processed_items = items.flatten.map do |item|
-        case item
-        when Expression::Base
-          item
-        when Symbol
-          # Create a RawIdentifier for variable names
-          Clause::Return::RawIdentifier.new(item.to_s)
-        when String
-          # Check if string looks like property access (e.g. "person.name")
-          # If so, treat as raw identifier, otherwise parameterize
-          if item.match?(/\A\w+\.\w+\z/)
-            Clause::Return::RawIdentifier.new(item)
-          else
-            # String literals should be coerced to expressions (parameterized)
-            Expression.coerce(item)
-          end
-        else
-          Expression.coerce(item)
-        end
-      end
+      processed_items = process_projection_items(items)
 
       # Process WHERE conditions if provided
       where_conditions = case where
                          when nil then []
-                         when Hash
-                           # Convert hash to equality comparisons
-                           where.map do |key, value|
-                             Expression::Comparison.new(
-                               Expression::PropertyAccess.new(@current_alias || infer_alias, key),
-                               :'=',
-                               value
-                             )
-                           end
+                         when Hash then hash_to_conditions(where)
                          when Array then where
                          else [where] # Single condition
                          end
 
       # Use AST-based implementation
       with_node = AST::WithNode.new(processed_items, distinct: distinct, where_conditions: where_conditions)
-      ast_clause = AST::ClauseAdapter.new(with_node)
-
-      # Find and replace existing with or add new one
-      existing_with_index = @clauses.find_index { |c| c.is_a?(Clause::With) || (c.is_a?(AST::ClauseAdapter) && c.ast_node.is_a?(AST::WithNode)) }
-
-      if existing_with_index
-        @clauses[existing_with_index] = ast_clause
-      else
-        add_clause(ast_clause)
-      end
-
-      self
+      replace_or_add_clause(AST::ClauseAdapter.new(with_node), Clause::With, AST::WithNode)
     end
 
     # Adds a RETURN clause.
@@ -384,41 +339,11 @@ module Cyrel
     # is a reserved keyword in Ruby. We're not crazy - we just want to provide
     # a clean DSL while respecting Ruby's language constraints.
     def return_(*items, distinct: false)
-      # Process items similar to existing Return clause
-      processed_items = items.flatten.map do |item|
-        case item
-        when Expression::Base
-          item
-        when Symbol
-          # Create a RawIdentifier for variable names
-          Clause::Return::RawIdentifier.new(item.to_s)
-        when String
-          # Check if string looks like property access (e.g. "person.name")
-          # If so, treat as raw identifier, otherwise parameterize
-          if item.match?(/\A\w+\.\w+\z/)
-            Clause::Return::RawIdentifier.new(item)
-          else
-            # String literals should be coerced to expressions (parameterized)
-            Expression.coerce(item)
-          end
-        else
-          Expression.coerce(item)
-        end
-      end
+      processed_items = process_projection_items(items)
 
       # Use AST-based implementation
       return_node = AST::ReturnNode.new(processed_items, distinct: distinct)
-      ast_clause = AST::ClauseAdapter.new(return_node)
-
-      # Find and replace existing return or add new one
-      existing_return_index = @clauses.find_index { |c| c.is_a?(Clause::Return) || (c.is_a?(AST::ClauseAdapter) && c.ast_node.is_a?(AST::ReturnNode)) }
-
-      if existing_return_index
-        @clauses[existing_return_index] = ast_clause
-      else
-        add_clause(ast_clause)
-      end
-      self
+      replace_or_add_clause(AST::ClauseAdapter.new(return_node), Clause::Return, AST::ReturnNode)
     end
 
     # Adds or replaces the ORDER BY clause.
@@ -432,17 +357,7 @@ module Cyrel
 
       # Use AST-based implementation
       order_by_node = AST::OrderByNode.new(items_array)
-      ast_clause = AST::ClauseAdapter.new(order_by_node)
-
-      # Find and replace existing order by or add new one
-      existing_order_index = @clauses.find_index { |c| c.is_a?(Clause::OrderBy) || (c.is_a?(AST::ClauseAdapter) && c.ast_node.is_a?(AST::OrderByNode)) }
-
-      if existing_order_index
-        @clauses[existing_order_index] = ast_clause
-      else
-        add_clause(ast_clause)
-      end
-      self
+      replace_or_add_clause(AST::ClauseAdapter.new(order_by_node), Clause::OrderBy, AST::OrderByNode)
     end
 
     # Adds or replaces the SKIP clause.
@@ -452,17 +367,7 @@ module Cyrel
     def skip(amount)
       # Use AST-based implementation
       skip_node = AST::SkipNode.new(amount)
-      ast_clause = AST::ClauseAdapter.new(skip_node)
-
-      # Find and replace existing skip or add new one
-      existing_skip_index = @clauses.find_index { |c| c.is_a?(Clause::Skip) || (c.is_a?(AST::ClauseAdapter) && c.ast_node.is_a?(AST::SkipNode)) }
-
-      if existing_skip_index
-        @clauses[existing_skip_index] = ast_clause
-      else
-        add_clause(ast_clause)
-      end
-      self
+      replace_or_add_clause(AST::ClauseAdapter.new(skip_node), Clause::Skip, AST::SkipNode)
     end
 
     # Adds or replaces the LIMIT clause.
@@ -472,18 +377,7 @@ module Cyrel
     def limit(amount)
       # Use AST-based implementation
       limit_node = AST::LimitNode.new(amount)
-      ast_clause = AST::ClauseAdapter.new(limit_node)
-
-      # Find and replace existing limit or add new one
-      existing_limit_index = @clauses.find_index { |c| c.is_a?(Clause::Limit) || (c.is_a?(AST::ClauseAdapter) && c.ast_node.is_a?(AST::LimitNode)) }
-
-      if existing_limit_index
-        @clauses[existing_limit_index] = ast_clause
-      else
-        add_clause(ast_clause)
-      end
-
-      self
+      replace_or_add_clause(AST::ClauseAdapter.new(limit_node), Clause::Limit, AST::LimitNode)
     end
 
     # Adds a CALL procedure clause.
@@ -600,6 +494,58 @@ module Cyrel
       add_clause(AST::ClauseAdapter.new(load_csv_node))
     end
 
+    # Coerces projection items (symbols, strings, expressions) for WITH/RETURN clauses.
+    def process_projection_items(items)
+      items.flatten.map do |item|
+        case item
+        when Expression::Base
+          item
+        when Symbol
+          # Create a RawIdentifier for variable names
+          Clause::Return::RawIdentifier.new(item.to_s)
+        when String
+          # Check if string looks like property access (e.g. "person.name")
+          # If so, treat as raw identifier, otherwise parameterize
+          if item.match?(/\A\w+\.\w+\z/)
+            Clause::Return::RawIdentifier.new(item)
+          else
+            # String literals should be coerced to expressions (parameterized)
+            Expression.coerce(item)
+          end
+        else
+          Expression.coerce(item)
+        end
+      end
+    end
+
+    # Converts a Hash into equality comparisons against the current alias.
+    def hash_to_conditions(hash)
+      hash.map do |key, value|
+        Expression::Comparison.new(
+          Expression::PropertyAccess.new(@current_alias || infer_alias, key),
+          :'=',
+          value
+        )
+      end
+    end
+
+    # Finds the index of an existing clause matching either the legacy clause
+    # class or an AST::ClauseAdapter wrapping the given AST node class.
+    def find_clause_index(clause_class, ast_node_class)
+      @clauses.find_index { |c| c.is_a?(clause_class) || (c.is_a?(AST::ClauseAdapter) && c.ast_node.is_a?(ast_node_class)) }
+    end
+
+    # Replaces an existing matching clause in place, or appends the new one.
+    def replace_or_add_clause(ast_clause, clause_class, ast_node_class)
+      existing_index = find_clause_index(clause_class, ast_node_class)
+      if existing_index
+        @clauses[existing_index] = ast_clause
+      else
+        add_clause(ast_clause)
+      end
+      self
+    end
+
     # private
 
     # Merges parameters from another query, ensuring keys are unique.