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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aae0b1907cab6d377de663093abb2aca70b7925b10dafc1596a50ccfc6f8a97f
-  data.tar.gz: 21ad9bce707aabfb247196a75bdfb7de97ffa215e53b210aaa2179dcf0a7b313
+  metadata.gz: a83e4601b0dc6294144bb3e5a87463cf322861e94927fc5ccfa7c14ab5389e0c
+  data.tar.gz: f7475774c957b6ad901caf376774ef2d09d97731874f3cd1b569aec141219089
 SHA512:
-  metadata.gz: 69811594f30155665847bc68fc4c66471de5e0f8ae1b1a83e39d08fd6d8426720e4206aa260f20358c395a87ba2ff2a530eafe518f7621235267d97831a05754
-  data.tar.gz: bc7823802abd14746151e12ae00050be8070be48b0fbed3ef593ef6654bdd0e6613c5c8ebdd78089d3ffbb7303830f06560cb637bb402d893ec279c57f111e43
+  metadata.gz: ef77aec97883fc7445c7ecf759d4d6438c614818bb27cbd6c85fe239d9757a0508cf9f0e2348871a2b291f101756a453ccc5930e76eecb6ecb61db6120e4f8d9
+  data.tar.gz: 0a37e339fa998ae143fc5691a4c50b4d18f8aa322e21ca9f66065ee1d1005304603928cfbe9884bb16905cb55f870eb8bd6facc5cd19f6df2c82c10f48639340

data/CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0.alpha.3] - 2026-11-01
+
+The release activegraph's `ActiveGraph::Core::Query` builds on.
+
+### Added
+
+- Raw fragments for host DSLs built on strings (Ruby-only, no Java counterpart): `Cypher.raw`
+  is accepted as a pattern element in MATCH/CREATE/MERGE, as a condition (also as operand of
+  `and`/`or`/`xor`/`not`), as a complete SET / ON CREATE SET / ON MATCH SET operation, and
+  `StatementBuilder#raw_clause(format, *args)` renders a whole clause verbatim.
+- Raw operands of a compound condition are parenthesised unless they already form one group,
+  so `Cypher.raw('a OR b').as_condition.and(c)` renders `((a OR b) AND c)`.
+
+## [0.1.0.alpha.2] - 2026-11-01
+
+Second pre-release. The whole upstream core test suite that applies to Ruby is now
+translated (1067 examples): all remaining integration tests (HintsIT, LoadCSVIT, DialectIT,
+SubqueriesGQLIT, UseIT, ExpressionsIT, IdentifiableExpressionsIT, Cypher5IT, labels, search
+and vector tests) and the unit tests for literals, escaping, preconditions and `toString`.
+Not translated: `DurationLiteralTests` (no duration type in Ruby's standard library), the
+Java-only reflection, package-structure and foreign-adapter tests, and the QueryDSL adapter.
+
+### Added
+
+- Planner hints: `using_index`, `using_index_seek`, `using_scan`, `using_join_on` (HintsIT).
+- LOAD CSV: `with_field_terminator`, `Cypher.using_periodic_commit`, `linenumber()`, `file()`.
+- All Java dialects including `NEO4J_5_26`, `NEO4J_5_CYPHER_5`, `NEO4J_5_CYPHER_25` with their
+  `CYPHER 5` / `CYPHER 25` prefixes; `NEO4J_5_DEFAULT_CYPHER` is the default.
+- Label expressions (`Labels.exactly/all/any`, `and`, `or`, `negate`, `conjunction_with`),
+  dynamic labels `n:$($labels)` on Neo4j 5.26+, `disable_dynamic_labels`.
+- Vector `SEARCH` clauses (`Cypher.search`) and `Cypher.vector` literals.
+- Generated names (`with_generated_names`) and `StatementCatalog#renamed_parameters`.
+- `Cypher.exists(property)` renders `exists()` on Neo4j 4 and `IS NOT NULL` afterwards;
+  `shortestPath()` / `allShortestPaths()` on Neo4j 4 and 5.
+- `StatementCatalog#identifiable_expressions`: the items of the final `RETURN` or `YIELD`
+  (SubqueriesGQLIT); also on the builder after a `WITH`/`RETURN` (IdentifiableExpressionsIT).
+- `Cypher.raw(format, *args)` with `$E` placeholders and `\$E` escapes (RawLiteralTests).
+- `COUNT { pattern WHERE … }` and `Cypher.subquery_with(…).count(…)` (ExpressionsIT).
+- `Cypher.use` validates nested `USE` and `EXPLAIN`/`PROFILE` inner statements and wraps
+  names, literals and parameters in `graph.byName(…)`; `Statement#explain` / `#profile` (UseIT).
+- `Date`, `Time` and `DateTime` literals render as `date(…)` / `datetime(…)`.
+- `Cypher.format`, `Cypher.quote`, `Cypher.has_labels_or_type`, `Cypher.sort(expr, direction)`,
+  `Property#name` / `#referenced_as`, `Configuration#==`, `to_s` on expressions and patterns
+  (the plain Cypher, as the Java `toString`).
+- Upstream preconditions: empty labels, unnamed nodes in `SET`/`+=`, missing patterns or
+  return items, non-updating clauses inside `FOREACH`, `DISTINCT` on non-aggregates,
+  unsupported literal types.
+
+### Fixed
+
+- Node and relationship names that need quoting (e.g. containing a backtick) are now
+  escaped inside patterns, not only where they are used as expressions.
+- A `CALL { }` following a leading `USE` renders as `CALL () { }`.
+- A `nil` additional label in `Cypher.node` raises `An empty label is not allowed.` instead of being
+  dropped silently; symbols and strings are validated alike.
+
+### Changed
+
+- The default dialect is `NEO4J_5_DEFAULT_CYPHER` (was `NEO4J_5_23`); the only difference
+  is that dynamic label expressions render as such.
+- Name escaping follows upstream exactly: ``` stands for a backtick, doubled
+  backticks are collapsed before escaping, and an already quoted name is quoted again.
+  String literals escape double quotes as well as single quotes and backslashes.
+
 ## [0.1.0.alpha.1] - 2026-10-31
 
 First pre-release, reserving the gem name. A Ruby reimplementation of the design of
@@ -28,5 +92,7 @@ collection, IssueRelatedIT, FunctionsIT).
 - Renderer with dialects (Neo4j 4, 5, 5.23+), pretty printing, identifier escaping,
   parameter collection (`Statement#catalog`).
 
-[Unreleased]: https://github.com/neo4jrb/cypher-dsl/compare/v0.1.0.alpha.1...HEAD
+[Unreleased]: https://github.com/neo4jrb/cypher-dsl/compare/v0.1.0.alpha.3...HEAD
+[0.1.0.alpha.3]: https://github.com/neo4jrb/cypher-dsl/compare/v0.1.0.alpha.2...v0.1.0.alpha.3
+[0.1.0.alpha.2]: https://github.com/neo4jrb/cypher-dsl/compare/v0.1.0.alpha.1...v0.1.0.alpha.2
 [0.1.0.alpha.1]: https://github.com/neo4jrb/cypher-dsl/releases/tag/v0.1.0.alpha.1

data/README.md

@@ -57,26 +57,88 @@ statement.parameter_names # => ["name"]
 `Cypher.anon_parameter(value)` lets the renderer pick the name (`$pcdsl01`, …).
 Binding one name to two different values raises `ConflictingParametersException`.
 
+`statement.catalog` also lists the expressions a statement hands back, i.e. the
+names and expressions of its final `RETURN` or `YIELD`:
+
+```ruby
+statement.catalog.identifiable_expressions # => [Cypher.name(:u)]
+```
+
+## Raw Cypher
+
+`Cypher.raw` embeds Cypher text verbatim. `$E` placeholders take the arguments in
+order, expressions as they are and anything else as a literal, while a `$name` that
+matches a named parameter among the arguments binds that parameter; `\$E` is a literal `$E`:
+
+```ruby
+Cypher.returning(Cypher.raw('($E + $E) * $factor', Cypher.parameter(:a), 2, Cypher.parameter(:factor, 3)).as(:r))
+  .build.cypher # => "RETURN ($a + 2) * $factor AS r"
+```
+
+A raw fragment is also accepted as a pattern element, as a condition, as a `SET`
+operation, and `raw_clause` renders a whole clause verbatim. These are escape hatches
+for DSLs that have to pass user-written Cypher through; a raw condition combined with
+others is parenthesised so its precedence survives:
+
+```ruby
+Cypher.match(Cypher.raw('(n)-[:KNOWS]->(m)'))
+  .where(Cypher.property(:n, :age).gt(30).and(Cypher.raw('m.name STARTS WITH "A" OR m.vip')))
+  .raw_clause('CALL db.labels() YIELD label')
+  .returning(:n, :label).build.cypher
+# => "MATCH (n)-[:KNOWS]->(m) WHERE (n.age > 30 AND (m.name STARTS WITH \"A\" OR m.vip)) CALL db.labels() YIELD label RETURN n, label"
+```
+
+Every expression and pattern answers `to_s` with its plain Cypher, e.g.
+`Cypher.node('Person').named(:n).to_s # => "(n:Person)"`.
+
 ## Rendering options
 
 ```ruby
 config = Renderer::Configuration.new_config
-  .with_dialect(Renderer::Dialect::NEO4J_4)   # default: NEO4J_5_23
+  .with_dialect(Renderer::Dialect::NEO4J_4)   # default: NEO4J_5_DEFAULT_CYPHER
   .always_escape_names(false)                  # default: true, false when pretty printing
   .with_pretty_print(true)                     # one clause per line, indented blocks
   .with_indent_style(:tab)                     # or .with_indent_size(4)
+  .disable_dynamic_labels                      # render n:$($labels) statically
   .build
 Renderer.get_renderer(config).render(statement)
 Renderer.get_renderer(Renderer::Configuration.pretty_printing).render(statement)
 ```
 
-The dialect decides how `CALL { }` subqueries import variables (`CALL (u) { … }`
-from Neo4j 5.23 on, `CALL { WITH u … }` before) and whether `elementId()` exists.
+The dialects mirror the Java enum: `NEO4J_4`, `NEO4J_5`, `NEO4J_5_23`, `NEO4J_5_26`,
+`NEO4J_5_DEFAULT_CYPHER`, `NEO4J_5_CYPHER_5`, `NEO4J_5_CYPHER_25` and `NEO4J_2025`.
+The dialect decides how `CALL { }` subqueries import variables (`CALL (u) { … }` from
+Neo4j 5.23 on, `CALL { WITH u … }` before), whether paths use `shortestPath()` or
+`SHORTEST 1`, `exists(n.prop)` or `n.prop IS NOT NULL`, `distance()` or
+`point.distance()`, whether `elementId()` exists, whether label expressions may be
+dynamic (`n:$($labels)`, Neo4j 5.26+) and whether the statement carries a `CYPHER 5`
+or `CYPHER 25` prefix.
+
+### Generated names
+
+`with_generated_names(true)` rewrites every variable, alias and parameter name while
+rendering (`v0`, `v1`, … and `p0`, `p1`, …), scope by scope, so that statements that
+differ only in their names render identically, which is useful as a query-cache key.
+A subset of the Java `GeneratedNames` flags narrows what gets rewritten:
+
+```ruby
+config = Renderer::Configuration.new_config
+  .with_generated_names(%i[entity_names parameter_names])   # or true for all flags
+  .build
+renderer = Renderer.get_renderer(config)
+renderer.render(statement)                     # => "MATCH (v0:`Movie`) WHERE v0.title = $p0 RETURN v0"
+renderer.catalog(statement).renamed_parameters # => {"title" => "p0"}
+```
+
+The flags are `entity_names`, `parameter_names`, `all_aliases`, `internal_aliases_only`
+(all aliases except those of the final `RETURN`) and `reuse_aliases`.
 
 ## Installation
 
+Pre-releases are not picked up by a bare requirement, so name the version:
+
 ```ruby
-gem 'cypher-dsl'
+gem 'cypher-dsl', '0.1.0.alpha.3'
 ```
 
 Requires Ruby 3.4 or newer.

data/lib/cypher_dsl/clauses/load_csv.rb

@@ -2,7 +2,13 @@
 
 module CypherDSL
   module Clauses
-    # `LOAD CSV [WITH HEADERS] FROM 'uri' AS alias`.
-    LoadCsv = Data.define(:uri, :with_headers, :alias_name)
+    # `[USING PERIODIC COMMIT [rate]] LOAD CSV [WITH HEADERS] FROM 'uri' AS alias [FIELDTERMINATOR ';']`.
+    # `periodic_commit` is nil, `true` or the commit rate.
+    LoadCsv = Data.define(:uri, :with_headers, :alias_name, :field_terminator, :periodic_commit) do
+      # A blank terminator leaves the clause as it is.
+      def with_field_terminator(terminator)
+        terminator.nil? || terminator.strip.empty? ? self : with(field_terminator: terminator)
+      end
+    end
   end
 end

data/lib/cypher_dsl/clauses/match.rb

@@ -2,7 +2,7 @@
 
 module CypherDSL
   module Clauses
-    # `[OPTIONAL] MATCH pattern [WHERE condition]`.
-    Match = Data.define(:optional, :pattern_elements, :where)
+    # `[OPTIONAL] MATCH pattern [USING hint …] [SEARCH …] [WHERE condition]`.
+    Match = Data.define(:optional, :pattern_elements, :hints, :search, :where)
   end
 end

data/lib/cypher_dsl/clauses/raw.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # A clause rendered verbatim from a {RawExpression}: the escape hatch for
+    # Cypher the builder does not model (`raw_clause('CALL db.labels()')`).
+    Raw = Data.define(:expression)
+  end
+end

data/lib/cypher_dsl/clauses.rb

@@ -5,9 +5,20 @@ module CypherDSL
   # code goes through the {StatementBuilder}; these exist for building clause
   # lists by hand, e.g. the body of a FOREACH.
   module Clauses
+    UPDATING_MESSAGE = 'Only updating clauses SET, REMOVE, CREATE, MERGE, DELETE, and FOREACH are allowed as ' \
+                       'clauses applied inside FOREACH.'
+
+    # True for any clause object.
+    def self.clause?(object) = constants.any? { |name| (type = const_get(name)).is_a?(Class) && object.is_a?(type) }
+
+    # True for the clauses allowed inside FOREACH.
+    def self.updating?(clause) = [Set, Remove, Create, Merge, Delete, Foreach].any? { |type| clause.is_a?(type) }
+
     module_function
 
     def for_each(variable, list, clauses)
+      raise ArgumentError, UPDATING_MESSAGE unless clauses.all? { |clause| Clauses.updating?(clause) }
+
       Foreach.new(variable: SymbolicName.of(variable), list: Expression.coerce(list), clauses: clauses.freeze)
     end
 

data/lib/cypher_dsl/comparison.rb

@@ -3,10 +3,16 @@
 module CypherDSL
   # A binary comparison (`a = b`, `a =~ b`, …) or a unary one (`a IS NULL`).
   class Comparison < Condition
+    UNARY_OPERATORS = ['IS NULL', 'IS NOT NULL'].freeze
+
     attr_reader :left, :operator, :right
 
     def initialize(left, operator, right)
       super()
+      raise ArgumentError, 'Left expression must not be null.' if left.nil?
+      raise ArgumentError, 'Operator must not be empty.' if operator.nil? || operator.to_s.strip.empty?
+      raise ArgumentError, 'Right expression must not be null.' if right.nil? && !UNARY_OPERATORS.include?(operator)
+
       @left = left
       @operator = operator
       @right = right

data/lib/cypher_dsl/condition.rb

@@ -10,7 +10,7 @@ module CypherDSL
       case value
       when Condition then value
       when Relationship, RelationshipChain then RelationshipPatternCondition.new(value)
-      when FunctionInvocation then ExpressionCondition.new(value) # boolean functions such as isEmpty()
+      when FunctionInvocation, RawExpression then ExpressionCondition.new(value) # isEmpty(), raw text
       else raise ArgumentError, "#{value.inspect} is not a condition"
       end
     end

data/lib/cypher_dsl/count_expression.rb

@@ -1,16 +1,20 @@
 # frozen_string_literal: true
 
 module CypherDSL
-  # `COUNT { pattern }` / `COUNT { statement }`.
+  # `COUNT { pattern [WHERE …] }` / `COUNT { [WITH imports] statement }`.
   class CountExpression
     include Expression
 
-    attr_reader :body, :imports
+    attr_reader :body, :imports, :where_condition
 
-    def initialize(body, imports = [])
+    def initialize(body, imports = [], where_condition: nil)
       @body = body
       @imports = imports.freeze
+      @where_condition = where_condition
       freeze
     end
+
+    # `COUNT { pattern WHERE condition }`.
+    def where(condition) = CountExpression.new(body, imports, where_condition: Condition.coerce(condition))
   end
 end

data/lib/cypher_dsl/cypher.rb

@@ -10,16 +10,36 @@ module CypherDSL
 
     # --- pattern elements ------------------------------------------------
 
-    # A node with one primary label and optional additional labels; a trailing
-    # map (`Cypher.node('Test', Cypher.map_of(…))`) sets its properties.
+    # A node with one primary label and optional additional labels (or lists of
+    # them); a map among the arguments (`Cypher.node('Test', Cypher.map_of(…))`)
+    # sets its properties.
     def node(primary_label, *additional_labels)
-      properties = additional_labels.pop if [MapExpression, Hash].any? { |type| additional_labels.last.is_a?(type) }
-      labels = [primary_label, *additional_labels].map { |label| label.is_a?(LabelExpression) ? label : label.to_s }
+      additional_labels = additional_labels.flatten
+      properties = additional_labels.find { |label| [MapExpression, Hash].any? { |type| label.is_a?(type) } }
+      labels = [primary_label, *additional_labels.reject { |label| properties && label.equal?(properties) }]
+      labels = labels.map { |label| label.is_a?(Labels) ? label : label.to_s }
+      raise ArgumentError, 'A primary label is required.' if blank_label?(labels.first)
+      raise ArgumentError, 'An empty label is not allowed.' if labels.drop(1).any? { |label| blank_label?(label) }
+
       node = Node.new(labels:)
       properties ? node.with_properties(properties) : node
     end
 
+    def blank_label?(label) = label.is_a?(String) && label.strip.empty?
+    private_class_method :blank_label?
+
     # A node without labels, optionally named.
+    # `Cypher.search(:movie).in('index').for_vector(v).limit(4).build`, see {Search}.
+    def search(name) = Search::Builder.new(name && SymbolicName.of(name))
+
+    # `vector([1, 2, 3], 3, INTEGER NOT NULL)`, see {VectorLiteral}.
+    def vector(elements, type = nil) = VectorLiteral.of(elements, type)
+
+    # Label expressions: `Cypher.node(Cypher.exactly_label('A').or('B'))`, `Cypher.node(Cypher.all_labels($labels))`.
+    def exactly_label(label) = Labels.exactly(label)
+    def all_labels(expression) = Labels.all(expression)
+    def any_label(expression) = Labels.any(expression)
+
     def any_node(name = nil)
       node = Node.new(labels: [])
       name ? node.named(name) : node
@@ -76,15 +96,16 @@ module CypherDSL
 
     # Path selectors, `Cypher.any_shortest.named(:p).defined_by(pattern)` → `p = ANY pattern`.
     def any_shortest = NamedPath::Selector.new('ANY')
-    def all_shortest = NamedPath::Selector.new('ALL SHORTEST')
+    def all_shortest = NamedPath::Selector.new('ALL SHORTEST', legacy_function: 'allShortestPaths')
     def shortest_k(count) = NamedPath::Selector.shortest_k(count)
     def shortest_k_groups(count) = NamedPath::Selector.shortest_k(count, groups: true)
 
     # `EXISTS { pattern }` / `EXISTS { pattern, pattern }` / `EXISTS { [WITH imports] statement }`.
-    # A property gives the condition `n.prop IS NOT NULL`, any other plain expression the
-    # legacy `exists(expr)` function.
+    # A property gives the condition `n.prop IS NOT NULL` (`exists(n.prop)` on Neo4j 4), any other
+    # plain expression the `exists(expr)` function.
     def exists(body, *imports)
-      return body.is_not_null if body.is_a?(Property)
+      raise ArgumentError, 'The expression or pattern for exists() is required.' if body.nil?
+      return PropertyExistsCondition.new(body) if body.is_a?(Property)
       return function('exists', body) if body.is_a?(Expression) && !body.is_a?(Statement) && !pattern?(body)
 
       ExistsCondition.new(body, imports.flatten.map { |import| Expression.coerce(import) })
@@ -95,6 +116,9 @@ module CypherDSL
 
     def pattern?(value) = PATTERN_TYPES.any? { |type| value.is_a?(type) }
 
+    # The condition `name:Label`, for a name that may stand for a node or a relationship.
+    def has_labels_or_type(name, *labels) = HasLabelCondition.new(SymbolicName.of(name), labels.flatten)
+
     # List predicates: `Cypher.all(:x).in(list).where(condition)`.
     def all(variable) = ListPredicate::Ongoing.new('all', variable)
     def any(variable) = ListPredicate::Ongoing.new('any', variable)
@@ -137,7 +161,26 @@ module CypherDSL
     # A map projection on a name: `Cypher.create_projection(:n, 'title')` → `n{.title}`.
     def create_projection(name, *entries) = MapProjection.new(SymbolicName.of(name), entries.flatten)
 
-    def sort(expression) = SortItem.new(Expression.coerce(expression), nil)
+    # A sort item, optionally with its direction (`:asc` / `:desc`).
+    def sort(expression, direction = nil) = SortItem.new(Expression.coerce(expression), direction)
+
+    # A string as a Cypher string literal, `'…'` with quotes and backslashes escaped.
+    def quote(string) = Literal.quote(string)
+
+    # A short textual form of an expression: the name of a named element, alias or
+    # symbolic name, `container.name` for a property, the rendered Cypher otherwise.
+    def format(expression)
+      case expression
+      when Node, Relationship then expression.required_symbolic_name.value
+      when AliasedExpression then expression.alias_name.value
+      when SymbolicName then expression.value
+      when Property then ([expression.container] + expression.names).map { |part| format_name(part) }.join('.')
+      else Renderer.plain.render_fragment(expression)
+      end
+    end
+
+    def format_name(name) = name.is_a?(Expression) ? format(name) : name
+    private_class_method :format_name
 
     # `size(list)` or `size(pattern)`.
     def size(expression_or_pattern)
@@ -145,12 +188,14 @@ module CypherDSL
       function('size', argument)
     end
 
-    # `count(expression)`, or `COUNT { pattern }` / `COUNT { statement }` for patterns and statements.
-    def count(expression_or_pattern)
-      subquery = pattern?(expression_or_pattern) || expression_or_pattern.is_a?(Statement)
-      return CountExpression.new(expression_or_pattern) if subquery
+    # `count(expression)`, or `COUNT { [WITH imports] pattern }` / `COUNT { … statement }`
+    # for patterns and statements.
+    def count(expression_or_pattern, *imports)
+      subquery = pattern?(expression_or_pattern) || expression_or_pattern.is_a?(Statement) ||
+                 expression_or_pattern.is_a?(UnionQuery)
+      return FunctionInvocation.new('count', [Expression.coerce(expression_or_pattern)]) unless subquery
 
-      FunctionInvocation.new('count', [Expression.coerce(expression_or_pattern)])
+      CountExpression.new(expression_or_pattern, imports.flatten.map { |import| Expression.coerce(import) })
     end
 
     # `Cypher.call('db.labels')` / `Cypher.call('db', 'labels')`: a procedure call (see {StandaloneCall});
@@ -161,15 +206,30 @@ module CypherDSL
       StandaloneCall.new(arguments)
     end
 
-    # `Cypher.use('graph', statement)` / `Cypher.use(Cypher.graph_by_name(name), statement)`:
-    # the statement prefixed with `USE graph`.
+    # `Cypher.use('graph', statement)`: the statement prefixed with `USE graph`. An
+    # expression as the target (a name, literal or parameter) is wrapped in
+    # `graph.byName(…)` unless it already is a function call.
     def use(graph, statement)
+      raise ArgumentError, 'Nested USE clauses are not supported' if statement.clauses.first.is_a?(Clauses::Use)
+      if statement.prefix
+        raise ArgumentError, "#{DECORATED[statement.prefix]} statements are not supported inside USE clauses"
+      end
+
+      graph = graph_by_name(graph) if graph.is_a?(Expression) && !graph.is_a?(FunctionInvocation)
       graph = graph.to_s unless graph.is_a?(Expression)
       Statement.new([Clauses::Use.new(graph:)] + statement.clauses)
     end
 
+    DECORATED = { 'EXPLAIN' => "EXPLAIN'ed", 'PROFILE' => "PROFILE'd" }.freeze
+    private_constant :DECORATED
+
     # `Cypher.load_csv('file:///x.csv').as(:line)`.
-    def load_csv(uri, with_headers: false) = StatementBuilder.new.load_csv(uri, with_headers:)
+    def load_csv(uri, positional_headers = false, with_headers: positional_headers) # rubocop:disable Style/OptionalBooleanParameter
+      StatementBuilder.new.load_csv(uri, with_headers:)
+    end
+
+    # `Cypher.using_periodic_commit(500).load_csv(uri).as(:line)`.
+    def using_periodic_commit(rate = nil) = UsingPeriodicCommit.new(rate:)
 
     # Imports for an EXISTS / COLLECT subquery: `Cypher.subquery_with(x).collect(statement)`.
     def subquery_with(*imports) = SubqueryWith.new(imports)
@@ -181,8 +241,9 @@ module CypherDSL
       StatementBuilder.new.send(:append, clause, nil)
     end
 
-    # Verbatim Cypher, the escape hatch.
-    def raw(cypher) = RawExpression.new(cypher)
+    # Verbatim Cypher, the escape hatch; `$E` placeholders take the arguments in
+    # order, `\$E` is a literal `$E`. See {RawExpression.create}.
+    def raw(*) = RawExpression.create(*)
 
     # Static comparison forms, `Cypher.gt(a, b)` etc.
     def eq(left, right) = Expression.coerce(left).is_equal_to(right)

data/lib/cypher_dsl/expression.rb

@@ -11,6 +11,9 @@ module CypherDSL
 
     def as(alias_name) = AliasedExpression.new(self, alias_name)
 
+    # The expression as Cypher, names escaped only when necessary (as the Java `toString`).
+    def to_s = Renderer.plain.render_fragment(self)
+
     # A property of this expression's value, e.g. `$param.key` or `datetime().epochSeconds`.
     def property(*names) = Property.new(self, names)
 

data/lib/cypher_dsl/function_invocation.rb

@@ -5,9 +5,16 @@ module CypherDSL
   class FunctionInvocation
     include Expression
 
+    # The functions that accept `DISTINCT`, lower-cased.
+    AGGREGATES = %w[avg collect count max min percentilecont percentiledisc stdev stdevp sum].freeze
+
     attr_reader :function_name, :arguments, :distinct
 
     def initialize(function_name, arguments, distinct: false)
+      if distinct && !AGGREGATES.include?(function_name.downcase)
+        raise ArgumentError, 'The distinct operator can only be applied within aggregate functions.'
+      end
+
       @function_name = function_name
       @arguments = arguments.freeze
       @distinct = distinct

data/lib/cypher_dsl/functions.rb

@@ -60,7 +60,13 @@ module CypherDSL
     def tail(expression) = function('tail', expression)
     def keys(expression) = function('keys', expression)
     def properties(expression) = function('properties', expression)
-    def coalesce(*expressions) = function('coalesce', *expressions)
+
+    def coalesce(*expressions)
+      raise ArgumentError, 'The expression for coalesce() is required.' if expressions.flatten.empty?
+
+      function('coalesce', *expressions)
+    end
+
     def is_empty(expression) = function('isEmpty', expression)
     def range(start_value, end_value, step = nil) = function('range', start_value, end_value, *[step].compact)
     def nodes(path) = function('nodes', path.required_symbolic_name)
@@ -87,6 +93,10 @@ module CypherDSL
     def to_boolean(expression) = function('toBoolean', expression)
     def random_uuid = function('randomUUID')
 
+    # `linenumber()` and `file()`, available inside LOAD CSV.
+    def linenumber = function('linenumber')
+    def file = function('file')
+
     # --- mathematical ----------------------------------------------------
 
     def abs(expression) = function('abs', expression)

data/lib/cypher_dsl/has_label_condition.rb

@@ -8,7 +8,7 @@ module CypherDSL
     def initialize(node, labels)
       super()
       @node = node
-      @labels = labels.map(&:to_s).freeze
+      @labels = labels.map { |label| label.is_a?(Labels) ? label : label.to_s }.freeze
       freeze
     end
   end

data/lib/cypher_dsl/hint.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A planner hint on a MATCH clause: `USING INDEX [SEEK] n:Label(prop, …)`,
+  # `USING SCAN n:Label` or `USING JOIN ON n, m`.
+  class Hint
+    attr_reader :type, :container, :schema_name, :property_names, :names
+
+    # `use_index_for(seek, *properties)`: all properties must belong to the same node or relationship.
+    def self.use_index_for(seek, *properties)
+      properties = properties.flatten
+      raise ArgumentError, 'Cannot use an index without properties!' if properties.empty?
+
+      references = properties.map { |property| index_reference(property) }
+      if references.map(&:first).uniq.size > 1
+        raise ArgumentError, 'If you want to use more than one index on different nodes you must use multiple ' \
+                             '`USING INDEX` statements.'
+      end
+
+      container, schema_name = references.first
+      new(seek ? :index_seek : :index, container:, schema_name:, property_names: properties.map { |p| p.names.first })
+    end
+
+    def self.use_scan_for(node)
+      raise ArgumentError, 'Cannot apply a SCAN hint without a node.' if node.nil?
+      raise ArgumentError, 'Exactly one label is required for a SCAN hint.' unless node.labels.size == 1
+
+      new(:scan, container: node, schema_name: node.labels.first)
+    end
+
+    def self.use_join_on(*nodes_or_names)
+      nodes_or_names = nodes_or_names.flatten
+      raise ArgumentError, 'At least one node is required to define a JOIN hint.' if nodes_or_names.empty?
+
+      names = nodes_or_names.map do |item|
+        item.respond_to?(:required_symbolic_name) ? item.required_symbolic_name : SymbolicName.of(item)
+      end
+      new(:join, names:)
+    end
+
+    # The container and its single label or type, validated for an index hint.
+    def self.index_reference(property)
+      container = property.container
+      unless container.is_a?(Node) || container.is_a?(Relationship)
+        raise ArgumentError, 'Cannot use a property without a reference to a container inside an index hint.'
+      end
+      raise ArgumentError, 'One single property is required. Nested properties are not supported.' if property.nested?
+
+      if container.is_a?(Node)
+        raise ArgumentError, 'Exactly one label is required to define the index.' unless container.labels.size == 1
+
+        [container, container.labels.first]
+      else
+        types = container.details.types
+        raise ArgumentError, 'Exactly one type is required to define the index.' unless types.size == 1
+
+        [container, types.first]
+      end
+    end
+    private_class_method :index_reference
+
+    def initialize(type, container: nil, schema_name: nil, property_names: [], names: [])
+      @type = type
+      @container = container
+      @schema_name = schema_name
+      @property_names = property_names.freeze
+      @names = names.freeze
+      freeze
+    end
+  end
+end

data/lib/cypher_dsl/label_operation.rb

@@ -1,18 +1,26 @@
 # frozen_string_literal: true
 
 module CypherDSL
-  # `n:Label:Other` as the target of SET or REMOVE; `remove` marks an operation
-  # built for REMOVE, which a SET clause rejects.
+  # `n:Label:Other` or `n:$($labels)` as the target of SET or REMOVE; `remove`
+  # marks an operation built for REMOVE, which a SET clause rejects.
   class LabelOperation
     attr_reader :node, :labels, :remove
 
     def initialize(node, labels, remove: false)
       @node = node
-      @labels = labels.map(&:to_s).freeze
+      @labels = labels.map { |label| label.is_a?(Labels) ? updatable(label) : label.to_s }.freeze
       @remove = remove
       freeze
     end
 
     def remove? = remove
+
+    private
+
+    def updatable(labels)
+      raise ArgumentError, Labels::UPDATE_MESSAGE unless labels.usable_in_update?
+
+      labels
+    end
   end
 end