Choosing a 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.

In this Topic:

Types of Stages

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.

A user’s stage does 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.

A table’s stage does not support setting file format options. Instead, you must specify file format and copy options as part of the COPY INTO <table> 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, you must have OWNERSHIP of the table itself.

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

Internal Named Stages

Internal stages are named database objects that provide the greatest degree of flexibility for data loading. Because they are database objects, the security/access rules that apply to all objects apply:

  • Users with the appropriate privileges on the stage can load data into any table.
  • Ownership of the stage can be transferred to another role, and privileges granted to use the stage can be modified to add or remove roles.
  • When you create a stage, you must explicitly grant privileges on the stage to one or more roles before users with those roles can use the stage.

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 internal 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 Stage below.

Creating a Stage

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

Web Interface:Click on Databases Databases tab » <db_name> » Stages
SQL:CREATE STAGE

Creating a Named 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;

Note

By specifying a named file format object (or individual file format options) for the stage, it isn’t 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);

Next: Staging Data Files from a Local File System