Managing and using worksheets in Snowsight

Worksheets provide a powerful and versatile method for running SQL queries or Python code, as well as performing other Snowflake data loading, definition, and manipulation tasks.

After you open a worksheet in Snowsight, you can do any of the following:

In addition, you can write SQL statements and visualize the results. You can also write Python code.

Browse other worksheets from a worksheet

When you open a worksheet, you can view other worksheets in the Worksheets explorer. You can search for other worksheets and manage worksheets from the Worksheets explorer.

Previewing worksheet contents

To preview the contents of a worksheet, you can hover over the name of the worksheet in the Worksheets explorer. The preview also shows the role used to run the worksheet.

From the preview, you can also copy the contents of the worksheet. Hover over the worksheet contents preview and select the Copy button that appears.

Update worksheets with keyboard shortcuts

Snowsight provides keyboard shortcuts to help you quickly navigate and edit queries in worksheets. For example, you can move your cursor within a worksheet, perform find and replace, copy lines, format queries, and more using hotkeys.

To see all available keyboard shortcuts, open a worksheet and press [CMD]+[SHIFT]+[?] on a Mac keyboard or [CTRL]+[SHIFT]+[?] on a Windows keyboard.

You can also hover over the tab for the worksheet and select more actions for worksheet, then choose Show Shortcuts to view the shortcuts.

Change the session context for a worksheet

Set the session context for a worksheet to define the role and warehouse to use to run the contents of a worksheet. The worksheet context is preserved for future sessions.

Note

You cannot choose multiple roles. The context selector does not support secondary roles. To enable secondary roles in a SQL worksheet, run USE SECONDARY ROLES.

The role context for a worksheet determines which operations can be performed on Snowflake objects based on the access control privileges granted to the role.

To set the session context for a worksheet, do the following:

  1. Sign in to Snowsight.

  2. Select Projects » Worksheets to open the list of worksheets.

  3. Open a worksheet.

  4. Open the context selector.

  5. Select a role to run the worksheet as.

  6. Select a warehouse that the role has privileges to use.

  7. Select anywhere outside the drop-down to close the context selector.

Note

Each worksheet is a unique session and can use roles different from the role you select in the account menu (your active role). Changing your active role does not change the role assigned to the worksheet with the context selector.

Resuming and resizing warehouses

Before or after you run your worksheet, you might need to resume or resize your warehouse.

You must have MODIFY or OWNERSHIP privileges on the warehouse to alter warehouse details.

To view and adjust warehouse details using the context selector, do the following:

  1. Sign in to Snowsight.

  2. Select Projects » Worksheets to open the list of worksheets.

  3. Open a worksheet.

  4. Open the context selector.

  5. Select the Show warehouse details icon.

  6. For the Status option, select the status and choose Resume if the warehouse is suspended.

  7. For the Size option, select the size and choose a different size.

  8. Select anywhere outside the drop-down to close the context selector.

Managing open worksheets

After you open a worksheet, select the more actions for worksheet visible when you hover over the tab for a worksheet to manage the open worksheet in the following ways:

When you have an open worksheet, you can also view and manage other worksheets in the Worksheets explorer:

  • Search for other worksheets.

  • Rename, duplicate, delete, or move the worksheet using the More options visible when you hover over the name of a worksheet.

  • Identify which worksheets are open in a tab using the worksheet icon. A filled-in icon indicates a worksheet open in a tab.

Organizing worksheets in folders

You can organize and manage worksheets in folders using Snowsight.

  1. Sign in to Snowsight.

  2. Select Projects » Worksheets.

  3. Select a worksheet to open it.

  4. Hover over the tab for the worksheet and select more actions for worksheet.

  5. In the drop-down list, select Move and then select a folder or dashboard to move the worksheet to, or create one.

Sharing worksheets and folders

You can share worksheets and folders of worksheets with other Snowflake users in your account. You can only share worksheets directly with users who have previously signed in to Snowsight. If you want to share with someone who has not yet signed in to Snowsight, share a link instead.

Sharing a worksheet or worksheet folder lets you collaborate with your colleagues on that worksheet and lets the recipients of a shared worksheet edit or view the worksheet contents, view the results, run the worksheet, or duplicate the shared worksheet. See Permissions for shared worksheets.

Permissions for shared worksheets

When you share a worksheet with someone, you can manage access to the worksheet and its contents by choosing which permissions to grant to the other user. These permissions are also used for sharing dashboards. Worksheet owners have the same permissions as worksheet editors.

Each worksheet in Snowsight uses a unique session with a specific role and warehouse assigned in the context of the worksheet. The worksheet role is the primary role last used to run the worksheet and is required to run the worksheet. The worksheet role can change if the worksheet owner or editor runs the worksheet using a different role.

To view the results of an earlier worksheet version, you need to have the worksheet role that was used to run the SQL statement that generated the results. See Viewing results for past runs of a worksheet.

Permissions Granted

Recipient Can:

Edit

  • Edit the worksheet contents.

  • Run the worksheet, including run the worksheet as a different role.

  • View past versions of the worksheet.

  • View the results for past versions of the worksheet, if they have the role used to generate the results.

  • Share the worksheet with others.

  • View past versions of the worksheet.

  • Add the worksheet to a different folder.

View + Run

  • If they have the worksheet role:

    • Run the worksheet.

    • View the results of the most recent worksheet version.

  • View the worksheet contents.

  • Duplicate and run the worksheet using their own role.

View Results

  • View the results of the most recent worksheet version, if they have the worksheet role.

  • View the worksheet contents.

  • Duplicate and run the worksheet using their own role.

Link with View + Run

  • If they have the worksheet role:

    • Run the worksheet.

    • View the results of the most recent worksheet version.

  • View the worksheet contents. Users with the link cannot duplicate and run the worksheet.

Link with View Results

  • View the results of the most recent worksheet version, if they have the worksheet role.

  • View the worksheet contents. Users with the link cannot duplicate and run the worksheet.

The worksheet owner is the user who created the worksheet and has the same permissions as a worksheet editor. The worksheet owner changes if a worksheet owner or editor adds the worksheet to a folder owned by another user.

If the worksheet owner is dropped from Snowflake, the dropped user remains the owner of the worksheet, but users with edit permissions can continue to use the worksheet. If you want to recover the worksheets owned by a dropped user, see Recover worksheets owned by a dropped user.

Viewing results for past runs of a worksheet

All users with access to a worksheet can view the results of the most recent worksheet run.

To view the results for past runs of a worksheet, the following must be true:

You can view the results of a past worksheet run by viewing the Query History for a worksheet. See View query history.

Caution

When you share a worksheet, you also share a cached version of the results. If your worksheet queries data protected by masking or row access policies, or if you have secondary roles enabled for your user, the cached results might contain results visible only to your user. Recipients of the shared worksheet might not have permission to generate those results, but if they have the worksheet role, they can view all cached results.

Share a worksheet

To share a worksheet, do the following:

  1. Sign in to Snowsight.

  2. Select Projects » Worksheets to open the list of worksheets.

  3. Open a worksheet.

  4. In the upper-right corner of the worksheet, select Share.

  5. Enter the names or usernames of the Snowflake users you want to invite to use your worksheet. The list only shows users who have previously signed in to Snowsight. If you want to share with someone who has not yet logged in to Snowsight, share a link instead.

  6. Choose the permissions to grant to the users with whom you share the worksheet.

  7. Optionally, set permissions for what people with the link to the worksheet can access.

  8. Optionally, select Get Link to get a link to your worksheet that you can share with others.

  9. Select Done.

Note

The most recently run version of a worksheet is the version of the worksheet that is shared. If you have not yet run the worksheet, an empty worksheet is shared.

Any edits that you make to your version of the worksheet, whether you’re an editor or an owner of the worksheet, do not appear for collaborators unless and until you run part or all of the worksheet code.

Share a folder of worksheets

To share a folder, including all worksheets in the folder, do the following:

  1. Sign in to Snowsight.

  2. Select Projects » Worksheets to open the list of worksheets.

  3. Open a folder.

  4. Select Share.

  5. Enter the names or usernames of the Snowflake users you want to invite to your folder. The list only shows users who have previously signed in to Snowsight. If you want to share with someone who has not yet logged in to Snowsight, share a link instead.

  6. Choose the permissions to grant to the users with whom you share the folder.

  7. Optionally, set permissions for what people with the link to the folder can access.

  8. Optionally, select Get Link to get a link to your folder that you can share with others.

  9. Select Done.

If you add a worksheet to a shared folder, the worksheet inherits the sharing settings of the folder. If the folder is owned by someone other than the worksheet owner, the user that owns the worksheet changes to the folder owner, and the original worksheet owner inherits the sharing permissions from the folder.

For example, if a worksheet owner adds a worksheet to a folder on which they have edit permissions, the worksheet updates to be owned by the folder owner, and the original worksheet owner then has edit permissions on the worksheet.

Sharing worksheets across accounts

Worksheets are not Snowflake objects, so cannot be replicated or shared across accounts. If you want to share the contents of a worksheet with users in another Snowflake account, copy the contents and share it with users in the account outside of Snowflake.

Managing worksheet history and versions

New versions of a worksheet are saved when you make changes and run a SQL query or the code in the worksheet.

When making changes to worksheets and managing worksheet versions, consider the following:

  • When you share a worksheet with other users, users with edit permissions can view past versions of the worksheet. All users that you share a worksheet with can view results for the most recent version of the worksheet.

  • Whenever someone with permissions runs a worksheet, a new version of the worksheet is saved.

  • If you make changes to the worksheet and they seem to disappear, use the version history to open the saved draft with your changes.

  • The most recently run version of the worksheet is the version visible to collaborators.

  • If you make changes to the worksheet that you want to be visible to the users with whom you shared the worksheet, you must run the worksheet.

  • If multiple users edit and run a shared worksheet at the same time, each run of the worksheet creates a new version. The most recently run version of the worksheet is the one visible when you open or refresh the worksheet.

Switching worksheet versions

If you want to view past versions of a worksheet, do the following:

  1. Sign in to Snowsight.

  2. Select Projects » Worksheets to open the list of worksheets.

  3. Open the worksheet.

  4. Select Code Versions for the worksheet.

  5. From the list of worksheet versions, select the timestamp of the version that you want to view.

  6. Review and optionally copy the worksheet details for that version.

  7. Select Close to return to the current version of the worksheet.

If you want to view the results of a past worksheet run, view the Query History for the worksheet. See View query history.

Stored results for past worksheet versions

Results for queries executed in worksheets are cached for up to 90 days, or 25 worksheet versions, whichever is greater. This cache is included in the data storage usage for your account.

Recover worksheets owned by a dropped user

If you drop a user, you can recover up to 500 of the worksheets owned by that user. To recover the worksheets, do the following:

  1. Download recovered worksheets owned by a dropped user.

  2. Create worksheets from a SQL file to add the recovered worksheets back to Snowflake.

If you want to change ownership or retain access to worksheets before dropping a user, ask that user to share the worksheets. See Sharing worksheets and folders.

Download recovered worksheets owned by a dropped user

To recover worksheets owned by a dropped user, download a .tar.gz archive file of up to 500 worksheets owned by that user.

Note

You must be granted the ACCOUNTADMIN role to recover worksheets of dropped users.

  1. Sign in to Snowsight.

  2. Select Projects » Worksheets.

  3. Select More options » Recover Worksheets from Dropped User.

  4. In the dialog box, enter the username of a dropped user in your account.

    Important

    The case and spelling of the username must exactly match the username as it was stored in Snowflake.

  5. Select Recover.

    Your web browser downloads a .tar file containing up to 500 worksheets. If the dropped user has more than 500 worksheets, only the 500 most recently modified worksheets are downloaded.

After downloading worksheets owned by a dropped user, add the recovered worksheets to Snowsight by creating worksheets from the SQL files.

You must expand the downloaded .tar file into a folder of .sql files before you can add recovered worksheets to Snowsight. You can only add one worksheet at a time to Snowsight, and the user who adds the recovered worksheets to Snowsight becomes the new owner of the worksheets.

See Create worksheets from a SQL file for details.

Considerations for recovering worksheets owned by dropped users

Considerations when recovering worksheets:

  • Only the title and contents of the most recently executed version of a worksheet are recovered. Worksheet version history, sharing recipients and permissions, query results, and worksheet metadata are not recovered.

  • A maximum of 500 worksheets are recovered. For dropped users with more than 500 worksheets, only the 500 most recently modified worksheets are recovered.

  • Only worksheets in Snowsight are recovered. Worksheets in Classic Console owned by dropped users cannot be recovered with this method.

  • If multiple dropped users have the same username, worksheets owned by all dropped users with that username are recovered.

If the worksheet recovery fails for unexpected reasons, contact Snowflake Support.

Internal Snowflake objects for worksheets

Snowflake creates the following internal objects to support using worksheets in Snowsight:

Object Type

Name

Security integration

WORKSHEETS

Blobs

WORKSHEETS_APP

Database

WORKSHEETS_APP

User

WORKSHEETS_APP_USER

Roles

APPADMIN, WORKSHEETS_APP_RL

These internal objects are used to cache query results in an internal stage in your account. This cached data is encrypted and protected by the key hierarchy for the account.

The limited privileges granted to the internal role only allow Snowsight to access the internal stage to store those results. The role cannot list objects in your account or access data in your tables.

The Snowsight user and role are returned when you query the USERS and ROLES views, respectively, in the ACCOUNT_USAGE schema in the SNOWFLAKE shared database. SHOW <objects> statements do not return these internal objects.