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

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,7 +161,18 @@ 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)
@@ -176,23 +212,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 +255,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)
@@ -244,7 +287,7 @@ module CypherDSL
 
     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 +299,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

data/lib/cypher_dsl/vector_literal.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `vector([1, 2, 3], 3, INTEGER NOT NULL)`: a typed vector literal. The Java
+  # overloads per primitive array become an optional type: `:integer8`,
+  # `:integer16`, `:integer32`, `:integer` (default for integers), `:float32`
+  # and `:float` (default for floats).
+  class VectorLiteral
+    include Expression
+
+    TYPES = { integer8: 'INTEGER8', integer16: 'INTEGER16', integer32: 'INTEGER32', integer: 'INTEGER',
+              float32: 'FLOAT32', float: 'FLOAT' }.freeze
+    FLOAT_TYPES = %i[float32 float].freeze
+    MAX_SIZE = 4096
+
+    attr_reader :content, :type
+
+    def self.of(elements, type = nil)
+      raise ArgumentError, 'Vector elements must not be literal null' if elements.nil?
+
+      size = elements.size
+      unless (1..MAX_SIZE).cover?(size)
+        raise ArgumentError,
+              "'#{size}' is not a valid value. Must be a number in the range 1 to #{MAX_SIZE} (GQL 42N31)"
+      end
+
+      new(elements, type || (elements.all?(Integer) ? :integer : :float))
+    end
+
+    def initialize(content, type)
+      raise ArgumentError, "Unknown vector type #{type.inspect}" unless TYPES.key?(type)
+
+      @type = type
+      @content = (FLOAT_TYPES.include?(type) ? content.map(&:to_f) : content.map(&:to_i)).freeze
+      freeze
+    end
+
+    # The literal as Cypher text; it does not depend on any rendering option.
+    def as_string = "vector([#{content.join(', ')}], #{content.size}, #{TYPES[type]} NOT NULL)"
+  end
+end

data/lib/cypher_dsl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CypherDSL
-  VERSION = '0.1.0.alpha.1'
+  VERSION = '0.1.0.alpha.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cypher-dsl
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.1
+  version: 0.1.0.alpha.2
 platform: ruby
 authors:
 - Heinrich Klobuczek
@@ -71,8 +71,9 @@ files:
 - lib/cypher_dsl/function_invocation.rb
 - lib/cypher_dsl/functions.rb
 - lib/cypher_dsl/has_label_condition.rb
-- lib/cypher_dsl/label_expression.rb
+- lib/cypher_dsl/hint.rb
 - lib/cypher_dsl/label_operation.rb
+- lib/cypher_dsl/labels.rb
 - lib/cypher_dsl/list_comprehension.rb
 - lib/cypher_dsl/list_expression.rb
 - lib/cypher_dsl/list_operator.rb
@@ -89,6 +90,7 @@ files:
 - lib/cypher_dsl/pattern_comprehension.rb
 - lib/cypher_dsl/pattern_expression.rb
 - lib/cypher_dsl/property.rb
+- lib/cypher_dsl/property_exists_condition.rb
 - lib/cypher_dsl/quantified_path_pattern.rb
 - lib/cypher_dsl/raw_expression.rb
 - lib/cypher_dsl/reduction.rb
@@ -99,9 +101,13 @@ files:
 - lib/cypher_dsl/renderer/configuration.rb
 - lib/cypher_dsl/renderer/dialect.rb
 - lib/cypher_dsl/renderer/escaper.rb
+- lib/cypher_dsl/renderer/generated_name_resolver.rb
+- lib/cypher_dsl/renderer/name_resolver.rb
 - lib/cypher_dsl/renderer/visitor.rb
 - lib/cypher_dsl/renderer/visitor/expressions.rb
+- lib/cypher_dsl/renderer/visitor/label_rendering.rb
 - lib/cypher_dsl/renderer/visitor/patterns.rb
+- lib/cypher_dsl/search.rb
 - lib/cypher_dsl/sort_item.rb
 - lib/cypher_dsl/standalone_call.rb
 - lib/cypher_dsl/statement.rb
@@ -111,6 +117,8 @@ files:
 - lib/cypher_dsl/symbolic_name.rb
 - lib/cypher_dsl/unary_operation.rb
 - lib/cypher_dsl/union_query.rb
+- lib/cypher_dsl/using_periodic_commit.rb
+- lib/cypher_dsl/vector_literal.rb
 - lib/cypher_dsl/version.rb
 homepage: https://github.com/neo4jrb/cypher-dsl
 licenses:
@@ -134,7 +142,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.20
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A Ruby DSL (builder) for the Cypher query language
 test_files: []

data/lib/cypher_dsl/label_expression.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-module CypherDSL
-  # A label expression as in `(n:A|B)`, `(n:A&!B)` or `(n:(A|B)&C)`; built from
-  # {Labels.exactly} and combined with {#or}, {#and} and {#negate}.
-  class LabelExpression
-    TYPES = %i[leaf conjunction disjunction negation].freeze
-
-    attr_reader :type, :value, :operands
-
-    def self.exactly(name) = new(:leaf, name.to_s, [])
-
-    def initialize(type, value, operands)
-      raise ArgumentError, "Unknown label expression type #{type.inspect}" unless TYPES.include?(type)
-
-      @type = type
-      @value = value
-      @operands = operands.freeze
-      freeze
-    end
-
-    def or(other) = LabelExpression.new(:disjunction, nil, [self, coerce(other)])
-    def and(other) = LabelExpression.new(:conjunction, nil, [self, coerce(other)])
-    def negate = LabelExpression.new(:negation, nil, [self])
-    alias not negate
-
-    def leaf? = type == :leaf
-
-    private
-
-    def coerce(other) = other.is_a?(LabelExpression) ? other : LabelExpression.exactly(other)
-  end
-
-  # Factory for label expressions: `Labels.exactly('A').or('B')`.
-  module Labels
-    module_function
-
-    def exactly(name) = LabelExpression.exactly(name)
-  end
-end