Metadata access control¶

Metadata access in Horizon Catalog is separate from data access. A role can view or curate metadata and lineage without being able to query the underlying data, so we recommend managing metadata access with roles that are separate from your data access roles.

This page covers three needs:

• Create a connector: for the role that sets up a metadata connector.
• View metadata and lineage: for end users and analysts who explore the catalog and lineage (read-only).
• Edit metadata: for data stewards who curate the descriptions and comments that appear in the catalog.

Create a connector¶

The role you select in Snowsight creates the connector and owns it. Snowsight behaves as if secondary roles are enabled, so privileges from any role you hold apply to most actions. Creating an object is the exception: the new object is owned by the primary role you select, so that role alone must have the privileges to create it. Privileges granted to your other roles don’t count, even when those roles together hold every privilege needed to create the object.

The role must have all of the following:

• MANAGE METADATA CONNECTORS on the account
• USAGE or OWNERSHIP on the database for the connector
• CREATE METADATA CONNECTOR or OWNERSHIP on the schema for the connector

If the selected role creates a new database and schema when it sets up the connector, it owns them and needs only MANAGE METADATA CONNECTORS, plus permission to create the database. Otherwise, grant the privileges for the default CONNECTORS.METADATA location:

GRANT MANAGE METADATA CONNECTORS ON ACCOUNT TO ROLE <role_name>;
GRANT USAGE ON DATABASE CONNECTORS TO ROLE <role_name>;
GRANT CREATE METADATA CONNECTOR ON SCHEMA CONNECTORS.METADATA TO ROLE <role_name>;

View metadata and lineage¶

Give end users read-only visibility into Snowflake metadata, connector metadata, and lineage. Viewing metadata doesn’t require access to the underlying data, so you can grant it to roles that have no query privileges.

Viewing lineage requires the VIEW LINEAGE privilege on the account, plus access to the objects in the lineage graph. VIEW LINEAGE is granted to the PUBLIC role by default, so most roles already have it. If your account has restricted this default grant, re-grant it before following the steps below. See Access control for lineage information.

Snowflake object metadata¶

To control visibility of Snowflake objects (databases, schemas, tables, views, and similar) in Horizon Catalog, grant USAGE and REFERENCES privileges using a combination of ALL and FUTURE grants:

• ALL grants apply the grant to every matching object that exists when you run the statement.
• FUTURE grants create a standing rule that applies the grant to objects created later.

Using ALL and FUTURE grants together gives a role visibility into both the objects that exist today and anything created in the future, which is the same effect as an inherited grant. For more information, see GRANT <privileges>.

-- Visibility of databases can be granted via USAGE.
GRANT USAGE ON DATABASE db TO ROLE r1;

-- Visibility of schemas can be granted via USAGE. Grant to all existing
-- schemas, and add a FUTURE grant for schemas created later.
GRANT USAGE ON ALL SCHEMAS IN DATABASE db TO ROLE r1;
GRANT USAGE ON FUTURE SCHEMAS IN DATABASE db TO ROLE r1;

-- Visibility of table-like objects beneath a schema can be granted via the
-- REFERENCES privilege. Use the same ALL and FUTURE combination so the role
-- has visibility into everything.
GRANT REFERENCES ON ALL TABLES IN DATABASE db TO ROLE r1;
GRANT REFERENCES ON FUTURE TABLES IN DATABASE db TO ROLE r1;

-- Enumerate each object type you want the role to see (views, and so on).
GRANT REFERENCES ON ALL VIEWS IN DATABASE db TO ROLE r1;
GRANT REFERENCES ON FUTURE VIEWS IN DATABASE db TO ROLE r1;

Connector metadata and lineage¶

A connector is created by the role that sets it up in Catalog > Connections, and that role owns it. Other roles can’t see the connector’s metadata and lineage until you grant them access. To see a connector’s external objects in lineage graphs and catalog metadata, the active role must have all of the following:

• USAGE on the database that contains the connector
• USAGE on the schema that contains the connector
• USAGE on the connector itself, or OWNERSHIP of it

All metadata connectors are created under the CONNECTORS.METADATA schema by default. Grant USAGE to each role that needs to view the connector’s metadata and lineage:

GRANT USAGE ON DATABASE CONNECTORS TO ROLE <role_name>;
GRANT USAGE ON SCHEMA CONNECTORS.METADATA TO ROLE <role_name>;
GRANT USAGE ON METADATA CONNECTOR CONNECTORS.METADATA.<connector_name> TO ROLE <role_name>;

If you stored your connector in a different database or schema, replace CONNECTORS and METADATA with the actual database and schema names. To find the connector’s location, run:

SHOW METADATA CONNECTORS;

Edit metadata¶

Give data stewards the ability to curate the comments, descriptions, and tags that appear in the catalog, without granting more permissive privileges such as MODIFY or OWNERSHIP:

• APPLY COMMENT: edit the comments and descriptions on objects and columns.
• APPLY TAG: set and unset tags on objects and columns. You can grant it on the account or on an individual tag. For the full tag privileges and grant syntax, see Tag privileges.

APPLY COMMENT¶

APPLY COMMENT lets a role set or unset the comment on an object, including column-level comments for table-like objects.

Grant syntax¶

APPLY COMMENT uses the standard GRANT <privileges> syntax. You can grant it at three scopes:

-- Per object
GRANT APPLY COMMENT ON <object_type> <object_name> TO ROLE <role_name>;

-- All existing objects of a type in a schema or database
GRANT APPLY COMMENT ON ALL <object_type_plural> IN { SCHEMA <schema_name> | DATABASE <database_name> }
    TO ROLE <role_name>;

-- Objects of a type created in the future in a schema or database
GRANT APPLY COMMENT ON FUTURE <object_type_plural> IN { SCHEMA <schema_name> | DATABASE <database_name> }
    TO ROLE <role_name>;

A role granted APPLY COMMENT still needs USAGE on the parent database and schema to resolve the target object. The privilege authorizes the comment change. It doesn’t grant the visibility needed to navigate to the object.

-- Examples granting a steward the ability to edit comments on a single table, on every table 
-- in a schema, and on every view created in a database going forward:
GRANT APPLY COMMENT ON TABLE finance.gl.journal TO ROLE finance_steward;
GRANT APPLY COMMENT ON ALL TABLES IN SCHEMA finance.gl TO ROLE finance_steward;
GRANT APPLY COMMENT ON FUTURE VIEWS IN DATABASE finance TO ROLE finance_steward;

To revoke the privilege, use REVOKE <privileges>:

REVOKE APPLY COMMENT ON TABLE finance.gl.journal FROM ROLE finance_steward;

Supported object types¶

You can grant APPLY COMMENT on the following object types:

• Database
• Schema
• Table
• Dynamic table
• Apache Iceberg™ table
• External table
• Event table
• Interactive table
• View
• Materialized view
• Semantic view
• Function
• Procedure
• Pipe
• Task
• Agent

Statements authorized¶

With APPLY COMMENT on an object, a role can set and unset the object comment and, for table-like objects, individual column comments. Both the ALTER … SET COMMENT and COMMENT ON forms are authorized:

-- Object comments
ALTER TABLE finance.gl.journal SET COMMENT = 'General ledger journal entries';
ALTER TABLE finance.gl.journal UNSET COMMENT;
COMMENT ON TABLE finance.gl.journal IS 'General ledger journal entries';

-- Column comments
ALTER TABLE finance.gl.journal ALTER COLUMN amount COMMENT 'Signed amount in USD';
ALTER TABLE finance.gl.journal MODIFY COLUMN amount COMMENT 'Signed amount in USD';
ALTER TABLE finance.gl.journal ALTER COLUMN amount UNSET COMMENT;
COMMENT ON COLUMN finance.gl.journal.amount IS 'Signed amount in USD';

-- A statement that changes only comments is authorized, even across multiple columns
ALTER TABLE finance.gl.journal ALTER COLUMN amount COMMENT 'USD', COLUMN currency COMMENT 'ISO code';

Statements not authorized¶

APPLY COMMENT is comment-only. It doesn’t authorize any other change, and a single statement that mixes a comment change with any non-comment change is rejected. The role needs MODIFY or OWNERSHIP for these statements.