什么是自动加载程序目录列表模式？

项目
08/15/2024

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

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

目录列表模式如何运行？

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

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

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

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

每个调用返回的结果数	对象存储
1000	S3
5000	ADLS Gen2
1024	GCS

增量列表（已弃用）

重要

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

注意

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

增量列表适用于 Azure Data Lake Storage Gen2 (abfss://)、S3 (s3://) 和 GCS (gs://)。

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

默认情况下，自动加载程序通过检查和比较以前完成的目录列表的文件路径，自动检测给定目录是否适用于增量列表。为了保证 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
...

AWS DMS 以版本控制方式将 CDC 文件上传到 AWS S3。

database_schema_name/table_name/LOAD00000001.csv
database_schema_name/table_name/LOAD00000002.csv
...

日期分区文件

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

// <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/）加载所有数据的每日引入作业，则可每天使用相同的检查点跟踪不同源目录中的引入状态信息，同时保留从以前使用的所有源目录中提取的文件的状态信息。

通过