Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/variable-definition/active-set-variable/ Documentation version: v5.3.2 # Active set variables An active set variable is used to store the set of nodes to be processed during procedure execution. The active set variable can be updated so that subsequent operations are performed only on these nodes. Active set variables are only applicable to [temporary graphs](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/graph-projection/create/). ## Prerequisites A temporary graph is created. For more information, see [CREATE TEMPORARY GRAPH](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/graph-projection/create/). ## Syntax diagramsource active_set_variable_definition ```` active_set_variable_definition ::= 'VALUE' active_set_variable '::'? 'ACTIVE_SET' ```` ## Parameters ### `active_set_variable` The name of the active set variable. `active_set_variable` can be a regular identifier or a delimited identifier enclosed with backticks (```). For more information about identifiers, see [Rules for naming identifiers](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/keywords-identifiers/#rules_for_naming_identifiers). ## Usage After defining an active set variable, you can assign values to it. The active set variable cannot be directly returned using the `RETURN` statement. It must be traversed in conjunction with a [match compute statement](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/match-compute/) to access the nodes it contains. You can also update the active set variable in subsequent operations to continuously track the nodes to be processed. Common operations include: - Assignment: Assign a node or a set of nodes to the active set variable. Syntax: ```` 'SET' active_set_variable '=' '[' element_list ']' ```` `element_list` is a list of unique identifiers for nodes in the temporary graph. For how to obtain a node's unique identifier, see [element_id()](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/graph/#element_id). For more information about the assignment operation, see [Variable manipulation](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/set/). - Traversal: Perform subsequent operations only on the nodes in the active set variable. Syntax: ```` 'WHERE' n 'IN' active_set_variable ```` This means that only the nodes in `active_set_variable` are processed. For more information about the `WHERE` clause, see [graph_pattern](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/match-compute/#graph_pattern). - Update: Modify the set of nodes in the active set variable in two ways: - Overwrite update: Replace the active set variable with a new set of nodes. Syntax: ```` 'FINALLY' '{' 'SET' active_set_variable '=' d '}' ```` - Incremental update: Merge the active set variable with a new set of nodes. Syntax: ```` 'FINALLY' '{' 'SET' active_set_variable '|=' d '}' ```` - Decremental update: Remove a set of nodes from the active set variable. Syntax: ```` 'FINALLY' '{' 'SET' active_set_variable '-=' d '}' ```` For more information about the `FINALLY` clause, see [active_set_operation](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/match-compute/#active_set_operation). ## Examples The following examples are based on the temporary graph `#movie_temporary_graph` created in [CREATE TEMPORARY GRAPH](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/graph-projection/create/). ### Assign an active set variable with given node unique identifiers The following example uses two given node unique identifiers (`288370005093646336` and `288370005093646337`) to demonstrate how to use the active set variable. ```` """ USE #movie_temporary_graph { // Define the active set variable VALUE active_set ACTIVE_SET // Define an aggregate value variable to aggregate the return values of subsequent statements VALUE list_id ListAgg // Assign the two node unique identifiers to `active_set` SET active_set = [288370005093646336, 288370005093646337] // For each node in the active set, match its neighboring nodes // and add the ID of the matched node to the list_id list MATCH (v) - (t) WHERE v IN active_set PER NODE(v) { SET @list_id += v.id } // Update the active set to the neighboring nodes FINALLY { SET active_set = t } // Match all nodes in the updated active set MATCH (n) WHERE n IN active_set PER NODE (n) { // Add the ID of the matched node to the list_id list SET @list_id += n.id } // Return all node IDs in the list_id list as ids RETURN @list_id AS ids } """ ```` Return: ```` +----------------------+ | ids | +----------------------+ | [2139,74614,557,187] | +----------------------+ ```` ### Assign an active set variable with dynamically obtained node unique identifiers The following example demonstrates how to dynamically obtain node unique identifiers, assign them to the active set variable, and then use the active set variable. ```` """ USE #movie_temporary_graph { // Define the active set variable VALUE active_set ACTIVE_SET // Define an aggregate value variable VALUE list_id ListAgg // Match nodes with the name "Tom Hanks" or "William Holden" MATCH (a) WHERE a.name = "Tom Hanks" OR a.name = "William Holden" PER NODE (a) { // Add the element_id of the matched node to the list_id list SET @list_id += element_id(a) } // Assign the list_id list to the active set variable active_set SET active_set = @list_id // Clear the list_id list for subsequent use SET @list_id.clear() // For each node in the active set, match its neighboring nodes MATCH (v) - (t) WHERE v IN active_set PER NODE(v) { // Add the ID of the matched node to the list_id list SET @list_id += v.id } // Update the active set to the matched neighboring nodes FINALLY { SET active_set = t } // Match all nodes in the updated active set MATCH (n) WHERE n IN active_set PER NODE(n) { // Add the ID of the matched node to the list_id list SET @list_id += n.id } // Return all node IDs in the list_id list as ids RETURN @list_id AS ids } """ ```` Return: ```` +-------------------+ | ids | +-------------------+ | [31,8252,599,497] | +-------------------+ ```` ### Update an active set variable incrementally and decrementally ```` """ USE #movie_temporary_graph { VALUE active_set ACTIVE_SET VALUE ids ListAgg MATCH (s1@User) WHERE s1.id in [1,3,4,5] FINALLY { // Incrementally update the active set variable by adding nodes with IDs 1, 3, 4, and 5 to it SET active_set |= s1 } MATCH (s2@User) WHERE s2.id in [1,3] FINALLY { // Decrementally update the active set variable by removing nodes with IDs 1 and 3 from it SET active_set -= s2 } MATCH (s) WHERE s IN active_set PER NODE (s) { SET @ids += s.id } FOR r IN @ids RETURN r } """ ```` Return: ```` +---+ | r | +---+ | 4 | | 5 | +---+ ````