PUT¶
将数据文件从本地文件系统上传到以下 Snowflake 暂存区之一:
已命名的内部暂存区。
指定表的内部暂存区。
当前用户的内部暂存区。
您可以使用 COPY INTO <table> 命令将暂存文件加载到表中。
备注
PUT :emph:` 不 ` 支持将文件上传到外部暂存区。要将文件上传到外部暂存区,请使用云服务提供的实用程序。
ODBC 驱动程序 支持使用在以下平台上托管的 Snowflake 账户执行 PUT:
Amazon Web Services
Google Cloud Platform
Microsoft Azure
- 另请参阅:
语法¶
PUT file://<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>]
必填参数¶
file://path_to_file/filename
指定客户端计算机上的数据文件 URI,其中:
path_to_file
是要上传的文件的本地目录路径。filename
是要上传的文件的名称。您可以使用通配符(*
、?
)上传多个文件。如果目录路径或文件名包含特殊字符或空格,请将整个文件 URI 放在单引号中。
URI 格式因客户端操作系统而异:
- Linux/macOS:
您必须在路径开头包含正斜杠。例如,对于名为
load
的文件,应使用file:///tmp/load
。- Windows:
您必须在路径中包含驱动器和反斜杠,并将反斜杠字符替换为正斜杠。例如,对于名为
load data
的文件,应使用file://C:/temp/load data
。
internalStage
指定 Snowflake 中上传文件的位置:
@[namespace.]int_stage_name[/path]
文件将上传到指定的命名内部暂存区。
@[namespace.]%table_name[/path]
文件将上传到指定表的暂存区。
@~[/path]
文件将上传到当前用户的暂存区。
其中:
namespace
是包含已命名的内部暂存区或表的数据库或架构。如果数据库和架构当前正在用户会话中使用,则此参数为 选填。path
是云存储位置中文件的可选路径且区分大小写,用于限制对一组文件的访问。不同的云存储服务也可以将路径称为 前缀 或 文件夹。
备注
如果暂存区名称或路径包含空格或特殊字符,则应将其放在单引号内。例如,对于名为
"my stage"
的暂存区,应使用'@"my stage"'
。
可选参数¶
PARALLEL = integer
指定用于上传文件的线程数。上传过程会按文件大小分批上传数据文件:
小文件(小于 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
BZ2
BROTLI
加载 Brotli 压缩的文件时必须使用此值。
ZSTD
支持 Zstandard v0.8(及更高版本)。
DEFLATE
使用 Deflate 压缩的文件(带有 zlib 标头、RFC1950)。
RAW_DEFLATE
使用 Raw Deflate 压缩的文件(无标头、RFC1951)。
NONE
要加载的数据文件尚未压缩。
默认:
AUTO_DETECT
备注
Snowflake 使用此选项来检测数据文件的压缩方式,以便将文件解压缩并提取数据进行加载;Snowflake :emph:` 不 ` 使用此选项来压缩文件。
目前不支持上传使用其他实用程序压缩的文件。
OVERWRITE = TRUE | FALSE
指定 Snowflake 是否在上传过程中覆盖同名的现有文件:
TRUE
:覆盖同名的现有文件。FALSE
:不覆盖同名的现有文件。请注意,对暂存区进行的 LIST 操作在后台执行,可能会影响 PUT 操作的性能。
如果由于目标暂存区存在同名文件而导致 PUT 文件尝试失败,可以使用以下选项:
将现有文件中的数据加载到一个或多个表中,然后从暂存区移除该文件。然后,执行 PUT 操作,将包含新数据或更新数据的文件放入暂存区。
重命名本地文件,然后再次尝试 PUT 操作。
在 PUT 语句中设置
OVERWRITE = TRUE
。只有在使用可能尚未加载到 Snowflake 中的数据覆盖文件确实安全的情况下,才执行此操作。
请注意,对于托管在 Google Cloud Platform 上的 Snowflake 账户,当 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 客户端的文档以验证是否支持此命令。
该命令 不支持 上传具有不同目录路径的多个文件,因为它在将文件上传到您的暂存区时不会保留文件系统目录结构。
例如,下面的 PUT 语句会返回一个错误,因为您不能在嵌套子目录中指定多个文件。
PUT file:///tmp/data/** @my_int_stage AUTO_COMPRESS=FALSE;
支持文件通配符模式,除非与模式匹配的文件具有不同的目录路径。
该命令 :emph:` 不会 ` 创建或重命名文件。
内部暂存区中用于数据加载和卸载操作的所有文件都会在服务器端使用 AES-256 强加密自动加密。默认情况下,Snowflake 使用 128 位密钥(可选择配置 256 位密钥)提供额外的客户端加密。有关更多信息,请参阅 内部暂存区的加密类型。
该命令将忽略您尝试上传到同一暂存区的重复文件。重复文件是与已暂存文件同名的未经修改的文件。
要覆盖已暂存文件,您必须修改正在上传的文件,使其内容与暂存文件不同,从而为新的暂存文件产生新的校验和。
小技巧
出于安全原因,该命令会在设定的时间段后超时。加载大型且未压缩的数据文件时,可能会发生这种情况。为了避免出现超时问题,我们建议先使用受支持的压缩类型来压缩大型数据文件,再上传文件。然后,使用 SOURCE_COMPRESSION
选项指定文件的压缩类型。
您还可以考虑增加 PARALLEL
选项的值,这样有助于提高上传大型数据文件时的性能。
此外,为了在将数据加载到表中(使用 COPY INTO <table> 命令)时利用并行操作的优势,我们建议使用 :emph:` 压缩后 ` 大小在 100 到 250 MB 之间的数据文件。如果数据文件较大,请考虑使用第三方工具将其拆分为较小的文件,然后再压缩和上传。
示例¶
将 /tmp/data
目录中名为 mydata.csv
的文件(在 Linux 或 macOS 环境中)上传到名为 my_int_stage
的内部暂存区:
PUT file:///tmp/data/mydata.csv @my_int_stage;
将 /tmp/data
目录中名为 orders_001.csv
的文件(在 Linux 或 macOS 环境中)上传到 orderstiny_ext
表的暂存区,并禁用自动数据压缩:
PUT file:///tmp/data/orders_001.csv @%orderstiny_ext AUTO_COMPRESS=FALSE;
与上面的示例相同,但在文件名中使用了通配符,以便上传多个文件:
PUT file:///tmp/data/orders_*01.csv @%orderstiny_ext AUTO_COMPRESS=FALSE;
将 C:\temp\data
目录中名为 mydata.csv
的文件(在 Windows 环境中)上传到当前用户的暂存区,并启用自动数据压缩:
PUT file://C:/temp/data/mydata.csv @~ AUTO_COMPRESS=TRUE;
与上一个示例类似,但从 C:\temp\load data
目录中上传(在 Windows 环境中):
PUT 'file://C:/temp/load data/mydata.csv' @~ AUTO_COMPRESS=TRUE;