feat: implement ISO-GQL SAME predicate for element identity compariso… (#692)

* feat: implement ISO-GQL SAME predicate for element identity comparison (#368)

Implement the ISO-GQL SAME predicate function to check if graph elements
refer to the same entity by comparing their identities. This feature adds
full ISO/IEC 39075:2024 Section 19.12 compliance for identity comparisons.

Changes:
- Parser Layer:
  * Add SqlSameCall AST node for SAME function calls
  * Add SqlSameOperator with BOOLEAN return type and VARIADIC operands
  * Register operator in BuildInSqlOperatorTable
  * Add syntax tests with 4 GQL test cases

- Runtime Layer:
  * Implement GeaFlowBuiltinFunctions.same() for identity comparison
    - Vertex comparison: compares vertex IDs using Objects.equals()
    - Edge comparison: compares both source and target IDs
    - Null handling: returns null following SQL ternary logic
    - Type safety: returns false for mismatched types
  * Add BuildInExpression.SAME constant for expression translation
  * Register SAME in ExpressionTranslator.processOtherTrans()

- Testing:
  * Add comprehensive SameTest with 13 unit tests (100% pass rate)
  * Test coverage: identical/different IDs, null handling, mixed types,
    string IDs, invalid types

Implementation follows Approach 1 (Built-in Function Pattern) with
minimal code changes (441 lines added across 9 files) for maximum
simplicity and maintainability.

Example usage:
  MATCH (a)->(b)->(c) WHERE SAME(a, c) RETURN a, b, c;

* fix(dsl): resolve ISO-GQL SAME predicate code review issues

- Fix SqlSameCall immutable operands list causing setOperand() failure
- Add type-specific same() overloads for RowVertex and RowEdge
- Add varargs same(Object...) for multi-element comparisons
- Add comprehensive unit tests for all same() overloads

Author: SeasonPilot

geaflow/geaflow-dsl/geaflow-dsl-parser/src/main/java/org/apache/geaflow/dsl/operator/SqlSameOperator.java

@@ -0,0 +1,78 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.geaflow.dsl.operator;
+
+import org.apache.calcite.sql.SqlCall;
+import org.apache.calcite.sql.SqlFunction;
+import org.apache.calcite.sql.SqlFunctionCategory;
+import org.apache.calcite.sql.SqlKind;
+import org.apache.calcite.sql.SqlLiteral;
+import org.apache.calcite.sql.SqlNode;
+import org.apache.calcite.sql.SqlWriter;
+import org.apache.calcite.sql.parser.SqlParserPos;
+import org.apache.calcite.sql.type.OperandTypes;
+import org.apache.calcite.sql.type.ReturnTypes;
+import org.apache.geaflow.dsl.sqlnode.SqlSameCall;
+
+/**
+ * SqlOperator for the ISO-GQL SAME predicate function.
+ *
+ * <p>This operator represents the SAME function which checks element identity.
+ *
+ * <p>Syntax: SAME(element1, element2, ...)
+ *
+ * <p>Returns: BOOLEAN - TRUE if all element references point to the same element,
+ * FALSE otherwise.
+ *
+ * <p>Implements ISO/IEC 39075:2024 Section 19.12.
+ */
+public class SqlSameOperator extends SqlFunction {
+
+    public static final SqlSameOperator INSTANCE = new SqlSameOperator();
+
+    private SqlSameOperator() {
+        super(
+            "SAME",
+            SqlKind.OTHER_FUNCTION,
+            ReturnTypes.BOOLEAN,
+            null,
+            // At least 2 operands, all must be of comparable types
+            OperandTypes.VARIADIC,
+            SqlFunctionCategory.USER_DEFINED_FUNCTION
+        );
+    }
+
+    @Override
+    public SqlCall createCall(
+        SqlLiteral functionQualifier,
+        SqlParserPos pos,
+        SqlNode... operands) {
+        return new SqlSameCall(pos, java.util.Arrays.asList(operands));
+    }
+
+    @Override
+    public void unparse(
+        SqlWriter writer,
+        SqlCall call,
+        int leftPrec,
+        int rightPrec) {
+        call.unparse(writer, leftPrec, rightPrec);
+    }
+}

geaflow/geaflow-dsl/geaflow-dsl-parser/src/main/java/org/apache/geaflow/dsl/sqlnode/SqlSameCall.java

@@ -0,0 +1,131 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.geaflow.dsl.sqlnode;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import org.apache.calcite.sql.SqlCall;
+import org.apache.calcite.sql.SqlNode;
+import org.apache.calcite.sql.SqlOperator;
+import org.apache.calcite.sql.SqlWriter;
+import org.apache.calcite.sql.parser.SqlParserPos;
+import org.apache.calcite.sql.validate.SqlValidator;
+import org.apache.calcite.sql.validate.SqlValidatorScope;
+import org.apache.geaflow.dsl.operator.SqlSameOperator;
+
+/**
+ * SqlNode representing the ISO-GQL SAME predicate function.
+ *
+ * <p>The SAME predicate checks if multiple element references point to the same
+ * graph element (identity check, not value equality).
+ *
+ * <p>Syntax: SAME(element_ref1, element_ref2 [, element_ref3, ...])
+ *
+ * <p>Example:
+ * <pre>
+ * MATCH (a:Person)-[:KNOWS]->(b), (b)-[:KNOWS]->(c)
+ * WHERE SAME(a, c)
+ * RETURN a.name, b.name;
+ * </pre>
+ *
+ * <p>This returns triangular paths where the start and end vertices are the same element.
+ *
+ * <p>Implements ISO/IEC 39075:2024 Section 19.12 (SAME predicate).
+ */
+public class SqlSameCall extends SqlCall {
+
+    private final List<SqlNode> operands;
+
+    /**
+     * Creates a SqlSameCall.
+     *
+     * @param pos Parser position
+     * @param operands List of element reference expressions (must be 2 or more)
+     */
+    public SqlSameCall(SqlParserPos pos, List<SqlNode> operands) {
+        super(pos);
+        // Create a mutable copy to allow setOperand to work
+        this.operands = new ArrayList<>(Objects.requireNonNull(operands, "operands"));
+
+        // ISO-GQL requires at least 2 arguments
+        if (operands.size() < 2) {
+            throw new IllegalArgumentException(
+                "SAME predicate requires at least 2 arguments, got: " + operands.size());
+        }
+    }
+
+    @Override
+    public SqlOperator getOperator() {
+        return SqlSameOperator.INSTANCE;
+    }
+
+    @Override
+    public List<SqlNode> getOperandList() {
+        return operands;
+    }
+
+    @Override
+    public void validate(SqlValidator validator, SqlValidatorScope scope) {
+        // Validation will be handled by GQLSameValidator
+        // This just validates the syntax is correct
+        for (SqlNode operand : operands) {
+            operand.validate(validator, scope);
+        }
+    }
+
+    @Override
+    public void setOperand(int i, SqlNode operand) {
+        if (i < 0 || i >= operands.size()) {
+            throw new IllegalArgumentException("Invalid operand index: " + i);
+        }
+        operands.set(i, operand);
+    }
+
+    @Override
+    public void unparse(SqlWriter writer, int leftPrec, int rightPrec) {
+        writer.print("SAME");
+        final SqlWriter.Frame frame =
+            writer.startList(SqlWriter.FrameTypeEnum.FUN_CALL, "(", ")");
+
+        for (int i = 0; i < operands.size(); i++) {
+            if (i > 0) {
+                writer.sep(",");
+            }
+            operands.get(i).unparse(writer, 0, 0);
+        }
+
+        writer.endList(frame);
+    }
+
+    /**
+     * Returns the number of operands (element references) in this SAME call.
+     */
+    public int getOperandCount() {
+        return operands.size();
+    }
+
+    /**
+     * Returns the operand at the specified index.
+     */
+    public SqlNode getOperand(int index) {
+        return operands.get(index);
+    }
+}

geaflow/geaflow-dsl/geaflow-dsl-parser/src/test/java/org/apache/geaflow/dsl/IsoGqlSyntaxTest.java

@@ -31,4 +31,11 @@ public void testIsoGQLMatch() throws Exception {
         String unParseStmts = parseStmtsAndUnParse(parseStmtsAndUnParse(unParseSql));
         Assert.assertEquals(unParseStmts, unParseSql);
     }
+
+    @Test
+    public void testIsoGQLSamePredicate() throws Exception {
+        String unParseSql = parseSqlAndUnParse("IsoGQLSame.sql");
+        String unParseStmts = parseStmtsAndUnParse(parseStmtsAndUnParse(unParseSql));
+        Assert.assertEquals(unParseStmts, unParseSql);
+    }
 }

geaflow/geaflow-dsl/geaflow-dsl-parser/src/test/resources/IsoGQLSame.sql

@@ -0,0 +1,23 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+MATCH (a:person)-[:know]->(b:person), (b)-[:know]->(c:person) WHERE SAME(a, c) RETURN a.name, b.name;
+MATCH (a:person)-[:know]->(b:person), (c:person)-[:know]->(d:person) WHERE SAME(a, c) RETURN a.id, b.id, c.id, d.id;
+MATCH (a:person {id: 1})-[e1:know]->(b:person), (c:person)-[e2:know]->(d:person) WHERE SAME(a, b, c) RETURN a.id, b.id;
+MATCH (a:person)-[e1:know]->(b:person)-[e2:know]->(c:person) WHERE SAME(a, c) RETURN a.name, b.name, c.name;

geaflow/geaflow-dsl/geaflow-dsl-plan/src/main/java/org/apache/geaflow/dsl/schema/function/BuildInSqlOperatorTable.java

@@ -24,6 +24,7 @@
 import org.apache.calcite.sql.SqlOperator;
 import org.apache.calcite.sql.fun.SqlStdOperatorTable;
 import org.apache.calcite.sql.util.ReflectiveSqlOperatorTable;
+import org.apache.geaflow.dsl.operator.SqlSameOperator;
 
 public class BuildInSqlOperatorTable extends ReflectiveSqlOperatorTable {
 
@@ -173,7 +174,9 @@ public class BuildInSqlOperatorTable extends ReflectiveSqlOperatorTable {
         SqlStdOperatorTable.CUME_DIST,
         SqlStdOperatorTable.ROW_NUMBER,
         SqlStdOperatorTable.LAG,
-        SqlStdOperatorTable.LEAD
+        SqlStdOperatorTable.LEAD,
+        // ISO-GQL SAME predicate
+        SqlSameOperator.INSTANCE
     };
 
     public BuildInSqlOperatorTable() {

geaflow/geaflow-dsl/geaflow-dsl-plan/src/main/java/org/apache/geaflow/dsl/schema/function/GeaFlowBuiltinFunctions.java

@@ -23,9 +23,12 @@
 import java.math.RoundingMode;
 import java.sql.Timestamp;
 import java.util.Calendar;
+import java.util.Objects;
 import java.util.Random;
 import org.apache.commons.lang3.time.DateUtils;
 import org.apache.geaflow.common.binary.BinaryString;
+import org.apache.geaflow.dsl.common.data.RowEdge;
+import org.apache.geaflow.dsl.common.data.RowVertex;
 
 public final class GeaFlowBuiltinFunctions {
 
@@ -1428,6 +1431,91 @@ public static Boolean equal(Object a, Object b) {
         return a.equals(b);
     }
 
+    /**
+     * ISO-GQL SAME predicate function for vertices.
+     * Checks if two vertices refer to the same element by comparing their IDs.
+     *
+     * @param a first vertex
+     * @param b second vertex
+     * @return true if vertices have the same ID, false otherwise, null if either is null
+     */
+    public static Boolean same(RowVertex a, RowVertex b) {
+        if (a == null || b == null) {
+            return null;
+        }
+        return Objects.equals(a.getId(), b.getId());
+    }
+
+    /**
+     * ISO-GQL SAME predicate function for edges.
+     * Checks if two edges refer to the same element by comparing their source and target IDs.
+     *
+     * @param a first edge
+     * @param b second edge
+     * @return true if edges have the same source and target IDs, false otherwise, null if either is null
+     */
+    public static Boolean same(RowEdge a, RowEdge b) {
+        if (a == null || b == null) {
+            return null;
+        }
+        return Objects.equals(a.getSrcId(), b.getSrcId())
+            && Objects.equals(a.getTargetId(), b.getTargetId());
+    }
+
+    /**
+     * ISO-GQL SAME predicate function (fallback for mixed or unknown types).
+     * Checks if two graph elements refer to the same element by comparing their identities.
+     * For vertices, compares vertex IDs.
+     * For edges, compares both source and target IDs.
+     *
+     * @param a first element (vertex or edge)
+     * @param b second element (vertex or edge)
+     * @return true if elements have the same identity, false otherwise, null if either is null
+     */
+    public static Boolean same(Object a, Object b) {
+        if (a == null || b == null) {
+            return null;
+        }
+        // Delegate to type-specific overloads when possible
+        if (a instanceof RowVertex && b instanceof RowVertex) {
+            return same((RowVertex) a, (RowVertex) b);
+        }
+        if (a instanceof RowEdge && b instanceof RowEdge) {
+            return same((RowEdge) a, (RowEdge) b);
+        }
+        // Different types cannot be the same
+        return false;
+    }
+
+    /**
+     * ISO-GQL SAME predicate function for multiple elements.
+     * Checks if all elements refer to the same graph element.
+     * Returns true only if all elements are identical (same type and same identity).
+     *
+     * @param elements array of elements to compare (minimum 2 required)
+     * @return true if all elements have the same identity, false otherwise, null if any is null
+     */
+    public static Boolean same(Object... elements) {
+        if (elements == null || elements.length < 2) {
+            return null;
+        }
+        // Check for any null elements
+        for (Object e : elements) {
+            if (e == null) {
+                return null;
+            }
+        }
+        // Compare all elements with the first one
+        Object first = elements[0];
+        for (int i = 1; i < elements.length; i++) {
+            Boolean result = same(first, elements[i]);
+            if (result == null || !result) {
+                return result;
+            }
+        }
+        return true;
+    }
+
     public static Boolean unequal(Long a, Long b) {
         if (a == null || b == null) {
             return null;