COPY INTO

适用于：选中标记为“是” Databricks SQL 选中标记为“是” Databricks Runtime

将文件位置中的数据加载到 Delta 表中。 这是可重试的幂等操作 – 会跳过已经加载的源位置中的文件。 即使文件自加载以来已被修改也是如此。 有关示例，请参阅使用 COPY INTO 的常见数据加载模式。

语法

COPY INTO target_table [ BY POSITION | ( col_name [ , <col_name> ... ] ) ]
  FROM { source_clause |
         ( SELECT expression_list FROM source_clause ) }
  FILEFORMAT = data_source
  [ VALIDATE [ ALL | num_rows ROWS ] ]
  [ FILES = ( file_name [, ...] ) | PATTERN = glob_pattern ]
  [ FORMAT_OPTIONS ( { data_source_reader_option = value } [, ...] ) ]
  [ COPY_OPTIONS ( { copy_option = value } [, ...] ) ]

source_clause
  source [ WITH ( [ CREDENTIAL { credential_name |
                                 (temporary_credential_options) } ]
                  [ ENCRYPTION (encryption_options) ] ) ]

参数

  • target_table

    标识现有的 Delta 表。 target_table不得包含临时规范或选项规范。

    如果表名称以位置的形式提供（例如 delta.`/path/to/table` ），则 Unity 目录可以控制对写入到的位置的访问。 可以通过以下方式写入到外部位置：

    • 将位置定义为外部位置并提供对该外部位置的 WRITE FILES 权限。

    • 拥有对命名存储凭据的 WRITE FILES 权限，以便提供使用 COPY INTO delta.`/some/location` WITH (CREDENTIAL <named-credential>) 写入到某个位置的授权

    有关更多详细信息，请参阅 使用 Unity 目录连接到云对象存储 。

  • BY POSITION | (col_name [ , <col_name> … ] )

    按位置顺序将源列与目标表列匹配。 会自动完成匹配列的类型转换。

    此参数仅支持无标头 CSV 文件格式。 需要指定 FILEFORMAT = CSV。 还需要将 FORMAT_OPTIONS 设置为 ("headers" = "false")（FORMAT_OPTIONS ("headers" = "false") 为默认值）。

    语法选项 1：BY POSITION

    • 自动按位置顺序将源列与目标表列匹配。
      • 该匹配不使用默认名称匹配。
      • 匹配源列时，将忽略目标表的 IDENTITY 列和 GENERATED 列。
      • 如果源列数不等于筛选的目标表列，则 COPY INTO 会引发错误。

    语法选项 2：( col_name [ , <col_name> ... ] )

    • 使用括号中的目标表列名称列表（用逗号分隔）按相对位置顺序将源列与指定的目标表列匹配。
      • 匹配时不使用原始表列顺序和列名称。
      • 列名称列表中不能指定 IDENTITY 列和 GENERATED 列，否则 COPY INTO 会引发错误。
      • 无法复制指定的列。
      • 当源列数不等于指定的表列时，COPY INTO 将引发错误。
      • 对于未在列名称列表中指定的列，COPY INTO 会分配默认值（如果有）或分配 NULL（如果没有）。 如果有任何列不可为 null，COPY INTO 将引发错误。

  • source

    要从中加载数据的文件位置。 此位置中的文件必须采用 FILEFORMAT 中指定的格式。 以 URI 的形式提供此位置。

    可通过以下命令提供对源位置的访问权限：

    • credential_name

      用于访问或写入存储位置的凭据的可选名称。 仅在文件位置未包含在外部位置中时才使用此凭据。 请参阅 credential_name。

    • 内联临时凭据。

    • 将源位置定义为外部位置，并通过 Unity 目录提供对外部位置的 READ FILES 权限。

    • 使用带 READ FILES 权限的命名存储凭据，这些权限提供通过 Unity 目录从位置进行读取所需的授权。

    如果路径已定义为你有权使用的外部位置，则无需提供内联或命名凭据。 有关更多详细信息 ，请参阅外部位置概述 。

    注意

    如果源文件路径为根路径，请在文件路径末尾添加斜杠 (/)，例如 s3://my-bucket/。

    接受的凭据选项如下：

    • 适用于 ADLS 和 Azure Blob 存储的 AZURE_SAS_TOKEN
    • 适用于 AWS S3 的 AWS_ACCESS_KEY、AWS_SECRET_KEY 和 AWS_SESSION_TOKEN

    接受的加密选项如下：

    • 适用于 AWS S3 的 TYPE = 'AWS_SSE_C' 和 MASTER_KEY

请参阅使用 COPY INTO 和临时凭据加载数据。

  • SELECT expression_list

    在复制到 Delta 表之前，从源数据中选择指定的列或表达式。 表达式可以是与 SELECT 语句一起使用的任何内容，包括窗口操作。 你只能将聚合表达式用于全局聚合 - 你不能在使用此语法的列上使用 GROUP BY。

  • FILEFORMAT = data_source

    要加载的源文件的格式。 CSV、JSON、AVRO、ORC、PARQUET、TEXT、BINARYFILE 之一。

  • VALIDATE

    适用于： Databricks SQL 选中标记为“是” Databricks Runtime 10.4 LTS 及更高版本check marked yes

    要加载到表中的数据会经过验证，但不写入表中。 这些验证包括：

    • 是否可以解析数据。
    • 架构是否与表匹配，或者架构是否需要演变。
    • 是否满足所有可空性和检查约束。

    默认是验证所有要加载的数据。 你可以提供要使用 ROWS 关键字验证的行数，例如 VALIDATE 15 ROWS。 当小于 50 的数字与 COPY INTO 关键字一起使用时，ROWS 语句返回 50 行或更少的数据的预览）。

  • FILES

    要加载的文件名的列表，限制为 1000 个文件。 无法使用 PATTERN 进行指定。

  • PATTERN

    glob 模式，用于标识要从源目录加载的文件。 无法使用 FILES 进行指定。

    模式 说明
    ? 匹配任何单一字符
    * 与零个或多个字符匹配
    [abc] 匹配字符集中的单个字符 {a,b,c}。
    [a-z] 匹配字符范围 {a...z} 中的单个字符。
    [^a] 匹配不是来自字符集或范围 {a} 的单个字符。 请注意，^ 字符必须立即出现在左括号的右侧。
    {ab,cd} 匹配字符串集 {ab, cd} 中的字符串。
    {ab,c{de, fh}} 匹配字符串集 {ab, cde, cfh} 中的字符串。

  • FORMAT_OPTIONS

    要传递给指定格式的 Apache Spark 数据源读取器的选项。 请参阅每种文件格式的格式 选项 。

  • COPY_OPTIONS

    用于控制 COPY INTO 命令的操作的选项。

    • force：布尔值，默认为 false。 如果设置为 true，则禁用幂等性并加载文件，而不管文件以前是否加载过。
    • mergeSchema：布尔值，默认为 false。 如果设置为 true，则架构可以根据传入的数据进行演变。

并发调用 COPY INTO

COPY INTO 支持对同一表进行并发调用。 只要对不同的输入文件集并发调用COPY INTO，每次调用最终都应成功，否则会导致事务冲突。 COPY INTO 不应并发调用以提高性能；具有多个文件的单个 COPY INTO 命令通常比分别具有单个文件的并发 COPY INTO 命令执行得更好。 COPY INTO 可在以下情况下并发调用：

  • 多个数据生成者没有一种简单的协调方式，并且无法进行单个调用。
  • 当可以逐子目录引入非常大的目录时。 引入包含大量文件的目录时，Databricks 建议尽可能使用 自动加载程序 。

访问文件元数据

若要了解如何访问基于文件的数据源的元数据，请参阅 “文件元数据”列。

格式选项

有关特定于每种文件格式的选项（JSON、CSV、XML、Parquet、Avro、文本、ORC 和二进制 ），请参阅 DataFrameReader 选项。

  • Last updated on