Choosing an Internal Stage for Local Files¶

A stage specifies where data files are stored (i.e. “staged”) so that the data in the files can be loaded into a table.

Types of Internal Stages¶

Snowflake supports the following types of internal stages:

User

Table

Named

By default, each user and table in Snowflake is automatically allocated an internal stage for staging data files to be loaded. In addition, you can create named internal stages.

File staging information is required during both steps in the data loading process:

You must specify an internal stage in the PUT command when uploading files to Snowflake.
You must specify the same stage in the COPY INTO <table> command when loading data into a table from the staged files.

Consider the best type of stage for specific data files. Each option provides benefits and potential drawbacks.

User Stages¶

Each user has a Snowflake stage allocated to them by default for storing files. This stage is a convenient option if your files will only be accessed by a single user, but need to be copied into multiple tables.

User stages have the following characteristics and limitations:

User stages are referenced using @~; e.g. use LIST @~ to list the files in a user stage.
Unlike named stages, user stages cannot be altered or dropped.
User stages do not support setting file format options. Instead, you must specify file format and copy options as part of the COPY INTO <table> command.

This option is not appropriate if:

Multiple users require access to the files.
The current user does not have INSERT privileges on the tables the data will be loaded into.

Table Stages¶

Each table has a Snowflake stage allocated to it by default for storing files. This stage is a convenient option if your files need to be accessible to multiple users and only need to be copied into a single table.

Table stages have the following characteristics and limitations:

Table stages have the same name as the table; e.g. a table named mytable has a stage referenced as @%mytable.
Unlike named stages, table stages cannot be altered or dropped.
Table stages do not support transforming data while loading it (i.e. using a query as the source for the COPY command).

Note that a table stage is not a separate database object; rather, it is an implicit stage tied to the table itself. A table stage has no grantable privileges of its own. To stage files to a table stage, list the files, query them on the stage, or drop them, you must be the table owner (have the role with the OWNERSHIP privilege on the table).

This option is not appropriate if you need to copy the data in the files into multiple tables.

Named Stages¶

Named stages are database objects that provide the greatest degree of flexibility for data loading:

Users with the appropriate privileges on the stage can load data into any table.
Because the stage is a database object, the security/access rules that apply to all objects apply. The privileges to use a stage can be granted or revoked from roles. In addition, ownership of the stage can be transferred to another role.

If you plan to stage data files that will be loaded only by you, or will be loaded only into a single table, then you may prefer to simply use either your user stage or the stage for the table into which you will be loading data.

Named stages are optional but recommended when you plan regular data loads that could involve multiple users and/or tables. For instructions on creating a named stage, see Creating a Named Stage below.

Creating a Named Stage¶

You can create a named internal stage using SQL or the web interface.

Note

You must use a role that is granted or inherits the USAGE privilege on the database and schema that store the stage and the CREATE STAGE privilege on the schema.

Refer to Access Control Requirements for CREATE STAGE.

Create a Named Stage Using SQL¶

Use the CREATE STAGE command to create a named stage using SQL.

The following example creates an internal stage that references the named file format object called my_csv_format that was created in Preparing to Load Data:

CREATE OR REPLACE STAGE my_stage
  FILE_FORMAT = my_csv_format;

Copy

Note

By specifying a named file format object (or individual file format options) for the stage, it is not necessary to later specify the same file format options in the COPY command used to load data from the stage.

The following example creates an internal stage that specifies ad hoc file format options rather than referencing a named file format. Data files in this stage have a CSV format and a pipe (|) field delimiter. When this stage is referenced, the COPY command skips the first line in the data files:

CREATE OR REPLACE STAGE my_stage
  file_format = (type = 'CSV' FIELD_DELIMITER = '|' SKIP_HEADER = 1);

Copy

Create a Named Stage Using Snowsight¶

To use Snowsight to create a named internal stage, do the following:

Sign in to Snowsight.
Select Data » Databases.
Select the database and schema where you want to create a stage.
Select Create » Stage » Snowflake Managed.
Enter a Stage Name.
Optionally deselect Directory table. Directory tables let you see files on the stage, but require a warehouse and thus incur a cost. You can choose to deselect this option for now and enable a directory table later.
Select the type of Encryption supported for all files on your stage. For details, see encryption for internal stages. You cannot change the encryption type after you create the stage.

Note

To enable data access, we recommend that you select server-side encryption. Otherwise, staged files are client-side encrypted by default and unreadable when downloaded. For more information, see Server-side Encryption for Unstructured Data Access.
Complete the fields to describe your stage. For more information, refer to CREATE STAGE.
Select Create.

Create a Named Stage Using Classic Console¶

Select Databases » <db_name> » Stages.

Next: Staging Data Files from a Local File System