Procedures overview¶

Procedures in GQL package computation for reuse. The following sections cover their categories and usage.

Definition¶

A procedure in GQL describes a computation that uses input arguments to produce an outcome and optionally modify data objects. The primary use of procedures is to encapsulate complex logic, streamline the query process, and facilitate the reuse of common computations, thereby enhancing operational efficiency.

Procedure body¶

Each procedure is described by a procedure body, which specifies the processing logic of the procedure. The syntax of the procedure body is as follows:

diagramsource

procedure_body

procedure_body ::=
    (variable_definition+)? statement_block+

As indicated in the syntax, a procedure body consists of zero or more variable definitions followed by one or more statement blocks that are sequentially executed. Only the output of the final statement block is returned as the result of the procedure body.

Note the following rules regarding statements in the procedure body:

Only the final statement in the procedure body can end with the RETURN statement.
The RETURN statement can appear inside a non-final statement only if its result is consumed by the subsequent statements via the keyword NEXT.
To terminate a statement early without returning any result, use FINISH.

The parameters of the procedure body are explained as follows:

`variable_definition`¶

The definition of a variable that is used within the procedure. The variable can be of the following types:

When used in a procedure body, node-attached aggregator value variables and active set variables can only operate on the single temporary graph on which the procedure is called.

For more information, see Variables.

`statement_block`¶

A block of one or more statements that are executed in the order in which they are written within the block. The statements can be of the following types:

Data definition statements
Data manipulation statements
Data query statements
Match compute statements
Control flow statements
- WHILE
- IF
- BREAK
- CONTINUE
Variable manipulation statements
Import and export statements
- IMPORT
- EXPORT
Logging statements

When a match compute statement is used in a procedure body, it can only operate on the single temporary graph on which the procedure is called.

When a WHILE statement is used in a procedure body, note the following rules:

A WHILE loop must not produce any result. In other words, it must not contain any RETURN statement.
To pass values out of a WHILE loop, you can update variables and break the loop with BREAK.
To produce a final result, you can add a RETURN statement after the WHILE loop.

When an IF statement is used in a procedure body, note the following rules:

If an IF block is the last statement in the procedure body, its branches can use RETURN statements to produce results.
If an IF block is not the last statement in the procedure body, its branches must not end with RETURN statements. In this case, you can update variables within the branches.

For more information, see Statement block.

Categories¶

Based on whether data or data schema is modified, procedures can be classified into three categories:

Procedures that modify data schemas: Modify data schemas. For example, create a graph, delete a graph, create a label, delete a label, and so on.
Procedures that modify data: Modify data. For example, insert data, delete data, update data, and so on.
Retrieval procedures: Do not modify data, only return results. For example, query data, compute data, and so on.

In GQL, procedures are divided into two types based on their definition and usage: named procedures and inline procedures.

Named procedures¶

Named procedures are procedures whose procedure bodies are defined in the GQL catalog and can be referenced directly by their names from within a query. They are suitable for general and reusable queries.

NebulaGraph Database Developer Edition provides a set of built-in named procedures, and also allows you to define your own named procedures.

Built-in procedures¶

To view the complete list of built-in procedures, you can run the SHOW PROCEDURES statement. For more information, see SHOW PROCEDURES. For more information about built-in procedures, their corresponding SHOW, KILL, and other commands, and how to call them, see Built-in named procedures.

User-defined procedures (UDPs)¶

You can create UDPs in the GQL language. For more information, see CREATE PROCEDURE to learn how to create UDPs.

Inline procedures¶

Inline procedures are procedures whose procedure bodies are defined and used directly within GQL queries. They do not need to be predefined in the catalog like named procedures. They are suitable for temporary or specific queries.

Currently, the procedure body of an inline procedure cannot contain any DDL or DML statements.

Usage¶

The clause CALL is used to invoke a procedure.

Named procedures: Named procedures are called by referencing the procedure name. For example:
```
'''
CALL show_graphs() 
RETURN *
'''
```
For more information, see CALL named procedures.

Inline procedures: Inline procedures are defined and used directly within query statements. For example:
```
'''
LET a = 1, b = 2 
CALL { 
  LET c = 3  
  RETURN c + 1 AS d } 
RETURN d
'''
```
For more information, see CALL inline procedures.