pglpg 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61a05d0f91dc037aefaaf82fa99143eae9a3c2742dd2308adcffa0d364b2f6fc
-  data.tar.gz: 1286500cadead4a337382e5bba4a5ec60bc861bcec88bfb04c07856aadaa4cf3
+  metadata.gz: dcdce167b8e343909f06e710fdb65a1833a5cfa3649c85a475050c830a463a0d
+  data.tar.gz: f7725ba5bd6255af98a77875b766ac0e7d3a180f4af7ced79b50446998fbda6d
 SHA512:
-  metadata.gz: c76e6ed407cbb7ef56cc9e79999cad98c91d67e7f46b08b2aba548c197cd52409b6d70ae83b029e032c9c3dcda1594a3825241727a0da45c91a553c456bead57
-  data.tar.gz: 5c4c89d4af4a6f57988a734cc0d154b9b9c96a8dea5a15c51b7ab3802078f27d5468e7f42c6e98a6698befca2cb58c9ce7e5c9cc44e0482470d157951100a804
+  metadata.gz: e536165dfa69606c33d7c15c4dd77c68878a3be01b6f8b7b097e4effd3597d26a6b65e2dd1c87d2ce5247c588980bebb779af6e674d4e29d84f3efcf05187b22
+  data.tar.gz: 7c6fbe3e465c7134ae05ec5601e61f941462687f60f1dd91242641b1ab22446e44d0f9836c3db4cb2ca6c330f0136ead5cd8c23c305eac300ff9d15374aa645a

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.0 (2026-11-04)
+
+### Added
+
+- `Context#parse_match(text, params: {})` builds a lazy query from a read-only
+  fixed-length GQL MATCH subset. It uses the Ruby query builder, named value
+  binds, and the caller’s visibility, date mode and execution limits. Malformed
+  query text and invalid parameters report located `Pglpg::ParseError` diagnostics.
+
 ## 0.3.0 (2026-11-03)
 
 ### Breaking

data/README.md

@@ -8,16 +8,13 @@ ordinary tables, written inside your own transactions. Every query applies
 your visibility policy to every node and edge on every hop, so hidden records
 never act as bridges and never show up in counts or limits.
 
-Status: **0.3.0 release candidate; not yet published.** The latest published
-version is 0.2.0. This candidate includes temporal edges, composite/edge keys
-and explicit open properties. The design and its decisions live in the
+Status: **0.4.0 release candidate**, with a read-only text MATCH parser.
+The latest published version is 0.3.0. The design and its decisions live in the
 [pglpg.md](https://knowen.md/nodes/36325) knowledge base. Requires Ruby ≥ 4.0,
 ActiveRecord ≥ 8.1 and PostgreSQL ≥ 18: the versions CI tests.
 
 ## Install
 
-After 0.3.0 publication:
-
 ```ruby
 gem "pglpg", "~> 0.3.0"
 ```
@@ -26,6 +23,26 @@ Before 1.0, minor releases may break compatibility. Read the
 [0.3.0 upgrade notes](CHANGELOG.md) and the migration steps below before
 upgrading from 0.2. Applications still on 0.1 must also apply the 0.2 notes.
 
+After 0.4.0 is published, use `gem "pglpg", "~> 0.4.0"`.
+
+## Upgrade from 0.3
+
+The parser is additive and requires no schema migration. Existing Ruby queries
+keep their behavior. Use text MATCH with named value parameters on an existing
+context:
+
+```ruby
+query = context.parse_match(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p LIMIT 20",
+  params: { name: "Ann" }
+)
+query.to_a
+```
+
+Text supports fixed-length patterns and a subset of read clauses. It uses the
+context's visibility policy, date mode, and execution limits. See the
+[API contract](https://knowen.md/nodes/36329) for the grammar and error codes.
+
 ## Upgrade from 0.2
 
 - Choose `as_of: Date` for dated reads or `as_of: :any` for all dates.
@@ -60,7 +77,7 @@ Existing timeless, closed schemas with unchanged keys need no migration solely
 for the version bump. Rerun your real-policy leak suite and label-drift checks
 when adopting this minor release.
 
-This candidate implements a documented standards subset: key components are
+This release implements a documented standards subset: key components are
 string/integer/boolean/enum, open extras are scalars/flat homogeneous lists,
 and temporal validity is one date interval with current authorization. It does
 not add alternate/overlap keys, open labels, dynamic query/model attributes,
@@ -232,7 +249,7 @@ row access. Scope and key are immutable. Existing data needs a transactional
 backfill and constraint migration; see the
 [API contract](https://knowen.md/nodes/36329).
 
-## Composite and edge keys (0.3.0 candidate)
+## Composite and edge keys (0.3.0)
 
 Keys can use a tuple of required string, integer, boolean or enum properties:
 
@@ -278,7 +295,7 @@ by `storage.sync_constraints!` on the same connection. No automatic migration
 runs when a declaration is loaded. Other property types, optional uniqueness
 and multiple alternate keys are outside this key API.
 
-## Open properties (0.3.0 candidate)
+## Open properties (0.3.0)
 
 Types stay closed by default. Opt in to extra properties explicitly:
 
@@ -326,7 +343,7 @@ Audit/backfill before closing types or promoting extras to typed declarations.
 Shape validation is at the library write boundary; raw SQL does not gain an
 open/closed constraint. The existing required-property and key checks remain.
 
-## Temporal edges (0.3.0 candidate)
+## Temporal edges (0.3.0)
 
 Opt in per edge type and use one date across the whole query:
 

data/lib/pglpg/context.rb

@@ -16,6 +16,8 @@ module Pglpg
     # Starts a fixed-length pattern query.
     def match = Query.new(self)
 
+    def parse_match(text, params: {}) = MatchParser.new(self, text, params).parse
+
     # The visible node or edge behind +ref+, or nil. A hidden element and a
     # missing one look the same.
     def find(ref)

data/lib/pglpg/errors.rb

@@ -4,6 +4,21 @@ module Pglpg
   # Base class for every error pglpg raises.
   class Error < StandardError; end
 
+  # Text MATCH errors report byte positions in the submitted query.
+  class ParseError < Error
+    attr_reader :code, :position, :line, :column, :token
+
+    def initialize(message, code:, text:, position:, token:)
+      @code = code
+      @position = position
+      prefix = text.byteslice(0, position).b
+      @line = prefix.count("\n") + 1
+      @column = position - (prefix.rindex("\n") || -1)
+      @token = token&.freeze
+      super("#{message} at line #{line}, column #{column}")
+    end
+  end
+
   # The graph type declaration is invalid.
   class SchemaError < Error; end
 

data/lib/pglpg/match_parser.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Pglpg
+  # The text front end builds the same immutable query state as the Ruby DSL.
+  class MatchParser
+    MAX_BYTES = 8 * 1024
+    MAX_HOPS = 8
+    MAX_PREDICATES = 32
+    MAX_PARAMETERS = 32
+
+    IDENTIFIER = /[A-Za-z_][A-Za-z_0-9]*/
+    PARAMETER = /\$#{IDENTIFIER}/
+    TOKEN = /#{PARAMETER}|#{IDENTIFIER}|[0-9]+|->|<-|[^\s]/
+    KEYWORDS = %w[MATCH WHERE AND RETURN DISTINCT ORDER BY ASC DESC LIMIT].freeze
+    UNSUPPORTED_WORDS = %w[OPTIONAL CREATE INSERT DELETE DETACH SET REMOVE MERGE
+                           CALL WITH UNION OFFSET SKIP GROUP HAVING].freeze
+    CONDITION_PREFIXES = %w[NOT ANY ALL NONE SINGLE EXISTS].freeze
+    CONDITION_OPERATORS = %w[IS IN NOT STARTS ENDS CONTAINS LIKE BETWEEN].freeze
+    CONDITION_CONNECTORS = %w[OR XOR].freeze
+    Token = Data.define(:text, :position)
+
+    def initialize(context, text, params)
+      raise ArgumentError, "MATCH text must be a String" unless text.is_a?(String)
+
+      @context = context
+      @text = text
+      @params = params
+      @bindings = {}
+      @types = {}
+    end
+
+    def parse
+      validate_text!
+      @scanner = StringScanner.new(@text)
+      advance
+      expect("MATCH")
+      start = node_pattern
+      hops = []
+      hops << edge_pattern while %w[- <- ~].include?(@token.text)
+      fail_at(:unsupported, "multiple patterns are outside the MATCH subset") if @token.text == ","
+      predicates = read_predicates
+      expect("RETURN")
+      distinct = accept("DISTINCT")
+      returns = [return_binding]
+      returns << return_binding while accept(",")
+      order = read_order if accept("ORDER")
+      limit = take_integer if accept("LIMIT")
+      accept(";")
+      expect_end!
+
+      if distinct && order && returns.none? { |var| var.text == order.first.text }
+        fail_at(:syntax, "DISTINCT ordering requires a returned binding", order.first)
+      end
+      check_cap(hops.size, MAX_HOPS, "hops", hops[MAX_HOPS]&.first)
+      check_cap(predicates.size, MAX_PREDICATES, "WHERE predicates", predicates[MAX_PREDICATES]&.first)
+      row_limit = validate_limit(limit)
+      values = parameter_values(predicates.map(&:last))
+
+      query = build_pattern(start, hops)
+      predicates.each do |var, name, param|
+        property!(var, name)
+        begin
+          query = query.where(var.text.to_sym => { name.text.to_sym => values.fetch(param.text.delete_prefix("$")) })
+        rescue ValidationError, ArgumentError, RangeError
+          fail_at(:parameter, "invalid equality value", param)
+        end
+      end
+      returns.each { type_for!(_1) }
+      query = query.return(*returns.map { _1.text.to_sym })
+      query = query.distinct if distinct
+      if order
+        var, name, direction = order
+        property!(var, name)
+        query = query.order(var.text.to_sym => { name.text.to_sym => direction })
+      end
+      row_limit ? query.limit(row_limit) : query
+    end
+
+    private
+
+    def validate_text!
+      unless [Encoding::UTF_8, Encoding::US_ASCII].include?(@text.encoding)
+        fail_at(:syntax, "text must use UTF-8 or US-ASCII", Token.new(nil, 0))
+      end
+      if @text.bytesize > MAX_BYTES
+        fail_at(:limit_exceeded, "text exceeds #{MAX_BYTES} bytes", Token.new(nil, MAX_BYTES))
+      end
+      return if @text.valid_encoding?
+
+      offset = 0
+      @text.each_char do |char|
+        fail_at(:syntax, "invalid text encoding", Token.new(nil, offset)) unless char.valid_encoding?
+        offset += char.bytesize
+      end
+    end
+
+    def advance
+      @scanner.skip(/\s+/)
+      position = @scanner.pos
+      if (comment = @scanner.scan(%r{//|/\*}))
+        fail_at(:unsupported, "comments are outside the MATCH subset", Token.new(comment, position))
+      end
+      @token = Token.new(@scanner.scan(TOKEN), position)
+    end
+
+    def take
+      token = @token
+      advance
+      token
+    end
+
+    def accept(text)
+      take if @token.text&.casecmp?(text)
+    end
+
+    def expect(text)
+      accept(text) || unexpected("expected #{text}")
+    end
+
+    def expect_end!
+      unexpected("expected end of input") if @token.text
+    end
+
+    def unexpected(message)
+      text = @token.text
+      unsupported = text && (UNSUPPORTED_WORDS.include?(text.upcase) || %w[{ } | & ! * + %].include?(text))
+      fail_at(unsupported ? :unsupported : :syntax, message)
+    end
+
+    def identifier
+      return take if @token.text&.match?(/\A#{IDENTIFIER}\z/)
+
+      unexpected("expected an identifier")
+    end
+
+    def binding
+      token = identifier
+      name = token.text
+      if name.start_with?("_") || KEYWORDS.include?(name.upcase) || @bindings.key?(name)
+        fail_at(:syntax, "reserved or duplicate binding", token)
+      end
+      @bindings[name] = true
+      token
+    end
+
+    def node_pattern
+      expect("(")
+      var = binding
+      expect(":")
+      label = identifier
+      expect(")")
+      [var, label]
+    end
+
+    def edge_pattern
+      connector = take
+      direction, ending = case connector.text
+                          when "-" then [:out, "->"]
+                          when "<-" then [:in, "-"]
+                          when "~" then [:both, "~"]
+                          end
+      expect("[")
+      var = binding unless @token.text == ":"
+      expect(":")
+      type = identifier
+      expect("]")
+      if direction == :out && @token.text == "-"
+        fail_at(:unsupported, "use a directed arrow or a symmetric tilde")
+      end
+      expect(ending)
+      [connector, direction, var, type, node_pattern]
+    end
+
+    def read_predicates
+      return [] unless accept("WHERE")
+
+      predicates = []
+      loop do
+        # Contextual keywords can still name a binding in a property reference.
+        prefix = CONDITION_PREFIXES.include?(@token.text&.upcase) && !@scanner.check(/\s*\./)
+        if @token.text == "(" || prefix
+          fail_at(:unsupported_condition, "only AND-joined equality predicates are supported")
+        end
+        var, property = property_reference
+        unless accept("=")
+          fail_at(:unsupported_condition, "only equality predicates are supported") if %w[< > !].include?(@token.text) ||
+            CONDITION_OPERATORS.include?(@token.text&.upcase)
+          unexpected("expected =")
+        end
+        unless @token.text&.match?(/\A#{PARAMETER}\z/)
+          fail_at(:unsupported_condition, "equality requires a named parameter") if @token.text && @token.text != "$" && !KEYWORDS.include?(@token.text.upcase)
+          unexpected("expected a named parameter")
+        end
+        predicates << [var, property, take]
+        fail_at(:unsupported_condition, "only AND conjunctions are supported") if CONDITION_CONNECTORS.include?(@token.text&.upcase)
+        break unless accept("AND")
+      end
+      predicates
+    end
+
+    def property_reference
+      var = identifier
+      expect(".")
+      [var, identifier]
+    end
+
+    def return_binding
+      var = identifier
+      fail_at(:unsupported, "RETURN accepts element bindings only") if %w[. ( AS].include?(@token.text&.upcase)
+      var
+    end
+
+    def read_order
+      expect("BY")
+      var, name = property_reference
+      direction = accept("DESC") ? :desc : :asc
+      accept("ASC") if direction == :asc
+      fail_at(:unsupported, "ORDER BY accepts one term") if @token.text == ","
+      [var, name, direction]
+    end
+
+    def take_integer
+      return take if @token.text&.match?(/\A[0-9]+\z/)
+
+      unexpected("expected a decimal integer")
+    end
+
+    def validate_limit(token)
+      return unless token
+
+      limit = token.text.to_i
+      fail_at(:syntax, "LIMIT must be positive", token) if limit.zero?
+      check_cap(limit, Pglpg.configuration.max_rows, "LIMIT", token)
+      limit
+    end
+
+    def parameter_values(references)
+      origin = Token.new(nil, 0)
+      fail_at(:parameter, "params must be a Hash", origin) unless @params.is_a?(Hash)
+      named = references.to_h { |token| [token.text.delete_prefix("$"), token] }
+      # The predicate cap also bounds the number of distinct references.
+      check_cap(@params.size, MAX_PARAMETERS, "parameter entries", origin)
+
+      values = {}
+      @params.each do |key, value|
+        unless (key.is_a?(String) || key.is_a?(Symbol)) &&
+               key.to_s.ascii_only? && key.to_s.match?(/\A#{IDENTIFIER}\z/)
+          fail_at(:parameter, "invalid parameter key", origin)
+        end
+        name = key.to_s
+        token = named[name] || origin
+        fail_at(:parameter, "duplicate parameter key", token) if values.key?(name)
+        fail_at(:parameter, "unused parameter", token) unless named.key?(name)
+        if value.nil? || value.is_a?(Array) || value.is_a?(Condition)
+          fail_at(:parameter, "equality requires a scalar value", token)
+        end
+        values[name] = value.is_a?(String) ? value.dup.freeze : value
+      end
+      named.each { |name, token| fail_at(:parameter, "missing parameter", token) unless values.key?(name) }
+      values
+    end
+
+    def build_pattern(start, hops)
+      schema = @context.graph.type
+      var, label = start
+      bind_type(var, label, schema.node_types)
+      query = @context.match.node(var.text, label.text)
+      hops.each do |connector, direction, edge, type, target|
+        edge_type = bind_type(edge, type, schema.edge_types)
+        if edge_type.symmetric? != (direction == :both)
+          fail_at(:unsupported, "edge direction does not match its type", connector)
+        end
+        var, label = target
+        bind_type(var, label, schema.node_types)
+        query = query.public_send(direction, type.text, var.text, label.text, edge: edge&.text)
+      end
+      query
+    end
+
+    def bind_type(var, name, types)
+      type = types[name.text.to_sym] || fail_at(:unknown_name, "unknown label or edge type", name)
+      @types[var.text] = type if var
+      type
+    end
+
+    def type_for!(var)
+      @types[var.text] || fail_at(:unknown_name, "unknown binding", var)
+    end
+
+    def property!(var, name)
+      property = type_for!(var).property_named(name.text)
+      fail_at(:unknown_name, "unknown declared property", name) unless property
+      fail_at(:unsupported, "property is not comparable", name) unless property.comparable?
+    end
+
+    def check_cap(count, max, unit, token)
+      fail_at(:limit_exceeded, "maximum #{unit} is #{max}", token) if count > max
+    end
+
+    def fail_at(code, message, token = @token)
+      raise ParseError.new(message, code:, text: @text, position: token.position,
+                           token: token.text || ("EOF" if token.position == @text.bytesize)), cause: nil
+    end
+  end
+  private_constant :MatchParser
+end

data/lib/pglpg/testing.rb

@@ -25,6 +25,7 @@ module Pglpg
         persons: -> { m.().node(:p, :Person).order(p: :name) },
         works_on: -> { m.().node(:p, :Person).out(:WORKS_ON, :j, :Project, edge: :w) },
         two_hops: -> { m.().node(:p, :Person).out(:WORKS_ON, :j, :Project).out(:BASED_AT, :l, :Location) },
+        parsed_knows_chain: -> { ctx.parse_match("MATCH (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person) RETURN a, b, c") },
         knows_chain: -> { m.().node(:a, :Person).out(:KNOWS, :b, :Person).out(:KNOWS, :c, :Person) },
         inbound: -> { m.().node(:l, :Location).in(:BASED_AT, :j, :Project).in(:WORKS_ON, :p, :Person) },
         branch: -> { m.().node(:j, :Project).in(:WORKS_ON, :p, :Person).out(:BASED_AT, :l, :Location, from: :j) },

data/lib/pglpg/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pglpg
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/pglpg.rb

@@ -23,6 +23,7 @@ require_relative "pglpg/graph"
 require_relative "pglpg/context"
 require_relative "pglpg/writer"
 require_relative "pglpg/query"
+require_relative "pglpg/match_parser"
 require_relative "pglpg/reachability"
 
 # Labeled property graphs stored in plain PostgreSQL tables.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pglpg
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Anton Fefilov
@@ -54,6 +54,7 @@ files:
 - lib/pglpg/element.rb
 - lib/pglpg/errors.rb
 - lib/pglpg/graph.rb
+- lib/pglpg/match_parser.rb
 - lib/pglpg/model.rb
 - lib/pglpg/model/base.rb
 - lib/pglpg/model/edge.rb