PUT¶

语法¶

PUT file://<absolute_path_to_file>/<filename> internalStage
    [ PARALLEL = <integer> ]
    [ AUTO_COMPRESS = TRUE | FALSE ]
    [ SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE ]
    [ OVERWRITE = TRUE | FALSE ]

其中：

internalStage ::=
    @[<namespace>.]<int_stage_name>[/<path>]
  | @[<namespace>.]%<table_name>[/<path>]
  | @~[/<path>]

Copy

必填参数¶

file://absolute_path_to_file/filename

指定客户端计算机上的数据文件 URI，其中：

• absolute_path_to_file 是要上传的文件的本地目录路径。

• filename 是要上传的文件的名称。您可以使用通配符（*、?）上传多个文件。如果目录路径或文件名包含特殊字符或空格，请将整个文件 URI 放在单引号中。

  注意

  使用 PUT 查询时要谨慎选择多个文件。匹配大量文件的 PUT 查询可能会产生高昂成本和显著的性能后果。

URI 格式因客户端操作系统而异：

Linux/macOS:

从根目录 (/) 指定文件的绝对路径。例如，对于名为 my-data.csv 的文件，应使用 file:///my/file/path/my-data.csv。

Windows:

指定从文件所在的驱动器根开始的绝对路径。例如，对于名为 file://C:temp\my-data.csv 的文件，应使用 。

如果文件路径包含特殊字符，您必须将整个路径放在引号里，并将驱动器和路径分隔符从后斜杠更改为前斜杠 (/)。例如，对于名为 my$data.csv 的文件，请使用：'file://C:/temp/my$data.csv'。

备注

Snowflake 不支持 tar（磁带归档）文件。

internalStage

指定要将文件上传到的内部暂存区位置：

@[namespace.]int_stage_name[/path]	文件将上传到指定的命名内部暂存区。
@[namespace.]%table_name[/path]	文件将上传到指定表的暂存区。
@~[/path]	文件将上传到当前用户的暂存区。

其中：

• namespace 是包含已命名的内部暂存区或表的数据库或架构。如果数据库和架构当前正在用户会话中使用，则此参数为 选填。

• path 是云存储位置中文件的可选路径且区分大小写，用于限制对一组文件的访问。不同的云存储服务也可以将路径称为 前缀 或 文件夹。

备注

如果暂存区名称或路径包含空格或特殊字符，则应将其放在单引号内。例如，对于名为 "my stage" 的暂存区，应使用 '@"my stage"'。

可选参数¶

PARALLEL = integer

指定用于上传文件的线程数。Snowflake 会按文件大小分批上传数据文件：

• 小于 64 MB 的文件（无论压缩与否）作为单独的文件并行暂存。

• 较大的文件会自动分割成块，同时暂存，然后在目标暂存区进行重组。单个线程可以上传多个块。

增加线程数可以提高上传大文件时的性能。

支持的值：从 1 （无并行性）到 99 （使用 99 个线程上传文件）之间的任何整数值。

默认：4

备注

旧版本的 Snowflake 驱动程序有 16 MB 的限制，这些版本包括：

• 3.12.1 之前的 JDBC 驱动程序版本。

• 2.20.5 之前的 ODBC 驱动程序版本。

• 2.2.0 之前的 Python Connector 版本。

AUTO_COMPRESS = TRUE | FALSE

指定 Snowflake 在上传过程中是否使用 gzip 来压缩文件：

• TRUE：Snowflake 压缩文件（如果文件尚未压缩）。

• FALSE：Snowflake 不压缩文件。

此选项不支持其他压缩类型。要使用其他压缩类型，请在执行 PUT 命令之前单独压缩文件。然后，使用 SOURCE_COMPRESSION 选项确定压缩类型。

请确保您的本地文件夹有足够的空间，以便 Snowflake 在暂存数据文件之前将其压缩。如有必要，请在操作系统中设置 TEMP、TMPDIR 或 TMP 环境变量，指向包含额外可用空间的本地文件夹。

默认：TRUE

SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

指定对正在暂存的已压缩文件使用的压缩方法：

支持的值	备注
AUTO_DETECT	压缩算法会自动检测，但 Brotli 压缩文件除外（目前无法自动检测）。如果加载 Brotli 压缩的文件，请显式使用 BROTLI，而不是 AUTO_DETECT。
GZIP	不支持 *.tar.gz 文件格式。
BZ2	不支持 *.tar.bz2 文件格式。
BROTLI	上传 Brotli 压缩的文件时必须使用此值。
ZSTD	支持 Zstandard v0.8（及更高版本）。
DEFLATE	使用 Deflate 压缩的文件（带有 zlib 标头、RFC1950）。
RAW_DEFLATE	使用 Raw Deflate 压缩的文件（无标头、RFC1951）。
NONE	数据文件尚未压缩。

默认：AUTO_DETECT

备注

Snowflake 使用此选项来检测数据文件的压缩方式，以便将文件解压缩并提取数据进行上传；Snowflake 不 使用此选项来压缩文件。

目前不支持加载使用其他实用程序压缩的文件。

OVERWRITE = TRUE | FALSE

指定 Snowflake 是否在上传过程中覆盖同名的现有文件：

• TRUE：覆盖同名的现有文件。

• FALSE：不覆盖同名的现有文件。

  Snowflake 在后台对暂存区进行 LIST 操作，可能会影响 PUT 操作的性能。

  如果由于目标暂存区存在同名文件而导致 PUT 文件尝试失败，您可以使用以下选项：

  • 将现有文件中的数据加载到一个或多个表中，然后从暂存区移除该文件。然后，执行 PUT 操作，将包含新数据或更新数据的文件放入暂存区。

  • 重命名本地文件，然后再次尝试 PUT 操作。

  • 在 PUT 语句中设置 OVERWRITE = TRUE。仅当使用相同名称覆盖现有（暂存）文件时，才执行此操作。

如果您的 Snowflake 账户托管在 Google Cloud 上，当 OVERWRITE 参数设置为 TRUE 时，PUT 语句将无法识别。PUT 操作 总是 用您正在上传的本地文件覆盖目标暂存区中的任何现有文件。

以下客户端支持托管在 Amazon Web Services 或 Microsoft Azure 上的 Snowflake 账户的 OVERWRITE 选项：

• SnowSQL

• Snowflake ODBC 驱动程序

• Snowflake JDBC 驱动程序

• Snowflake Connector for Python

支持的值：TRUE、FALSE

默认：FALSE。

使用说明¶

• 该命令无法从任一 Snowflake Web 界面中的 Worksheets 页面执行；请改用 SnowSQL 客户端 或 驱动程序 上传数据文件，或查看特定 Snowflake 客户端的文档以验证是否支持此命令。

  或者，您可以 使用 Snowsight UI 将文件上传到名称内部暂存区。

• Snowflake 支持使用通配符等文件匹配模式，但 不支持 上传来自不同目录路径的多个文件。这是因为在将文件上传到暂存区时，Snowflake 不会保留原始文件系统的目录结构。

  例如，下面的 PUT 语句会返回一个错误，因为您不能在嵌套子目录中指定多个文件。

  PUT file:///tmp/data/** @my_int_stage AUTO_COMPRESS=FALSE;
  

  Copy

• 该命令 :emph:` 不会 ` 创建或重命名文件。

• 内部暂存区中用于数据加载和卸载操作的所有文件都会在服务器端使用 AES-256 强加密自动加密。默认情况下，Snowflake 使用 128 位密钥（可选择配置 256 位密钥）提供额外的客户端加密。有关更多信息，请参阅 内部暂存区的加密类型。

• 该命令将忽略您尝试上传到同一暂存区的重复文件。重复文件是与已暂存文件同名的未经修改的文件。

  要覆盖已暂存文件，您必须修改正在上传的文件，使其内容与暂存文件不同，从而为新的暂存文件产生新的校验和。

• 对于 PUT 和 GET 命令，QUERY_HISTORY 中 success 的 EXECUTION_STATUS 并 不 表示已成功上传或下载数据文件。相反，该状态表示 Snowflake 已收到继续进行文件传输的授权。

示例¶

PUT file:///tmp/data/mydata.csv @my_int_stage;

PUT file:///tmp/data/orders_001.csv @%orderstiny_ext
  AUTO_COMPRESS = FALSE;

PUT file:///tmp/data/orders_*01.csv @my_int_stage
  AUTO_COMPRESS = FALSE;

PUT 'file:///tmp/data/orders 001.csv' @my_int_stage
  AUTO_COMPRESS = FALSE;

PUT file://C:\temp\data\mydata.csv @~
  AUTO_COMPRESS = TRUE;

PUT 'file://C:/temp/data/my data.csv' @my_int_stage
  AUTO_COMPRESS = TRUE;