CALL named procedures

Use the CALL statement to run a named procedure.

Built-in named procedures and user-defined procedures (UDPs) use the same CALL syntax. They differ in how they are provided and managed, not in how they are called. For information about built-in named procedures, see Built-in named procedures.

When calling a named procedure, specify the procedure name and its arguments, if any. To check the available named procedures and their input parameters and return fields, see SHOW PROCEDURES.

In addition, you must append a primitive result statement to the call statement to specify the return. Otherwise, an error is returned.

For information about how to call an inline procedure, see CALL inline procedures.

Note

An operation involving a non-default schema or an object in it requires access to the schema, either implicitly or through an explicit USAGE grant, as well as the privilege required for the operation. The schema access check and the privilege check for the requested operation are independent; satisfying one does not satisfy the other. Schema access control does not apply to temporary graphs or built-in procedures and functions. For more information, see Schema access control.

Prerequisites

To call a UDP, you must either be the owner of the UDP, be granted to perform the action EXECUTE on the UDP, or be granted to perform the action EXECUTE ANY PROCEDURE on the used schema. For more information, see Roles and privileges.

Syntax

diagramsource

call_procedure_statement

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

Parameters

OPTIONAL

When the keyword OPTIONAL is used, the query returns null as the result even if the named procedure does not find a match. The query continues to return data that may match other queries. Otherwise, the query returns no results if the named procedure does not find a match.

procedure_name

The name of the procedure to call. For information about available named procedures, see SHOW PROCEDURES.

argument_list

The list of arguments passed to the named procedure. Separate multiple arguments with commas (,).

Note that each string-typed argument must be enclosed with a pair of single quotes (') or double quotes ("). For example, 'arg1' or "arg1".

For information about the input parameters accepted by a named procedure, see SHOW PROCEDURES.

yield_clause

The YIELD clause specifies which procedure output columns can be referenced by subsequent statements. You can also use AS to rename these columns. Use YIELD when you need to limit the procedure output columns visible to subsequent statements or rename a column to avoid a name conflict. If you only need to select the final output columns, omit YIELD and use RETURN directly.

For more information, see the YIELD clause and the Primitive result statement.

Common usage

Queries involving graph data in this section and More examples are based on the example dataset.

The following usage applies to both built-in named procedures and UDPs. The examples primarily use built-in named procedures so that you can run them directly. Use the following common form to call a named procedure and select, filter, and process its results. The contents in square brackets are optional:

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

This form is not a separate CALL syntax. The first line follows the call_procedure_statement defined in Syntax. The remaining lines are subsequent statements that process the procedure results in a linear query.

YIELD controls which procedure output columns enter the remainder of the query, whereas RETURN controls the columns in the final result. Use YIELD only when you need to select or rename intermediate columns. If there is no name conflict and you only need to select the final output columns, use RETURN directly. If you do not need the procedure output, use FINISH to end the query.

Note

• RETURN * is supported for returning all available columns, but YIELD * is not supported.
• YIELD accepts only procedure output column names and their aliases. Use expressions, functions, and aggregations in RETURN.
• If a procedure output column has the same name as a variable from a preceding statement, you must assign the output column a different alias with YIELD <column> AS <alias>.

Return all or specific columns

If you do not need to process intermediate columns, omit YIELD and select the final output columns directly with RETURN. For example, the following statement returns only the graph name, its schema, and its owner:

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

To return all columns, use:

CALL show_graphs() RETURN *

Because schema is a reserved keyword, enclose it in backticks (`) to use it as a column name.

Filter and process procedure results

You can filter rows directly based on procedure output column values:

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

To limit the procedure output columns that subsequent statements can reference, or to rename an output column, add a YIELD clause before FILTER:

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

Procedure output can also be calculated, aggregated, sorted, and paginated. For example, the following statement returns up to 20 online services:

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

The following statement counts leader partitions:

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

Pass procedure results to another procedure

A procedure output column can be passed as an argument to a subsequent procedure. For example, the following statement finds and terminates queries whose query text contains a specified unique identifier:

'''
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

The subsequent procedure runs once for every row produced by the preceding query. For example, if FILTER selects three queries, kill_query(qid) runs three times and terminates all three queries.

Before performing a termination, write, or control operation, remove the subsequent procedure call and return only the filtered results to verify that they contain only the intended targets:

'''
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
'''

After verifying the results, run the statement that contains CALL kill_query(qid). These operations may also require additional privileges.

Use preceding variables as procedure arguments

A CALL statement can reference variables defined by preceding statements. The procedure runs once for each row in the preceding binding table. For example:

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

This form also applies to graph algorithm procedures that operate on a node, edge, or ID from each row. To preserve an input row when the procedure produces no result, use OPTIONAL CALL. In this case, the procedure output columns are set to null. For more information, see Optionally call a named procedure.

Ignore procedure output

If you only need to run an administration, write, or control procedure and do not need its output, end the query with FINISH. For example:

CALL cancel_balance_data() FINISH

Use a procedure result in a scalar subquery

You can call a procedure in a VALUE scalar subquery and use its value in an expression, condition, or subsequent calculation. The scalar subquery must produce a single-row, single-column result. For example:

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

More examples

Omit an optional argument

The procedure show_graphs() accepts an optional graph_type_name argument for filtering results by graph type. When this argument is omitted, the procedure returns all graphs and temporary graphs in the current schema.

CALL show_graphs() RETURN *

In the preceding statement, the procedure show_graphs() is called with no arguments. The RETURN * clause is used to return all columns.

Return:

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

Call a named procedure with a string argument

The procedure stats() submits a job to calculate the statistics of the specified graph. It takes one input parameter graph_name and returns one output parameter job_id.

CALL stats("movie") RETURN *

In the preceding statement, the procedure stats() is called with one string argument "movie".

Return:

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

Call a named procedure with an integer argument

The procedure show_job() displays the details of a job. It takes one input parameter job_id and returns the job details.

CALL show_job(1) RETURN *

In the preceding statement, the procedure show_job() is called with one integer argument 1.

Return:

+-----------------------------+-----------------------------+------------+----------------+---------+
| 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       |
+-----------------------------+-----------------------------+------------+----------------+---------+

Call a named procedure with a boolean argument

The procedure version() displays the version information of NebulaGraph Database Developer Edition. It takes one input parameter verbose and returns one output parameter version. The parameter verbose is of type boolean and defaults to false.

CALL version(true) RETURN *

In the preceding statement, the procedure version() is called with one boolean argument true, which means that the version information is displayed in verbose mode.

Return:

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

Calculate a return value after YIELD

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

In the preceding statement, the clause YIELD is used to select the column version. The statement RETURN is used to return the first 5 characters of the column version as v.

Return:

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

Optionally call a named procedure

'''
// Create a graph type named 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 *
'''

The preceding statement uses the keyword OPTIONAL to call the named procedure show_graphs() to retrieve graphs created based on the graph type gt_for_optional. Since no graph is created based on this type, null is returned, along with other query results.

Return:

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

Call a UDP with no arguments

'''
// Create a UDP
CREATE PROCEDURE IF NOT EXISTS test1() RETURNS ret INT AS { RETURN 1 }
'''

'''
// Call the UDP
CALL test1() RETURN ret
'''

The preceding statement calls the UDP test1. For more information about how to create UDPs, see CREATE PROCEDURE.

Call a UDP with a node type argument

'''
// Create a UDP with an input parameter of node type
CREATE OR REPLACE PROCEDURE set_proc_param_node (a NODE) RETURNS r INT  {
  RETURN 1
}
'''

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

Return:

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

Call a UDP with an edge type argument

'''
// Create a UDP with an input parameter of edge type
CREATE OR REPLACE PROCEDURE set_proc_param_edge(e EDGE) RETURNS r INT  {
  MATCH ()-[e]->(f:Genre) RETURN COUNT(f) AS r
}
'''

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

Return:

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

Call a UDP with a table type argument

'''
// Create a UDP with an input parameter of table type
CREATE OR REPLACE PROCEDURE set_proc_param_table(a TABLE) RETURNS r INT  {
  RETURN size(a) AS r
}
'''

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

Return:

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