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

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

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. For command syntax, see GRANT and REVOKE.

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.

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.

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