Optimize vertex/edge field access with direct array indexing

NOTE: This PR was created using AI tools and a human.

Leverage deterministic key ordering from uniqueify_agtype_object() to
access vertex/edge fields in O(1) instead of O(log n) binary search.

Fields are sorted by key length, giving fixed positions:
- Vertex: id(0), label(1), properties(2)
- Edge: id(0), label(1), end_id(2), start_id(3), properties(4)

Changes:
- Add field index constants and accessor macros to agtype.h
- Update age_id(), age_start_id(), age_end_id(), age_label(),
  age_properties() to use direct field access
- Add fill_agtype_value_no_copy() for read-only scalar extraction
  without memory allocation
- Add compare_agtype_scalar_containers() fast path for scalar comparison
- Update hash_agtype_value(), equals_agtype_scalar_value(), and
  compare_agtype_scalar_values() to use direct field access macros
- Add fast path in get_one_agtype_from_variadic_args() bypassing
  extract_variadic_args() for single argument case
- Add comprehensive regression test (30 tests)

Performance impact: Improves ORDER BY, hash joins, aggregations, and
Cypher functions (id, start_id, end_id, label, properties) on vertices
and edges.

All previous regression tests were not impacted.
Additional regression test added to enhance coverage.

modified:   Makefile
new file:   regress/expected/direct_field_access.out
new file:   regress/sql/direct_field_access.sql
modified:   src/backend/utils/adt/agtype.c
modified:   src/backend/utils/adt/agtype_util.c
modified:   src/include/utils/agtype.h

Author: jrgemignani

Makefile

@@ -112,7 +112,8 @@ REGRESS = scan \
           name_validation \
           jsonb_operators \
           list_comprehension \
-          map_projection
+          map_projection \
+          direct_field_access
 
 ifneq ($(EXTRA_TESTS),)
   REGRESS += $(EXTRA_TESTS)

src/backend/utils/adt/agtype.c

@@ -5409,10 +5409,24 @@ Datum age_id(PG_FUNCTION_ARGS)
         ereport(ERROR, (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                         errmsg("id() argument must be a vertex, an edge or null")));
 
-    agtv_result = GET_AGTYPE_VALUE_OBJECT_VALUE(agtv_object, "id");
-
-    Assert(agtv_result != NULL);
-    Assert(agtv_result->type = AGTV_INTEGER);
+    /*
+     * Direct field access optimization: id is at a fixed index for both
+     * vertex and edge objects due to key length sorting.
+     */
+    if (agtv_object->type == AGTV_VERTEX)
+    {
+        agtv_result = AGTYPE_VERTEX_GET_ID(agtv_object);
+    }
+    else if (agtv_object->type == AGTV_EDGE)
+    {
+        agtv_result = AGTYPE_EDGE_GET_ID(agtv_object);
+    }
+    else
+    {
+        ereport(ERROR,
+                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
+                 errmsg("id() unexpected argument type")));
+    }
 
     PG_RETURN_POINTER(agtype_value_to_agtype(agtv_result));
 }
@@ -5447,10 +5461,11 @@ Datum age_start_id(PG_FUNCTION_ARGS)
         ereport(ERROR, (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                         errmsg("start_id() argument must be an edge or null")));
 
-    agtv_result = GET_AGTYPE_VALUE_OBJECT_VALUE(agtv_object, "start_id");
-
-    Assert(agtv_result != NULL);
-    Assert(agtv_result->type = AGTV_INTEGER);
+    /*
+     * Direct field access optimization: start_id is at index 3 for edge
+     * objects due to key length sorting (id=0, label=1, end_id=2, start_id=3).
+     */
+    agtv_result = AGTYPE_EDGE_GET_START_ID(agtv_object);
 
     PG_RETURN_POINTER(agtype_value_to_agtype(agtv_result));
 }
@@ -5485,10 +5500,11 @@ Datum age_end_id(PG_FUNCTION_ARGS)
         ereport(ERROR, (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                         errmsg("end_id() argument must be an edge or null")));
 
-    agtv_result = GET_AGTYPE_VALUE_OBJECT_VALUE(agtv_object, "end_id");
-
-    Assert(agtv_result != NULL);
-    Assert(agtv_result->type = AGTV_INTEGER);
+    /*
+     * Direct field access optimization: end_id is at index 2 for edge
+     * objects due to key length sorting (id=0, label=1, end_id=2).
+     */
+    agtv_result = AGTYPE_EDGE_GET_END_ID(agtv_object);
 
     PG_RETURN_POINTER(agtype_value_to_agtype(agtv_result));
 }
@@ -6038,10 +6054,25 @@ Datum age_properties(PG_FUNCTION_ARGS)
                         errmsg("properties() argument must be a vertex, an edge or null")));
     }
 
-    agtv_result = GET_AGTYPE_VALUE_OBJECT_VALUE(agtv_object, "properties");
-
-    Assert(agtv_result != NULL);
-    Assert(agtv_result->type = AGTV_OBJECT);
+    /*
+     * Direct field access optimization: properties is at index 2 for vertex
+     * (id=0, label=1, properties=2) and index 4 for edge (id=0, label=1,
+     * end_id=2, start_id=3, properties=4) due to key length sorting.
+     */
+    if (agtv_object->type == AGTV_VERTEX)
+    {
+        agtv_result = AGTYPE_VERTEX_GET_PROPERTIES(agtv_object);
+    }
+    else if (agtv_object->type == AGTV_EDGE)
+    {
+        agtv_result = AGTYPE_EDGE_GET_PROPERTIES(agtv_object);
+    }
+    else
+    {
+        ereport(ERROR,
+                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
+                 errmsg("properties() unexpected argument type")));
+    }
 
     PG_RETURN_POINTER(agtype_value_to_agtype(agtv_result));
 }
@@ -7170,8 +7201,24 @@ Datum age_label(PG_FUNCTION_ARGS)
 
     }
 
-    /* extract the label agtype value from the vertex or edge */
-    label = GET_AGTYPE_VALUE_OBJECT_VALUE(agtv_value, "label");
+    /*
+     * Direct field access optimization: label is at a fixed index for both
+     * vertex and edge objects due to key length sorting.
+     */
+    if (agtv_value->type == AGTV_VERTEX)
+    {
+        label = AGTYPE_VERTEX_GET_LABEL(agtv_value);
+    }
+    else if (agtv_value->type == AGTV_EDGE)
+    {
+        label = AGTYPE_EDGE_GET_LABEL(agtv_value);
+    }
+    else
+    {
+        ereport(ERROR,
+                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
+                 errmsg("label() unexpected argument type")));
+    }
 
     PG_RETURN_POINTER(agtype_value_to_agtype(label));
 }
@@ -10507,6 +10554,59 @@ agtype *get_one_agtype_from_variadic_args(FunctionCallInfo fcinfo,
     Oid *types = NULL;
     agtype *agtype_result = NULL;
 
+    /*
+     * Fast path optimization: For non-variadic calls where the argument
+     * is already an agtype, we can avoid the overhead of extract_variadic_args
+     * which allocates three arrays. This is the common case for most agtype
+     * comparison and arithmetic operators.
+     */
+    if (!get_fn_expr_variadic(fcinfo->flinfo))
+    {
+        int total_args = PG_NARGS();
+        int actual_nargs = total_args - variadic_offset;
+
+        /* Verify expected number of arguments */
+        if (actual_nargs != expected_nargs)
+        {
+            ereport(ERROR, (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
+                            errmsg("number of args %d does not match expected %d",
+                                   actual_nargs, expected_nargs)));
+        }
+
+        /* Check for SQL NULL */
+        if (PG_ARGISNULL(variadic_offset))
+        {
+            return NULL;
+        }
+
+        /* Check if the argument is already an agtype */
+        if (get_fn_expr_argtype(fcinfo->flinfo, variadic_offset) == AGTYPEOID)
+        {
+            agtype_container *agtc;
+
+            agtype_result = DATUM_GET_AGTYPE_P(PG_GETARG_DATUM(variadic_offset));
+            agtc = &agtype_result->root;
+
+            /*
+             * Is this a scalar (scalars are stored as one element arrays)?
+             * If so, test for agtype NULL.
+             */
+            if (AGTYPE_CONTAINER_IS_SCALAR(agtc) &&
+                AGTE_IS_NULL(agtc->children[0]))
+            {
+                return NULL;
+            }
+
+            return agtype_result;
+        }
+
+        /*
+         * Not an agtype, need to convert. Fall through to use
+         * extract_variadic_args for type conversion handling.
+         */
+    }
+
+    /* Standard path using extract_variadic_args */
     nargs = extract_variadic_args(fcinfo, variadic_offset, false, &args, &types,
                                   &nulls);
     /* throw an error if the number of args is not the expected number */