COPY FILES¶

语法¶

从暂存区复制

COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
  FROM @[<namespace>.]<stage_name>[/<path>/]
  [ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
  [ PATTERN = '<regex_pattern>' ]
  [ DETAILED_OUTPUT = { TRUE | FALSE } ]

从查询复制

COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
  FROM ( SELECT <existing_url> [ , <new_filename> ] FROM ... )
  [ DETAILED_OUTPUT = { TRUE | FALSE } ]

必填参数¶

INTO @[namespace.]stage_name[/path/]

指定复制文件的目标位置。

• namespace 是内部或外部暂存区所在的数据库或架构，形式为 database_name.schema_name 或 schema_name。如果数据库和架构现在正在用户会话中使用，则命名空间为 可选；否则，为必填。

• path 是云存储位置中一个可选且区分大小写的路径，用于指定要从源暂存区或目标暂存区的特定位置复制的一组文件。您的云存储服务可能会将路径称为 前缀 或 文件夹。

备注

• 如果目标或源路径名包含特殊字符或空格，则必须将 INTO ... 值放在单引号里。

• INTO ... 的值必须是字面量常量。这些值不能是 SQL 变量。

可选参数¶

FILES = ( 'file_name' [ , 'file_name' ... ] )

指定要复制的一个或多个用逗号分隔的文件名的列表。这些文件必须已暂存到您在命令中指定的源位置。Snowflake 会跳过任何无法找到的指定文件。

您最多可以指定 1000 个文件名。

从查询复制文件不支持此选项。请使用查询来提供文件名列表。

备注

要设置外部暂存区的文件路径，Snowflake 会将暂存区定义中的 URL 添加到列表中的每个文件名前面。

但是，Snowflake 不会在路径和文件名之间插入分隔符。您必须在暂存区定义中 URL 的末尾或此 FILES 列表中每个文件名开头显式插入分隔符 (/)。

PATTERN = 'regex_pattern'

指定用于筛选要复制的文件列表的正则表达式模式。此命令将正则表达式应用于 FROM 子句中的整个存储位置。

从查询复制文件不支持此选项。相反，使用查询来匹配模式。

小技巧

为了获得最佳性能，请避免对大量文件进行筛选的模式。

DETAILED_OUTPUT = { TRUE | FALSE }

指定命令输出是应汇总复制操作的结果，还是列出复制的每个文件。

值:

• 如果是 TRUE，则输出包含复制到目标位置的每个文件的行。名为 file 的单个列包含每个复制文件的目标路径（如果适用）和文件名。

• 如果是 FALSE，则输出为单行，其中包含已复制的文件数。

默认值:

TRUE

访问控制要求¶

用于执行此 SQL 命令的 :ref:` 角色 <label-access_control_overview_roles>` 必须至少具有以下 :ref:` 权限 <label-access_control_overview_privileges>` （取决于源位置和目标位置）：

要对架构中的任何对象执行操作，需要对父数据库和架构的 USAGE 权限。

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

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

使用说明¶

• 此命令不支持以下操作：

  • 将文件复制到 表 暂存区或从中复制文件。

  • 使用暂存区作为源时，将文件复制到 用户 暂存区或从中复制文件。

  • 复制归档云存储类中保存的数据，这些数据需要恢复后才能检索。存档存储类包括 Amazon S3 Glacier Flexible Retrieval、Glacier Deep Archive 或 Microsoft Azure Archive Storage。

  • 复制大于 5GB 的文件。

• 运行此命令的注意事项：

  • COPY FILES 语句将覆盖目标位置中名称匹配的任何现有文件。此命令 不 移除与复制文件的名称不匹配的任何现有文件。

  • 如果文件复制操作失败，Snowflake 不会执行任何自动清理。

  • 从 Google Cloud Storage 复制文件：如果外部暂存区的对象列表包含一个或多个目录 Blob，COPY FILES 语句可能会失败。目录 Blob 是以正斜杠字符 (/) 结尾的路径。在 LIST @<stage> 的以下示例输出中，my_gcs_stage/load/ 是一个目录 Blob。

    +---------------------------------------+------+----------------------------------+-------------------------------+
    | name                                  | size | md5                              | last_modified                 |
    |---------------------------------------+------+----------------------------------+-------------------------------|
    | my_gcs_stage/load/                    |  12  | 12348f18bcb35e7b6b628ca12345678c | Mon, 11 Aug 2022 16:57:43 GMT |
    | my_gcs_stage/load/data_0_0_0.csv.gz   |  147 | 9765daba007a643bdff4eae10d43218y | Mon, 11 Aug 2022 18:13:07 GMT |
    +---------------------------------------+------+----------------------------------+-------------------------------+
    

    使用 Google Cloud Console 创建目录时，Google 会创建目录 Blob。

    要避免此问题并指定要复制哪些文件，请使用 PATTERN 选项（用于从暂存区复制）或 :samp:`FROM`（用于从查询复制）。

    有关示例，请参阅 使用模式匹配复制文件。

• COPY FILES 命令会产生数据传输和计算成本：

  • 数据传输：云提供商可能会对传输到其自身网络以外的数据收费。为收回这些费用，当您将文件从内部 Snowflake 暂存区复制到不同 区域 或不同云提供商的外部暂存区时，Snowflake 会按字节收费。Snowflake 不对数据入口收费（例如，将文件从外部暂存区复制到内部暂存区时）。

    有关数据传输计费的更多信息，请参阅 了解数据传输成本。

  • 计算：COPY FILES 是一个 无服务器 功能，不需要虚拟仓库。Snowflake 账单上的 COPY FILES 命令的行项目不包括任何云服务费用。

    有关计算资源计费的更多信息，请参阅 了解计算成本。

  备注

  某些 Snowflake 功能（例如 Native App 和工作表）会产生 COPY FILES 收费。因此，即使您尚未执行 COPY FILES 命令，您也可能会看到 COPY FILES 费用。有关这些费用的更多信息，请联系 ` Snowflake 支持 `_。

• Snowflake 不维护此命令的文件复制历史记录。

示例¶

COPY FILES
  INTO @trg_stage
  FROM @src_stage;

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  FILES = ('file1.csv', 'file2.csv');

COPY FILES
  INTO @trg_stage/trg_path/
  FROM @src_stage/src_path/;

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  PATTERN='.*/.*/.*[.]csv[.]gz';

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  PATTERN='.*sales.*[.]csv';

COPY FILES
  INTO @trg_stage
  FROM (SELECT '@src_stage/file.txt');

COPY FILES
  INTO @trg_stage
  FROM (SELECT '@src_stage/file.txt', 'new_filename.txt');

-- Create a table with URLs
CREATE TABLE urls(src_file STRING, trg_file STRING);
INSERT INTO urls VALUES ('@src_stage/file.txt', 'new_filename.txt');

-- Insert additional URLs here
COPY FILES
  INTO @trg_stage
  FROM (SELECT src_file, trg_file FROM urls);

COPY FILES
  INTO @trg_stage
  FROM (SELECT src_file, trg_file FROM urls WHERE src_file LIKE '%file%');

COPY FILES
  INTO @trg_stage
  FROM (SELECT relative_path FROM directory(@src_stage) WHERE relative_path LIKE '%.txt');