Skip to content
Developer Edition runs on one host and does not require a product license file. Need multi-host deployment or performance testing at scale? Explore Enterprise Edition

USE clause

The USE clause declares a working graph in a query. A working graph is the graph or temporary graph where the query is executed.

If your query involves multiple graphs or temporary graphs, you can use the USE clause multiple times to declare different working graphs.

If your query mainly involves one graph or temporary graph, you can also set it for the current session by using the SESSION SET statement. You can then query it without declaring it as the working graph.

The working graph specified by the USE clause is only valid in the current query statement and overrides the graph or temporary graph that is set in the current session.

When the working graph is persistent, the current user must have USAGE on its parent schema in addition to the privileges required by the subsequent operations. A fully qualified graph path does not bypass this check. This requirement does not apply to temporary graphs. For more information, see Schema access control.

The following is a list of statements and commands that can be added after the USE clause:

Syntax

use_clause
USE schema_reference / graph_name temp_graph_name 

use_clause ::=
    'USE' ((schema_reference '/')? graph_name | temp_graph_name)

Parameters

schema_reference

The reference to the path of the schema. It specifies the schema path of the graph to be used as the working graph.

Both absolute and relative schema paths can be used in the statement. To set a graph that resides outside the schema in the current session as the working graph, the schema path must be specified. For information about setting and viewing the schema for the current session, see SESSION SET statement and SHOW CURRENT_SCHEMA statement.

graph_name

The name of the graph to be used as the working graph.

temp_graph_name

The name of the temporary graph to be used as the working graph. It must start with a number sign (#).

Examples

The following examples are based on the example dataset.

Set the graph in the current schema as a working graph in a query statement

'''
USE movie 
MATCH (n:Person WHERE n.id = 107224) 
RETURN n.name
'''

Return:

+-------------+
| n.name      |
+-------------+
| Olivia Hack |
+-------------+

Set the graph in the specified schema as a working graph in a query statement

'''
// Create a schema
CREATE SCHEMA IF NOT EXISTS /my_schema
''' 

'''
// Set the schema for the current session
SESSION SET SCHEMA /my_schema
'''

'''
// Specify a working graph and execute query
USE /default_schema/movie 
MATCH (n:Person WHERE n.id = 107224) 
RETURN n.name
'''

Return:

+-------------+
| n.name      |
+-------------+
| Olivia Hack |
+-------------+

Declare multiple working graphs in a linear query

When executing statements sequentially with NEXT, each statement can use USE to declare a different working graph:

'''
USE movie
MATCH (m:Movie)
RETURN m.id AS movie_id, m.name AS movie_name
NEXT
USE movie_2
MATCH (m2:Movie)
WHERE m2.id = movie_id
RETURN movie_id, movie_name, m2.name AS name_in_movie_2
'''

NEXT passes the output table of the preceding statement to the next statement. In a cross-graph query, pass properties such as business IDs or names through RETURN, and use a new graph element variable in the next graph.

Declare multiple working graphs in a composite query statement

If there are multiple graphs, you can query the data in different graphs by declaring different working graphs.

'''
USE movie MATCH (n:Movie WHERE n.id = 363) RETURN n.name AS movie_name 
UNION 
USE movie_2 MATCH (n:Movie WHERE n.id = 302) RETURN n.name AS movie_name
'''

The preceding statement performs the following operations:

  1. Declares the working graph as movie and then queries the movie with an ID of 363.
  2. Declares the working graph as movie_2 and then queries the movie with an ID of 302.
  3. Merge the results of the two statements with UNION.

Return:

+---------------+
| movie_name    |
+---------------+
| Head-On       |
| Swimming Pool |
+---------------+

Each query operand in UNION, INTERSECT, or EXCEPT has an independent variable scope, so variable names can be reused across operands. For more information, see Composite queries.

Declare a working graph multiple times in a nested query statement

'''
USE movie
MATCH (n@`User` WHERE n.id = 599)-[]->(m:Movie) RETURN n.id AS audience, m.name AS movie, VALUE {
    USE movie
    MATCH (c:Movie)<-[e:Watch]-() WHERE c.name =m.name RETURN avg(e.rate) AS average_rate GROUP BY ()
    } AS average_rate
ORDER BY average_rate DESC
LIMIT 10
'''

The preceding statement performs the following operations:

  1. Declares the working graph as movie and then queries the movies watched by the user with an ID of 599.
  2. In the subquery, declares the working graph as movie again and then calculates the average rating of each movie.
  3. Returns the user ID, movie name, and average rating of the top 10 movies watched by the user.

Return:

+----------+--------------------------------------+--------------------+
| audience | movie                                | average_rate       |
+----------+--------------------------------------+--------------------+
| 599      | Sunset Blvd.                         | 4.333333333333333  |
| 599      | Shichinin no samurai                 | 4.1875             |
| 599      | Sen To Chihiro No Kamikakushi        | 4.155172413793103  |
| 599      | Green Mile                           | 4.148648648648648  |
| 599      | City of God                          | 4.1466666666666665 |
| 599      | Lock, Stock & Two Smoking Barrels    | 4.052238805970149  |
| 599      | Wallace & Gromit: The Wrong Trousers | 4.035714285714286  |
| 599      | Nausicaä of the Valley of the Wind   | 4.0                |
| 599      | Run Lola Run                         | 4.0                |
| 599      | Princess Mononoke                    | 3.9583333333333335 |
+----------+--------------------------------------+--------------------+

Declare a different working graph in a subquery

A subquery can use USE to declare a working graph different from that of the outer query. The following query returns movies in movie that also exist in movie_2:

'''
USE movie
MATCH (m:Movie)
WHERE EXISTS {
  USE movie_2
  MATCH (m2:Movie)
  WHERE m2.id = m.id
  RETURN m2
}
RETURN m.id, m.name
'''

If USE is omitted from the subquery, the subquery continues to use the working graph of the outer query. When associating data across graphs, use different variables for graph elements from different graphs and compare properties such as business IDs. For more information, see Subquery value expressions.

Declare a working graph in a data-modifying statement

'''
USE movie
INSERT (:Movie{id:10000,name:"movie"}), 
       (IS Genre{id:11000,name:"genre"})
'''

The preceding statement declares the working graph as movie and then inserts a movie node and a genre node.