Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/call/call-procedure/
Documentation version: v5.3.2

# CALL named procedures

Use the `CALL` statement to run a [named procedure](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/procedures/create/).

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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/procedures/built-in/).

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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/show-procedures/).

In addition, you must append a [primitive result](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/call/call-inline-procedure/).

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](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/authorization/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](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/authorization/).

## 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/clauses/yield/) clause and the [Primitive result](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/primitive-result/) statement.

## Common usage

Queries involving graph data in this section and [More examples](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/call/call-procedure/#more_examples) are based on the [example dataset](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/call/call-procedure/#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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/call/call-procedure/#optional_call_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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/procedures/create/).

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

````