Skip to content

Docs: clarify VLE semantics and cost model (#2349)#2413

Merged
jrgemignani merged 1 commit intoapache:masterfrom
gregfelice:docs_2349_vle_semantics
Apr 25, 2026
Merged

Docs: clarify VLE semantics and cost model (#2349)#2413
jrgemignani merged 1 commit intoapache:masterfrom
gregfelice:docs_2349_vle_semantics

Conversation

@gregfelice
Copy link
Copy Markdown
Contributor

Summary

Adds an in-source design-note comment block at the top of src/backend/utils/adt/age_vle.c documenting:

  1. Semantics — edge-isomorphism per openCypher: no repeated edges per path, vertices may recur. Includes a small triangle example showing why a visited-node ("vertex-isomorphism") optimization would silently drop spec-valid paths.
  2. Cost model — bounded [*min..max] is polynomial in edge count for fixed max; unbounded [*] / [*1..] is factorial worst-case on cycle-rich graphs. This is inherent to edge-isomorphic enumeration and cannot be reduced without changing semantics.
  3. Implementation pointer — one paragraph identifying edge_state_entry.used_in_path, dfs_find_a_path_between/dfs_find_a_path_from, and is_edge_in_path() as the cycle-prevention enforcement sites.

Motivation

Issue #2349 misdiagnosed the VLE as lacking cycle detection and proposed a visited-node filter as a fix. Cycle prevention already exists via edge-uniqueness, and the proposed change would violate the openCypher specification. The current source has no overview comment explaining these semantics, so a future reader would have to reconstruct them from the DFS code and the spec. This comment block captures the semantics and cost model at a point the reader is guaranteed to pass through, preventing repeat misanalysis.

Per @jrgemignani's guidance on #2349, no GUC, no code change — just documentation.

Scope

  • Files changed: 1 (src/backend/utils/adt/age_vle.c — 44-line comment block inserted between the license header and the first #include).
  • No behavior change, no new symbols, no tests added (nothing to test).

Test plan

  • Cassert build (--enable-cassert PG18) clean, no new warnings
  • Cassert installcheck green — 33/33 AGE tests pass, including cypher_vle

Adds a block comment at the top of age_vle.c documenting (a) the
edge-isomorphism semantics that openCypher mandates for variable-length
relationship matching, (b) the cost model distinction between bounded
and unbounded patterns, and (c) a pointer to the enforcement site
(edge_state_entry.used_in_path, dfs_find_a_path_*, is_edge_in_path).

Motivation: issue apache#2349 misdiagnosed the VLE as lacking cycle detection
and proposed a visited-node filter as a fix. Cycle prevention already
exists via edge-uniqueness, and swapping to vertex-isomorphism would
silently drop spec-valid paths (e.g. triangle traversals where the
endpoint coincides with the start vertex). Capturing the semantics and
cost model in-source prevents future readers from repeating the same
misanalysis.

No behavior change. Cassert installcheck: 33/33.
@jrgemignani jrgemignani merged commit 9f9d0f3 into apache:master Apr 25, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants