使用 CALL 调用命名过程¶

本文介绍如何使用CALL语句调用命名过程。

内置命名过程和用户定义过程（User-Defined Procedure，简称 UDP）使用相同的CALL语法。两者的区别在于过程的提供和管理方式，不在于调用方式。有关内置命名过程的信息，请参见内置命名过程。

调用命名过程时，需指定过程名称及参数值（若有）。要查看可用的命名过程及其输入参数和返回字段，请参见 SHOW PROCEDURES。

此外，必须在CALL语句后加上最终输出语句来指定返回值，否则会报错。

有关如何调用内联过程，请参见使用 CALL 调用内联过程。

Note

对非默认 Schema 或其中的对象执行操作时，用户既要通过隐式访问规则或显式USAGE授权获得该 Schema 的访问权，也要具备目标操作所需的权限。Schema 访问校验和目标操作所需的权限校验相互独立，满足其中一项不能替代另一项。Schema 访问控制不适用于临时图、内置 Procedure 和内置 Function。更多信息，请参见 Schema 访问控制。

前提条件¶

若要调用 UDP，必须是 UDP 的所有者，或具备在 UDP 上执行EXECUTE操作的权限，或具备在当前 Schema 执行EXECUTE ANY PROCEDURE操作的权限。更多信息，请参见角色与权限。

语法 ¶

语法图源码

call_procedure_statement

call_procedure_statement ::=
    'OPTIONAL'? 'CALL' procedure_name '(' argument_list? ')' yield_clause?

参数¶

`OPTIONAL`¶

当使用关键字OPTIONAL时，即使命名过程没有找到匹配的结果，查询仍会返回null作为结果，并返回其他查询结果。否则，如果命名过程没有找到匹配的结果，查询将不返回结果。

`procedure_name`¶

要调用的命名过程的名称。有关可被调用的命名过程的信息，请参见 SHOW PROCEDURES。

`argument_list`¶

传给命名过程的参数值列表。

注意，字符串类型的参数值必须用一组单引号(')或双引号(")包围。例如，'arg1'或"arg1"。

有关命名过程接受的参数信息，请参见 SHOW PROCEDURES。

`yield_clause`¶

YIELD子句用于指定哪些过程输出列可以被后续语句引用，并可以使用AS重命名这些列。主要在需要限制后续语句可见的过程输出列，或者需要通过重命名避免列名冲突时使用。如果只需要选择最终输出列，可以省略YIELD，直接使用RETURN。

更多信息，请参见 YIELD 子句和最终输出语句。

常用用法¶

本节及更多示例中涉及图数据的查询基于示例数据集。

以下用法同时适用于内置命名过程和 UDP。示例主要使用内置命名过程，以便直接运行。可以按照以下常见形式调用命名过程，并对过程返回的数据进行选择、筛选和处理。方括号中的内容为可选项：

'''
CALL <procedure_name>(<arguments>)
[YIELD <column> [AS <alias>], ...]
[FILTER <condition>]
RETURN <expression>, ...
[GROUP BY <grouping_element>]
[ORDER BY <expression>]
[LIMIT <count>]
'''

上述形式不是另一套CALL语法。第一行遵循语法中定义的call_procedure_statement；其余各行是在线性查询中处理过程结果的后续语句。

YIELD控制进入后续查询的过程输出列，RETURN控制最终返回给用户的列。仅在需要裁剪或重命名中间列时使用YIELD；如果不存在列名冲突，并且只需要选择最终输出列，可以直接使用RETURN。如果不需要过程的返回值，请使用FINISH语句结束查询。

Note

可以使用RETURN *返回所有可用列，但不支持YIELD *。
YIELD子句仅接受过程返回的列名及其别名。请在RETURN语句中使用表达式、函数和聚合。
如果过程返回列与前序语句中的变量同名，必须使用YIELD <column> AS <alias>为返回列指定不同的别名。

返回全部或指定列¶

不需要处理中间列时，可以省略YIELD子句，直接使用RETURN语句选择最终输出列。例如，以下语句仅返回图名称、图所在的 Schema 和图所有者：

'''
CALL show_graphs()
RETURN name, `schema`, owner
'''

要返回所有列，可以使用：

CALL show_graphs() RETURN *

由于schema是保留关键字，必须使用反引号（`）包围，以将其表示为列名。

筛选和处理过程结果¶

可以直接根据过程返回列的值筛选数据行：

'''
CALL show_graphs()
FILTER name = "ldbc"
RETURN name, `schema`
'''

如果需要限制后续语句可引用的过程输出列，或者需要重命名返回列，可以在FILTER语句之前使用YIELD子句：

'''
CALL show_graphs()
YIELD name AS graph_name, `schema` AS schema_path
FILTER graph_name = "ldbc"
RETURN graph_name, schema_path
'''

过程返回的数据还可以参与计算、聚合、排序和分页。例如，以下语句返回最多 20 个在线服务：

'''
CALL show_services()
FILTER status = "ONLINE"
RETURN service_type, host, port
ORDER BY service_type, host
LIMIT 20
'''

以下语句计算 Leader 分片数：

'''
CALL show_peers()
FILTER state = "LEADER"
RETURN count(partition_id) AS leader_count
GROUP BY ()
'''

将过程结果传递给其他过程¶

过程的返回列可以作为后续过程的入参。例如，以下语句查找并终止查询文本中包含指定唯一标识的查询：

'''
CALL show_queries()
YIELD query_id AS qid, `query` AS query_text
FILTER query_text LIKE "%<unique_text_in_target_query>%"
CALL kill_query(qid)
YIELD query_id AS killed_query_id
RETURN killed_query_id
'''

Warning

后一个过程会对前面查询产生的每一行执行一次。例如，FILTER筛选出 3 个查询时，kill_query(qid)会执行 3 次，并终止这 3 个查询。

执行终止、写入或控制操作前，建议先移除后续的过程调用，仅返回筛选结果，确认其中只包含目标对象：

'''
CALL show_queries()
YIELD query_id AS qid, `query` AS query_text
FILTER query_text LIKE "%<unique_text_in_target_query>%"
RETURN qid, query_text
'''

确认结果后，再执行包含CALL kill_query(qid)的语句。这类操作可能还需要额外权限。

使用前序变量作为过程入参¶

CALL语句可以引用前序语句定义的变量。过程会针对前序绑定表中的每一行执行一次。例如：

'''
USE movie
MATCH (p:Person)
CALL version(p.id > 10)
RETURN p.id, version
LIMIT 5
'''

该用法也适用于需要根据每行中的点、边或 ID 执行的图算法过程。如果需要在过程未产生结果时仍保留对应的输入行，请使用OPTIONAL CALL。此时，过程返回列的值为null。更多信息，请参见使用 OPTIONAL CALL 调用命名过程。

不使用过程返回值¶

如果仅需要执行管理、写入或控制类过程，不需要返回其结果，可以使用FINISH语句结束查询。例如：

CALL cancel_balance_data() FINISH

在标量子查询中使用过程结果¶

可以在VALUE标量子查询中调用过程，并将返回值用于表达式、条件判断或后续计算。标量子查询必须产生单行单列结果。例如：

'''
LET current_version = VALUE {
  CALL version()
  RETURN version
  LIMIT 1
}
RETURN current_version
'''

更多示例 ¶

省略可选入参¶

过程show_graphs()接受可选入参graph_type_name，用于按图类型筛选结果。省略该入参时，过程返回当前 Schema 中的所有图和临时图。

CALL show_graphs() RETURN *

在上述语句中，过程show_graphs()调用时不传入参数值，RETURN *语句用于返回所有列。

返回：

+-------+------------+-------+-------+-----------------+
| extra | graph_type | name  | owner | schema          |
+-------+------------+-------+-------+-----------------+
|       | movie_type | movie | root  | /default_schema |
+-------+------------+-------+-------+-----------------+

调用入参为字符串的命名过程¶

过程stats()用于提交计算指定图的统计信息的作业。它接受一个输入参数graph_name并返回一个输出参数job_id。

CALL stats("movie") RETURN *

在上述语句中，过程stats()调用时传入字符串类型的参数值"movie"。

返回：

+--------+
| job_id |
+--------+
| 1      |
+--------+

调用入参为整数的命名过程¶

过程show_job()用于返回作业的详细信息。它接受一个输入参数job_id并返回作业的详细信息。

CALL show_job(1) RETURN *

在上述语句中，过程show_job()调用时传入整数类型的参数值1。

返回：

+-----------------------------+-----------------------------+------------+----------------+---------+
| dispatch_time               | end_time                    | service_id | state          | task_id |
+-----------------------------+-----------------------------+------------+----------------+---------+
| 2026-09-08T07:56:21.984000Z | 2026-09-08T07:56:22.004000Z | 2          | TASK_SUCCEEDED | 1       |
+-----------------------------+-----------------------------+------------+----------------+---------+

调用入参为布尔值的命名过程¶

过程version()用于显示悦数图数据库开发版的版本信息。它接受一个输入参数verbose并返回一个输出参数version。参数verbose为布尔类型，默认值为false。

CALL version(true) RETURN *

在上述语句中，过程version()调用时传入布尔类型的参数值true，也即以详细模式显示悦数图数据库开发版的版本信息。

返回：

+-------------------------------------------------------+
| version                                               |
+-------------------------------------------------------+
| 5.3.2, Git: 37XX278, Build Time: XXX XX 2025 XX:XX:XX |
+-------------------------------------------------------+

使用`YIELD`后计算返回值¶

CALL version(true) YIELD version RETURN substring(version, 1,5) AS v

在上述语句中，YIELD子句用于选择列version。RETURN语句用于返回列version的前5个字符，并将其命名v。

返回：

+-------+
| v     |
+-------+
| 5.3.2 |
+-------+

使用 OPTIONAL CALL 调用命名过程 ¶

'''
// 创建一个名为 gt_for_optional 图类型
CREATE GRAPH TYPE gt_for_optional AS {} 
'''

'''
// 使用 OPTIONAL CALL 调用 show_graphs
CALL show_graph_types() 
YIELD graph_type AS gt 
FILTER WHERE gt = "gt_for_optional"    
OPTIONAL CALL show_graphs(gt)   
YIELD `name` as graphName  
RETURN *
'''

上述语句使用关键字OPTIONAL调用命名过程show_graphs()获取基于图类型gt_for_optional创建的图。因为未基于gt_for_optional创建图，所以查询返回null，并返回其他查询结果。

返回：

+-----------+-----------------+
| graphName | gt              |
+-----------+-----------------+
| null      | gt_for_optional |
+-----------+-----------------+

调用入参为空的 UDP¶

'''
// 创建一个名为 test1 的 UDP
CREATE PROCEDURE IF NOT EXISTS test1() RETURNS ret INT AS { RETURN 1 }
'''

'''
// 调用 test1
CALL test1() RETURN ret
'''

上述语句调用了名为 test1 的 UDP。有关如何创建 UDP，请参见 CREATE PROCEDURE。

调用入参为点类型的 UDP¶

'''
// 创建一个入参为点类型 UDP
CREATE OR REPLACE PROCEDURE set_proc_param_node (a NODE) RETURNS r INT  {
  RETURN 1
}
'''

'''
// 调用 UDP
USE movie {
  MATCH (v:Movie) LIMIT 1
  RETURN v
  NEXT
  CALL set_proc_param_node(v)
  RETURN r
}
'''

返回：

+---+
| r |
+---+
| 1 |
+---+

调用入参为边类型的 UDP¶

'''
// 创建一个入参为边类型 UDP
CREATE OR REPLACE PROCEDURE set_proc_param_edge(e EDGE) RETURNS r INT  {
  MATCH ()-[e]->(f:Genre) RETURN COUNT(f) AS r
}
'''

'''
// 调用 UDP
USE movie
MATCH (v:Movie{id: 100})-[e:WithGenre]->()
CALL set_proc_param_edge(e)
RETURN r
'''

返回：

+---+
| r |
+---+
| 1 |
| 1 |
| 1 |
| 1 |
| 1 |
| 1 |
| 1 |
| 1 |
| 1 |
+---+

调用入参为表类型的 UDP¶

'''
// 创建一个入参为表类型 UDP
CREATE OR REPLACE PROCEDURE set_proc_param_table(a TABLE) RETURNS r INT  {
  RETURN size(a) AS r
}
'''

'''
// 调用 UDP
TABLE t {id, name} = (1, "a"), (2, "b"), (3, "c")
CALL set_proc_param_table(t)
RETURN r
'''

返回：

+---+
| r |
+---+
| 3 |
+---+