cypher-dsl 0.1.0.alpha.1 → 0.1.0.alpha.2

data/lib/cypher_dsl/renderer/visitor/expressions.rb

@@ -17,7 +17,7 @@ module CypherDSL
           when Asterisk then '*'
           when AliasedExpression then render_aliased_reference(expression)
           when NamedPath then render_expression(expression.symbolic_name)
-          when RawExpression then expression.content
+          when RawExpression then render_raw(expression)
           when CollectExpression
             block('COLLECT {', '}') { render_subquery(expression.statement, expression.imports) }
           when CountExpression then render_count(expression)
@@ -60,6 +60,7 @@ module CypherDSL
           when LabelOperation then render_labels(expression.node, expression.labels)
           when Reduction then render_reduction(expression)
           when PatternExpression then render_pattern_expression(expression.pattern)
+          when VectorLiteral then expression.as_string
           else render_condition_or_operation(expression)
           end
         end
@@ -71,7 +72,7 @@ module CypherDSL
         end
 
         def render_labels(node, labels)
-          "#{render_expression(node)}#{labels.map { |label| ":#{escape_schema_name(label)}" }.join}"
+          "#{render_expression(node)}#{labels.map { |label| render_label(label) }.join}"
         end
 
         def render_condition_or_operation(expression)
@@ -81,6 +82,7 @@ module CypherDSL
           when ConstantCondition then expression.value.to_s
           when ExpressionCondition then render_expression(expression.expression)
           when ExistsCondition then render_exists(expression)
+          when PropertyExistsCondition then render_property_exists(expression)
           when RelationshipPatternCondition then render_pattern_expression(expression.pattern)
           when ListPredicate then render_list_predicate(expression)
           when HasLabelCondition then render_labels(expression.node, expression.labels)
@@ -109,18 +111,29 @@ module CypherDSL
           "exists(#{render_pattern_expression(body)})"
         end
 
+        # A pattern body renders bare; with imports it needs a MATCH after the WITH.
         def render_count(count)
           body = count.body
-          return block('COUNT {', '}') { render_subquery(body, count.imports) } if body.is_a?(Statement)
+          return block('COUNT {', '}') { render_subquery(body, count.imports) } unless pattern_body?(body)
 
-          "COUNT { #{render_in_own_scope { render_pattern_element(body) }} }"
+          rendered = render_in_own_scope do
+            imports = count.imports.map { |import| render_projection_item(import) }
+            parts = [("WITH #{imports.join(', ')} MATCH" unless imports.empty?), render_pattern_element(body)]
+            parts << "WHERE #{render_expression(count.where_condition)}" if count.where_condition
+            parts.compact.join(' ')
+          end
+          "COUNT { #{rendered} }"
         end
 
+        def pattern_body?(body) = !(body.is_a?(Statement) || body.is_a?(UnionQuery))
+
         # Renders with the current scope, discarding names introduced inside.
         def render_in_own_scope
           outer_scope = @visited_names.dup
+          @names.enter_scope(:all)
           yield
         ensure
+          @names.leave_scope([])
           @visited_names = outer_scope
         end
 
@@ -166,13 +179,13 @@ module CypherDSL
         # A pattern comprehension is its own scope: names it introduces do not
         # count as visited outside of it.
         def render_pattern_comprehension(comprehension)
-          outer_scope = @visited_names.dup
-          parts = [render_pattern_element(comprehension.pattern)]
-          parts << "WHERE #{render_expression(comprehension.where_condition)}" if comprehension.where_condition
-          projection = comprehension.projection.map { |expression| render_expression(expression) }
-          parts << "| #{projection.size == 1 ? projection.first : "[#{projection.join(', ')}]"}"
-          @visited_names = outer_scope
-          "[#{parts.join(' ')}]"
+          render_in_own_scope do
+            parts = [render_pattern_element(comprehension.pattern)]
+            parts << "WHERE #{render_expression(comprehension.where_condition)}" if comprehension.where_condition
+            projection = comprehension.projection.map { |expression| render_expression(expression) }
+            parts << "| #{projection.size == 1 ? projection.first : "[#{projection.join(', ')}]"}"
+            "[#{parts.join(' ')}]"
+          end
         end
 
         def render_list_comprehension(comprehension)
@@ -185,7 +198,8 @@ module CypherDSL
         # Records every use for the catalog; anonymous parameters get `pcdslNN`,
         # shared between anonymous parameters with equal values.
         def render_parameter(parameter)
-          name = parameter.anonymous? ? anonymous_parameter_name(parameter) : parameter.name
+          name = parameter.anonymous? ? anonymous_parameter_name(parameter) : @names.resolve_parameter(parameter)
+          @renamed_parameters[parameter.name] = name if !parameter.anonymous? && name != parameter.name
           (@parameter_uses[name] ||= []) << parameter.value
           "$#{Escaper.escape_parameter_name(name)}"
         end
@@ -206,11 +220,18 @@ module CypherDSL
           "#{render_expression(property.container)}#{lookups.join}"
         end
 
+        # Verbatim text with its embedded expressions rendered (and their parameters collected).
+        def render_raw(raw)
+          raw.parts.map { |part| part.is_a?(String) ? part : render_expression(part) }.join
+        end
+
         def render_literal(value)
           case value
-          when String then "'#{value.gsub('\\') { '\\\\' }.gsub("'") { "\\'" }}'"
+          when String then Literal.quote(value)
           when nil then 'NULL'
           when true, false, Numeric then value.to_s
+          when DateTime, Time then "datetime('#{value.iso8601}')"
+          when Date then "date('#{value.iso8601}')"
           else raise ArgumentError, "Cannot render literal #{value.inspect}"
           end
         end
@@ -243,9 +264,21 @@ module CypherDSL
         end
 
         # Pretty printed, each further operand starts an indented line: `(a\n  AND b)`.
+        # `exists(n.prop)` on Neo4j 4, `n.prop IS NOT NULL` afterwards.
+        def render_property_exists(condition, negated: false)
+          property = render_expression(condition.property)
+          return "exists(#{property})" if @configuration.legacy_functions?
+
+          "#{property} IS #{'NOT ' unless negated}NULL"
+        end
+
         def render_compound_condition(condition)
           if condition.negation?
             negated = condition.conditions.first
+            if negated.is_a?(PropertyExistsCondition) && !@configuration.legacy_functions?
+              return render_property_exists(negated, negated: true)
+            end
+
             rendered = render_expression(negated)
             return negated.is_a?(RelationshipPatternCondition) ? "NOT #{rendered}" : "NOT (#{rendered})"
           end
@@ -255,9 +288,13 @@ module CypherDSL
         end
 
         def render_function_invocation(invocation)
-          arguments = invocation.arguments.map { |argument| render_expression(argument) }
+          arguments = invocation.arguments.map do |argument|
+            rendered = render_expression(argument)
+            # Pretty printed, a map argument keeps a space after the parenthesis: `collect( {`.
+            pretty? && rendered.start_with?('{') ? " #{rendered}" : rendered
+          end
           name = invocation.function_name
-          legacy = @configuration.dialect == Dialect::NEO4J_4
+          legacy = @configuration.legacy_functions?
           # Neo4j 4 has no elementId(); the closest equivalent is the stringified internal id.
           return "toString(id(#{arguments.join(', ')}))" if name == 'elementId' && legacy
 

data/lib/cypher_dsl/renderer/visitor/label_rendering.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  class Renderer
+    class Visitor
+      # Rendering of node labels: plain names and {Labels} expressions, dynamic
+      # (`:$($labels)`) where the dialect allows it, static otherwise.
+      module LabelRendering
+        STATIC_MESSAGE = 'Cannot render the given Labels in a Cypher pre 5.26 compatible way'
+
+        private
+
+        # One label entry including its leading colon.
+        def render_label(label)
+          label.is_a?(Labels) ? render_labels_expression(label) : ":#{escape_schema_name(label)}"
+        end
+
+        def render_labels_expression(labels)
+          return render_static_labels(labels) if !@configuration.dynamic_labels? && static_renderable?(labels)
+          return '' if labels.empty?
+
+          ":#{render_labels_tree(labels, nil)}"
+        end
+
+        def static_renderable?(labels)
+          labels.lhs.nil? && labels.rhs.nil? && %i[leaf colon_conjunction].include?(labels.type)
+        end
+
+        # Pre-5.26: the label names are taken from literals and parameter values and rendered as `:A:B`.
+        def render_static_labels(labels)
+          names = labels.values.flat_map { |value| static_label_names(value.value) }
+          names.map { |name| ":#{escape_schema_name(name)}" }.join
+        end
+
+        def static_label_names(value)
+          case value
+          when String then [value]
+          when Parameter then value.value? ? static_label_names(value.value) : raise(ArgumentError, STATIC_MESSAGE)
+          when ListExpression then value.elements.flat_map { |element| static_label_names(element) }
+          when Literal then value.value.is_a?(String) ? [value.value] : raise(ArgumentError, STATIC_MESSAGE)
+          when Array then value.flat_map { |item| static_label_names(item) }
+          else raise ArgumentError, STATIC_MESSAGE
+          end
+        end
+
+        # Mirrors the Java renderer's bracketing rules for `&`, `|` and `!`.
+        def render_labels_tree(labels, parent)
+          current = labels.type
+          close = false
+          unless labels.leaf?
+            close = (!parent.nil? || labels.negated?) && current != parent
+            close = false if close && !labels.negated? && (current == :conjunction || parent == :disjunction)
+          end
+
+          parts = []
+          parts << '!' if labels.negated?
+          parts << '(' if close
+          parts << render_labels_tree(labels.lhs, current) if labels.lhs
+          parts << render_label_values(labels, current)
+          parts << render_labels_tree(labels.rhs, current) if labels.rhs
+          parts << ')' if close
+          parts.join
+        end
+
+        def render_label_values(labels, current)
+          return labels.values.map { |value| render_label_value(value) }.join if labels.leaf?
+          if %i[colon_conjunction colon_disjunction].include?(current) && labels.values.any?
+            return labels.values.map { |value| render_label_value(value) }.join(':')
+          end
+
+          labels.empty? ? '' : Labels::OPERATORS[current]
+        end
+
+        def render_label_value(value)
+          case value.modifier
+          when :static then escape_schema_name(value.value)
+          when :all then "$(#{render_expression(value.value)})"
+          when :any then "$any(#{render_expression(value.value)})"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cypher_dsl/renderer/visitor/patterns.rb

@@ -19,9 +19,16 @@ module CypherDSL
           end
         end
 
+        # `p = SHORTEST 1 pattern`, or `p = shortestPath(pattern)` on dialects before Neo4j 5.21.
         def render_named_path(path)
-          selector = path.selector && "#{path.selector.keyword} "
-          "#{render_expression(path.symbolic_name)} = #{selector}#{render_pattern_element(path.pattern)}"
+          name = render_expression(path.symbolic_name)
+          pattern = render_pattern_element(path.pattern)
+          selector = path.selector
+          if selector&.legacy_function && @configuration.legacy_path_selectors?
+            "#{name} = #{selector.legacy_function}(#{pattern})"
+          else
+            "#{name} = #{"#{selector.keyword} " if selector}#{pattern}"
+          end
         end
 
         def render_quantified_path_pattern(quantified)
@@ -41,35 +48,15 @@ module CypherDSL
         # Inside a pattern expression (a pattern used as a condition) no new
         # variables may be introduced, so an unknown name is left out.
         def render_node(node)
-          name = node.symbolic_name && resolve_name(node.symbolic_name)
-          return "(#{name})" if name && @visited_names.include?(name)
+          name = node.symbolic_name && resolve_name(node.symbolic_name, in_entity: true)
+          return "(#{Escaper.escape_if_necessary(name)})" if name && @visited_names.include?(name)
 
           @visited_names << name if name && !@in_pattern_expression
           name = nil if @in_pattern_expression
-          labels = node.labels.map { |label| ":#{render_label(label)}" }.join
+          labels = node.labels.map { |label| render_label(label) }.join
           properties = node.properties && " #{render_expression(node.properties)}"
           where = node.where_condition && " WHERE #{render_expression(node.where_condition)}"
-          "(#{name}#{labels}#{properties}#{where})"
-        end
-
-        def render_label(label)
-          label.is_a?(LabelExpression) ? render_label_expression(label) : escape_schema_name(label)
-        end
-
-        # `A|B`, `A&B`, `!A`; operands of another kind are parenthesised.
-        def render_label_expression(expression)
-          case expression.type
-          when :leaf then escape_schema_name(expression.value)
-          when :negation then "!#{render_label_operand(expression.operands.first, expression)}"
-          else
-            operator = expression.type == :conjunction ? '&' : '|'
-            expression.operands.map { |operand| render_label_operand(operand, expression) }.join(operator)
-          end
-        end
-
-        def render_label_operand(operand, parent)
-          rendered = render_label_expression(operand)
-          operand.leaf? || operand.type == parent.type || operand.type == :negation ? rendered : "(#{rendered})"
+          "(#{name && Escaper.escape_if_necessary(name)}#{labels}#{properties}#{where})"
         end
 
         # A pattern used as a condition: known names render bare, unknown ones are dropped.
@@ -83,9 +70,9 @@ module CypherDSL
         # Like nodes, a named relationship renders in full once and as `[name]` afterwards.
         def render_relationship_details(relationship)
           details = relationship.details
-          name = relationship.symbolic_name && resolve_name(relationship.symbolic_name)
+          name = relationship.symbolic_name && resolve_name(relationship.symbolic_name, in_entity: true)
           inner = if name && @visited_names.include?(name)
-                    "[#{name}]"
+                    "[#{Escaper.escape_if_necessary(name)}]"
                   else
                     @visited_names << name if name && !@in_pattern_expression
                     content = render_details_content(relationship)
@@ -103,7 +90,8 @@ module CypherDSL
         def render_details_content(relationship)
           details = relationship.details
           types = details.types.map { |type| escape_schema_name(type) }.join('|')
-          name = relationship.symbolic_name && !@in_pattern_expression ? resolve_name(relationship.symbolic_name) : nil
+          named = relationship.symbolic_name && !@in_pattern_expression
+          name = named ? Escaper.escape_if_necessary(resolve_name(relationship.symbolic_name, in_entity: true)) : nil
           [
             name,
             (":#{types}" unless types.empty?),

data/lib/cypher_dsl/renderer/visitor.rb

@@ -8,28 +8,54 @@ module CypherDSL
     class Visitor
       include Patterns
       include Expressions
+      include LabelRendering
 
       def initialize(configuration)
         @configuration = configuration
         @visited_names = Set.new
         @defined_aliases = {}
-        @generated_names = {}.compare_by_identity
+        @names = if configuration.use_generated_names?
+                   GeneratedNameResolver.new(configuration.generated_names)
+                 else
+                   NameResolver.new
+                 end
+        @renamed_parameters = {}
         @parameter_uses = {}
+        @depth = 0
+        @in_last_return = false
         @anonymous_parameters = []
         @level = 0
       end
 
-      # The parameters seen while rendering; see {Renderer#catalog}.
-      def catalog = StatementCatalog.from_uses(@parameter_uses)
+      # The parameters seen while rendering `statement`; see {Renderer#catalog}.
+      def catalog(statement = nil) = StatementCatalog.from_uses(@parameter_uses, @renamed_parameters, statement:)
+
+      # A part of a statement on its own.
+      def render_fragment(fragment)
+        case fragment
+        when Search then render_search(fragment).lstrip
+        when Node, Relationship, RelationshipChain, NamedPath, QuantifiedPathPattern
+          render_pattern_element(fragment)
+        when Statement, UnionQuery then render(fragment)
+        else Clauses.clause?(fragment) ? render_clause(fragment) : render_expression(fragment)
+        end
+      end
 
       def render(statement)
         return render_union(statement) if statement.is_a?(UnionQuery)
 
+        @depth += 1
+        last = statement.clauses.size - 1
+        leading_use = statement.clauses.first.is_a?(Clauses::Use)
         rendered = statement.clauses.each_with_index.map do |clause, index|
-          @first_clause = index.zero? && @visited_names.empty?
+          # A leading USE does not count: `USE g CALL () {…}` opens the statement's scope.
+          @first_clause = (index.zero? || (leading_use && index == 1)) && @visited_names.empty?
+          @in_last_return = @depth == 1 && index == last && clause.is_a?(Clauses::Return)
           render_clause(clause)
         end.join(break_line)
         statement.prefix ? "#{statement.prefix} #{rendered}" : rendered
+      ensure
+        @depth -= 1
       end
 
       private
@@ -73,12 +99,8 @@ module CypherDSL
         end.join("#{keyword}#{break_line}")
       end
 
-      # Unresolved symbolic names get a generated, render-stable name.
-      def resolve_name(symbolic_name)
-        return symbolic_name.value if symbolic_name.resolved?
-
-        @generated_names[symbolic_name] ||= "#{symbolic_name.hint}#{format('%03d', @generated_names.size + 1)}"
-      end
+      # The rendered name of a symbolic name; see {NameResolver}.
+      def resolve_name(symbolic_name, in_entity: false) = @names.resolve(symbolic_name, in_entity:)
 
       private
 
@@ -108,8 +130,15 @@ module CypherDSL
       end
 
       def render_load_csv(clause)
-        headers = clause.with_headers ? ' WITH HEADERS' : ''
-        "LOAD CSV#{headers} FROM #{render_literal(clause.uri)} AS #{render_expression(clause.alias_name)}"
+        parts = []
+        if clause.periodic_commit
+          rate = clause.periodic_commit == true ? '' : " #{clause.periodic_commit}"
+          parts << "USING PERIODIC COMMIT#{rate}"
+        end
+        parts << (clause.with_headers ? 'LOAD CSV WITH HEADERS' : 'LOAD CSV')
+        parts << "FROM #{render_literal(clause.uri)} AS #{render_expression(clause.alias_name)}"
+        parts << "FIELDTERMINATOR #{render_literal(clause.field_terminator)}" if clause.field_terminator
+        parts.join(' ')
       end
 
       def render_call(clause)
@@ -138,11 +167,21 @@ module CypherDSL
           opening = "CALL (#{list}) {"
         end
         rendered = block(opening, '}', inline_padding: '') do
-          [prefix, render_in_scope(body, scope_of(imports))].compact.join(break_line)
+          [prefix, render_in_scope(body, scope_of(imports), imports)].compact.join(break_line)
         end
         "#{rendered}#{suffix}"
       end
 
+      # What a subquery hands back to the outer scope: the items of its final RETURN.
+      def exports_of(body)
+        return [] unless body.is_a?(Statement) && body.clauses.last.is_a?(Clauses::Return)
+
+        items = body.clauses.last.items
+        return :all if items.any?(Asterisk)
+
+        items.select { |item| [SymbolicName, AliasedExpression, Node, Relationship].any? { |type| item.is_a?(type) } }
+      end
+
       # An aliased import (`nodes AS x`) imports the name and renames it with a
       # leading `WITH nodes AS x` inside the body.
       def subquery_body_and_imports(clause)
@@ -177,37 +216,69 @@ module CypherDSL
         imports.filter_map { |import| import.is_a?(SymbolicName) ? resolve_name(import) : nil }.to_set
       end
 
-      def render_in_scope(body, scope)
-        return body.content if body.is_a?(RawExpression)
+      # A CALL subquery body: only the imports are visible inside, the final RETURN is exported.
+      def render_in_scope(body, scope, imports)
+        return render_raw(body) if body.is_a?(RawExpression)
 
         outer_scope = @visited_names
         @visited_names = scope
+        @names.enter_scope(imports.any?(Asterisk) ? :all : imports)
         rendered = render(body)
+        @names.leave_scope(exports_of(body))
         @visited_names = outer_scope
         rendered
       end
 
       # A subquery statement rendered within the current scope (EXISTS / COLLECT).
       def render_subquery(statement, imports = [])
-        outer_scope = @visited_names.dup
         prefix = imports.empty? ? '' : "WITH #{imports.map { |import| render_projection_item(import) }.join(', ')} "
-        rendered = render(statement)
-        @visited_names = outer_scope
+        rendered = render_in_own_scope { render(statement) }
         "#{prefix}#{rendered}"
       end
 
       # The body of a FOREACH is its own scope: names rendered inside it do not
       # count as visited outside.
       def render_foreach(clause)
-        outer_scope = @visited_names.dup
-        body = clause.clauses.map { |inner| render_clause(inner) }.join(' ')
-        @visited_names = outer_scope
+        body = render_in_own_scope { clause.clauses.map { |inner| render_clause(inner) }.join(' ') }
         "FOREACH (#{render_expression(clause.variable)} IN #{render_expression(clause.list)} | #{body})"
       end
 
       def render_match(clause)
+        hints = clause.hints.map { |hint| "#{break_line}#{render_hint(hint)}" }
+        search = clause.search && render_search(clause.search)
         [('OPTIONAL ' if clause.optional), 'MATCH ', render_pattern_elements(clause.pattern_elements),
-         render_where(clause.where)].join
+         *hints, search, render_where(clause.where)].join
+      end
+
+      # `SEARCH name IN (VECTOR INDEX index FOR vector [WHERE …] LIMIT k) [SCORE AS score]`; pretty
+      # printed it sits indented under its MATCH with one option per line.
+      def render_search(search)
+        score = search.score_name && " SCORE AS #{render_expression(search.score_name)}"
+        name = render_expression(search.name)
+        return " SEARCH #{name} IN (#{search_options(search).join(' ')})#{score}" unless pretty?
+
+        body = nested { nested { search_options(search).join(break_line) } }
+        "#{break_line(@level + 1)}SEARCH #{name} IN (#{break_line(@level + 2)}#{body}#{break_line(@level + 1)})#{score}"
+      end
+
+      def search_options(search)
+        predicate = search.predicates.inject { |all, predicate| all.and(predicate) }
+        options = ["VECTOR INDEX #{Escaper.escape_if_necessary(search.index_name)}",
+                   "FOR #{render_expression(search.vector)}"]
+        options << "WHERE #{render_expression(predicate)}" if predicate
+        options << "LIMIT #{search.top_k}" if search.top_k
+        options
+      end
+
+      def render_hint(hint)
+        case hint.type
+        when :join then "USING JOIN ON #{hint.names.map { |name| render_expression(name) }.join(', ')}"
+        when :scan then "USING SCAN #{render_expression(hint.container)}:#{escape_schema_name(hint.schema_name)}"
+        else
+          keyword = hint.type == :index_seek ? 'USING INDEX SEEK' : 'USING INDEX'
+          properties = hint.property_names.map { |name| Escaper.escape_if_necessary(name) }.join(', ')
+          "#{keyword} #{render_expression(hint.container)}:#{escape_schema_name(hint.schema_name)}(#{properties})"
+        end
       end
 
       def render_merge(clause)
@@ -238,7 +309,7 @@ module CypherDSL
       def exported_names(items)
         items.filter_map do |item|
           case item
-          when AliasedExpression then resolve_name(item.alias_name)
+          when AliasedExpression then @names.resolve_alias(item, in_last_return: @in_last_return)
           when SymbolicName then resolve_name(item)
           when Node, Relationship then item.symbolic_name && resolve_name(item.symbolic_name)
           end
@@ -259,16 +330,17 @@ module CypherDSL
       def render_projection_item(item)
         return render_expression(item) unless item.is_a?(AliasedExpression)
 
-        alias_name = resolve_name(item.alias_name)
+        alias_name = @names.resolve_alias(item, in_last_return: @in_last_return)
         return Escaper.escape_if_necessary(alias_name) if alias_defined?(item, alias_name)
 
-        rendered = "#{render_expression(item.delegate)} AS #{render_expression(item.alias_name)}"
+        delegate = render_expression(item.delegate)
+        alias_name = @names.resolve_alias(item, define: true, in_last_return: @in_last_return)
         @defined_aliases[alias_name] = item.delegate
-        rendered
+        "#{delegate} AS #{Escaper.escape_if_necessary(alias_name)}"
       end
 
       def render_aliased_reference(item)
-        alias_name = resolve_name(item.alias_name)
+        alias_name = @names.resolve_alias(item, in_last_return: @in_last_return)
         return Escaper.escape_if_necessary(alias_name) if alias_defined?(item, alias_name)
 
         render_expression(item.delegate)

data/lib/cypher_dsl/renderer.rb

@@ -3,7 +3,10 @@
 module CypherDSL
   # Turns a {Statement} into Cypher text according to a {Renderer::Configuration}.
   class Renderer
-    def self.default = @default ||= new(Configuration::DEFAULT)
+    def self.default = @default ||= new(Configuration.default)
+
+    # The default configuration without forced escaping; used by `to_s` on expressions and patterns.
+    def self.plain = @plain ||= new(Configuration.new(always_escape_names: false))
 
     # Mirrors `Renderer.getRenderer(configuration)`.
     def self.get_renderer(configuration) = new(configuration)
@@ -15,14 +18,17 @@ module CypherDSL
       freeze
     end
 
-    def render(statement) = Visitor.new(configuration).render(statement)
+    def render(statement) = "#{configuration.prefix}#{Visitor.new(configuration).render(statement)}"
+
+    # Renders a part of a statement on its own: an expression, a pattern, a clause or a {Search}.
+    def render_fragment(fragment) = Visitor.new(configuration).render_fragment(fragment)
 
-    # The statement's parameters as a {StatementCatalog}; raises
-    # {ConflictingParametersException} when a name is bound inconsistently.
+    # The statement's parameters and identifiable expressions as a {StatementCatalog};
+    # raises {ConflictingParametersException} when a name is bound inconsistently.
     def catalog(statement)
       visitor = Visitor.new(configuration)
       visitor.render(statement)
-      visitor.catalog
+      visitor.catalog(statement)
     end
   end
 end

data/lib/cypher_dsl/search.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `SEARCH movie IN (VECTOR INDEX moviePlots FOR $vector WHERE … LIMIT 4) SCORE AS score`,
+  # attached to a MATCH clause. Built with
+  # `Cypher.search(:movie).in('moviePlots').for_vector(vector).where(…).limit(4).score(:s).build`.
+  class Search
+    SUPPORTED_VECTORS = [VectorLiteral, ListExpression, Parameter, Property].freeze
+
+    attr_reader :name, :index_name, :vector, :predicates, :top_k, :score_name
+
+    def initialize(name:, index_name:, vector:, predicates:, top_k:, score_name:)
+      @name = name
+      @index_name = index_name
+      @vector = vector
+      @predicates = predicates.freeze
+      @top_k = top_k
+      @score_name = score_name
+      freeze
+    end
+
+    # The search rendered on its own with the default renderer.
+    def cypher = Renderer.default.render_fragment(self)
+    alias to_s cypher
+
+    # The ongoing definition; every step returns a new builder.
+    class Builder
+      def initialize(name, index_name: nil, vector: nil, predicates: [], top_k: nil, score_name: nil)
+        raise ArgumentError, 'Name is required' if name.nil?
+
+        @name = name
+        @index_name = index_name
+        @vector = vector
+        @predicates = predicates
+        @top_k = top_k
+        @score_name = score_name
+        freeze
+      end
+
+      def in(index_name)
+        if index_name.nil? || index_name.to_s.strip.empty?
+          raise ArgumentError, 'The index name must not be null or empty'
+        end
+
+        with(index_name: index_name.to_s)
+      end
+
+      def for_vector(vector)
+        raise ArgumentError, 'Vector is required' if vector.nil?
+        unless Search::SUPPORTED_VECTORS.any? { |type| vector.is_a?(type) }
+          raise ArgumentError, "Unsupported vector expression #{vector.inspect}"
+        end
+
+        with(vector:)
+      end
+
+      # Only comparisons; several are combined with AND.
+      def where(*predicates)
+        predicates = predicates.flatten
+        raise ArgumentError, 'A predicate is required' if predicates.empty? || predicates.any?(nil)
+        raise ArgumentError, 'Only comparison conditions are supported' unless predicates.all?(Comparison)
+
+        with(predicates:)
+      end
+
+      def limit(top_k)
+        raise ArgumentError, 'topK must be greater than or equal to 0' if top_k.negative?
+
+        with(top_k:)
+      end
+
+      def score(name) = with(score_name: SymbolicName.of(name))
+
+      def build
+        raise ArgumentError, 'The index name is required' if @index_name.nil?
+        raise ArgumentError, 'The vector is required' if @vector.nil?
+
+        Search.new(name: @name, index_name: @index_name, vector: @vector, predicates: @predicates, top_k: @top_k,
+                   score_name: @score_name)
+      end
+
+      private
+
+      def with(**changes)
+        options = { index_name: @index_name, vector: @vector, predicates: @predicates, top_k: @top_k,
+                    score_name: @score_name }.merge(changes)
+        Builder.new(@name, **options)
+      end
+    end
+  end
+end