--- title: "Grant" sidebarTitle: "Grant" description: "GRANT and REVOKE: privileges on every catalog object, from a database down to a Function." icon: user-lock keywords: ["grant", "revoke", "privileges", "authorization", "sql", "ownership"] availability: embedded: unavailable enterprise: available --- ```sql SQL icon="database" GRANT [, ...] ON TO [, ...] REVOKE [, ...] ON FROM [, ...] ::= SYSTEM | DATABASE | SCHEMA | NAMESPACE [IN ] | TABLE | VIEW | MATERIALIZED VIEW | SECRET | STORAGE INTEGRATION | FUNCTION ::= [ROLE] | [USER] { | ID '' } | [GROUP] { | ID '' } ``` ```sql SQL icon="database" GRANT OPERATE, USAGE ON SYSTEM TO ROLE ops GRANT USAGE, CREATE SCHEMA ON DATABASE analytics TO ROLE readers GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE events TO ROLE etl GRANT CREATE SECRET, CREATE FUNCTION ON SCHEMA platform TO ROLE platform_admins GRANT USAGE, UPDATE ON SECRET platform.`model-api-key` TO ROLE etl, rotation_service GRANT USAGE ON SECRET platform.`model-api-key` TO USER alice, GROUP ID 'g1' GRANT USAGE ON FUNCTION platform.embed TO ROLE research GRANT OWNERSHIP ON SECRET platform.`model-api-key` TO ROLE platform_admins REVOKE USAGE ON FUNCTION platform.embed FROM ROLE research ``` ## Privileges {#privileges} | Target | Privileges it accepts | | --- | --- | | `SYSTEM` | `OPERATE`, `CREATE DATABASE`, `USAGE` -- no `OWNERSHIP`; the system itself has no owner | | `DATABASE` | `OWNERSHIP`, `USAGE`, `CREATE SCHEMA` (or `CREATE NAMESPACE`) | | `SCHEMA` (a namespace) | `OWNERSHIP`, `USAGE`, `CREATE NAMESPACE`, `CREATE TABLE`, `CREATE MATERIALIZED VIEW`, `CREATE VIEW`, `CREATE SECRET`, `CREATE STORAGE INTEGRATION`, `CREATE FUNCTION` | | `TABLE`, `MATERIALIZED VIEW` | `OWNERSHIP`, `SELECT`, `INSERT`, `UPDATE`, `DELETE` | | `VIEW` | `OWNERSHIP`, `SELECT` | | `SECRET` | `OWNERSHIP`, `USAGE` (bind it to a Function), `UPDATE` (rotate it) | | `STORAGE INTEGRATION` | `OWNERSHIP`, `USAGE` | | `FUNCTION` | `OWNERSHIP`, `USAGE` (call it in a query, bind it to a column, or refresh a column it computes) | `OWNERSHIP` cannot be revoked, only granted to someone else, which transfers it: an object always has exactly one owner. `GRANT OWNERSHIP` is refused with more than one grantee for the same reason. See [Privileges](/governance/privileges) for what each privilege allows in full, and how a creation privilege resolves against an object's parent when the object doesn't exist yet. ## Grantees {#grantees} A grantee is a role, or a user or group named by its identity-directory name or its directory ID. A grantee with no leading `ROLE`/`USER`/`GROUP` keyword takes the kind of the one before it, so `TO ROLE a, b` names two roles -- but the first grantee in the list always needs its keyword. An unquoted name is folded to lowercase before it is looked up; quote one that has capitals, such as `TO ROLE "DataEng"`. ## Naming the target {#targets} A `SECRET` or `FUNCTION` target can be qualified with its namespace and database, the same as anywhere else: `SECRET analytics.api_key`, `SECRET db1.analytics.api_key`. `SCHEMA` and `NAMESPACE` both target a namespace but aren't interchangeable: `SCHEMA ` takes the namespace's complete path, while `NAMESPACE [IN ]` takes one unqualified component, resolved under an explicit parent schema or the session's current namespace when `IN` is omitted -- `NAMESPACE a.b` (a qualified name with no `IN`) is refused. A `MATERIALIZED VIEW` is a table for authorization purposes: the same privileges apply, and granting one does not reach the non-materialized `VIEW` beside it. ## How a statement is applied {#semantics} - A statement applies all of its changes or none of them. - The caller must already hold `OWNERSHIP` on the object to change any grant on it. - Granting a privilege a grantee already holds, or revoking one it does not hold, is a no-op. - `GRANT` requires the object to exist; `REVOKE` does not, so an entry left on a dropped object can still be removed. A role need not exist beforehand, but a `USER` or `GROUP` name must resolve to exactly one identity in your identity provider -- checked only after the caller's `OWNERSHIP` -- or the statement fails. The `ID ''` form is not looked up. - `GRANT ... ON ... FROM ...` and `REVOKE ... ON ... TO ...` are both refused; `GRANT` always takes `TO`, `REVOKE` always takes `FROM`. - Returns one row per privilege and grantee, with status `granted`, `already_granted`, `revoked` or `not_granted`. SQL has no syntax for binding a Secret to a Function; that's a registration-time argument to `create_function` in the Python SDK. See [Vend a Secret to a Function](/curation/vend-secret). ## SHOW GRANTS {#show-grants} ```sql SQL icon="database" SHOW GRANTS [ON ] [TO [, ...]] [LIMIT n] ``` ```sql SQL icon="database" SHOW GRANTS SHOW GRANTS ON TABLE events TO ROLE readers LIMIT 2 SHOW GRANTS ON NAMESPACE features IN analytics.team SHOW GRANTS TO USER ID 'p1' ``` Lists grants as rows of `subject_id`, `subject_name`, `object` and `privilege`. `ON` filters to one target's own grants; `TO` filters to one or more grantees; combine both, or omit both for every grant the caller can see. `ON ` requires `USAGE` on that target; a target-less call requires system `USAGE` instead, since it can surface grants across the whole catalog. `SHOW ROLE BINDINGS` is the counterpart for role membership rather than object privileges -- see [Role membership in SQL](/governance/principals#membership). ## What to read next {#next} The full privilege model, and how creation privileges resolve upward. Creating the schemas these privileges apply to.