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:

  1. You must specify an internal stage in the PUT command when uploading files to Snowflake.

  2. 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 either the web interface or SQL:

Classic Console

Click on Databases Databases tab » <db_name> » Stages

SQL

CREATE STAGE

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

Next: Staging Data Files from a Local File System

Language: English