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 } ]

必填参数¶

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

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

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

指定要暂存复制的文件的源位置。

对于 INTO 和 FROM 参数：

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

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

  备注

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

  • INTO ... 和 FROM ... 的值必须是字面量常量。这些值不能是 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 选项指定要复制的文件。有关示例，请参阅 使用模式匹配复制文件。

• 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';