Generates a scoped Snowflake-hosted URL to a staged file using the stage name and relative file path as inputs. A scoped URL is encoded and permits access to a specified file for a limited period of time.
Call this SQL function in a query, view, user-defined function (UDF), or stored procedure. The scoped URL in the output is valid for the caller only until the persisted query result period ends (i.e. the results cache expires): currently 24 hours.
Access files in a stage using either of the following methods:
Retrieve a scoped URL in Snowsight. Click on the scoped URL in the results table.
Send the scoped URL in a request to the REST API for file support. When users send a scoped URL to the REST API to access files, Snowflake performs the following actions:
Authenticate the user. Verify that it was the current user who called the BUILD_SCOPED_FILE_URL function and generated the scoped URL.
Verify that the scoped URL is not expired.
Redirect the user to the staged file in the cloud storage service.
BUILD_SCOPED_FILE_URL( @<stage_name> , '<relative_file_path>' )
Name of the internal or external stage where the file is stored.
If the stage name includes spaces or special characters, it must be enclosed in single quotes (e.g.
'@"my stage"'for a stage named
Path and filename of the file relative to its location in the stage.
The permissions required to call this SQL function differ depending on how it is called:
USAGE (external stage) or READ (internal stage)
Column definition in a view
The view owner (i.e. role that has the OWNERSHIP privilege on the view) must have the stage privilege: USAGE (external stage) or READ (internal stage).
A role that queries the view only requires the SELECT privilege on the view.
The stored procedure owner (i.e. role that has the OWNERSHIP privilege on the stored procedure) must have the stage privilege: USAGE (external stage) or READ (internal stage).
A role that queries the stored procedure only requires the USAGE privilege on the stored procedure.
The UDF owner (i.e. role that has the OWNERSHIP privilege on the UDF) must have the stage privilege: USAGE (external stage) or READ (internal stage).
A role that queries the UDF only requires the USAGE privilege on the UDF.
An HTTP client that sends a scoped URL to the REST API must be configured to allow redirects.
When a scoped URL is accessed, the query history shows that the internal GET_SCOPED_FILE function was called.
The function returns a scoped URL in the following format:
Hostname of the Snowflake account for your stage. The hostname starts with an account locator (provided by Snowflake) and ends with the Snowflake domain (
For more details, see Account Identifiers.
Query ID of the BUILD_SCOPED_FILE_URL call that generated the scoped URL.
Encoded path to the files to access using the scoped URL.
Retrieve a scoped URL for a bitmap format image file in an external stage:
Create a secure view that filters the results of a BUILD_SCOPED_FILE_URL function call for a specific audience. In this example, querying
the secure view returns only those files in the stage file path that include the string
-- Create a table that stores the relative file path for each staged file along with any other related data. CREATE TABLE acct_table ( acct_name string, relative_file_path string ); -- Create a secure view on the table you created. -- A role that has the SELECT privilege on the secure view has scoped access to the filtered set of files that include the acct1 text string. CREATE SECURE VIEW acct1_files AS SELECT BUILD_SCOPED_FILE_URL(@acct_files, relative_file_path) FROM acct_table WHERE acct_name = 'acct1';