Apache AGE Python驱动中构建Cypher与执行预处理语句的差异及疑问

我无法理解为何会执行两个查询：先是执行预处理语句，随后又使用buildCypher函数。相关代码如下：

def execCypher(conn:ext.connection, graphName:str, cypherStmt:str, cols:list=None, params:tuple=None) -> ext.cursor :
    if conn == None or conn.closed:
        raise _EXCEPTION_NoConnection

    cursor = conn.cursor()
    #clean up the string for modification
    cypherStmt = cypherStmt.replace("\n", "")
    cypherStmt = cypherStmt.replace("\t", "")
    cypher = str(cursor.mogrify(cypherStmt, params))
    cypher = cypher[2:len(cypher)-1]

    preparedStmt = "SELECT * FROM age_prepare_cypher({graphName},{cypherStmt})"
    
    cursor = conn.cursor()
    try:
        cursor.execute(sql.SQL(preparedStmt).format(graphName=sql.Literal(graphName),cypherStmt=sql.Literal(cypher)))
    except SyntaxError as cause:
        conn.rollback()
        raise cause
    except Exception as cause:
        conn.rollback()
        raise SqlExecutionError("Execution ERR[" + str(cause) +"](" + preparedStmt +")", cause)

    stmt = buildCypher(graphName, cypher, cols)

    cursor = conn.cursor()
    try:
        cursor.execute(stmt)
        return cursor
    except SyntaxError as cause:
        conn.rollback()
        raise cause
    except Exception as cause:
        conn.rollback()
        raise SqlExecutionError("Execution ERR[" + str(cause) +"](" + stmt +")", cause)

两个步骤的核心区别 #

1. age_prepare_cypher 预处理查询 #

• 核心功能：仅做Cypher语法校验与预处理，不会执行实际查询，也不返回业务数据。它的作用是验证输入的Cypher语句在指定图中的语法合法性，提前捕获语法错误。
• 执行逻辑：调用AGE提供的age_prepare_cypher函数，传入图名和处理后的Cypher语句，完成语法校验。

2. buildCypher生成的查询 #

• 核心功能：真正执行Cypher查询并返回结果。buildCypher会把原始Cypher语句包装成PostgreSQL可识别的SQL格式（例如SELECT * FROM cypher('graph_name', $$MATCH (n) RETURN n$$) AS (n agtype)），让PostgreSQL能通过AGE扩展执行该图查询。

为何需要执行两次查询？ #

• 提前排错，减少无效开销：在实际执行查询前先做语法校验，能快速抛出语法错误，避免后续执行阶段才发现问题，减少不必要的数据库执行开销。
• 职责拆分，逻辑更清晰：将语法校验和实际执行拆分为两个步骤，让代码职责更明确——预处理负责校验合法性，buildCypher负责生成可执行语句并执行。
• 兼容AGE与PostgreSQL的交互逻辑：AGE作为PostgreSQL的扩展，最终查询必须转换为PostgreSQL支持的SQL结构，预处理步骤确保转换前的Cypher语句本身是合法的，避免转换后执行时出现无效语句。

内容的提问来源于stack exchange，提问作者Fahad Zaheer