Building a Data Stack Live with AI AgentsLivestream August 18

Skip to main content

GRANT READ ON SHARE

Requires permissionRoles and access control →
Manage all organization SharesAdmin ✓Builder —Explorer —

Marked preset roles include the permission by default; a custom role qualifies when it inherits a role that includes it. Only the share owner can grant access to a Share. Organization Admins can view a Share's grants (SHOW GRANTS ON SHARE) but cannot grant access to Shares they do not own.

note

Only the owner of a Share can run GRANT READ ON SHARE. Organization Admins can view existing grants with SHOW GRANTS ON SHARE, but running GRANT against a Share owned by another account fails with Catalog Error: Database share <name> not found. In a multi-service-account (hypertenancy) setup, authenticate as the Share's owner to manage its grants.

For restricted Shares, use the GRANT command to give access to individual users or to a role. After being granted access, a user still needs to run an ATTACH command to query the shared database.

Syntax​

GRANT READ ON SHARE <share name> TO { USER <username> | ROLE <role name> } [, ...];

A bare grantee name without USER or ROLE is treated as a user.

Example usage​

-- Give the user 'duck' access to the share 'birds'.
GRANT READ ON SHARE birds TO USER duck;

-- Give two users access to the share 'taxis'.
GRANT READ ON SHARE taxis TO USER user_1, USER user_2;

-- Give every user with the 'finance' role access.
GRANT READ ON SHARE birds TO ROLE finance;

-- Grant to a mix of users and roles in one statement.
GRANT READ ON SHARE taxis TO USER user_1, USER user_2, ROLE finance;

-- Grant organization-wide access by granting to the Explorer role.
GRANT READ ON SHARE birds TO ROLE explorer;

If a username contains special characters, such as '@', it must be enclosed in double quotes (").

Granting to a role gives access to every current and future user with that role. Because preset roles are concentric, granting to the Explorer role also reaches Builder and Admin. See how data access grants flow.

Complete workflow example​

Below is a complete workflow showing how to share a database with a restricted audience and how recipients can access it. We will first create a share and grant access to specific users. Then, we will show how recipients can attach and query the shared database. For more information on each step, refer to the CREATE SHARE, LIST SHARES, and ATTACH documentation.

1. Owner creates a share and grants access​

-- Owner: create a restricted share of database 'analytics'
-- Using CREATE OR REPLACE allows updating the share if it already exists.
-- ACCESS RESTRICTED is required to use GRANT/REVOKE.
CREATE OR REPLACE SHARE analytics_share FROM analytics (ACCESS RESTRICTED);

-- Owner: Grant access to specific users.
-- If a username contains special characters like '@', enclose it in double quotes.
GRANT READ ON SHARE analytics_share TO user_1, "user_2@example-com";

-- Owner retrieves the share URL to provide to recipients.
-- The URL uniquely identifies the share.
LIST SHARES;
-- Example output contains URL like: md:_share/analytics/0a9a026ec5a55946a9de39851087ed81

-- Owner shares the full URL (e.g., 'md:_share/analytics/0a9a026ec5a55946a9de39851087ed81') with the granted users.

2. Recipient attaches and queries the shared database​

-- Recipient: attach the shared database using the full URL provided by the owner.
-- Using the full URL prevents naming conflicts.
ATTACH 'md:_share/analytics/0a9a026ec5a55946a9de39851087ed81' AS analytics_data;

-- Recipient: switch to the attached database
USE analytics_data;

-- Recipient: query the shared database
SELECT * FROM customer_metrics LIMIT 10;

When the share is attached, it creates a read-only reference to the shared database that doesn't consume additional storage for the recipient. Recipients can query the data but cannot modify it.