perf: VLE terminal-qual rewrite (#2420)

perf: VLE terminal-qual rewrite — emit endpoint equalities instead of SRF
qual functions.

Removes the per-row age_match_vle_terminal_edge and age_match_two_vle_edges
qual functions from VLE query plans. The cypher transformer now emits the
endpoint match as a plain graphid/int8 equality on new SRF output columns,
evaluated by the planner like any other join clause — no detoasting, no
per-row C function dispatch. Stages land as one commit:

  S1  Inline start_vid/end_vid in VLE_path_container header
  S2  Read VLE qual endpoints from header-only TOAST slice
  S4  Emit start_id/end_id as scalar SRF output columns
      (age_vle now RETURNS SETOF record with edges/start_id/end_id)
  S5  Cypher transformer rewrites terminal-edge match quals as
      integer equalities (drops age_match_vle_terminal_edge call)
  S6  Cypher transformer emits graphid equality for two-VLE-edge
      joins (drops age_match_two_vle_edges call)

Performance (SF3 LDBC SNB, 5 runs/3 warmup, vs clean master baseline_v2):

  IC sum    198,958 → 109,322 ms   −45.05 %  (1.82× end-to-end speedup)
  IC1   8,625 →  4,600 ms  −46.67 %
  IC3  21,239 →  9,784 ms  −53.93 %
  IC5  21,051 →  5,696 ms  −72.94 %
  IC6  15,916 →  4,447 ms  −72.06 %
  IC9  44,839 → 21,161 ms  −52.81 %
  IC10 13,104 →  2,432 ms  −81.44 %
  IC11 11,676 →    241 ms  −97.93 %  (48× speedup)
  IC2/4/7/8/12: parity (within ±3.3 %; IC4 is −2.47 %, no regression)
  IS sum:  1,009 → 1,004 ms   −0.51 %  (no VLE traffic)
  IU sum:     77 →    71 ms   −8.38 %  (IU1 −16.09 %; incidental)

Memory: header-only TOAST slice for VLE qual evaluation avoids
detoasting full path containers on every row; reduces per-call
palloc/pfree churn in long DFS paths. No measured RSS change.

Dead-code removal:
  - Bodies of age_match_vle_terminal_edge and age_match_two_vle_edges
    are gone from age_vle.c (~225 lines).  C entry points remain as
    error-raising stubs solely so the upgrade-test snapshot loader
    (which sources an older 1.7.0_initial SQL against the current
    age.so) can resolve the symbols before the immediate ALTER
    EXTENSION UPDATE drops them.  No regress test references either
    function.
  - SQL CREATE FUNCTION declarations removed from fresh install
    (sql/agtype_typecast.sql).
  - DROP FUNCTION IF EXISTS for both qual functions added to the
    upgrade script (age--1.7.0--y.y.y.sql).

API change: ag_catalog.age_vle(...) now RETURNS SETOF record with
output columns (edges agtype, start_id graphid, end_id graphid)
instead of RETURNS SETOF agtype.  Both 7-arg and 8-arg overloads
are updated in fresh-install (sql/agtype_typecast.sql) and upgrade
(age--1.7.0--y.y.y.sql) paths.  age_match_vle_terminal_edge and
age_match_two_vle_edges are dropped on upgrade and absent from
fresh installs.  Internal AGE callers are unaffected; external SQL
that called any of these directly must adapt.

Hardening (in response to PR #2420 review feedback):
  - cypher_clause.c: terminal-edge and two-VLE-edge join-qual
    emission paths now bracket the existing Assert(vle_alias != NULL)
    with a runtime ereport(ERROR, ...) so a missing alias produces a
    clean error in production builds (where Asserts compile out)
    instead of a NULL-deref crash inside makeString().
  - age_vle.c: VLE_path_container struct comment now documents that
    the layout is transient (consumed within the producing query and
    never persisted), so the new start_vid/end_vid fields do not
    require an AGT_FBINARY_TYPE_VLE_PATH version bump or backward-
    compatible reader. The note also flags the constraint a future
    change would need to honor if the container ever became
    persistable.

Tested on PostgreSQL 18.3 (REL_18_STABLE): all 34 regression tests
pass (installcheck), warning-free build.

modified:   age--1.7.0--y.y.y.sql
modified:   regress/expected/cypher_match.out
modified:   regress/expected/cypher_vle.out
modified:   regress/expected/expr.out
modified:   sql/agtype_typecast.sql
modified:   src/backend/parser/cypher_clause.c
modified:   src/backend/parser/cypher_transform_entity.c
modified:   src/backend/utils/adt/age_vle.c
modified:   src/include/parser/cypher_transform_entity.h

Author: jrgemignani

age--1.7.0--y.y.y.sql

@@ -490,3 +490,49 @@ AS 'SELECT $1::text::agtype';
 
 CREATE CAST (jsonb AS agtype)
     WITH FUNCTION ag_catalog.jsonb_to_agtype(jsonb);
+
+--
+-- S4: VLE SRF signature change
+--
+-- The age_vle SRF now emits start_id and end_id as scalar graphid columns
+-- alongside the existing `edges` column. This allows the cypher transformer
+-- to rewrite terminal-edge match quals as plain integer equalities,
+-- removing the per-row age_match_vle_terminal_edge and age_match_two_vle_edges
+-- function calls from VLE query plans.  Both qual functions are dropped.
+--
+-- BREAKING CHANGE for any external SQL that called age_vle(...) directly
+-- and relied on `RETURNS SETOF agtype`, or called age_match_vle_terminal_edge
+-- / age_match_two_vle_edges directly.  Internal AGE callers (the cypher
+-- transformer) are not affected.
+--
+DROP FUNCTION IF EXISTS ag_catalog.age_match_vle_terminal_edge(variadic "any");
+DROP FUNCTION IF EXISTS ag_catalog.age_match_two_vle_edges(agtype, agtype);
+
+DROP FUNCTION IF EXISTS ag_catalog.age_vle(agtype, agtype, agtype, agtype,
+                                           agtype, agtype, agtype);
+DROP FUNCTION IF EXISTS ag_catalog.age_vle(agtype, agtype, agtype, agtype,
+                                           agtype, agtype, agtype, agtype);
+
+CREATE FUNCTION ag_catalog.age_vle(IN agtype, IN agtype, IN agtype, IN agtype,
+                                   IN agtype, IN agtype, IN agtype,
+                                   OUT edges    agtype,
+                                   OUT start_id graphid,
+                                   OUT end_id   graphid)
+    RETURNS SETOF record
+LANGUAGE C
+STABLE
+CALLED ON NULL INPUT
+PARALLEL UNSAFE
+AS 'MODULE_PATHNAME';
+
+CREATE FUNCTION ag_catalog.age_vle(IN agtype, IN agtype, IN agtype, IN agtype,
+                                   IN agtype, IN agtype, IN agtype, IN agtype,
+                                   OUT edges    agtype,
+                                   OUT start_id graphid,
+                                   OUT end_id   graphid)
+    RETURNS SETOF record
+LANGUAGE C
+STABLE
+CALLED ON NULL INPUT
+PARALLEL UNSAFE
+AS 'MODULE_PATHNAME';

regress/expected/cypher_match.out

@@ -2784,13 +2784,13 @@ SELECT * FROM cypher('cypher_match', $$ MATCH p=()-[*]->() RETURN length(p) $$)
  length 
 --------
  1
- 2
  1
+ 2
  1
  1
  2
- 1
  2
+ 1
 (8 rows)
 
 SELECT * FROM cypher('cypher_match', $$ MATCH p=()-[*]->() WHERE length(p) > 1 RETURN length(p) $$) as (length agtype);
@@ -2812,8 +2812,8 @@ SELECT * FROM cypher('cypher_match', $$ MATCH p=()-[*]->() WHERE size(nodes(p))
 SELECT * FROM cypher('cypher_match', $$ MATCH (n {name:'Dave'}) MATCH p=()-[*]->() WHERE nodes(p)[0] = n RETURN length(p) $$) as (length agtype);
  length 
 --------
- 1
  2
+ 1
 (2 rows)
 
 SELECT * FROM cypher('cypher_match', $$ MATCH p1=(n {name:'Dave'})-[]->() MATCH p2=()-[*]->() WHERE p2=p1 RETURN p2=p1 $$) as (path agtype);

regress/expected/cypher_vle.out

@@ -70,10 +70,14 @@ PARALLEL SAFE
 AS 'MODULE_PATHNAME';
 
 -- original VLE function definition
+-- S4: emit start_id/end_id as scalar columns to enable transformer rewrite
+-- of terminal-edge quals as integer equalities (see PERF_VLE_TERMINAL_QUAL_PLAN).
 CREATE FUNCTION ag_catalog.age_vle(IN agtype, IN agtype, IN agtype, IN agtype,
                                    IN agtype, IN agtype, IN agtype,
-                                   OUT edges agtype)
-    RETURNS SETOF agtype
+                                   OUT edges    agtype,
+                                   OUT start_id graphid,
+                                   OUT end_id   graphid)
+    RETURNS SETOF record
 LANGUAGE C
 STABLE
 CALLED ON NULL INPUT
@@ -84,8 +88,10 @@ AS 'MODULE_PATHNAME';
 -- caching mechanism to coexist with the previous VLE version.
 CREATE FUNCTION ag_catalog.age_vle(IN agtype, IN agtype, IN agtype, IN agtype,
                                    IN agtype, IN agtype, IN agtype, IN agtype,
-                                   OUT edges agtype)
-    RETURNS SETOF agtype
+                                   OUT edges    agtype,
+                                   OUT start_id graphid,
+                                   OUT end_id   graphid)
+    RETURNS SETOF record
 LANGUAGE C
 STABLE
 CALLED ON NULL INPUT
@@ -100,15 +106,6 @@ CREATE FUNCTION ag_catalog.age_build_vle_match_edge(agtype, agtype)
 PARALLEL SAFE
 AS 'MODULE_PATHNAME';
 
--- function to match a terminal vle edge
-CREATE FUNCTION ag_catalog.age_match_vle_terminal_edge(variadic "any")
-    RETURNS boolean
-    LANGUAGE C
-    STABLE
-CALLED ON NULL INPUT
-PARALLEL SAFE
-AS 'MODULE_PATHNAME';
-
 -- function to create an AGTV_PATH from a VLE_path_container
 CREATE FUNCTION ag_catalog.age_materialize_vle_path(agtype)
     RETURNS agtype
@@ -135,14 +132,6 @@ RETURNS NULL ON NULL INPUT
 PARALLEL SAFE
 AS 'MODULE_PATHNAME';
 
-CREATE FUNCTION ag_catalog.age_match_two_vle_edges(agtype, agtype)
-    RETURNS boolean
-    LANGUAGE C
-    STABLE
-RETURNS NULL ON NULL INPUT
-PARALLEL SAFE
-AS 'MODULE_PATHNAME';
-
 -- list functions
 CREATE FUNCTION ag_catalog.age_keys(agtype)
     RETURNS agtype

regress/expected/expr.out

@@ -3982,10 +3982,6 @@ static List *make_join_condition_for_edge(cypher_parsestate *cpstate,
     {
         Node *left_id = NULL;
         Node *right_id = NULL;
-        String *ag_catalog = makeString("ag_catalog");
-        String *func_name;
-        List *qualified_func_name;
-        List *args = NIL;
         List *quals = NIL;
 
         /*
@@ -3998,56 +3994,107 @@ static List *make_join_condition_for_edge(cypher_parsestate *cpstate,
         }
 
         /*
-         * If the previous node and the next node are in the join tree, we need
-         * to create the age_match_vle_terminal_edge to compare the vle returned
-         * results against the two nodes.
+         * S5: if the previous and next nodes are both in the join tree,
+         * emit two graphid equality A_Exprs:
+         *   <vle_alias>.start_id = prev_node.id
+         *   <vle_alias>.end_id   = next_node.id
+         * This replaces the historical per-row
+         *   age_match_vle_terminal_edge(prev.id, next.id, edges)
+         * function call with plain integer (int8) equality quals on the
+         * SRF's S4 output columns.  The planner can now drive the join
+         * directly on these keys (HashJoin hash keys, NestLoop index
+         * conditions where indexed).
          */
         if (prev_node->in_join_tree)
         {
-            func_name = makeString("age_match_vle_terminal_edge");
-            qualified_func_name = list_make2(ag_catalog, func_name);
+            ColumnRef *cr_start;
+            ColumnRef *cr_end;
+            A_Expr    *eq_start;
+            A_Expr    *eq_end;
 
             /*
-             * Get the vertex's id and pass to the function. Pass in NULL
-             * otherwise.
+             * Production-build runtime guard. Asserts compile out in
+             * non-debug builds, so a NULL vle_alias would otherwise reach
+             * makeString() and crash the backend during ColumnRef build.
              */
-            left_id = (Node *)make_qual(cpstate, prev_node, "id");
+            if (entity->vle_alias == NULL)
+            {
+                ereport(ERROR,
+                        (errcode(ERRCODE_INTERNAL_ERROR),
+                         errmsg("VLE edge entity is missing its alias; cannot emit terminal-edge join qual")));
+            }
+            Assert(entity->vle_alias != NULL);
+
+            cr_start = makeNode(ColumnRef);
+            cr_start->fields = list_make2(makeString(entity->vle_alias),
+                                          makeString("start_id"));
+            cr_start->location = -1;
+
+            cr_end = makeNode(ColumnRef);
+            cr_end->fields = list_make2(makeString(entity->vle_alias),
+                                        makeString("end_id"));
+            cr_end->location = -1;
+
+            left_id  = (Node *)make_qual(cpstate, prev_node, "id");
             right_id = (Node *)make_qual(cpstate, next_node, "id");
 
-            /* create the argument list */
-            args = list_make3(left_id, right_id, entity->expr);
+            eq_start = makeSimpleA_Expr(AEXPR_OP, "=",
+                                        (Node *)cr_start, left_id, -1);
+            eq_end   = makeSimpleA_Expr(AEXPR_OP, "=",
+                                        (Node *)cr_end,   right_id, -1);
 
-            /* add to quals */
-            quals = lappend(quals, makeFuncCall(qualified_func_name, args,
-                                                COERCE_EXPLICIT_CALL, -1));
+            quals = lappend(quals, eq_start);
+            quals = lappend(quals, eq_end);
         }
 
         /*
-         * When the previous node is not in the join tree, but there is a vle
-         * edge before that join, then we need to compare this vle's start node
-         * against the previous vle's end node. No need to check the next edge,
-         * because that would be redundant.
+         * S6: when the previous node is not in the join tree but there is
+         * a vle edge before that join, emit a single graphid equality
+         * connecting the two VLE SRFs:
+         *
+         *     prev_vle.end_id = this_vle.start_id
+         *
+         * This replaces the per-row age_match_two_vle_edges(prev, this)
+         * function call with a plain int8 equality on the S4 scalar
+         * output columns of both age_vle SRFs.  No detoasting of either
+         * VLE_path_container is needed.
          */
         if (!prev_node->in_join_tree &&
             prev_edge != NULL &&
             prev_edge->type == ENT_VLE_EDGE)
         {
-            List *qualified_name;
-            String *match_qual;
-            FuncCall *fc;
+            ColumnRef *cr_prev_end;
+            ColumnRef *cr_this_start;
+            A_Expr    *eq_chain;
 
-            match_qual = makeString("age_match_two_vle_edges");
+            /*
+             * Production-build runtime guard for both VLE aliases; see
+             * note above on entity->vle_alias.
+             */
+            if (prev_edge->vle_alias == NULL || entity->vle_alias == NULL)
+            {
+                ereport(ERROR,
+                        (errcode(ERRCODE_INTERNAL_ERROR),
+                         errmsg("VLE edge entity is missing its alias; cannot emit two-VLE-edge join qual")));
+            }
+            Assert(prev_edge->vle_alias != NULL);
+            Assert(entity->vle_alias != NULL);
 
-            /* make the qualified function name */
-            qualified_name = list_make2(ag_catalog, match_qual);
+            cr_prev_end = makeNode(ColumnRef);
+            cr_prev_end->fields = list_make2(makeString(prev_edge->vle_alias),
+                                             makeString("end_id"));
+            cr_prev_end->location = -1;
 
-            /* make the args */
-            args = list_make2(prev_edge->expr, entity->expr);
+            cr_this_start = makeNode(ColumnRef);
+            cr_this_start->fields = list_make2(makeString(entity->vle_alias),
+                                               makeString("start_id"));
+            cr_this_start->location = -1;
 
-            /* create the function call */
-            fc = makeFuncCall(qualified_name, args, COERCE_EXPLICIT_CALL, -1);
+            eq_chain = makeSimpleA_Expr(AEXPR_OP, "=",
+                                        (Node *)cr_prev_end,
+                                        (Node *)cr_this_start, -1);
 
-            quals = lappend(quals, fc);
+            quals = lappend(quals, eq_chain);
         }
 
         return quals;
@@ -4898,6 +4945,12 @@ static transform_entity *transform_VLE_edge_entity(cypher_parsestate *cpstate,
     vle_entity = make_transform_entity(cpstate, ENT_VLE_EDGE, (Node *)rel,
                                        (Expr *)var);
 
+    /*
+     * S5: stash the auto-generated alias name so make_join_condition_for_edge
+     * can build ColumnRefs for the SRF's start_id/end_id output columns.
+     */
+    vle_entity->vle_alias = alias->aliasname;
+
     /* return the vle entity */
     return vle_entity;
 }

sql/agtype_typecast.sql

@@ -52,6 +52,7 @@ transform_entity *make_transform_entity(cypher_parsestate *cpstate,
     entity->declared_in_current_clause = true;
     entity->expr = expr;
     entity->in_join_tree = expr != NULL;
+    entity->vle_alias = NULL;
 
     return entity;
 }