activecypher 0.15.3 → 0.15.5

data/lib/active_cypher/connection_adapters/memgraph_adapter.rb

@@ -112,6 +112,8 @@ module ActiveCypher
         end
       end
 
+      TRANSIENT_RETRIES = 3
+
       # Override run to execute queries using auto-commit mode.
       # Memgraph auto-commits each query, so we send RUN + PULL directly
       # without BEGIN/COMMIT wrapper. This avoids transaction state issues.
@@ -120,7 +122,26 @@ module ActiveCypher
         logger.debug { "[#{context}] #{cypher} #{params.inspect}" }
 
         instrument_query(cypher, params, context: context, metadata: { db: db, access_mode: access_mode }) do
-          run_auto_commit(cypher, prepare_params(params))
+          with_transient_retry(context) { run_auto_commit(cypher, prepare_params(params)) }
+        end
+      end
+
+      # Retry write/write conflicts the server flagged as transient. Safe only
+      # because this path is auto-commit (the whole query rolled back); do NOT
+      # lift into the explicit-transaction path, where earlier statements may
+      # already have applied.
+      def with_transient_retry(context)
+        attempts = 0
+        begin
+          yield
+        rescue ActiveCypher::TransientError => e
+          attempts += 1
+          raise if attempts > TRANSIENT_RETRIES
+
+          # Full jitter, so conflicting writers don't back off in step.
+          sleep(rand * 0.05 * (2**(attempts - 1)))
+          logger.debug { "[#{context}] transient conflict, retry #{attempts}/#{TRANSIENT_RETRIES}: #{e.message}" }
+          retry
         end
       end
 
@@ -159,10 +180,7 @@ module ActiveCypher
                 # End of results
                 break
               when Bolt::Messaging::Failure
-                code = msg.metadata['code']
-                message = msg.metadata['message']
-                connection.reset!
-                raise QueryError, "Query failed: #{code} - #{message}"
+                raise_query_failure(msg)
               else
                 raise ProtocolError, "Unexpected response during PULL: #{msg.class}"
               end
@@ -170,16 +188,21 @@ module ActiveCypher
 
             rows
           when Bolt::Messaging::Failure
-            code = run_response.metadata['code']
-            message = run_response.metadata['message']
-            connection.reset!
-            raise QueryError, "Query failed: #{code} - #{message}"
+            raise_query_failure(run_response)
           else
             raise ProtocolError, "Unexpected response to RUN: #{run_response.class}"
           end
         end
       end
 
+      # Reset the connection and raise a QueryError for a Bolt Failure message.
+      # @param failure [Bolt::Messaging::Failure]
+      # @raise [QueryError]
+      def raise_query_failure(failure)
+        connection.reset!
+        raise QueryError, "Query failed: #{failure.metadata['code']} - #{failure.metadata['message']}"
+      end
+
       # Memgraph defaults to **implicit auto‑commit** transactions
       # so we simply run the Cypher and return the rows.
       def execute_cypher(cypher, params = {}, ctx = 'Query')
@@ -276,7 +299,7 @@ module ActiveCypher
       module Persistence
         include PersistenceMethods
 
-        module_function :create_record, :update_record, :destroy_record
+        module_function :create_record, :update_record, :destroy_record, :node_id_expr
       end
 
       class ProtocolHandler < AbstractProtocolHandler

data/lib/active_cypher/connection_adapters/neo4j_adapter.rb

@@ -133,7 +133,7 @@ module ActiveCypher
       module Persistence
         include PersistenceMethods
 
-        module_function :create_record, :update_record, :destroy_record
+        module_function :create_record, :update_record, :destroy_record, :node_id_expr
       end
 
       protected

data/lib/active_cypher/connection_adapters/persistence_methods.rb

@@ -20,11 +20,7 @@ module ActiveCypher
         # OPTIMIZED: Use string template instead of Cyrel for known-safe CREATE pattern
         # Labels come from model class (safe), props are parameterized (safe)
         label_string = labels.map { |l| ":#{l}" }.join
-        cypher = if adapter.id_function == 'elementId'
-                   "CREATE (n#{label_string} $props) RETURN elementId(n) AS internal_id"
-                 else
-                   "CREATE (n#{label_string} $props) RETURN id(n) AS internal_id"
-                 end
+        cypher = "CREATE (n#{label_string} $props) RETURN #{node_id_expr(adapter)} AS internal_id"
 
         data = model.connection.execute_cypher(cypher, { props: props }, 'Create')
 
@@ -59,11 +55,7 @@ module ActiveCypher
         label_string = labels.map { |l| ":#{l}" }.join
         set_clauses = changes.keys.map { |property| "n.#{property} = $#{property}" }.join(', ')
 
-        cypher = if adapter.id_function == 'elementId'
-                   "MATCH (n#{label_string}) WHERE elementId(n) = $node_id SET #{set_clauses} RETURN n"
-                 else
-                   "MATCH (n#{label_string}) WHERE id(n) = $node_id SET #{set_clauses} RETURN n"
-                 end
+        cypher = "MATCH (n#{label_string}) WHERE #{node_id_expr(adapter)} = $node_id SET #{set_clauses} RETURN n"
 
         params = changes.merge(node_id: node_id_param)
         model.connection.execute_cypher(cypher, params, 'Update')
@@ -91,15 +83,20 @@ module ActiveCypher
         # Labels come from model class (safe)
         label_string = labels.map { |l| ":#{l}" }.join
 
-        cypher = if adapter.id_function == 'elementId'
-                   "MATCH (n#{label_string}) WHERE elementId(n) = $node_id DETACH DELETE n RETURN count(*) AS deleted"
-                 else
-                   "MATCH (n#{label_string}) WHERE id(n) = $node_id DETACH DELETE n RETURN count(*) AS deleted"
-                 end
+        cypher = "MATCH (n#{label_string}) WHERE #{node_id_expr(adapter)} = $node_id DETACH DELETE n RETURN count(*) AS deleted"
 
         result = model.connection.execute_cypher(cypher, { node_id: node_id_param }, 'Destroy')
         result.present? && result.first[:deleted].to_i.positive?
       end
+
+      private
+
+      # The node-id function call for the adapter's dialect (Neo4j uses elementId, Memgraph id).
+      # @param adapter [#id_function] the connection's id handler
+      # @return [String] "elementId(n)" or "id(n)"
+      def node_id_expr(adapter)
+        adapter.id_function == 'elementId' ? 'elementId(n)' : 'id(n)'
+      end
     end
   end
 end

data/lib/active_cypher/connection_pool.rb

@@ -25,27 +25,40 @@ module ActiveCypher
         @spec = resolved_config.merge(@spec.except(:url))
       end
 
-      @conn_ref = nil # holds the adapter instance
-      @creation_mutex = Mutex.new # prevents multiple threads from creating connections simultaneously
+      # One connection per thread: Bolt is a stateful, ordered protocol, so
+      # sharing a socket across threads corrupts the stream. @connections
+      # exists only so disconnect can close them all; the thread-local is
+      # what the hot path reads.
+      @connections = {}
+      @creation_mutex = Mutex.new
     end
 
-    # Returns a live adapter, initializing it once in a thread‑safe way.
+    # Returns a live adapter belonging to the calling thread.
     def connection
-      # Fast path — already connected and alive
-      conn = @conn_ref
+      conn = Thread.current[thread_key]
       return conn if conn&.active?
 
-      # Use mutex for the slow path to prevent thundering herd
-      @creation_mutex.synchronize do
-        # Check again inside the mutex in case another thread created it
-        conn = @conn_ref
-        return conn if conn&.active?
+      # Built outside the mutex: connecting does network IO.
+      new_conn = build_connection
+      Thread.current[thread_key] = new_conn
+
+      # Reap dead threads' connections, or each short-lived thread leaks a
+      # socket the server counts against max_connections.
+      orphaned = @creation_mutex.synchronize do
+        dead = @connections.reject { |t, _| t.alive? }
+        dead.each_key { |t| @connections.delete(t) }
+        @connections[Thread.current] = new_conn
+        dead.values
+      end
 
-        # Create a new connection
-        new_conn = build_connection
-        @conn_ref = new_conn
-        return new_conn
+      # Closed outside the mutex: disconnecting does IO too.
+      orphaned.each do |conn|
+        conn.disconnect
+      rescue StandardError => e
+        puts "Warning: Error disconnecting orphaned connection: #{e.message}" if ENV['DEBUG']
       end
+
+      new_conn
     end
     alias checkout connection
 
@@ -54,23 +67,31 @@ module ActiveCypher
       @retry_count >= @spec[:max_retries]
     end
 
-    # Explicitly close and reset the connection
+    # Explicitly close every connection this pool handed out.
     def disconnect
-      conn = @conn_ref
-      return unless conn
+      conns = @creation_mutex.synchronize do
+        taken = @connections.values
+        @connections.clear
+        taken
+      end
 
-      begin
+      conns.each do |conn|
         conn.disconnect
       rescue StandardError => e
         # Log but don't raise to ensure cleanup continues
         puts "Warning: Error disconnecting: #{e.message}" if ENV['DEBUG']
-      ensure
-        @conn_ref = nil
       end
+
+      Thread.current[thread_key] = nil
     end
 
     private
 
+    # Namespaced per pool instance so multiple databases don't share.
+    def thread_key
+      @thread_key ||= :"active_cypher_connection_#{object_id}"
+    end
+
     def build_connection
       adapter_name = @spec[:adapter]
       raise ArgumentError, 'Missing adapter name in connection specification' unless adapter_name

data/lib/active_cypher/fixtures.rb

@@ -35,11 +35,7 @@ module ActiveCypher
       connections = model_classes.map(&:connection).compact.uniq
 
       # 6. Wipe all nodes in each relevant connection
-      connections.each do |conn|
-        conn.execute_cypher('MATCH (n) DETACH DELETE n')
-      rescue StandardError => e
-        warn "[ActiveCypher::Fixtures.load] Failed to clear connection #{conn.inspect}: #{e.class}: #{e.message}"
-      end
+      wipe_connections(connections, 'load')
 
       # 7. Evaluate nodes and relationships (batched if large)
       if dsl_context.nodes.size > 100 || dsl_context.relationships.size > 200
@@ -77,12 +73,39 @@ module ActiveCypher
       connections = model_classes.map(&:connection).compact.uniq
 
       # Wipe all nodes in each connection
+      wipe_connections(connections, 'clear_all')
+      true
+    end
+
+    # Build a comparable connection fingerprint for cross-database detection.
+    # @param conn [Object] a model connection
+    # @return [Hash] adapter/config/object_id details
+    def self.connection_details(conn)
+      {
+        adapter: conn.class.name,
+        config: conn.instance_variable_get(:@config),
+        object_id: conn.object_id
+      }
+    end
+
+    # Memoized connection-details lookup for a model class.
+    # @param klass [Class] the model class
+    # @param cache [Hash] class => details mapping, populated on miss
+    # @return [Hash] the connection details
+    def self.conn_details_for(klass, cache)
+      cache[klass] ||= connection_details(klass.connection)
+    end
+
+    # Detach-delete every node across the given connections, logging per-connection failures.
+    # @param connections [Array] connections to wipe
+    # @param context [String] caller name used in the warning prefix
+    # @return [void]
+    def self.wipe_connections(connections, context)
       connections.each do |conn|
         conn.execute_cypher('MATCH (n) DETACH DELETE n')
       rescue StandardError => e
-        warn "[ActiveCypher::Fixtures.clear_all] Failed to clear connection #{conn.inspect}: #{e.class}: #{e.message}"
+        warn "[ActiveCypher::Fixtures.#{context}] Failed to clear connection #{conn.inspect}: #{e.class}: #{e.message}"
       end
-      true
     end
 
     # Validates relationships for cross-DB issues
@@ -96,13 +119,8 @@ module ActiveCypher
         next unless klass < ActiveCypher::Base
         next if klass.respond_to?(:abstract_class?) && klass.abstract_class?
 
-        conn = klass.connection
         # Store connection details for comparison
-        model_connections[klass] = {
-          adapter: conn.class.name,
-          config: conn.instance_variable_get(:@config),
-          object_id: conn.object_id
-        }
+        model_connections[klass] = connection_details(klass.connection)
       end
 
       relationships.each do |rel|
@@ -120,30 +138,9 @@ module ActiveCypher
         from_class = from_node.class
         to_class = to_node.class
 
-        # Look up connection details for each class
-        from_conn_details = model_connections[from_class]
-        to_conn_details = model_connections[to_class]
-
-        # If either class isn't in our mapping, refresh it
-        unless from_conn_details
-          conn = from_class.connection
-          from_conn_details = {
-            adapter: conn.class.name,
-            config: conn.instance_variable_get(:@config),
-            object_id: conn.object_id
-          }
-          model_connections[from_class] = from_conn_details
-        end
-
-        unless to_conn_details
-          conn = to_class.connection
-          to_conn_details = {
-            adapter: conn.class.name,
-            config: conn.instance_variable_get(:@config),
-            object_id: conn.object_id
-          }
-          model_connections[to_class] = to_conn_details
-        end
+        # Look up connection details for each class, refreshing the cache on miss
+        from_conn_details = conn_details_for(from_class, model_connections)
+        to_conn_details = conn_details_for(to_class, model_connections)
 
         # Compare connection details
         next unless from_conn_details[:object_id] != to_conn_details[:object_id] ||

data/lib/active_cypher/migration.rb

@@ -40,14 +40,7 @@ module ActiveCypher
       composite = props.size > 1 if composite.nil?
 
       cypher = if connection.vendor == :memgraph
-                 if composite && props.size > 1
-                   # Memgraph 3.2+ composite index: CREATE INDEX ON :Label(prop1, prop2)
-                   props_list = props.join(', ')
-                   ["CREATE INDEX ON :#{label}(#{props_list})"]
-                 else
-                   # Memgraph single property indexes
-                   props.map { |p| "CREATE INDEX ON :#{label}(#{p})" }
-                 end
+                 memgraph_index_statements('INDEX', label, props, composite)
                else
                  # Neo4j syntax
                  props_clause = props.map { |p| "n.#{p}" }.join(', ')
@@ -72,13 +65,7 @@ module ActiveCypher
       composite = props.size > 1 if composite.nil?
 
       cypher = if connection.vendor == :memgraph
-                 if composite && props.size > 1
-                   # Memgraph 3.2+ composite edge index
-                   props_list = props.join(', ')
-                   ["CREATE EDGE INDEX ON :#{rel_type}(#{props_list})"]
-                 else
-                   props.map { |p| "CREATE EDGE INDEX ON :#{rel_type}(#{p})" }
-                 end
+                 memgraph_index_statements('EDGE INDEX', rel_type, props, composite)
                else
                  # Neo4j syntax
                  props_clause = props.map { |p| "r.#{p}" }.join(', ')
@@ -221,6 +208,22 @@ module ActiveCypher
 
     private
 
+    # Build Memgraph CREATE [EDGE] INDEX statements for a label/type and properties.
+    # @param index_keyword [String] "INDEX" for nodes, "EDGE INDEX" for relationships
+    # @param label [Symbol, String] node label or relationship type
+    # @param props [Array<Symbol, String>] properties to index
+    # @param composite [Boolean] emit a single composite index when more than one prop
+    # @return [Array<String>] one or more Cypher statements
+    def memgraph_index_statements(index_keyword, label, props, composite)
+      if composite && props.size > 1
+        # Memgraph 3.2+ composite index: CREATE [EDGE] INDEX ON :Label(prop1, prop2)
+        ["CREATE #{index_keyword} ON :#{label}(#{props.join(', ')})"]
+      else
+        # Single property indexes
+        props.map { |p| "CREATE #{index_keyword} ON :#{label}(#{p})" }
+      end
+    end
+
     def execute_operations
       if connection.vendor == :memgraph
         # Memgraph requires auto-commit for DDL operations

data/lib/active_cypher/rails_lens_ext/annotator.rb

@@ -115,24 +115,10 @@ module ActiveCypher
           models = []
 
           # Find all Node classes (ActiveCypher::Base descendants)
-          if defined?(::ActiveCypher::Base)
-            ObjectSpace.each_object(Class) do |klass|
-              next unless klass < ::ActiveCypher::Base
-              next if klass == ::ActiveCypher::Base
-
-              models << klass
-            end
-          end
+          models.concat(descendants_of(::ActiveCypher::Base)) if defined?(::ActiveCypher::Base)
 
           # Find all Relationship classes (ActiveCypher::Relationship descendants)
-          if defined?(::ActiveCypher::Relationship)
-            ObjectSpace.each_object(Class) do |klass|
-              next unless klass < ::ActiveCypher::Relationship
-              next if klass == ::ActiveCypher::Relationship
-
-              models << klass
-            end
-          end
+          models.concat(descendants_of(::ActiveCypher::Relationship)) if defined?(::ActiveCypher::Relationship)
 
           # Filter out abstract classes unless requested
           models.reject! { |m| m.respond_to?(:abstract_class?) && m.abstract_class? } unless options[:include_abstract]
@@ -152,6 +138,19 @@ module ActiveCypher
           models.sort_by { |m| m.name || '' }
         end
 
+        # Collect every loaded subclass of +base+ (excluding +base+ itself).
+        # @param base [Class] the ancestor to scan for
+        # @return [Array<Class>] strict descendants of +base+
+        def descendants_of(base)
+          [].tap do |found|
+            ObjectSpace.each_object(Class) do |klass|
+              next unless klass < base
+
+              found << klass
+            end
+          end
+        end
+
         # Eager load graph models from Rails app
         def eager_load_graph_models
           return unless defined?(Rails) && Rails.respond_to?(:root)

data/lib/active_cypher/version.rb

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

data/lib/activecypher.rb

@@ -52,6 +52,14 @@ module ActiveCypher
   # Could be you. Could be Cypher. Could be fate.
   class QueryError < Error; end
 
+  # A uniqueness or existence constraint said no.
+  # Rescue this to ignore duplicates without swallowing every QueryError.
+  class ConstraintError < QueryError; end
+
+  # Two writers touched the same node. Nothing is wrong with your query.
+  # The server is politely asking you to try again.
+  class TransientError < QueryError; end
+
   # Your Cypher syntax is... interpretive.
   # Unfortunately, the parser isn’t in the mood for interpretive dance.
   class CypherSyntaxError < QueryError; end

data/lib/cyrel/ast/compiler.rb

@@ -84,10 +84,7 @@ module Cyrel
         @output << 'RETURN '
         @output << 'DISTINCT ' if node.distinct
 
-        node.items.each_with_index do |item, index|
-          @output << ', ' if index.positive?
-          render_expression(item)
-        end
+        render_comma_separated(node.items)
       end
 
       # Visit a SET node
@@ -109,10 +106,7 @@ module Cyrel
         @output << 'WITH '
         @output << 'DISTINCT ' if node.distinct
 
-        node.items.each_with_index do |item, index|
-          @output << ', ' if index.positive?
-          render_expression(item)
-        end
+        render_comma_separated(node.items)
 
         # Add WHERE clause if present
         return unless node.where_conditions && !node.where_conditions.empty?
@@ -139,13 +133,8 @@ module Cyrel
         if node.expression.is_a?(Array)
           # Array literal
           @output << format_array_literal(node.expression)
-        elsif node.expression.is_a?(Symbol)
-          # Parameter reference
-          param_key = register_parameter(node.expression)
-          @output << "$#{param_key}"
         else
-          # Other expressions
-          render_expression(node.expression)
+          render_param_or_expression(node.expression)
         end
 
         @output << " AS #{node.alias_name}"
@@ -280,11 +269,11 @@ module Cyrel
 
             subquery_compiler = QueryIntegratedCompiler.new(parameter_proxy)
             clause_cypher, = subquery_compiler.compile(clause.ast_node)
-            @output << clause_cypher.split("\n").map { |line| "  #{line}" }.join("\n")
+            @output << indent_block(clause_cypher)
           else
             # For legacy clauses, render normally
             clause_output = clause.render(subquery)
-            @output << clause_output.split("\n").map { |line| "  #{line}" }.join("\n") unless clause_output.blank?
+            @output << indent_block(clause_output) unless clause_output.blank?
 
             # Merge subquery parameters
             subquery.parameters.each_value do |value|
@@ -346,18 +335,12 @@ module Cyrel
       def visit_foreach_node(node)
         @output << "FOREACH (#{node.variable} IN "
 
-        # Handle the expression - could be an array literal or an expression
+        # Handle the expression - could be an array literal or an expression.
+        # An array is parameterized whole; everything else defers to the shared helper.
         if node.expression.is_a?(Array)
-          # Array literal - convert to parameter
-          param_key = register_parameter(node.expression)
-          @output << "$#{param_key}"
-        elsif node.expression.is_a?(Symbol)
-          # Symbol reference to parameter
-          param_key = register_parameter(node.expression)
-          @output << "$#{param_key}"
+          @output << "$#{register_parameter(node.expression)}"
         else
-          # Other expressions
-          render_expression(node.expression)
+          render_param_or_expression(node.expression)
         end
 
         @output << ' | '
@@ -392,8 +375,6 @@ module Cyrel
           inner_compiler.instance_variable_set(:@loop_variables, @loop_variables.dup)
           clause_cypher, = inner_compiler.compile([clause.ast_node])
           @output << clause_cypher
-
-          # For other clause types, render directly
         end
 
         # Restore previous loop variables context
@@ -518,6 +499,34 @@ module Cyrel
         end
       end
 
+      # Render a list of items separated by commas (RETURN/WITH projections).
+      # @param items [Array] the expressions to render
+      # @return [void]
+      def render_comma_separated(items)
+        items.each_with_index do |item, index|
+          @output << ', ' if index.positive?
+          render_expression(item)
+        end
+      end
+
+      # Indent every line of a Cypher fragment by two spaces (subquery nesting).
+      # @param text [String] the fragment to indent
+      # @return [String] the indented fragment
+      def indent_block(text)
+        text.split("\n").map { |line| "  #{line}" }.join("\n")
+      end
+
+      # Render a symbol as a parameter reference, otherwise delegate to {#render_expression}.
+      # @param expression [Object] the value to render
+      # @return [void]
+      def render_param_or_expression(expression)
+        if expression.is_a?(Symbol)
+          @output << "$#{register_parameter(expression)}"
+        else
+          render_expression(expression)
+        end
+      end
+
       # Render an expression (could be a literal, parameter, property access, etc.)
       def render_expression(expr)
         case expr

data/lib/cyrel/clause/set.rb

@@ -17,34 +17,14 @@ module Cyrel
       #     e.g., [[:n, "NewLabel"], [:m, "AnotherLabel"]]
       #   Note: Mixing hash and array styles in one call is not directly supported, use multiple SET clauses if needed.
       def initialize(assignments)
-        @assignments = process_assignments(assignments)
+        @assignments = self.class.normalize_assignments(assignments)
       end
 
-      # Renders the SET clause.
-      # @param query [Cyrel::Query] The query object for rendering expressions.
-      # @return [String, nil] The Cypher string fragment, or nil if no assignments exist.
-      def render(query)
-        return nil if @assignments.empty?
-
-        set_parts = @assignments.map do |assignment|
-          render_assignment(assignment, query)
-        end
-
-        "SET #{set_parts.join(', ')}"
-      end
-
-      # Merges assignments from another Set clause.
-      # @param other_set [Cyrel::Clause::Set] The other Set clause to merge.
-      def merge!(other_set)
-        # Simple concatenation, assumes no conflicting assignments on the same property.
-        # More sophisticated merging might be needed depending on requirements.
-        @assignments.concat(other_set.assignments)
-        self
-      end
-
-      private
-
-      def process_assignments(assignments)
+      # Normalize raw SET assignments (Hash of props/labels or Array of label pairs)
+      # into the internal tuple form consumed by both Clause::Set and Query#set.
+      # @param assignments [Hash, Array]
+      # @return [Array<Array>] tuples like [:property, ...], [:variable_properties, ...], [:label, ...]
+      def self.normalize_assignments(assignments)
         case assignments
         when Hash
           assignments.flat_map do |key, value|
@@ -68,19 +48,43 @@ module Cyrel
           end
         when Array
           assignments.map do |item|
-            unless item.is_a?(Array) && item.length == 2 && item[0].is_a?(Symbol) && item[1].is_a?(String)
+            unless item.is_a?(Array) && item.length == 2
               raise ArgumentError,
                     "Invalid label assignment format. Expected [[:variable, 'Label'], ...], got #{item.inspect}"
             end
 
             # SET n:Label
-            [:label, item[0], item[1]]
+            [:label, item[0].to_sym, item[1]]
           end
         else
           raise ArgumentError, "Invalid assignments type for SET clause: #{assignments.class}"
         end
       end
 
+      # Renders the SET clause.
+      # @param query [Cyrel::Query] The query object for rendering expressions.
+      # @return [String, nil] The Cypher string fragment, or nil if no assignments exist.
+      def render(query)
+        return nil if @assignments.empty?
+
+        set_parts = @assignments.map do |assignment|
+          render_assignment(assignment, query)
+        end
+
+        "SET #{set_parts.join(', ')}"
+      end
+
+      # Merges assignments from another Set clause.
+      # @param other_set [Cyrel::Clause::Set] The other Set clause to merge.
+      def merge!(other_set)
+        # Simple concatenation, assumes no conflicting assignments on the same property.
+        # More sophisticated merging might be needed depending on requirements.
+        @assignments.concat(other_set.assignments)
+        self
+      end
+
+      private
+
       def render_assignment(assignment, query)
         type, target, value, op = assignment
         case type