`read_files` 表值函数

项目
09/09/2024

适用于：勾选“是” Databricks SQL Databricks Runtime 13.3 LTS 及更高版本

读取提供位置下方的文件，并以表格形式返回数据。

支持读取 JSON、CSV、XML、TEXT、BINARYFILE、PARQUET、AVRO 和 ORC 文件格式。可以自动检测文件格式，并跨所有文件推断出统一的架构。

语法

read_files(path [, option_key => option_value ] [...])

参数

此函数需要用于选项键的命名参数调用。

path：一种 STRING，其中包含数据位置的 URI。支持从 Azure Data Lake Storage Gen2 ('abfss://')、S3 (s3://) 和 Google Cloud Storage ('gs://') 读取。可以包含 glob。有关详细信息，请参阅文件发现。
option_key：要配置的选项的名称。对于包含点 (.) 的选项需要使用反引号。
option_value：用于设置选项的常数表达式。接受文本和标量函数。

由从给定 path 下方读取的文件中的数据组成的表。

文件发现

read_files 可以读取提供的目录下的单个文件或多个文件。 read_files 以递归方式发现提供的目录下的所有文件，除非提供了 glob 指示 read_files 递归到特定的目录模式中。

使用 glob 模式筛选目录或文件

在路径中提供 Glob 模式时，可用于筛选目录和文件。

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

发现具有 glob 的文件后，read_files 使用“自动加载器”严格的 globber。使用“useStrictGlobber”选项来配置。如禁用严格的 globber，会删除末尾的斜杠 (/)，而 /*/ 等星星图案可以扩展到发现多个目录中。请参阅以下示例，查看它们行为之间的差异。

模式	文件路径	已禁用严格 globber	已启用严格 globber
`/a/b`	`/a/b/c/file.txt`	是	是
`/a/b`	`/a/b_dir/c/file.txt`	否	否
`/a/b`	`/a/b.txt`	否	否
`/a/b/`	`/a/b.txt`	否	否
`/a/*/c/`	`/a/b/c/file.txt`	是	是
`/a/*/c/`	`/a/b/c/d/file.txt`	是	是
`/a/*/d/`	`/a/b/c/d/file.txt`	是	否
`/a/*/c/`	`/a/b/x/y/c/file.txt`	是	否
`/a/*/c`	`/a/b/c_file.txt`	是	否
`/a/*/c/`	`/a/b/c_file.txt`	是	否
`/a/*/c`	`/a/b/cookie/file.txt`	是	否
`/a/b*`	`/a/b.txt`	是	是
`/a/b*`	`/a/b/file.txt`	是	是
`/a/{0.txt,1.txt}`	`/a/0.txt`	是	是
`/a/*/{0.txt,1.txt}`	`/a/0.txt`	否	否
`/a/b/[cde-h]/i/`	`/a/b/c/i/file.txt`	是	是

架构推理

可以使用“schema”选项，将文件的架构明确地提供给 read_files。如果未提供架构，则 read_files 会尝试在发现的文件中推出统一的架构。除非使用 LIMIT 语句，否则这需要读取所有文件。即使在使用 LIMIT 查询时，也可能要读取比所需更多的文件数才能返回更具代表性的数据架构。如果用户未提供，则 Databricks 会自动在笔记本和 SQL 编辑器中为 SELECT 查询添加 LIMIT 语句。

“schemaHints”选项可用于修复推断出的架构的子集。有关详细信息，请参阅使用架构提示覆盖架构推理。

默认情况下提供 rescuedDataColumn 来补救与架构不匹配的任何数据。有关详细信息，请参阅什么是补救的数据列？。可以通过设置选项“schemaEvolutionMode => 'none'”来删除 rescuedDataColumn。

分区架构推理

如果文件存储在采用 Hive 样式分区的目录下，即 /column_name=column_value/，则 read_files 也可以推理出分区依据列。如果提供了 schema，则发现的分区列将使用 schema 中提供的类型。如果分区列不是所提供的 schema 中的一部分，则推理出的分区列将被忽略。

如果分区架构和数据列中同时存在某个列，则会使用从分区值而非数据值中读取到的值。若要忽略来自目录的值并使用数据列，可以使用“partitionColumns”选项以逗号分隔列表的形式提供分区列的列表。

此外，“partitionColumns”选项还可用于指示 read_files 在最终推理出的架构中包含哪些发现的列。提供空的字符串会忽略所有分区列。

还可以提供“schemaHints”选项来覆盖推理出的某个分区列的架构。

TEXT 和 BINARYFILE 具有固定的架构，不过 read_files 在条件允许时也会尝试推出这些格式的分区。

流式处理表中的使用情况

可在流式处理表中使用 read_files，将文件引入 Delta 湖中。用在流式处理表查询中时，read_files 利用“自动加载器”。关键字“STREAM”必须与 read_files 一起使用。有关详细信息，请参阅什么是自动加载器？。

如果用于流式处理查询，read_files 将使用一个数据示例来引入架构，并可以在其处理更多数据时改进架构。有关详细信息，请参阅在自动加载程序中配置架构推理和演变。

基本选项

选项
`format` 类型：`String` 源路径中的数据文件格式。如果未提供，则自动推断。允许的值包括： * `avro`：Avro 文件 * `binaryFile`：二进制文件 * `csv`：阅读 CSV 文件 * `json`：JSON 文件 * `orc`：ORC 文件 * `parquet`：使用 Azure Databricks 读取 Parquet 文件 * `text`：文本文件 * `xml`：读取和写入 XML 文件默认值：无
`inferColumnTypes` 类型：`Boolean` 在利用架构推理时是否推断确切的列类型。默认情况下，在推断 JSON 和 CSV 数据集时，会推断列。有关更多详细信息，请参阅架构推理。请注意，这与默认的自动加载器相反。默认值：30`true`
`partitionColumns` 类型：`String` 要从文件目录结构推断出的 Hive 样式分区列的逗号分隔列表。 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`，则针对 `file1.csv`，将返回 `year=2022`，但 `month` 和 `day` 列将为 `null`。对于 `file2.csv` 和 `file3.csv`，将正确分析 `month` 和 `day`。默认值：无
`schemaHints` 类型：`String` 在架构推理期间向自动加载程序提供的架构信息。有关更多详细信息，请参阅架构提示。默认值：无
`useStrictGlobber` 类型：`Boolean` 是否使用与 Apache Spark 中其他文件源的默认通配行为相匹配的严格通配符。有关更多详细信息，请参阅常见数据加载模式。在 Databricks Runtime 12.2 LTS 及更高版本中可用。请注意，这与“自动加载器”的默认值相反。默认值：30`true`

泛型选项

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

选项
`ignoreCorruptFiles` 类型：`Boolean` 是否忽略损坏的文件。如果为 true，则当遇到损坏的文件时，Spark 作业将继续运行，并且仍会返回已读取的内容。可观测到，如 `numSkippedCorruptFiles` 中所示 Delta Lake 历史记录的 `operationMetrics` 列。在 Databricks Runtime 11.3 LTS 及更高版本中可用。默认值：30`false`
`ignoreMissingFiles` 类型：`Boolean` 是否忽略缺少的文件。如果为 true，则当遇到缺少的文件时，Spark 作业将继续运行，并且仍会返回已读取的内容。在 Databricks Runtime 11.3 LTS 及更高版本中可用。默认值： `false` （`COPY INTO` 的 `true`）
`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 模式。等效于 `COPY INTO` 中的 `PATTERN`。 `fileNamePattern` 可在 `read_files` 中使用。默认值：无
`recursiveFileLookup` 类型：`Boolean` 是否在架构推理期间跳过分区推理。这不会影响加载的文件。默认值：30`false`

`JSON` 选项

选项
`allowBackslashEscapingAnyCharacter` 类型：`Boolean` 是否允许反斜杠对其后面的任何字符进行转义。如果未启用，则只能对按 JSON 规范显式列出的字符进行转义。默认值：30`false`
`allowComments` 类型：`Boolean` 是否允许在分析的内容中使用 Java、C 和 C++ 样式的注释（`'/'`、`'*'` 和 `'//'` 变体）。默认值：30`false`
`allowNonNumericNumbers` 类型：`Boolean` 是否允许将非数字 (`NaN`) 标记集用作合法浮点数字值。默认值：30`true`
`allowNumericLeadingZeros` 类型：`Boolean` 是否允许整数以附加的（可忽略的）零开头（例如 `000001`）。默认值：30`false`
`allowSingleQuotes` 类型：`Boolean` 是否允许使用单引号（撇号字符 `'\'`）来引用字符串（名称和字符串值）。默认值：30`true`
`allowUnquotedControlChars` 类型：`Boolean` 是否允许 JSON 字符串包含未转义的控制字符（值小于 32 的 ASCII 字符，包括制表符和换行符）。默认值：30`false`
`allowUnquotedFieldNames` 类型：`Boolean` 是否允许使用不带引号的字段名称（JavaScript 允许，但 JSON 规范不允许）。默认值：30`false`
`badRecordsPath` 类型：`String` 用于记录错误 JSON 记录相关信息的存储文件的路径。默认值：无
`columnNameOfCorruptRecord` 类型：`String` 用于存储因格式不正确而无法分析的记录的列。如果用于分析的 `mode` 设置为 `DROPMALFORMED`，则此列将为空。默认值：30`_corrupt_record`
`dateFormat` 类型：`String` 用于分析日期字符串的格式。默认值：30`yyyy-MM-dd`
`dropFieldIfAllNull` 类型：`Boolean` 在进行架构推理期间是否忽略所有 null 值或空数组和结构的列。默认值：30`false`
`encoding` 或 `charset` 类型：`String` JSON 文件编码的名称。有关选项列表，请参阅 `java.nio.charset.Charset`。当 `multiline` 为 `true` 时，不能使用 `UTF-16` 和 `UTF-32`。默认值：30`UTF-8`
`inferTimestamp` 类型：`Boolean` 是否尝试将时间戳字符串推理为 `TimestampType`。设置为为 `true` 时，架构推理可能需要明显更长的时间。必须启用 `cloudFiles.inferColumnTypes` 才能与自动加载程序一起使用。默认值：30`false`
`lineSep` 类型：`String` 两个连续 JSON 记录之间的字符串。默认值：None，涵盖 `\r`、`\r\n` 和 `\n`
`locale` 类型：`String` 一个 `java.util.Locale` 标识符。影响 JSON 中的默认日期、时间戳和十进制分析。默认值：30`US`
`mode` 类型：`String` 围绕处理格式错误的记录提供的分析程序模式。 `'PERMISSIVE'`、 `'DROPMALFORMED'` 或 `'FAILFAST'` 中的一项。默认值：30`PERMISSIVE`
`multiLine` 类型：`Boolean` JSON 记录是否跨多行。默认值：30`false`
`prefersDecimal` 类型：`Boolean` 如果可能，尝试将字符串推断为 `DecimalType` 而不是浮点型或双精度型。还必须通过启用以下项来使用架构推理 `inferSchema` 或配合使用 `cloudFiles.inferColumnTypes` 和自动加载程序。默认值：30`false`
`primitivesAsString` 类型：`Boolean` 是否将数字和布尔值等基元类型推理为 `StringType`。默认值：30`false`
`readerCaseSensitive` 类型：`Boolean` 指定启用 `rescuedDataColumn` 时区分大小写的行为。如果为 true，则拯救名称因大小写而与架构不同的数据列；否则，请以不区分大小写的方式读取数据。在 Databricks Runtime 13.3 及更高版本中可用。默认值：30`true`
`rescuedDataColumn` 类型：`String` 是否将因数据类型不匹配或架构不匹配（包括列大小写）而无法分析的所有数据收集到单独的列。使用自动加载程序时，默认包含此列。有关更多详细信息，请参考什么是补救的数据列？。默认值：无
`singleVariantColumn` 类型：`String` 是否引入整个 JSON 文档，解析为单个 Variant 列，并使用给定的字符串作为列名。如果禁用，则 JSON 字段将引入到自己的列中。默认值：无
`timestampFormat` 类型：`String` 用于分析时间戳字符串的格式。默认值：30`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`
`timeZone` 类型：`String` 分析时间戳和日期时要使用的 `java.time.ZoneId`。默认值：无

`CSV` 选项

选项
`badRecordsPath` 类型：`String` 用于记录错误 CSV 记录相关信息的存储文件的路径。默认值：无
`charToEscapeQuoteEscaping` 类型：`Char` 用来对引号的转义字符进行转义的字符。例如，对于以下记录：`[ " a\\", b ]`： * 如果未定义用来对 `'\'` 进行转义的字符，则不会分析记录。分析程序会将字符读取为 `[a],[\],["],[,],[ ],[b]`，并引发错误，因为它找不到右引号。 * 如果将用来对 `'\'` 转义的字符定义为 `'\'`，则读取的记录会带有 2 个值：`[a\]` 和 `[b]`。默认值：30`'\0'`
`columnNameOfCorruptRecord` > [!NOTE] >> 支持自动加载程序。不支持 `COPY INTO`。类型：`String` 用于存储因格式不正确而无法分析的记录的列。如果用于分析的 `mode` 设置为 `DROPMALFORMED`，则此列将为空。默认值：30`_corrupt_record`
`comment` 类型：`Char` 定义表示行注释的字符（位于文本行的开头时）。请使用 `'\0'` 来禁用注释跳过。默认值：30`'\u0000'`
`dateFormat` 类型：`String` 用于分析日期字符串的格式。默认值：30`yyyy-MM-dd`
`emptyValue` 类型：`String` 空值的字符串表示形式。默认值：30`""`
`encoding` 或 `charset` 类型：`String` CSV 文件编码的名称。有关选项列表，请参阅 `java.nio.charset.Charset`。当 `multiline` 为 `true` 时，不能使用 `UTF-16` 和 `UTF-32`。默认值：30`UTF-8`
`enforceSchema` 类型：`Boolean` 是否将指定的或推理出的架构强制应用于 CSV 文件。如果启用此选项，则会忽略 CSV 文件的标题。默认情况下，当使用自动加载程序来补救数据并允许架构演变时，会忽略此选项。默认值：30`true`
`escape` 类型：`Char` 分析数据时要使用的转义字符。默认值：30`'\'`
`header` 类型：`Boolean` CSV 文件是否包含标题。自动加载程序在推理架构时会假定文件具有标题。默认值：30`false`
`ignoreLeadingWhiteSpace` 类型：`Boolean` 是否忽略每个所分析值的前导空格。默认值：30`false`
`ignoreTrailingWhiteSpace` 类型：`Boolean` 是否忽略每个所分析值的尾随空格。默认值：30`false`
`inferSchema` 类型：`Boolean` 是推理所分析 CSV 记录的数据类型，还是假定所有列都是 `StringType` 类型的。如果设置为 `true`，则需要对数据进行另一轮操作。对于自动加载程序，请改用 `cloudFiles.inferColumnTypes`。默认值：30`false`
`lineSep` 类型：`String` 两个连续 CSV 记录之间的字符串。默认值：None，涵盖 `\r`、`\r\n` 和 `\n`
`locale` 类型：`String` 一个 `java.util.Locale` 标识符。影响 CSV 中的默认日期、时间戳和十进制分析。默认值：30`US`
`maxCharsPerColumn` 类型：`Int` 要分析的值预期包含的最大字符数。可用于避免内存错误。默认为 `-1`，表示无限制。默认值：30`-1`
`maxColumns` 类型：`Int` 记录可以包含的列数的硬限制。默认值：30`20480`
`mergeSchema` 类型：`Boolean` 是否跨多个文件推理架构并合并每个文件的架构。已默认在推理架构时为自动加载程序启用。默认值：30`false`
`mode` 类型：`String` 围绕处理格式错误的记录提供的分析程序模式。 `'PERMISSIVE'`、 `'DROPMALFORMED'` 和 `'FAILFAST'`。默认值：30`PERMISSIVE`
`multiLine` 类型：`Boolean` CSV 记录是否跨多行。默认值：30`false`
`nanValue` 类型：`String` 分析 `FloatType` 和 `DoubleType` 列时非数字值的字符串表示形式。默认值：30`"NaN"`
`negativeInf` 类型：`String` 分析 `FloatType` 或 `DoubleType` 列时负无穷大的字符串表示形式。默认值：30`"-Inf"`
`nullValue` 类型：`String` null 值的字符串表示形式。默认值：30`""`
`parserCaseSensitive`（已弃用）类型：`Boolean` 读取文件时，将标题中声明的列与架构对齐时是否区分大小写。对于自动加载程序，此项默认为 `true`。如果启用，则会在 `rescuedDataColumn` 中补救大小写不同的列。已不推荐使用此选项，推荐使用 `readerCaseSensitive`。默认值：30`false`
`positiveInf` 类型：`String` 分析 `FloatType` 或 `DoubleType` 列时正无穷大的字符串表示形式。默认值：30`"Inf"`
`preferDate` 类型：`Boolean` 如果可能，尝试将字符串推断为日期而不是时间戳。还必须通过启用 `inferSchema` 或使用以下项来使用架构推理 `cloudFiles.inferColumnTypes` 与自动加载程序。默认值：30`true`
`quote` 类型：`Char` 当字段分隔符是值的一部分时用于对值进行转义的字符。默认值：30`"`
`readerCaseSensitive` 类型：`Boolean` 指定启用 `rescuedDataColumn` 时区分大小写的行为。如果为 true，则拯救名称因大小写而与架构不同的数据列；否则，请以不区分大小写的方式读取数据。默认值：30`true`
`rescuedDataColumn` 类型：`String` 是否将因数据类型不匹配和架构不匹配（包括列大小写）而无法分析的所有数据收集到单独的列。使用自动加载程序时，默认包含此列。有关更多详细信息，请参考什么是补救的数据列？。默认值：无
`sep` 或 `delimiter` 类型：`String` 列之间的分隔符字符串。默认值：30`","`
`skipRows` 类型：`Int` CSV 文件开头应忽略的行数（包括注释行和空行）。如果 `header` 为 true，则标头将是第一个未跳过和未注释的行。默认值：30`0`
`timestampFormat` 类型：`String` 用于分析时间戳字符串的格式。默认值：30`yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`
`timeZone` 类型：`String` 分析时间戳和日期时要使用的 `java.time.ZoneId`。默认值：无
`unescapedQuoteHandling` 类型：`String` 用于处理未转义的引号的策略。允许的选项： * `STOP_AT_CLOSING_QUOTE`：如果在输入中发现了未转义的引号，则会累积引号字符并继续将值解析为带引号的值，直至找到右引号。 * `BACK_TO_DELIMITER`：如果在输入中发现了未转义的引号，则会将该值视为无引号的值。这会让分析程序累积当前所分析值的所有字符，直至找到 `sep` 定义的分隔符。如果在值中找不到分隔符，则分析程序会继续从输入中累积字符，直到找到分隔符或行尾。 * `STOP_AT_DELIMITER`：如果在输入中发现了未转义的引号，则会将该值视为无引号的值。这会让分析程序累积所有字符，直至在输入中找到 `sep` 定义的分隔符或找到行尾。 * `SKIP_VALUE`：如果在输入中发现了未转义的引号，则将跳过针对给定值所解析的内容（直至找到下一个分隔符），并将改为生成 `nullValue` 中设置的值。 * `RAISE_ERROR`：如果在输入中发现了未转义的引号，则会引发 `TextParsingException`。默认值：30`STOP_AT_DELIMITER`

`XML` 选项

选项	说明	范围
`rowTag`	要作为行处理的 XML 文件的行标记。在示例 XML `<books> <book><book>...<books>` 中，相应的值为 `book`。这是必需选项。	读取
`samplingRatio`	定义用于架构推理的行的一部分。 XML 内置函数会忽略此选项。默认：`1.0`。	读取
`excludeAttribute`	是否排除元素中的属性。默认：`false`。	读取
`mode`	在分析期间处理损坏记录的模式。 `PERMISSIVE`：对于损坏的记录，将格式错误的字符串放入由 `columnNameOfCorruptRecord` 配置的字段中，并将格式错误的字段设置为 `null`。若要保留损坏的记录，可以在用户定义的架构中设置名为 `columnNameOfCorruptRecord` 的 `string` 类型字段。如果架构没有该字段，则会在分析期间删除损坏的记录。推理架构时，分析程序会在输出架构中隐式添加 `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`	是否将因数据类型不匹配和架构不匹配（包括列大小写）而无法分析的所有数据收集到单独的列中。使用自动加载程序时，默认包含此列。有关详细信息，请参阅什么是补救的数据列？。默认值：无。	读取

`PARQUET` 选项

选项
`datetimeRebaseMode` 类型：`String` 控制 DATE 和 TIMESTAMP 值在儒略历与外推格里历之间的基本值重定。允许的值：`EXCEPTION`、`LEGACY` 和 `CORRECTED`。默认值：30`LEGACY`
`int96RebaseMode` 类型：`String` 控制 INT96 时间戳值在儒略历与外推格里历之间的基本值重定。允许的值：`EXCEPTION`、`LEGACY` 和 `CORRECTED`。默认值：30`LEGACY`
`mergeSchema` 类型：`Boolean` 是否跨多个文件推理架构并合并每个文件的架构。默认值：30`false`
`readerCaseSensitive` 类型：`Boolean` 指定启用 `rescuedDataColumn` 时区分大小写的行为。如果为 true，则拯救名称因大小写而与架构不同的数据列；否则，请以不区分大小写的方式读取数据。默认值：30`true`
`rescuedDataColumn` 类型：`String` 是否将因数据类型不匹配和架构不匹配（包括列大小写）而无法分析的所有数据收集到单独的列。使用自动加载程序时，默认包含此列。有关更多详细信息，请参考什么是补救的数据列？。默认值：无

`AVRO` 选项

选项
`avroSchema` 类型：`String` 用户以 Avro 格式提供的可选架构。读取 Avro 时，可以将此选项设置为一个演变的架构，该架构与实际 Avro 架构兼容但不同。反序列化架构会与演变的架构保持一致。例如，如果你设置的演变架构包含一个具有默认值的附加列，则读取结果也会包含该新列。默认值：无
`datetimeRebaseMode` 类型：`String` 控制 DATE 和 TIMESTAMP 值在儒略历与外推格里历之间的基本值重定。允许的值：`EXCEPTION`、`LEGACY` 和 `CORRECTED`。默认值：30`LEGACY`
`mergeSchema` 类型：`Boolean` 是否跨多个文件推理架构并合并每个文件的架构。 Avro 的 `mergeSchema` 不放宽数据类型。默认值：30`false`
`readerCaseSensitive` 类型：`Boolean` 指定启用 `rescuedDataColumn` 时区分大小写的行为。如果为 true，则拯救名称因大小写而与架构不同的数据列；否则，请以不区分大小写的方式读取数据。默认值：30`true`
`rescuedDataColumn` 类型：`String` 是否将因数据类型不匹配和架构不匹配（包括列大小写）而无法分析的所有数据收集到单独的列。使用自动加载程序时，默认包含此列。有关更多详细信息，请参考什么是补救的数据列？。默认值：无

`BINARYFILE` 选项

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

`TEXT` 选项

选项
`encoding` 类型：`String` TEXT 文件编码的名称。有关选项列表，请参阅 `java.nio.charset.Charset`。默认值：30`UTF-8`
`lineSep` 类型：`String` 两个连续 TEXT 记录之间的字符串。默认值：None，涵盖 `\r`、`\r\n` 和 `\n`
`wholeText` 类型：`Boolean` 是否将文件读取为单个记录。默认值：30`false`

`ORC` 选项

选项
`mergeSchema` 类型：`Boolean` 是否跨多个文件推理架构并合并每个文件的架构。默认值：30`false`

流式处理选项

当在流式处理表或流式处理查询中使用 read_files 时，会应用这些选项。

选项
`allowOverwrites` 类型：`Boolean` 是否重新处理发现后已修改的文件。如果自上次成功刷新查询启动时间起，文件已修改，则会在刷新过程中处理文件的最新可用版本。默认值：30`false`
`includeExistingFiles` 类型：`Boolean` 是包含流式处理输入路径中的现有文件，还是仅处理初始设置后到达的新文件。仅在首次启动流时会评估此选项。在重启流后更改此选项不起作用。默认值：30`true`
`maxBytesPerTrigger` 类型：`Byte String` 要在每个触发器中处理的最大新字节数。你可以指定一个字节字符串（例如 `10g`），将每个微批限制为 10 GB 数据。这个一个软性最大值。如果每个文件为 3 GB，则 Azure Databricks 在一个微批中可以处理 12 GB。与 `maxFilesPerTrigger` 一起使用时，Azure Databricks 最多将消耗 `maxFilesPerTrigger` 或 `maxBytesPerTrigger` 的最低限制（以先达到者为准）。注意：对于在无服务器 SQL 仓库中创建的流式处理表，不得将此选项和 `maxFilesPerTrigger` 设置为使用动态许可控制，该控制按工作负载大小和无服务器计算资源进行缩放，从而为你提供最佳延迟和性能。默认值：无
`maxFilesPerTrigger` 类型：`Integer` 要在每个触发器中处理的最大新文件数。与 `maxBytesPerTrigger` 一起使用时，Azure Databricks 最多将消耗 `maxFilesPerTrigger` 或 `maxBytesPerTrigger` 的最低限制（以先达到者为准）。注意：对于在无服务器 SQL 仓库中创建的流式处理表，不得将此选项和 `maxBytesPerTrigger` 设置为使用动态许可控制，该控制按工作负载大小和无服务器计算资源进行缩放，从而为你提供最佳延迟和性能。默认值：1000
`schemaEvolutionMode` 类型：`String` 在数据中发现新列时架构演变的模式。默认情况下，在推断 JSON 数据集时，将列推断为字符串。有关更多详细信息，请参阅架构演变。此选项不适用于 `text` 和 `binaryFile` 文件。默认值：在未提供架构时为 `"addNewColumns"`。否则为 `"none"`。
`schemaLocation` 类型：`String` 存储推断出的架构和后续更改的位置。有关更多详细信息，请参阅架构推理。在流式处理表查询中使用时，不需要架构位置。默认值：无

示例

-- Reads the files available in the given path. Auto-detects the format and schema of the data.
> SELECT * FROM read_files('abfss://container@storageAccount.dfs.core.chinacloudapi.cn/base/path');

-- Reads the headerless CSV files in the given path with the provided schema.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv',
    schema => 'id int, ts timestamp, event string');

-- Infers the schema of CSV files with headers. Because the schema is not provided,
-- the CSV files are assumed to have headers.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv')

-- Reads files that have a csv suffix.
> SELECT * FROM read_files('s3://bucket/path/*.csv')

-- Reads a single JSON file
> SELECT * FROM read_files(
    'abfss://container@storageAccount.dfs.core.chinacloudapi.cn/path/single.json')

-- Reads JSON files and overrides the data type of the column `id` to integer.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'json',
    schemaHints => 'id int')

-- Reads files that have been uploaded or modified yesterday.
> SELECT * FROM read_files(
    'gs://my-bucket/avroData',
    modifiedAfter => date_sub(current_date(), 1),
    modifiedBefore => current_date())

-- Creates a Delta table and stores the source file path as part of the data
> CREATE TABLE my_avro_data
  AS SELECT *, _metadata.file_path
  FROM read_files('gs://my-bucket/avroData')

-- Creates a streaming table that processes files that appear only after the table's creation.
-- The table will most likely be empty (if there's no clock skew) after being first created,
-- and future refreshes will bring new data in.
> CREATE OR REFRESH STREAMING TABLE avro_data
  AS SELECT * FROM STREAM read_files('gs://my-bucket/avroData', includeExistingFiles => false);

通过

read_files 表值函数

语法

参数

返回

文件发现

使用 glob 模式筛选目录或文件

架构推理

分区架构推理

流式处理表中的使用情况

选项

基本选项

泛型选项

JSON 选项

CSV 选项

XML 选项

PARQUET 选项

AVRO 选项

BINARYFILE 选项

TEXT 选项

ORC 选项