Configure parameters¶

Each parameter consists of a name and a value. The name must start with a dollar sign ($), and the value must be a literal of one of the following data types: Numeric, String, Boolean, Temporal, List, or Record. The data type of the parameter value is inferred from the literal itself. For more information, see Literals.

GQL allows you to configure session parameters and query parameters.

Session parameters are set in the session context and are available to all statements in the current session. For more information about how to set session parameters, see SESSION SET.
Query parameters are set in the query context and are available only to the current query. For more information about how to set query parameters, see Set query parameters.

In case a query parameter and a session parameter have the same name, the query parameter takes precedence.

Set query parameters¶

You can set query parameters by using the PARAMETERS keyword in a statement, as shown below:

PARAMETERS $i=20 USE movie MATCH (n:Person WHERE n.id = $i) RETURN n.id

Return:

+------+
| n.id |
+------+
| 20   |
+------+

You can also set multiple query parameters in a single statement:

PARAMETERS $x=1, $y=2 USE movie MATCH (n:Person WHERE n.id = $x OR n.id = $y) RETURN n.id

The PARAMETERS keyword can be omitted if you use the shorthand form:

$i=20 USE movie MATCH (n:Person WHERE n.id = $i) RETURN n.id

Query parameter values can also use composite data types such as lists:

PARAMETERS $ids = [1, 2, 3] USE movie MATCH (n:Person WHERE n.id IN $ids) RETURN n.id

Query parameters can be used together with query hints in a single query to adjust both optimizer behavior and input values:

/*+ SET_VAR(query_concurrency = 1) */
PARAMETERS $i=1
USE movie MATCH (n:Person WHERE n.id = $i) RETURN n.name

Use session parameters¶

After a session parameter is set, it can be used directly in any statement in the current session. You can also set multiple parameters at the same time, and parameter values can use composite types such as lists and records:

SESSION SET VALUE $param = 100

SESSION SET VALUE $i_1 = 10, $i_2 = 20

SESSION SET VALUE $ids = [1, 2, 3]

SESSION SET VALUE $config = RECORD {a: 1, b: true, c: "test"}

After setting a parameter, you can reference it in a query, as shown below:

USE movie MATCH (n@Actor WHERE n.id = $param) RETURN n.name AS name

Return:

+----------------+
| name           |
+----------------+
| Scott Speedman |
+----------------+

To show the parameters set in the session, see SHOW PARAMETERS.

View and delete parameters¶

To view all parameters in the current session, see SHOW PARAMETERS.
To view the value of a specific parameter, use SHOW PARAMETER $parameter_name.
To remove a specific session parameter, use SESSION RESET $parameter_name.
To remove all session parameters, use SESSION RESET ALL PARAMETERS.