CREATE STAGE¶

语法¶

-- Internal stage
CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] STAGE [ IF NOT EXISTS ] <internal_stage_name>
    internalStageParams
    directoryTableParams
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

-- External stage
CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] STAGE [ IF NOT EXISTS ] <external_stage_name>
    externalStageParams
    directoryTableParams
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

其中：

internalStageParams ::=
  [ ENCRYPTION = (TYPE = 'SNOWFLAKE_FULL' | TYPE = 'SNOWFLAKE_SSE') ]

Copy

externalStageParams (for Amazon S3) ::=
  URL = { 's3://<bucket>[/<path>/]' | 's3gov://<bucket>[/<path>/]' }

  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( {  { AWS_KEY_ID = '<string>' AWS_SECRET_KEY = '<string>' [ AWS_TOKEN = '<string>' ] } | AWS_ROLE = '<string>'  } ) } ]
  [ ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] |
                   [ TYPE = 'AWS_SSE_S3' ] |
                   [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] ] |
                   [ TYPE = 'NONE' ] ) ]

Copy

externalStageParams (for Google Cloud Storage) ::=
  URL = 'gcs://<bucket>[/<path>/]'
  [ STORAGE_INTEGRATION = <integration_name> ]
  [ ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = 'NONE' ] ) ]

Copy

externalStageParams (for Microsoft Azure) ::=
  URL = 'azure://<account>.blob.core.windows.net/<container>[/<path>/]'
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( [ AZURE_SAS_TOKEN = '<string>' ] ) } ]
   [ ENCRYPTION = ( [ TYPE = 'AZURE_CSE' ] [ MASTER_KEY = '<string>' ] | [ TYPE = 'NONE' ] ) ]

Copy

externalStageParams (for Amazon S3-compatible Storage) ::=
  URL = 's3compat://{bucket}[/{path}/]'
  ENDPOINT = '<s3_api_compatible_endpoint>'
  [ { CREDENTIALS = ( AWS_KEY_ID = '<string>' AWS_SECRET_KEY = '<string>' ) } ]

Copy

directoryTableParams (for internal stages) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ REFRESH_ON_CREATE =  { TRUE | FALSE } ] ) ]

Copy

directoryTableParams (for Amazon S3) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ REFRESH_ON_CREATE =  { TRUE | FALSE } ]
                  [ AUTO_REFRESH = { TRUE | FALSE } ] ) ]

Copy

directoryTableParams (for Google Cloud Storage) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ AUTO_REFRESH = { TRUE | FALSE } ]
                  [ REFRESH_ON_CREATE =  { TRUE | FALSE } ]
                  [ NOTIFICATION_INTEGRATION = '<notification_integration_name>' ] ) ]

Copy

directoryTableParams (for Microsoft Azure) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ REFRESH_ON_CREATE =  { TRUE | FALSE } ]
                  [ AUTO_REFRESH = { TRUE | FALSE } ]
                  [ NOTIFICATION_INTEGRATION = '<notification_integration_name>' ] ) ]

Copy

必填参数¶

internal_stage_name 或 . external_stage_name

指定暂存区的标识符；对于在其中创建暂存区的架构来说，此标识符必须唯一。

此外，标识符必须以字母字符开头，且不能包含空格或特殊字符，除非整个标识符字符串放在双引号内（例如，"My object"）。放在双引号内的标识符也区分大小写。

有关更多详细信息，请参阅 标识符要求。

可选参数¶

{ TEMP | TEMPORARY }

指定所创建是临时暂存区，将在创建该暂存区的会话结束时删除。注意：

• 在临时 * 外部 * 暂存区被删除时，删除的只有暂存区本身；数据文件不会被移除。

• 在临时 * 内部 * 暂存区被删除时，暂存区内的所有文件都会从 Snowflake 中被清除，无论其加载状态如何。这可以防止处于临时内部暂存区的文件占用数据存储，从而产生存储费用。但这也意味着一旦暂存区被删除，就无法通过 Snowflake 恢复暂存文件。

  小技巧

  如果计划创建和使用临时内部暂存区，则应在 Snowflake 之外维护数据文件的副本。

COMMENT = 'string_literal'

为暂存区指定注释。

默认：无值

TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] )

指定 标签 名称和标签字符串值。

标签值始终为字符串，标签值的最大字符数为 256。

有关在语句中指定标签的信息，请参阅 对象和列的标签配额。

内部暂存区参数 (internalStageParams)¶

[ ENCRYPTION = (TYPE = 'SNOWFLAKE_FULL' | TYPE = 'SNOWFLAKE_SSE') ]

指定暂存区上存储的所有文件支持的加密类型。创建暂存区后，无法更改加密类型。

TYPE = ...

指定使用的加密类型。

可能的值：

• SNOWFLAKE_FULL：客户端和服务器端加密。在客户端使用 PUT 将文件上传到内部暂存区时，由客户端对这些文件进行加密。Snowflake 默认使用 128 位加密密钥。可以通过设置 CLIENT_ENCRYPTION_KEY_SIZE 参数来配置 256 位密钥。

  所有文件也都会使用服务器端的 AES-256 强加密机制自动加密。

• SNOWFLAKE_SSE：仅限服务器端加密。当文件到达暂存区时，您的 Snowflake 账户所在的云服务会对其进行加密。

  如果计划查询暂存文件的预签名 URLs，请指定服务器端加密。有关更多信息，请参阅 可用于访问文件的 URLs 类型。

默认：SNOWFLAKE_FULL

外部暂存区参数 (externalStageParams)¶

URL = 'cloud_specific_url'

如果省略此参数，Snowflake 将创建一个内部暂存区

重要

• 将 URL 放在单引号 ('') 内，以便 Snowflake 识别字符串。如果省略了引号，您提供的任何凭据都可能以纯文本形式显示在历史记录中。强烈建议在执行 CREATE STAGE 语句之前验证其语法。

  在 Snowflake Web 界面中创建暂存区时，该界面会按需自动将字段值放在引号字符之间。

• 追加正斜杠 (/) 到 URL，以筛选到指定的文件夹路径。如果省略正斜杠，则包含以指定路径的前缀开头的所有文件和文件夹。

  请注意，必须添加 正斜杠才能访问和检索暂存区中的非结构化数据文件。

Amazon S3

URL = { 's3://{bucket}[/{path}/]' | 's3gov://{bucket}[/{path}/]' }

指定用于存储数据文件以进行加载/卸载的外部位置（现有 S3 桶）的 URL，其中：

• s3 前缀代表公共 AWS 区域中的 S3 存储。

  s3gov 前缀代表 政府区域 中的 S3 存储。请注意，目前只能通过在 AWS 的同一政府区域上托管的 Snowflake 账户，使用存储集成访问政府区域中的 AWS S3 存储。支持使用直接凭据从政府区域之外托管的账户访问 S3 存储。

• bucket 是 S3 桶的名称。

• path 是云存储位置中文件（即文件的名称以通用字符串开头）的可选区分大小写的路径，用于限制文件集。不同的云存储服务也可以将路径称为 前缀 或 文件夹。

Google Cloud Storage

URL = 'gcs://bucket[/path/]'

指定用于存储数据文件以进行加载/卸载的外部位置（现有 GCS 桶）的 URL，其中：

• bucket 是 GCS 桶的名称。

• path 是云存储位置中文件（即文件的名称以通用字符串开头）的可选区分大小写的路径，用于限制文件集。不同的云存储服务也可以将路径称为 前缀 或 文件夹。

Microsoft Azure

URL = 'azure://account.blob.core.windows.net/container[/path/]'

指定用于存储数据文件以进行加载的外部位置（现有 Azure 容器）的 URL，其中：

• account 是 Azure 账户的名称（例如 myaccount）。将 blob.core.windows.net 端点用于所有受支持类型的 Azure Blob 存储账户，包括 Data Lake Storage Gen2。

  请注意，目前只能通过在 Azure 同一政府区域中托管的 Snowflake 账户，使用存储集成访问 政府区域 中的 Azure Blob 存储。支持使用直接凭据从政府区域外部托管的账户访问 Blob 存储。

• container 是 Azure 容器的名称（例如 mycontainer）。

• path 是云存储位置中文件（即文件的名称以通用字符串开头）的可选区分大小写的路径，用于限制文件集。不同的云存储服务也可以将路径称为 前缀 或 文件夹。

默认：无值（创建内部暂存区）

STORAGE_INTEGRATION = integration_name 或 . CREDENTIALS = ( cloud_specific_credentials )

仅有私有/受保护的存储位置才需要；公共存储桶/容器不需要

Amazon S3

STORAGE_INTEGRATION = integration_name

指定将外部云存储的身份验证责任委托给 Snowflake Identity and Access Management (IAM) 实体的存储集成的名称。有关更多详细信息，请参阅 CREATE STORAGE INTEGRATION。

备注

• 我们强烈建议使用存储集成。此选项避免了在创建暂存或加载数据时使用 CREDENTIALS 参数提供云存储凭据的需要。

• 只能通过在 AWS 同一政府区域中托管的 Snowflake 账户，使用存储集成访问政府区域中的 S3 存储。支持使用直接凭据从政府区域之外托管的账户访问 S3 存储。

CREDENTIALS = ( AWS_KEY_ID = 'string' AWS_SECRET_KEY = 'string' [ AWS_TOKEN = 'string' ] ) 或 . CREDENTIALS = ( AWS_ROLE = 'string' )

指定用于连接 AWS 和访问暂存要加载/卸载的文件的私有/受保护的 S3 桶的安全凭证。有关更多信息，请参阅 配置对 Amazon S3 的安全访问。

您指定的凭证取决于您是否将桶的 Snowflake 访问权限与 AWS IAM (Identity & Access Management) 用户或角色关联：

• IAM ** 用户： ** IAM 凭据是必需的。临时（又名“作用域”）凭据由 AWS Security Token Service (STS) 生成，由三个组件组成：

  • AWS_KEY_ID

  • AWS_SECRET_KEY

  • AWS_TOKEN

  访问专用/受保护的桶 需要 这三个组件。指定时间段后，临时凭证将过期，无法再使用。然后，您必须生成一组新的有效临时凭据。

  重要

  COPY 命令还允许使用永久（又名“长期”）凭据；但是，出于安全原因，Snowflake 不 建议使用它们。如果必须使用永久凭据，Snowflake 建议定期为外部暂存区生成新的永久凭据。

• IAM 角色： 省略安全凭证和访问密钥，而是使用 AWS_ROLE 并指定 AWS 角色 ARN (Amazon Resource Name) 来标识角色。

Google Cloud Storage

STORAGE_INTEGRATION = integration_name

指定将外部云存储的身份验证责任委托给 Snowflake Identity and Access Management (IAM) 实体的存储集成的名称。有关更多详细信息，请参阅 CREATE STORAGE INTEGRATION。

Microsoft Azure

STORAGE_INTEGRATION = integration_name

指定将外部云存储的身份验证责任委托给 Snowflake Identity and Access Management (IAM) 实体的存储集成的名称。有关更多详细信息，请参阅 CREATE STORAGE INTEGRATION。

备注

• 我们强烈建议使用存储集成。此选项避免了在创建暂存或加载数据时使用 CREDENTIALS 参数提供云存储凭据的需要。

• 使用存储集成访问 政府区域 中的 Azure Blob 存储时，只能使用 Azure 在同一政府区域中托管的 Snowflake 账户。支持使用直接凭据从政府区域外部托管的账户访问 Blob 存储。

CREDENTIALS = ( AZURE_SAS_TOKEN = 'string' )

指定 SAS（共享访问签名）令牌，用于连接到 Azure 并访问暂存包含已加载数据的文件的专用/受保护容器。凭据由 Azure 生成。

默认：无值（未为外部暂存区提供凭据）

ENCRYPTION = ( cloud_specific_encryption )

仅从加密文件加载/卸载时需要；如果存储位置和文件未加密，则不需要

数据加载:

修改用于解密存储位置中的加密文件和提取数据的加密设置。

数据卸载:

修改用于加密卸载到存储位置的文件的加密设置。

Amazon S3

ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] | [ TYPE = 'AWS_SSE_S3' ] | [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] ] | [ TYPE = 'NONE' ] )

TYPE = ...

指定使用的加密类型。可能的值：

• AWS_CSE：客户端加密（需要一个 MASTER_KEY 值）。目前，您提供的客户端 ` 主密钥 <https://csrc.nist.gov/glossary/term/master_key (https://csrc.nist.gov/glossary/term/master_key)>`_ 只能是对称密钥。请注意，当提供 MASTER_KEY 值时，Snowflake 假定 TYPE = AWS_CSE （即，当提供 MASTER_KEY 值时，不需要 TYPE）。

• AWS_SSE_S3：不需要其他加密设置的服务器端加密。

• AWS_SSE_KMS：接受可选的 KMS_KEY_ID 值服务端加密。

有关加密类型的详细信息，请参阅 ` 客户端加密 <http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingClientSideEncryption.html (http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingClientSideEncryption.html)>`_ 或 ` 服务器端加密 <http://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html (http://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html)>`_ 的 AWS 文档。

• NONE：无加密。

MASTER_KEY = 'string' （仅适用于 AWS_CSE 加密）

指定用于加密桶中文件的客户端主密钥。主密钥必须是 Base64 编码形式的 128 位或 256 位密钥。

KMS_KEY_ID = 'string' （仅适用于 AWS_SSE_KMS 加密）

（可选）指定用于加密 卸载 到桶中的文件的 AWS KMS 托管密钥的 ID。如果未提供任何值，则默认 KMS 密钥 ID 用于在卸载时加密文件。

请注意，数据加载时会忽略此值。

Google Cloud Storage

ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' | 'NONE' ] [ KMS_KEY_ID = 'string' ] )

TYPE = ...

指定使用的加密类型。可能的值：

• GCS_SSE_KMS：接受可选的 KMS_KEY_ID 值服务端加密。

  有关更多信息，请参阅 Google Cloud Platform 文档：

  • https://cloud.google.com/storage/docs/encryption/customer-managed-keys (https://cloud.google.com/storage/docs/encryption/customer-managed-keys)

  • https://cloud.google.com/storage/docs/encryption/using-customer-managed-keys (https://cloud.google.com/storage/docs/encryption/using-customer-managed-keys)

• NONE：无加密。

KMS_KEY_ID = 'string' （仅适用于 GCS_SSE_KMS 加密）

（可选）指定用于加密 卸载 到桶中的文件的 Cloud KMS 托管密钥的 ID。如果未提供任何值，则桶中默认设置的 KMS 密钥 ID 用于在卸载时加密文件。

请注意，数据加载时会忽略此值。如果服务账户有足够的权限来解密桶中的数据，则加载操作应会成功。

Microsoft Azure

ENCRYPTION = ( [ TYPE = 'AZURE_CSE' | 'NONE' ] [ MASTER_KEY = 'string' ] )

TYPE = ...

指定使用的加密类型。可能的值：

• AZURE_CSE：客户端加密（需要一个 MASTER_KEY 值）。有关信息，请参阅 Microsoft Azure 文档中的 ` 客户端加密信息 <https://docs.microsoft.com/en-us/azure/storage/common/storage-client-side-encryption (https://docs.microsoft.com/en-us/azure/storage/common/storage-client-side-encryption)>`_。

• NONE：无加密。

MASTER_KEY = 'string' （仅适用于 AZURE_CSE 加密）

指定用于加密或解密文件的客户端主密钥。主密钥必须是 Base64 编码形式的 128 位或 256 位密钥。

兼容 Amazon S3 的存储的外部暂存区参数 (externalStageParams)¶

URL = 's3compat://bucket[/path/]'

指定用于存储数据文件的外部位置（使用 S3 兼容 API 端点访问的现有桶）的 URL，其中：

• bucket 是桶的名称。

• path 是云存储位置中的文件的可选区分大小写的路径（在 S3 术语中称为 * 前缀 *，即文件名称以通用字符串开头）。

ENDPOINT = 's3_api_compatible_endpoint'

指向 S3 兼容 API 端点的完全限定域名。

目录表参数 (directoryTableParams)¶

ENABLE = TRUE | FALSE

指定是否向暂存区添加 目录表。当值为 TRUE 时，将创建包含暂存区的目录表。

备注

与 S3 兼容的外部暂存区 不 支持将此参数设置为 TRUE。无法自动刷新与 S3 兼容的外部暂存区的元数据。

默认：FALSE

访问控制要求¶

用于执行此 SQL 命令的 角色 必须至少具有以下 权限：

请注意，对架构中的对象进行操作还需要对父数据库和架构具有 USAGE 权限。

有关创建具有指定权限集的自定义角色的说明，请参阅 创建自定义角色。

有关对 安全对象 执行 SQL 操作的相应角色和权限授予的一般信息，请参阅 访问控制概述。

使用说明¶

• CREATE STAGE 不会检查指定 URL 或凭据是否有效。如果凭据无效，在尝试使用暂存区时，系统将返回错误。

• 关于元数据：

  注意

  客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。

示例¶

CREATE STAGE my_int_stage
  ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE');

CREATE TEMPORARY STAGE my_temp_int_stage;