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

data/lib/cypher_dsl/renderer/visitor.rb

@@ -8,28 +8,55 @@ module CypherDSL
     class Visitor
       include Patterns
       include Expressions
+      include Conditions
+      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 +100,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
 
@@ -95,21 +118,32 @@ module CypherDSL
         when Clauses::Set then "SET #{render_operations(clause.operations)}"
         when Clauses::Remove then "REMOVE #{render_operations(clause.items)}"
         when Clauses::Delete then render_delete(clause)
-        when Clauses::Unwind
-          "UNWIND #{render_expression(clause.expression)} AS #{render_expression(clause.variable)}"
+        when Clauses::Unwind then render_unwind(clause)
         when Clauses::Finish then 'FINISH'
         when Clauses::Foreach then render_foreach(clause)
         when Clauses::Call then render_call(clause)
         when Clauses::CallSubquery then render_call_subquery(clause)
         when Clauses::LoadCsv then render_load_csv(clause)
         when Clauses::Use then "USE #{clause.graph.is_a?(String) ? clause.graph : render_expression(clause.graph)}"
+        when Clauses::Raw then render_raw(clause.expression)
         else raise ArgumentError, "Cannot render clause #{clause.inspect}"
         end
       end
 
+      def render_unwind(clause)
+        "UNWIND #{render_expression(clause.expression)} AS #{render_expression(clause.variable)}"
+      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 +172,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 +221,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 +314,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 +335,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

data/lib/cypher_dsl/standalone_call.rb

@@ -6,8 +6,6 @@ module CypherDSL
   # `build` finishes a bare call, `as_function` turns it into a function
   # invocation instead.
   class StandaloneCall
-    AGGREGATES = %w[avg collect count max min percentilecont percentiledisc stdev stdevp sum].freeze
-
     attr_reader :name_parts, :arguments
 
     # `name_parts` as given to `Cypher.call`: strings, symbols or arrays, dotted names split.
@@ -37,10 +35,6 @@ module CypherDSL
 
     # The procedure as a function invocation; `distinct` only for aggregates.
     def as_function(distinct = false) # rubocop:disable Style/OptionalBooleanParameter
-      if distinct && !AGGREGATES.include?(procedure_name.downcase)
-        raise ArgumentError, 'The distinct operator can only be applied within aggregate functions.'
-      end
-
       FunctionInvocation.new(procedure_name, arguments, distinct:)
     end
 

data/lib/cypher_dsl/statement.rb

@@ -23,6 +23,10 @@ module CypherDSL
       @cypher ||= Renderer.default.render(self).freeze
     end
 
+    # The same statement with `EXPLAIN` / `PROFILE` in front.
+    def explain = Statement.new(clauses, prefix: 'EXPLAIN')
+    def profile = Statement.new(clauses, prefix: 'PROFILE')
+
     # Parameter names and bound values; raises {ConflictingParametersException}
     # when a name is bound inconsistently. Memoised, like `cypher`.
     def catalog

data/lib/cypher_dsl/statement_builder.rb

@@ -19,11 +19,32 @@ module CypherDSL
     # `match(pattern, …)` or, as in Java, `match(optional, pattern, …)` with a leading flag.
     def match(*pattern_elements)
       optional = [true, false].include?(pattern_elements.first) ? pattern_elements.shift : false
-      append(Clauses::Match.new(optional:, pattern_elements: pattern_elements.flatten.freeze, where: nil), :condition)
+      raise ArgumentError, 'Patterns to match are required.' if pattern_elements.any?(&:nil?)
+
+      pattern_elements = pattern_elements.flatten.freeze
+      raise ArgumentError, 'At least one pattern to match is required.' if pattern_elements.empty?
+
+      append(Clauses::Match.new(optional:, pattern_elements:, hints: [].freeze, search: nil, where: nil), :condition)
+    end
+
+    # A vector `SEARCH` on the preceding MATCH; see {Search}.
+    def search(search)
+      update_last(:condition) do |clause|
+        raise ArgumentError, 'SEARCH needs a preceding MATCH.' unless clause.is_a?(Clauses::Match)
+
+        clause.with(search:)
+      end
     end
 
     def optional_match(*pattern_elements) = match(true, *pattern_elements)
 
+    # Planner hints on the preceding MATCH: `using_index(n.property(:name))`,
+    # `using_index_seek(…)`, `using_scan(n)`, `using_join_on(n, m)`.
+    def using_index(*properties) = add_hint(Hint.use_index_for(false, *properties))
+    def using_index_seek(*properties) = add_hint(Hint.use_index_for(true, *properties))
+    def using_scan(node) = add_hint(Hint.use_scan_for(node))
+    def using_join_on(*nodes_or_names) = add_hint(Hint.use_join_on(*nodes_or_names))
+
     def where(condition)
       if @clauses.last.is_a?(Clauses::CallSubquery)
         raise ArgumentError, 'A CALL{} clause requires to WITH before you can add further conditions'
@@ -52,15 +73,19 @@ module CypherDSL
     def returning_raw(*expressions) = append(Clauses::RawReturn.new(items: coerce_items(expressions)), :projection)
 
     def with(*expressions)
-      append(Clauses::With.new(distinct: false, items: coerce_items(expressions), order: nil, skip: nil, limit: nil,
-                               where: nil), :condition)
+      append(Clauses::With.new(distinct: false, items: projection_items(expressions), order: nil, skip: nil,
+                               limit: nil, where: nil), :condition)
     end
 
     def with_distinct(*expressions)
-      append(Clauses::With.new(distinct: true, items: coerce_items(expressions), order: nil, skip: nil, limit: nil,
-                               where: nil), :condition)
+      append(Clauses::With.new(distinct: true, items: projection_items(expressions), order: nil, skip: nil,
+                               limit: nil, where: nil), :condition)
     end
 
+    # The names and expressions in scope after the last WITH or RETURN, as
+    # `getIdentifiableExpressions()` on the Java builder states.
+    def identifiable_expressions = StatementCatalog.identifiable_expressions_of(build)
+
     def order_by(*sort_items)
       update_last(:order) { |clause| clause.with(order: Clauses::Order.new(items: coerce_sort_items(sort_items))) }
     end
@@ -136,11 +161,34 @@ module CypherDSL
     end
 
     # `load_csv('file:///x.csv').as(:line)`.
-    def load_csv(uri, with_headers: false) = OngoingLoadCsv.new(self, uri.to_s, with_headers)
+    def load_csv(uri, positional_headers = false, with_headers: positional_headers, periodic_commit: nil) # rubocop:disable Style/OptionalBooleanParameter
+      OngoingLoadCsv.new(self, uri.to_s, with_headers, periodic_commit)
+    end
+
+    # `FIELDTERMINATOR ';'` on the preceding LOAD CSV.
+    def with_field_terminator(terminator)
+      update_last(nil) do |clause|
+        raise ArgumentError, 'FIELDTERMINATOR needs a preceding LOAD CSV.' unless clause.is_a?(Clauses::LoadCsv)
+
+        clause.with_field_terminator(terminator&.to_s)
+      end
+    end
 
     # The statement built so far as an `EXISTS { … }` condition.
     def as_condition = ExistsCondition.new(build)
 
+    # --- escape hatch ----------------------------------------------------
+
+    # A clause rendered verbatim, for Cypher the builder does not model, e.g.
+    # `raw_clause('CALL db.labels() YIELD label')`. Takes the arguments of
+    # `Cypher.raw` (a format with `$E` placeholders) or a ready {RawExpression}.
+    # The next clause starts afresh: a raw clause cannot be refined with WHERE,
+    # ORDER BY, SKIP or LIMIT.
+    def raw_clause(format, *)
+      expression = format.is_a?(RawExpression) ? format : RawExpression.create(format, *)
+      append(Clauses::Raw.new(expression:), nil)
+    end
+
     # --- finishing -------------------------------------------------------
 
     # Continues with the clauses of another statement, e.g. after a `CALL … YIELD`.
@@ -176,23 +224,22 @@ module CypherDSL
 
       def in(list) = OngoingForeach.new(@builder, @variable, Expression.coerce(list))
 
-      def apply(*clauses)
-        foreach = Clauses::Foreach.new(variable: @variable, list: @list, clauses: clauses.flatten.freeze)
-        @builder.send(:append, foreach, nil)
-      end
+      def apply(*clauses) = @builder.send(:append, Clauses.for_each(@variable, @list, clauses.flatten), nil)
     end
 
     # Intermediate state of `load_csv(uri)` waiting for `as(alias)`.
     class OngoingLoadCsv
-      def initialize(builder, uri, with_headers)
+      def initialize(builder, uri, with_headers, periodic_commit)
         @builder = builder
         @uri = uri
         @with_headers = with_headers
+        @periodic_commit = periodic_commit
         freeze
       end
 
       def as(alias_name)
-        clause = Clauses::LoadCsv.new(uri: @uri, with_headers: @with_headers, alias_name: SymbolicName.of(alias_name))
+        clause = Clauses::LoadCsv.new(uri: @uri, with_headers: @with_headers, alias_name: SymbolicName.of(alias_name),
+                                      field_terminator: nil, periodic_commit: @periodic_commit)
         @builder.send(:append, clause, nil)
       end
     end
@@ -220,6 +267,14 @@ module CypherDSL
       Clauses::CallSubquery.new(body: statement, imports: coerce_items(imports), in_transactions:, rows:)
     end
 
+    def add_hint(hint)
+      update_last(:condition) do |clause|
+        raise ArgumentError, 'Hints need a preceding MATCH.' unless clause.is_a?(Clauses::Match)
+
+        clause.with(hints: clause.hints + [hint])
+      end
+    end
+
     def add_merge_action(type, operations)
       update_last(nil) do |clause|
         raise ArgumentError, 'ON CREATE / ON MATCH need a preceding MERGE.' unless clause.is_a?(Clauses::Merge)
@@ -240,11 +295,12 @@ module CypherDSL
       arguments.each_slice(2).map { |target, value| Operation.new(target, '=', Expression.coerce(value)) }.freeze
     end
 
-    def operation?(argument) = argument.is_a?(Operation) || argument.is_a?(LabelOperation)
+    # A raw fragment such as `Cypher.raw("n.name = 'x'")` counts as a complete operation.
+    def operation?(argument) = [Operation, LabelOperation, RawExpression].any? { |type| argument.is_a?(type) }
 
     def label_operation?(arguments)
       arguments.size > 1 && arguments.first.is_a?(Node) &&
-        arguments.drop(1).all? { |argument| argument.is_a?(String) || argument.is_a?(Symbol) }
+        arguments.drop(1).all? { |argument| [String, Symbol, Labels].any? { |type| argument.is_a?(type) } }
     end
 
     def optional_expression(value) = value.nil? ? nil : Expression.coerce(value)
@@ -256,7 +312,17 @@ module CypherDSL
     end
 
     def return_clause(distinct, expressions)
-      Clauses::Return.new(distinct:, items: coerce_items(expressions), order: nil, skip: nil, limit: nil)
+      Clauses::Return.new(distinct:, items: projection_items(expressions), order: nil, skip: nil, limit: nil)
+    end
+
+    # RETURN/WITH items with the upstream preconditions.
+    def projection_items(expressions)
+      raise ArgumentError, 'Expressions to return are required.' if expressions.any?(&:nil?)
+
+      items = coerce_items(expressions)
+      raise ArgumentError, 'At least one expressions to return is required.' if items.empty?
+
+      items
     end
 
     def add_sort_item(expression)

data/lib/cypher_dsl/statement_catalog.rb

@@ -1,24 +1,58 @@
 # frozen_string_literal: true
 
 module CypherDSL
-  # What a statement uses: its parameter names, and the values of the
-  # parameters that carry one. Built from a rendering pass.
+  # What a statement uses: its parameter names, the values of the parameters
+  # that carry one, and the expressions it hands back. Built from a rendering pass.
   class StatementCatalog
-    attr_reader :parameters, :parameter_names
+    attr_reader :parameters, :parameter_names, :renamed_parameters, :identifiable_expressions
 
     # `uses` maps each parameter name to every value it was given, in render
     # order, with {Parameter::NO_VALUE} for unbound uses.
-    def self.from_uses(uses)
+    def self.from_uses(uses, renamed_parameters = {}, statement: nil)
       conflicts = uses.filter_map { |name, values| [name, values.uniq.to_set] if values.uniq.size > 1 }.to_h
       raise ConflictingParametersException, conflicts unless conflicts.empty?
 
       bound = uses.filter_map { |name, values| [name, values.first] unless values.first.equal?(Parameter::NO_VALUE) }
-      new(parameters: bound.to_h, parameter_names: uses.keys)
+      new(parameters: bound.to_h, parameter_names: uses.keys, renamed_parameters:,
+          identifiable_expressions: identifiable_expressions_of(statement))
     end
 
-    def initialize(parameters:, parameter_names:)
+    # The expressions a statement hands back to its caller: the identifiable items of
+    # its final RETURN or WITH (names for aliased items and named entities, properties
+    # as they are), or the names a bare procedure call yields. Empty otherwise.
+    def self.identifiable_expressions_of(statement)
+      case statement
+      when UnionQuery then statement.statements.flat_map { |part| identifiable_expressions_of(part) }.uniq
+      when Statement then result_items_of(statement.clauses.last).filter_map { |item| identifiable_expression(item) }
+      else []
+      end
+    end
+
+    def self.result_items_of(clause)
+      case clause
+      when Clauses::Return, Clauses::With then clause.items
+      when Clauses::Call then clause.yield_items
+      else []
+      end
+    end
+    private_class_method :result_items_of
+
+    # Only names, aliases, named entities and properties identify something; a literal does not.
+    def self.identifiable_expression(item)
+      case item
+      when AliasedExpression then item.alias_name
+      when Node, Relationship then item.symbolic_name
+      when SymbolicName, Property then item
+      end
+    end
+    private_class_method :identifiable_expression
+
+    # `renamed_parameters` maps original names to generated ones when the renderer rewrites them.
+    def initialize(parameters:, parameter_names:, renamed_parameters: {}, identifiable_expressions: [])
       @parameters = parameters.freeze
       @parameter_names = parameter_names.freeze
+      @renamed_parameters = renamed_parameters.freeze
+      @identifiable_expressions = identifiable_expressions.freeze
       freeze
     end
   end

data/lib/cypher_dsl/subquery_with.rb

@@ -10,6 +10,7 @@ module CypherDSL
     end
 
     def collect(statement) = CollectExpression.new(statement, @imports)
+    def count(statement_or_pattern) = CountExpression.new(statement_or_pattern, @imports)
     def exists(statement_or_pattern) = ExistsCondition.new(statement_or_pattern, @imports)
   end
 end

data/lib/cypher_dsl/symbolic_name.rb

@@ -15,7 +15,7 @@ module CypherDSL
     end
 
     # A name to be generated at render time; `hint` seeds the generated name (letters only).
-    def self.unresolved(hint) = new(nil, hint: hint.to_s.gsub(/[^a-zA-Z]/, ''))
+    def self.unresolved(hint = '') = new(nil, hint: hint.to_s.gsub(/[^a-zA-Z]/, ''))
 
     def initialize(value, hint: nil)
       raise ArgumentError, 'A symbolic name must not be empty.' if value && value.empty?

data/lib/cypher_dsl/using_periodic_commit.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `Cypher.using_periodic_commit(500).load_csv(uri).as(:line)`: the legacy
+  # `USING PERIODIC COMMIT [rate]` prefix of a LOAD CSV statement.
+  UsingPeriodicCommit = Data.define(:rate) do
+    def load_csv(uri, positional_headers = false, with_headers: positional_headers) # rubocop:disable Style/OptionalBooleanParameter
+      StatementBuilder.new.load_csv(uri, with_headers:, periodic_commit: rate || true)
+    end
+  end
+end