特定于 cloudFiles 源的配置选项以 cloudFiles 为前缀，因此它们位于与其他结构化流式处理源选项不同的命名空间中。
常见自动装载器选项
可以为 Auto Loader 数据流配置以下选项。
| 选项 |
|---|
cloudFiles.allowOverwrites类型： Boolean是否允许输入目录文件更改替代现有数据。 有关配置注意事项，请参阅自动加载程序在追加或覆盖文件时是否再次处理文件？ 默认值： false |
cloudFiles.backfillInterval类型： Interval String自动加载程序可以按给定间隔触发异步回填。 例如 1 day ，每天回填或 1 week 每周回填。 有关详细信息，请参阅 使用 cloudFiles.backfillInterval 触发常规回填。请勿在 cloudFiles.useManagedFileEvents 被设置为 true 时使用。默认值：无 |
cloudFiles.cleanSource类型： String是否自动从输入目录中删除已处理的文件。 设置为 OFF （默认值）时，不会删除任何文件。设置为 DELETE时，自动加载程序会在处理文件 30 天后自动删除文件。 为此，自动加载程序必须具有对源目录的写入权限。设置为 MOVE 后，自动加载程序将在文件被 cloudFiles.cleanSource.moveDestination 处理后 30 天内自动移动到指定位置。 为此，自动加载程序必须对源目录以及移动位置具有写入权限。当某个文件在 commit_time 表值函数的结果中具有 cloud_files_state 的非 null 值时，即认为该文件已被处理。 请参阅 cloud_files_state 表值函数。 可以使用 cloudFiles.cleanSource.retentionDuration配置处理后的 30 天额外等待时间。注意：如果有多个流从源位置使用数据，则 Databricks 不建议使用此选项，因为速度最快的使用者会删除文件，因此这些文件不会被引入到速度较慢的源中。 注意：启用此功能需要自动加载程序在其检查点中维护额外的状态，这会产生性能开销，但可以通过 cloud_files_state 表值函数提高可观测性。 请参阅 cloud_files_state 表值函数。注意： cleanSource 使用当前设置来决定是否对给定文件进行 MOVE 或 DELETE 操作。 例如，假设文件最初处理时的设置是MOVE，但在30天后文件成为清理候选时已更改为DELETE。 在这种情况下，cleanSource 将删除该文件。在 Databricks Runtime 16.4 及更高版本中可用。 默认值：OFF |
cloudFiles.cleanSource.retentionDuration类型： Interval String在已处理文件成为通过 cleanSource 进行存档的候选文件之前需等待的时间。 对于 DELETE 操作来说必须长于 7 天。 对于 MOVE 操作来说没有最低限制。在 Databricks Runtime 16.4 及更高版本中可用。 默认值：30 天 |
cloudFiles.cleanSource.moveDestination类型： String当 cloudFiles.cleanSource 设置为 MOVE 时已处理文件的存档路径。移动位置受到以下限制：
自动加载程序必须对此目录具有写入权限。 在 Databricks Runtime 16.4 及更高版本中可用。 默认值： 无 |
cloudFiles.format类型： String源路径中的数据 文件格式 。 允许的值包括：
默认值：无（必需选项） |
cloudFiles.includeExistingFiles类型： Boolean是包含流式处理输入路径中的现有文件，还是仅处理初始设置后到达的新文件。 仅在您首次启动流时会对该选项进行评估。 在重启流后更改此选项不起作用。 默认值： true |
cloudFiles.inferColumnTypes类型： Boolean在利用架构推理时是否推断确切的列类型。 默认情况下，在推断 JSON 和 CSV 数据集时，列将被推断为字符串。 有关更多详细信息 ，请参阅架构推理 。 默认值： false |
cloudFiles.maxBytesPerTrigger类型： Byte String要在每个触发器中处理的最大新字节数。 你可以指定一个字节字符串（例如 10g），将每个微批限制为 10 GB 数据。 这是一个软性最大值。 如果每个文件为 3 GB，则 Azure Databricks 在一个微批中可以处理 12 GB。 与 cloudFiles.maxFilesPerTrigger 一起使用时，Azure Databricks 最多消耗 cloudFiles.maxFilesPerTrigger 或 cloudFiles.maxBytesPerTrigger 的最低限制（以先达到者为准）。 与 Trigger.Once()（Trigger.Once() 已弃用）一起使用时，此选项不起作用。默认值：无 |
cloudFiles.maxFileAge类型： Interval String出于重复数据删除目的而跟踪文件事件的时长。 Databricks 建议不要优化此参数，除非你是在以每小时数百万个文件的速度引入数据。 有关更多详细信息，请参阅 文件事件跟踪 部分。 过于激进地调整 cloudFiles.maxFileAge 可能会导致数据质量问题，例如重复引入或缺少文件。 因此，Databricks 建议为 cloudFiles.maxFileAge 使用保守设置，例如 90 天，这与类似数据引入解决方案建议的值相当。默认值：无 |
cloudFiles.maxFilesPerTrigger类型： Integer要在每个触发器中处理的最大新文件数。 与 cloudFiles.maxBytesPerTrigger 一起使用时，Azure Databricks 最多消耗 cloudFiles.maxFilesPerTrigger 或 cloudFiles.maxBytesPerTrigger 的最低限制（以先达到者为准）。 与 Trigger.Once()（已弃用）一起使用时，此选项不起作用。默认值：1000 |
cloudFiles.partitionColumns类型： StringHive 样式分区列的逗号分隔列表，你需要从文件的目录结构推断出该列表。 Hive 样式分区列是由等号组合的键值对，例如 <base-path>/a=x/b=1/c=y/file.format。 在此示例中，分区列为 a、b 和 c。 默认情况下，如果使用架构推理并提供 <base-path> 从中加载数据，这些列会自动添加到架构中。 如果提供架构，则自动加载程序会期望这些列包含在架构中。 如果你不希望这些列成为架构的一部分，则可以指定 "" 以忽略这些列。 此外，当你希望在复杂目录结构中推断出列的文件路径时，可以使用此选项，如下例所示：<base-path>/year=2022/week=1/file1.csv<base-path>/year=2022/month=2/day=3/file2.csv<base-path>/year=2022/month=2/day=4/file3.csv将 cloudFiles.partitionColumns 指定为 year,month,day 会针对 year=2022 返回 file1.csv，但 month 和 day 列为 null。month 和 day 已正确解析为 file2.csv 和 file3.csv。默认值：无 |
cloudFiles.schemaEvolutionMode类型： String在数据中发现新列时对架构进行演变的模式。 默认情况下，在推断 JSON 数据集时，将列推断为字符串。 有关更多详细信息，请参阅 架构演变 。 默认值： addNewColumns 未提供架构时， none 否则 |
cloudFiles.schemaHints类型： String在架构推理期间向自动加载程序提供的架构信息。 有关更多详细信息 ，请参阅架构提示 。 默认值：无 |
cloudFiles.schemaLocation类型： String存储推断出的架构和后续更改的位置。 有关更多详细信息 ，请参阅架构推理 。 默认值：无（推断架构所需的） |
cloudFiles.useStrictGlobber类型： Boolean是否使用与 Apache Spark 中其他文件源的默认通配行为相匹配的严格通配符。 有关更多详细信息 ，请参阅常见数据加载模式 。 在 Databricks Runtime 12.2 LTS 及更高版本中可用。 默认值： false |
cloudFiles.validateOptions类型： Boolean是否对自动加载器选项进行验证，并对未知或不一致的选项返回错误。 默认值： true |
目录列表选项
以下选项与目录列表模式相关。
| 选项 |
|---|
cloudFiles.useIncrementalListing（已弃用）类型： String此功能已弃用。 Databricks 建议将 文件通知模式用于文件事件 而不是使用 cloudFiles.useIncrementalListing。是否在目录列表模式下使用增量列表而不是完整列表。 默认情况下，自动加载程序尽最大努力自动检测给定目录是否适用于增量列表。 可以显式使用增量列表，或者通过将完整目录列表分别设置为 true 或 false 来使用该列表。错误地在非按词汇排序的目录上启用增量列表会阻止自动加载程序发现新文件。 适用于 Azure Data Lake Storage （ abfss://）。在 Databricks Runtime 9.1 LTS 及更高版本中可用。 默认值： auto在 Databricks Runtime 16.4 LTS 及更低版本上， false 在 Databricks Runtime 17.0 及更高版本上可用值： auto、true、false |
文件通知选项
以下选项与文件通知模式相关。
| 选项 |
|---|
cloudFiles.fetchParallelism类型： Integer从队列服务中提取消息时要使用的线程数。 请勿在 cloudFiles.useManagedFileEvents 被设置为 true 时使用。默认值：1 |
cloudFiles.pathRewrites类型：JSON 字符串 仅当指定从多个 S3 存储桶接收文件通知的 queueUrl，并且希望利用为访问这些容器中的数据而配置的装入点时，才需要此选项。 借助此选项可以使用装入点重写 bucket/key 路径的前缀。 只能重写前缀。 例如，对于配置 {"<databricks-mounted-bucket>/path": "dbfs:/mnt/data-warehouse"}，路径 s3://<databricks-mounted-bucket>/path/2017/08/fileA.json 将重写为 dbfs:/mnt/data-warehouse/2017/08/fileA.json。请勿在 cloudFiles.useManagedFileEvents 被设置为 true 时使用。默认值：无 |
cloudFiles.resourceTag类型： Map(String, String)一系列键值标记对，可帮助关联和识别相关资源，例如： cloudFiles.option("cloudFiles.resourceTag.myFirstKey", "myFirstValue") .option("cloudFiles.resourceTag.mySecondKey", "mySecondValue")有关 AWS 的详细信息，请参阅 Amazon SQS 成本分配标记 和 配置 Amazon SNS 主题的标记。 (1) 有关 Azure 的详细信息，请参阅命名队列和元数据以及 properties.labels中的覆盖范围。 自动加载程序将这些键值标记对以 JSON 格式存储为标签。
(1)请勿在 cloudFiles.useManagedFileEvents 被设置为 true 时使用。 而是使用云提供程序控制台设置资源标记。默认值：无 |
cloudFiles.useManagedFileEvents预览：自动加载器对文件事件的支持已进入公共预览阶段。 它仅适用于 Databricks Runtime 14.3 LTS 及更高版本。 设置为 true时，Auto Loader 使用文件事件服务来检测外部位置中的文件。 仅当加载路径位于启用了文件事件的外部位置时，才能使用此选项。 请参阅 将文件通知模式与文件事件配合使用。文件事件在文件发现中提供通知级性能，因为自上次运行以来，自动加载程序可以发现新文件。 与目录列表不同，此过程不需要列出目录中的所有文件。 在某些情况下，即使启用了文件事件选项，自动加载程序也使用目录列表：
|
cloudFiles.useNotifications类型： Boolean是否使用文件通知模式来确定何时存在新文件。 如果为 false，则使用目录列表模式。 请参阅 “比较自动加载程序文件检测模式”。请勿在 cloudFiles.useManagedFileEvents 被设置为 true 时使用。默认值： false |
（1） 默认情况下，自动加载程序会尽力添加以下键值标记对：
-
vendor：Databricks -
path：从中加载数据的位置。 由于标签限制，在 GCP 中不可用。 -
checkpointLocation：流检查点的位置。 由于标签限制，在 GCP 中不可用。 -
streamId：流的全局唯一标识符。
这些键名称是预留的，无法更改其值。
文件格式选项
使用自动加载程序，可引入 JSON、CSV、PARQUET、AVRO、TEXT、BINARYFILE 和 ORC 文件。
泛型选项
以下选项适用于所有文件格式。
| 选项 |
|---|
ignoreCorruptFiles类型： Boolean是否忽略损坏的文件。 如果为 true，则当遇到损坏的文件时，Spark 作业将继续运行，并且仍会返回已读取的内容。 可观测到，如 numSkippedCorruptFiles 中所示Delta Lake 历史记录的 operationMetrics 列。 在 Databricks Runtime 11.3 LTS 及更高版本中可用。默认值： false |
ignoreMissingFiles类型： Boolean是否忽略缺少的文件。 如果为 true，则当遇到缺少的文件时，Spark 作业将继续运行，并且仍会返回已读取的内容。 在 Databricks Runtime 11.3 LTS 及更高版本中可用。 默认值：对于自动加载程序为 false，对于 true（旧版）为 COPY INTO |
modifiedAfter类型： Timestamp String，例如 2021-01-01 00:00:00.000000 UTC+0可选时间戳作为筛选器，用于仅引入在提供的时间戳之后具有修改时间戳的文件。 默认值： 无 |
modifiedBefore类型： Timestamp String，例如 2021-01-01 00:00:00.000000 UTC+0可选时间戳作为筛选器，用于仅引入在提供的时间戳之前具有修改时间戳的文件。 默认值： 无 |
pathGlobFilter 或 fileNamePattern类型： String提供用来选择文件的一种潜在 glob 模式。 等效于 PATTERN（旧版）中的 COPY INTO。
fileNamePattern 可在 read_files 中使用。默认值： 无 |
recursiveFileLookup类型： Boolean即使它们的名称不遵循日期=2019-07-01 等分区命名方案，此选项也会搜索嵌套目录。 默认值： false |
JSON 选项
| 选项 |
|---|
allowBackslashEscapingAnyCharacter类型： Boolean是否允许反斜杠对其后面的任何字符进行转义。 如果未启用，则只能对按 JSON 规范显式列出的字符进行转义。 默认值： false |
allowComments类型： Boolean是否允许在分析的内容中使用 Java、C 和 C++ 样式的注释（ '/'、'*' 和 '//' 变体）。默认值： false |
allowNonNumericNumbers类型： Boolean是否允许将非数字 ( NaN) 标记集用作合法浮点数字值。默认值： true |
allowNumericLeadingZeros类型： Boolean是否允许整数以附加的（可忽略的）零开头（例如 000001）。默认值： false |
allowSingleQuotes类型： Boolean是否允许使用单引号（撇号字符 '\'）来引用字符串（名称和字符串值）。默认值： true |
allowUnquotedControlChars类型： Boolean是否允许 JSON 字符串包含未转义的控制字符（值小于 32 的 ASCII 字符，包括制表符和换行符）。 默认值： false |
allowUnquotedFieldNames类型： Boolean是否允许使用不带引号的字段名称（JavaScript 允许，但 JSON 规范不允许）。 默认值： false |
badRecordsPath类型： String用于存储记录错误 JSON 信息的文件路径。 badRecordsPath使用基于文件的数据源中的选项具有以下限制：
默认值： 无 |
columnNameOfCorruptRecord类型： String用于存储因格式不正确而无法分析的记录的列。 如果用于分析的 mode 设置为 DROPMALFORMED，则此列将为空。默认值： _corrupt_record |
dateFormat类型： String用于分析日期字符串的格式。 默认值： yyyy-MM-dd |
dropFieldIfAllNull类型： Boolean在进行架构推理期间是否忽略所有 null 值或空数组和结构的列。 默认值： false |
encoding 或 charset类型： StringJSON 文件编码的名称。 有关选项列表，请参阅 java.nio.charset.Charset。 当 UTF-16 为 UTF-32 时，不能使用 multiline 和 true。默认值： UTF-8 |
inferTimestamp类型： Boolean是否尝试将时间戳字符串推理为 TimestampType。 设置为 true 时，架构推理可能需要明显更长的时间。 必须启用 cloudFiles.inferColumnTypes 才能与自动加载程序一起使用。默认值： false |
lineSep类型： String两个连续 JSON 记录之间的字符串。 默认值：None，涵盖 \r、\r\n 和 \n |
locale类型： String一个 java.util.Locale 标识符。 影响 JSON 中的默认日期、时间戳和十进制分析。默认值： US |
mode类型： String围绕处理格式错误的记录提供的分析程序模式。 之 PERMISSIVEDROPMALFORMED一，或FAILFAST。默认值： PERMISSIVE |
multiLine类型： BooleanJSON 记录是否跨多行。 默认值： false |
prefersDecimal类型： Boolean如果可能，尝试将字符串推断为 DecimalType 而不是浮点型或双精度型。 还必须通过启用以下项来使用架构推理inferSchema 或配合使用 cloudFiles.inferColumnTypes 和自动加载程序。默认值： false |
primitivesAsString类型： Boolean是否将数字和布尔值等基元类型推理为 StringType。默认值： false |
readerCaseSensitive类型： Boolean指定启用 rescuedDataColumn 时区分大小写的行为。 如果为 true，则拯救名称因大小写而与架构不同的数据列；否则，请以不区分大小写的方式读取数据。 可在 Databricks Runtime 中使用13.3 及以上。 默认值： true |
rescuedDataColumn类型： String是否将因数据类型不匹配或架构不匹配（包括列大小写）而无法分析的所有数据收集到单独的列。 使用自动加载程序时，默认包含此列。 有关更多详细信息，请参阅什么是补救的数据列？。 COPY INTO（旧版）不支持已获救的数据列，因为无法使用 COPY INTO手动设置架构。 Databricks 建议对大多数引入方案使用自动加载程序。默认值： 无 |
singleVariantColumn类型： String是否引入整个 JSON 文档，解析为单个 Variant 列，并使用给定的字符串作为列名。 如果禁用，则 JSON 字段将导入至各自的列。 默认值： 无 |
timestampFormat类型： String用于分析时间戳字符串的格式。 默认值： yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX] |
timeZone类型： String分析时间戳和日期时要使用的 java.time.ZoneId。默认值： 无 |
CSV 选项
| 选项 |
|---|
badRecordsPath类型： String用于记录错误 CSV 记录相关信息的存储文件的路径。 默认值： 无 |
charToEscapeQuoteEscaping类型： Char用来对引号的转义字符进行转义的字符。 例如，对于以下记录： [ " a\\", b ]：
默认值： '\0' |
columnNameOfCorruptRecord支持自动加载程序。 不支持 COPY INTO（旧版）。类型： String用于存储因格式不正确而无法分析的记录的列。 如果用于分析的 mode 设置为 DROPMALFORMED，则此列将为空。默认值： _corrupt_record |
comment类型： Char定义表示行注释的字符（位于文本行的开头时）。 请使用 '\0' 来禁用注释跳过。默认值： '\u0000' |
dateFormat类型： String用于分析日期字符串的格式。 默认值： yyyy-MM-dd |
emptyValue类型： String空值的字符串表示形式。 默认值： "" |
encoding 或 charset类型： StringCSV 文件编码的名称。 有关选项列表，请参阅 java.nio.charset.Charset。 当 UTF-16 为 UTF-32 时，不能使用 multiline 和 true。默认值： UTF-8 |
enforceSchema类型： Boolean是否将指定的或推理出的架构强制应用于 CSV 文件。 如果启用此选项，则会忽略 CSV 文件的标题。 默认情况下，当使用自动加载程序来补救数据并允许架构演变时，会忽略此选项。 默认值： true |
escape类型： Char分析数据时要使用的转义字符。 默认值： '\' |
header类型： BooleanCSV 文件是否包含标题。 自动加载程序在推理架构时会假定文件具有标题。 默认值： false |
ignoreLeadingWhiteSpace类型： Boolean是否忽略每个所分析值的前导空格。 默认值： false |
ignoreTrailingWhiteSpace类型： Boolean是否忽略每个解析值的尾随空格。 默认值： false |
inferSchema类型： Boolean是推断已解析 CSV 记录的数据类型，还是假定所有列都是 StringType 类型的。 如果设置为 true，则需要对数据进行另一轮操作。 对于自动加载程序，请改用 cloudFiles.inferColumnTypes。默认值： false |
lineSep类型： String两个连续 CSV 记录之间的字符串。 默认值：None，涵盖 \r、\r\n 和 \n |
locale类型： String一个 java.util.Locale 标识符。 影响 CSV 中的默认日期、时间戳和十进制分析。默认值： US |
maxCharsPerColumn类型： Int要分析的值预期包含的最大字符数。 可用于避免内存错误。 默认为 -1，表示无限制。默认值： -1 |
maxColumns类型： Int记录可以包含的列数的硬限制。 默认值： 20480 |
mergeSchema类型： Boolean是否在多个文件之间推断模式并合并每个文件的模式。 已默认在推理架构时为自动加载程序启用。 默认值： false |
mode类型： String围绕处理格式错误的记录提供的分析程序模式。 'PERMISSIVE'、'DROPMALFORMED' 和 'FAILFAST'。默认值： PERMISSIVE |
multiLine类型： BooleanCSV 记录是否跨多行。 默认值： false |
nanValue类型： String分析 FloatType 和 DoubleType 列时非数字值的字符串表示形式。默认值： "NaN" |
negativeInf类型： String分析 FloatType 或 DoubleType 列时负无穷大的字符串表示形式。默认值： "-Inf" |
nullValue类型： Stringnull 值的字符串表示形式。 默认值： "" |
parserCaseSensitive（已弃用）类型： Boolean读取文件时，将标题中声明的列与架构对齐时是否区分大小写。 对于自动加载程序，此项默认为 true。 如果启用，则会在 rescuedDataColumn 中补救大小写不同的列。 出于对 readerCaseSensitive 的偏好，已不推荐使用此选项。默认值： false |
positiveInf类型： String分析 FloatType 或 DoubleType 列时正无穷大的字符串表示形式。默认值： "Inf" |
preferDate类型： Boolean如果可能，尝试将字符串推断为日期而不是时间戳。 还必须通过启用 inferSchema 或使用以下项来使用架构推理cloudFiles.inferColumnTypes 与自动加载程序。默认值： true |
quote类型： Char当字段分隔符是值的一部分时用于对值进行转义的字符。 默认值： " |
readerCaseSensitive类型： Boolean指定启用 rescuedDataColumn 时区分大小写的行为。 如果为 true，则拯救名称因大小写而与架构不同的数据列；否则，请以不区分大小写的方式读取数据。默认值： true |
rescuedDataColumn类型： String是否将因数据类型不匹配和架构不匹配（包括列大小写）而无法分析的所有数据收集到单独的列。 使用自动加载程序时，默认包含此列。 有关更多详细信息，请参阅什么是恢复的数据列？ COPY INTO（旧版）不支持已获救的数据列，因为无法使用 COPY INTO手动设置架构。 Databricks 建议对大多数引入方案使用自动加载程序。默认值： 无 |
sep 或 delimiter类型： String列之间的分隔符字符串。 默认值： "," |
skipRows类型： IntCSV 文件开头应忽略的行数（包括注释行和空行）。 如果 header 为 true，则标头将是第一个未跳过和未注释的行。默认值： 0 |
timestampFormat类型： String用于分析时间戳字符串的格式。 默认值： yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX] |
timeZone类型： String分析时间戳和日期时要使用的 java.time.ZoneId。默认值： 无 |
unescapedQuoteHandling类型： String用于处理未转义的引号的策略。 允许的选项：
默认值： STOP_AT_DELIMITER |
XML 选项
| 选项 | 说明 | Scope |
|---|---|---|
rowTag |
要作为行处理的 XML 文件的行标记。 在示例 XML <books> <book><book>...<books> 中，相应的值为 book。 这是必需选项。 |
读取 |
samplingRatio |
定义用于架构推理的行的一部分。 XML 内置函数会忽略此选项。 默认：1.0。 |
读取 |
excludeAttribute |
是否排除元素中的属性。 默认：false。 |
读取 |
mode |
在解析过程中处理损坏的记录的一种模式。PERMISSIVE：对于损坏的记录，将格式错误的字符串放入由 columnNameOfCorruptRecord 配置的字段中，并将格式错误的字段设置为 null。 若要保留损坏的记录，可以在用户定义的架构中设置名为 string 的 columnNameOfCorruptRecord 类型字段。 如果架构没有该字段，则会在分析期间删除损坏的记录。 推理架构时，分析程序会在输出架构中隐式添加 columnNameOfCorruptRecord 字段。DROPMALFORMED：忽略损坏的记录。 XML 内置函数不支持此模式。FAILFAST：分析程序遇到损坏的记录时引发异常。 |
读取 |
inferSchema |
如果为 true，则尝试推断每个生成的 DataFrame 列的相应类型。 如果为 false，则生成的所有列均为 string 类型。 默认值：true。 XML 内置函数会忽略此选项。 |
读取 |
columnNameOfCorruptRecord |
允许对包含由不正确字符串创建的新字段进行重命名 PERMISSIVE 模式。 默认：spark.sql.columnNameOfCorruptRecord。 |
读取 |
attributePrefix |
属性的前缀，用于区分属性和元素。 这将是字段名称的前缀。 默认值为 _。 读取 XML 时可以为空，但写入时不能为空。 |
读取、写入 |
valueTag |
该标记用于同时具有属性元素或子元素的元素中的字符数据。 用户可以在架构中指定 valueTag 字段，或者当字符数据存在于具有其他元素或属性的元素中时，该字段将在架构推断期间自动添加。 默认值：_VALUE |
读取、写入 |
encoding |
若要读取，请根据给定的编码类型解码 XML 文件。 对于写入，请指定已保存的 XML 文件的编码（字符集）。 XML 内置函数会忽略此选项。 默认：UTF-8。 |
读取、写入 |
ignoreSurroundingSpaces |
定义是否应跳过正在读取的值周围的空格。 默认：true。 将忽略只有空格的字符数据。 |
读取 |
rowValidationXSDPath |
可选 XSD 文件的路径，用于单独验证每行的 XML。 未能通过验证的行视为上述解析错误。 XSD 不会以其他方式影响提供或推理的架构。 | 读取 |
ignoreNamespace |
如果为 true，则忽略 XML 元素和属性上的命名空间前缀。 例如，标记 <abc:author> 和 <def:author> 会被视为只是 <author>。 不能忽略 rowTag 元素上的命名空间，只忽略其读取子元素。 XML 分析不识别命名空间，即使 false。 默认：false。 |
读取 |
timestampFormat |
遵循 日期时间模式 格式的自定义时间戳格式字符串。 它适用于 timestamp 类型。 默认：yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]。 |
读取、写入 |
timestampNTZFormat |
遵循日期/时间模式格式的不带时区的自定义时间戳格式字符串。 这适用于 TimestampNTZType 类型。 默认值：yyyy-MM-dd'T'HH:mm:ss[.SSS] |
读取、写入 |
dateFormat |
遵循 日期时间模式 格式的自定义日期格式字符串。 这适用于日期类型。 默认：yyyy-MM-dd。 |
读取、写入 |
locale |
将地区设置为 IETF BCP 47 格式的语言标签。 例如，在分析日期和时间戳时使用 locale。 默认：en-US。 |
读取 |
rootTag |
XML 文件的根标记。 例如，在 <books> <book><book>...</books> 中，相应的值为 books。 可以通过指定类似于 books foo="bar" 的值来包含基本属性。 默认：ROWS。 |
写入 |
declaration |
每个输出 XML 文件开头（rootTag 之前）要写入的 XML 声明内容。 例如，值 foo 会导致写入 <?xml foo?>。 设置为空字符串以禁用。 默认值：version="1.0"encoding="UTF-8" standalone="yes"。 |
写入 |
arrayElementName |
写入时将数组值列的每个元素括起来的 XML 元素的名称。 默认：item。 |
写入 |
nullValue |
设置 null 值的字符串表示形式。 默认值：字符串 null。 当为 null 时，分析程序不会为字段写入属性和元素。 |
读取、写入 |
compression |
保存到文件时使用的压缩代码。 这可以是已知不区分大小写的缩短名称之一（none、bzip2、gzip、lz4、snappy 和deflate）。 XML 内置函数会忽略此选项。 默认：none。 |
写入 |
validateName |
如果为 true，则当 XML 元素名称验证失败时引发错误。 例如，SQL 字段名称可以有空格，但 XML 元素名称不能为空。 默认值：true。 |
写入 |
readerCaseSensitive |
指定启用 rescuedDataColumn 时区分大小写的行为。 如果为 true，则拯救名称因大小写而与架构不同的数据列；否则，请以不区分大小写的方式读取数据。 默认：true。 |
读取 |
rescuedDataColumn |
是否将因数据类型不匹配和架构不匹配（包括列大小写）而无法分析的所有数据收集到单独的列中。 使用自动加载程序时，默认包含此列。 有关更多详细信息，请参阅什么是恢复的数据列？COPY INTO（旧版）不支持已获救的数据列，因为无法使用 COPY INTO手动设置架构。 Databricks 建议对大多数引入方案使用自动加载程序。默认值：无。 |
读取 |
singleVariantColumn |
指定单个变体列的名称。 如果指定此选项用于读取，将整个 XML 记录解析为一个单个 Variant 列，并将该选项字符串值作为列名称。 如果为写入提供了此选项，则将单个 Variant 列的值写入 XML 文件。 默认：none。 |
读取、写入 |
PARQUET 选项
| 选项 |
|---|
datetimeRebaseMode类型： String控制 DATE 和 TIMESTAMP 值在儒略历与外推格里历之间的基本值重定。 允许的值： EXCEPTION、LEGACY 和CORRECTED。默认值： LEGACY |
int96RebaseMode类型： String控制 INT96 时间戳值在儒略历与外推格里历之间的基本值重定。 允许的值： EXCEPTION、LEGACY 和CORRECTED。默认值： LEGACY |
mergeSchema类型： Boolean是否在多个文件之间推断模式并合并每个文件的模式。 默认值： false |
readerCaseSensitive类型： Boolean指定启用 rescuedDataColumn 时区分大小写的行为。 如果为 true，则拯救名称因大小写而与架构不同的数据列；否则，请以不区分大小写的方式读取数据。默认值： true |
rescuedDataColumn类型： String是否将因数据类型不匹配和架构不匹配（包括列大小写）而无法分析的所有数据收集到单独的列。 使用自动加载程序时，默认包含此列。 有关更多详细信息，请参阅什么是恢复的数据列？ COPY INTO（旧版）不支持已获救的数据列，因为无法使用 COPY INTO手动设置架构。 Databricks 建议对大多数引入方案使用自动加载程序。默认值： 无 |
AVRO 选项
| 选项 |
|---|
avroSchema类型： String用户以 Avro 格式提供的可选架构。 读取 Avro 时，可以将此选项设置为一个演变的架构，该架构与实际 Avro 架构兼容但不同。 反序列化架构会与演变的架构保持一致。 例如，如果你设置的演变架构包含一个具有默认值的附加列，则读取结果也会包含该新列。 默认值： 无 |
datetimeRebaseMode类型： String控制 DATE 和 TIMESTAMP 值在儒略历与外推格里历之间的基本值重定。 允许的值： EXCEPTION、LEGACY 和CORRECTED。默认值： LEGACY |
mergeSchema类型： Boolean是否在多个文件之间推断模式并合并每个文件的模式。 Avro 的 mergeSchema 不放宽数据类型。默认值： false |
readerCaseSensitive类型： Boolean指定启用 rescuedDataColumn 时区分大小写的行为。 如果为 true，则拯救名称因大小写而与架构不同的数据列；否则，请以不区分大小写的方式读取数据。默认值： true |
rescuedDataColumn类型： String是否将因数据类型不匹配和架构不匹配（包括列大小写）而无法分析的所有数据收集到单独的列。 使用自动加载程序时，默认包含此列。 COPY INTO（旧版）不支持已获救的数据列，因为无法使用 COPY INTO手动设置架构。 Databricks 建议对大多数引入方案使用自动加载程序。有关更多详细信息，请参阅什么是恢复的数据列？ 默认值： 无 |
BINARYFILE 选项
二进制文件没有任何额外的配置选项。
TEXT 选项
| 选项 |
|---|
encoding类型： StringTEXT 文件行分隔符的编码的名称。 有关选项列表，请参阅 java.nio.charset.Charset。文件的内容不受此选项的影响，仍会读取as-is。 默认值： UTF-8 |
lineSep类型： String两个连续 TEXT 记录之间的字符串。 默认值：None，涵盖 \r、\r\n 和 \n |
wholeText类型： Boolean是否将文件读取为单个记录。 默认值： false |
ORC 选项
| 选项 |
|---|
mergeSchema类型： Boolean是否在多个文件之间推断模式并合并每个文件的模式。 默认值： false |
特定于云的选项
自动加载程序提供许多用于配置云基础结构的选项。
特定于 Azure 的选项
如果指定 cloudFiles.useNotifications = true，并且希望自动加载程序设置通知服务，则必须为以下所有选项提供值：
| 选项 |
|---|
cloudFiles.resourceGroup类型： String在其下创建了存储帐户的 Azure 资源组。 默认值：无 |
cloudFiles.subscriptionId类型： String创建资源组所用的 Azure 订阅 ID。 默认值：无 |
databricks.serviceCredential类型： String您的 Databricks 服务凭据的名称。 在 Databricks Runtime 16.1 及更高版本中可用。 默认值：无 |
如果 Databricks 服务凭据不可用，可以改为提供以下身份验证选项：
| 选项 |
|---|
cloudFiles.clientId类型： String服务主体的客户端 ID 或应用程序 ID。 默认值：无 |
cloudFiles.clientSecret类型： String服务主体的客户端密钥。 默认值：无 |
cloudFiles.connectionString类型： String存储帐户的连接字符串，基于帐户访问密钥或共享访问签名 (SAS)。 默认值：无 |
cloudFiles.tenantId类型： String在其下创建了服务主体的 Azure 租户 ID。 默认值：无 |
重要
自动通知设置在由世纪互联运营的 Azure 和具有 Databricks Runtime 9.1 及更高版本的政府区域中可用。 在较低的 DBR 版本的这些区域中，必须提供 queueName 才能将自动加载程序与文件通知配合使用。
仅当你选择 cloudFiles.useNotifications = true 并希望自动加载程序使用已设置的队列时，才提供以下选项：
| 选项 |
|---|
cloudFiles.queueName类型： StringAzure 队列的名称。 如果提供了此项，则云文件源会直接使用此队列中的事件，而不是设置自己的 Azure 事件网格和队列存储服务。 在这种情况下， databricks.serviceCredential 或 cloudFiles.connectionString 只需要对队列具有读取权限。默认值：无 |