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 Catalog 连接到云对象存储和服务。

• 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 目录从位置进行读取所需的授权。

  如果路径已定义为你有权使用的外部位置，则无需提供内联或命名凭据。 请参阅创建外部位置以将云存储连接到 Azure Databricks 了解详细信息。

  注意

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

  接受的凭据选项如下：

  • 适用于 ADLS Gen2 和 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 及更高版本

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

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

  默认是验证所有要加载的数据。 你可以提供要使用 ROWS 关键字验证的行数，例如 VALIDATE 15 ROWS。 当小于 50 的数字与 ROWS 关键字一起使用时，COPY INTO 语句返回 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 选项
• BINARYFILE 选项
• TEXT 选项
• ORC 选项

泛型选项

以下选项适用于所有文件格式。

JSON 选项

CSV 选项

XML 选项

PARQUET 选项

AVRO 选项

BINARYFILE 选项

二进制文件没有任何额外的配置选项。

TEXT 选项

ORC 选项

相关文章

• 凭据
• DELETE
• INSERT
• MERGE
• PARTITION
• query
• UPDATE
• 开始使用 COPY INTO 加载数据