Source: https://dev-docs.nebula-graph.io/v5.3.2/server-admin/authorization/schema-access-control/
Documentation version: v5.3.2

# Schema access control

To access a resource in a non-default schema, a regular user needs two privileges: `USAGE` on the schema and the privilege required to operate on the resource.

## Prerequisites

- User `alice` exists, has joined the service group, and has `CONNECT`.
- `/finance/orders` exists. Replace the example path if you use another resource.
- Connect to the Graph service as a user with `ADMIN` to grant privileges. See [Configure user access](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/authorization/configure-user-access/) for user creation and invitation steps.

## Grant example

To allow `alice` to query graph `/finance/orders`, grant both privileges:

````
'''
GRANT USAGE ON SCHEMA /finance TO USER alice
'''

'''
GRANT MATCH ON GRAPH /finance/orders TO USER alice
'''

````

- `USAGE` allows `alice` to see and use schema `/finance`.
- `MATCH` allows `alice` to query graph `/finance/orders`.

With only `USAGE`, `alice` cannot query the graph. With only `MATCH`, `alice` cannot access schema `/finance`.

## Privilege checks

To perform an operation on an object in a schema, a user must have both:

- `USAGE` on the schema that contains the object, either provided automatically by the system or received through a grant.
- The privilege required for the operation.

The operation privilege can be granted directly on the target object or provided by a parent resource. For example, `MATCH ANY GRAPH` on a schema allows queries on every graph in that schema. For a complete list, see [Privilege reference](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/authorization/privilege-reference/).

Privileges on sibling object types are not required. For example, `USAGE` on `/finance` and `MATCH` on graph `/finance/orders` are sufficient to query the graph. The user does not also need privileges on the graph type used by `orders`.

Note

Schema access control applies to schemas and their objects. It does not apply to temporary graphs or built-in procedures and functions.

## Get access to a schema

A user can receive schema access automatically from the system or through a `USAGE` grant:

 | User or condition | How schema access is obtained
 | A user with the `ADMIN` role | Automatically has access to every schema.
 | The current schema owner | Automatically has access to the owned schema.
 | Any user accessing `/default_schema` | Automatically has access to `/default_schema`.
 | A user granted `USAGE` directly or through a role | Has access to the specified schema.

These settings do not automatically provide access to the parent schema:

- Setting the schema, or a graph in it, as the user's home schema or home graph.
- Owning a graph, graph type, UDP, or UDF in the schema.
- Having only `CONNECT` on the service group.

## Grant schema access

You can grant `USAGE` directly to a user:

````
GRANT USAGE ON SCHEMA /finance TO USER alice

````

For easier management, grant `USAGE` and the required operation privileges to a role, and then grant the role to users:

````
'''
CREATE ROLE IF NOT EXISTS finance_reader
'''

'''
GRANT USAGE ON SCHEMA /finance TO ROLE finance_reader
'''

'''
GRANT MATCH ON GRAPH /finance/orders TO ROLE finance_reader
'''

'''
GRANT ROLE finance_reader TO USER alice
'''

````

In this example, `alice` can access `/finance` and query `/finance/orders`. No privilege on the graph type is required. With only `USAGE`, `alice` can select `/finance` but cannot query `orders`.

Only the schema owner and a user with the `ADMIN` role can grant or revoke `USAGE` on the schema. For the complete workflow, see [Configure user access](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/authorization/configure-user-access/). For command syntax, see [GRANT](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/authorization/grant-privilege/) and [REVOKE](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/authorization/revoke-privilege/).

## Revoke schema access

To revoke access granted directly to a user:

````
REVOKE USAGE ON SCHEMA /finance FROM USER alice

````

To revoke access provided by a role:

````
REVOKE USAGE ON SCHEMA /finance FROM ROLE finance_reader

````

If the user cannot obtain schema access from another source, the following changes occur after the privilege change takes effect:

- The schema is no longer visible to the user.
- Existing sessions can no longer access the schema or its objects.
- `SHOW CURRENT_SCHEMA` and `SHOW CURRENT_GRAPH` no longer display the inaccessible schema or graph selected in the session.
- Privileges and ownership on objects in the schema remain unchanged.
- Granting `USAGE` again restores schema access. Unchanged object privileges do not need to be granted again.

## Changes to schema access

### Schema ownership

The access automatically provided to a schema owner cannot be revoked.

After `ALTER OWNER SCHEMA`:

- The new owner automatically receives access to the schema.
- The former owner loses the access provided by schema ownership. Any `USAGE` previously granted directly or through a role remains effective. Otherwise, the former owner must receive `USAGE` to continue accessing the schema.
- Ownership and privileges on child objects are unchanged.

For more information, see [ALTER OWNER](https://dev-docs.nebula-graph.io/v5.3.2/server-admin/authorization/alter-owner/).

### Home schema and home graph

A home schema and home graph are the schema and graph used by default when the user connects. Setting them does not grant the user `USAGE` on the parent schema.

If the user loses all access to the home schema:

- The user cannot access the home schema or home graph through a new or existing session.
- `SESSION RESET SCHEMA` clears the current schema instead of resetting it to the inaccessible home schema.
- `SESSION RESET GRAPH` clears the current graph if the home graph belongs to the inaccessible schema.
- The user can explicitly switch to `/default_schema`:

````
SESSION SET SCHEMA /default_schema

````

An administrator can set a different accessible home schema for the user. For more information, see [ALTER USER](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/alter-user/).

### `/default_schema`

Every user automatically has `USAGE` on `/default_schema`. This privilege cannot be granted or revoked explicitly:

````
'''
GRANT USAGE ON SCHEMA /default_schema TO USER alice
'''

'''
REVOKE USAGE ON SCHEMA /default_schema FROM USER alice
'''

````

Both commands return an insufficient privilege error.