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

# 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/sessions/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](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/authorization/schema-access-control/).

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

- DDL statements

  - [CREATE NORMAL INDEX](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/index/create/)
  - [CREATE VECTOR INDEX](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/index/create-vector/)
  - [CREATE SPATIAL INDEX](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/index/create-geo/)
  - [CREATE FULLTEXT INDEX](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/index/create-fulltext/)
  - [DROP INDEX](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/index/drop/)
  - [CREATE TTL](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/ttl/create/)
  - [ALTER TTL](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/ttl/alter/)
  - [DROP TTL](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/ddl/ttl/drop/)

- DML statements

  - [INSERT](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dml/insert/)
  - [SET](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dml/set/)
  - [DELETE](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dml/delete/)

- DQL statements

  - [MATCH](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/match/)

- SHOW commands

  - [SHOW (ALL) INDEXES](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/show-indexes/)
  - [SHOW TTLS](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/show-ttls/)
  - [SHOW STATS](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/show-stats/)

## Syntax

diagramsource

 use_clause  

````
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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/sessions/set/) and [SHOW CURRENT_SCHEMA statement](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/show-current-schema/).

### `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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/let/), 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/dql/composite-query/).

### 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/expressions/subquery/).

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