具有目录列表模式的自动加载程序流

2025-08-16

本页介绍如何配置自动加载程序流以使用目录列表模式以增量方式发现和引入云数据。

默认情况下，自动加载程序使用目录列表模式。在目录列表模式下，自动加载程序通过列出输入目录来识别新文件。通过目录列表模式，你无需任何权限配置即可快速启动自动加载程序流，而无需访问云存储上的数据。

若要获得目录列表模式的最佳性能，请使用 Databricks Runtime 9.1 或更高版本。本文介绍目录列表模式的默认功能以及基于文件词法排序的优化。

注意

Databricks 建议对大多数工作负荷使用基于外部位置文件事件的文件通知模式，而非目录列表模式。如果目前在目录列表模式下使用自动加载程序，Databricks 建议使用文件事件迁移到文件通知模式，以查看显著的性能改进。请参阅在文件通知模式下配置自动加载程序流。

目录列表模式如何运行？

Azure Databricks 优化了自动加载程序的目录列表模式，可比其他 Apache Spark 选项更高效地发现云存储中的文件。

例如，如果每隔 5 分钟就有文件上传为 /some/path/YYYY/MM/DD/HH/fileName，那么，为了找到这些目录中的所有文件，Apache Spark 文件源会并行列出所有子目录。以下算法估计对对象存储的 API LIST 目录调用总数：

1（基础目录）+ 365（每天）* 24（每小时）= 8761 次调用

通过从存储接收平展响应，自动加载器将 API 调用的数量减少到存储中的文件数量除以每次 API 调用返回的结果的数量，大大降低了云成本。下表显示了每个 API 调用为通用对象存储返回的文件数：

每个调用返回的结果数	对象存储
五千	ADLS

增量列表（已弃用）

重要

此功能已弃用。 Databricks 建议将文件通知模式与文件事件一起使用，而不是增量列表。

注意

在 Databricks Runtime 9.1 LTS 及更高版本中可用。

增量列表适用于 Azure Data Lake Storage （abfss://）。

对于按字典顺序生成的文件，自动加载程序可以利用字典顺序的文件排序和经过优化的列表 API，通过从最近引入的文件中列出而不是列出整个目录的内容，从而来提高目录列表的效率。

如果 cloudFiles.useIncrementalListing 设置为 auto，自动加载程序通过检查和比较以前完成的目录列表的文件路径，自动检测给定目录是否适用于增量列表。为了保证 auto 模式中数据的最终完整性，自动加载程序会在完成 7 个连续的增量列表后自动触发一个完整的目录列表。可以设置 cloudFiles.backfillInterval 以在给定的时间间隔触发异步回填，从而控制完整目录列表的频率。

文件的词法排序

对于要按词法排序的文件，上载的新文件需要具有在字典上大于现有文件的前缀。下面显示了词法排序目录的一些示例。

带版本控制的文件

Delta Lake 按词法顺序提交表事务日志。

<path-to-table>/_delta_log/00000000000000000000.json
<path-to-table>/_delta_log/00000000000000000001.json <- guaranteed to be written after version 0
<path-to-table>/_delta_log/00000000000000000002.json <- guaranteed to be written after version 1
...

日期分区文件

文件可以按日期分区格式上传。这些功能的示例包括：

// <base-path>/yyyy/MM/dd/HH:mm:ss-randomString
<base-path>/2021/12/01/10:11:23-b1662ecd-e05e-4bb7-a125-ad81f6e859b4.json
<base-path>/2021/12/01/10:11:23-b9794cf3-3f60-4b8d-ae11-8ea320fad9d1.json
...

// <base-path>/year=yyyy/month=MM/day=dd/hour=HH/minute=mm/randomString
<base-path>/year=2021/month=12/day=04/hour=08/minute=22/442463e5-f6fe-458a-8f69-a06aa970fc69.csv
<base-path>/year=2021/month=12/day=04/hour=08/minute=22/8f00988b-46be-4112-808d-6a35aead0d44.csv <- this may be uploaded before the file above as long as processing happens less frequently than a minute

使用日期分区上传文件时，要记住的一些事项是：

月份、天、小时、分钟需要用零填充，以确保词法排序（应上传为 hour=03，而不是 hour=3 或 2021/05/03，也不是 2021/5/3）。
只要处理发生的频率低于父目录的时间粒度，文件就不一定非要按词法顺序上传到最深的目录中。

一些可以按日期分区词法排序上传文件的服务是：

可以将 Azure 数据工厂配置为按词法顺序上传文件。请参阅此处的示例。
Kinesis Firehose

更改自动加载程序的源路径

在 Databricks Runtime 11.3 LTS 及更高版本中，可以更改配置为目录列表模式的自动加载程序的目录输入路径，而无需选择新的检查点目录。

警告

文件通知模式不支持此功能。如果使用文件通知模式并更改了路径，则可能无法引入目录更新时新目录中已存在的文件。

例如，如果希望运行一个从按天组织的目录结构（例如 /YYYYMMDD/）加载所有数据的每日引入作业，则可每天使用相同的检查点跟踪不同源目录中的引入状态信息，同时保留从以前使用的所有源目录中提取的文件的状态信息。

Compartir a través de