读取 ======== 使用不同的读取器把多样的数据格式加载为结构化临时视图。 语法 ------- load [格式] [查询] [选项] 格式 ------- 当前支持的数据源格式包括：``csv``、``xlsx``、``json``、``xml``、``parquet``、``orc``、``avro``、``binaryFile``、``jdbc``。 查询 -------- 文件数据源传递文件的绝对路径或文件夹搭配文件名过滤正则表达式批量读取，Jdbc传递查询语句及连接使用的数据源名。 其它数据源或者格式使用不同的查询方式。意味着 ``[查询]`` 没有固定格式，取决于所连数据源的特性。 Csv ^^^^^^ 从Csv文件加载数据。 .. code-block:: sql load csv '/path/orders.csv' option sep=',', encoding='utf-8'; 带上 ``inferSchema`` 选项可以自动推断列数据类型。 .. code-block:: sql load csv '/path/' option inferSchema='true', pathGlobFilter='*-part.csv'; ``pathGlobFilter`` 选项可正则匹配要读取的文件，批量读取。文件数据源类型读取都可以使用这个选项。 也可以不带任何选项，一切默认。 .. code-block:: sql load csv '/path/orders.csv'; Xlsx ^^^^^ 从Xlsx文件加载数据。 .. code-block:: sql load xlsx '/path/' option inferSchema='true', pathGlobFilter='*-part.xlsx', -- 文件名过滤 workbookPassword='123', -- 读取密码 timestampFormat='yyyy-mm-dd hh:mm'; -- 时间戳读取格式 也可以不带任何选项，一切默认。 .. code-block:: sql load xlsx '/path/orders.xlsx'; Json ^^^^^^ 从Json文件加载数据。 .. code-block:: sql load json '/path/' option pathGlobFilter='*-part.json', -- 文件名过滤 allowComments='true', -- 忽略JSON记录中的注释 allowUnquotedFieldNames='true', -- 允许不带引号的JSON字段名 allowSingleQuotes='true', -- 除双引号外，还允许单引号 encoding='utf-8', -- 字符编码 timestampFormat='yyyy-mm-dd hh:mm'; -- 时间戳读取格式 也可以不带任何选项，一切默认。 .. code-block:: sql load json '/path/orders.json'; Xml ^^^^^ 从Xml文件加载数据。 .. code-block:: sql load xml '/path/' option pathGlobFilter='*-part.xml' option charset='utf-8', -- 字符编码 rowTag='row'; -- 代表行的XML标签名称: ... 也可以不带任何选项，一切默认。 .. code-block:: sql load xml '/path/orders.xml'; Parquet、Orc、Avro ^^^^^^^^^^^^^^^^^^^ 从Parquet、Orc、Avro文件加载数据。以Parquet为例。 .. code-block:: sql load parquet '/path/' option pathGlobFilter='*-part.parquet' 也可以不带任何选项，一切默认。 .. code-block:: sql load parquet '/path/orders.parquet'; BinaryFile ^^^^^^^^^^^ .. code-block:: sql load binaryFile '/path/' option pathGlobFilter='*.png' 也可以不带任何选项，一切默认。 .. code-block:: sql load binaryFile '/path/face.png'; 读取二进制文件并将每个文件转换为一个记录，其中包含文件的原始内容和元数据。它生成一个数据集，其中包含以下列，可能还有分区列： ================ ============== 列名 描述 ================ ============== path 路径 modificationTime 修改时间 length 长度 content 二进制内容 ================ ============== Jdbc ^^^^^^ 从关系型数据库或者任意支持JDBC协议查询数据的系统或引擎加载数据。 .. code-block:: sql load jdbc "select * from orders where buy_date='2020-06-12'" option ds='default' ``ds`` 选项值为数据源名，可实现接口改变数据源的创建方式，默认是从本地配置文件读取并创建。 数据源名不是必须的，如果不显式指定，则默认会去查找名称是 ``default`` 的数据源配置。 .. code-block:: sql load jdbc 'select * from products' 选项 -------- .. important:: 所有选项都有默认值，可以满足绝大部分数据加载要求，当遇到不能读取时，可参考选择其它选项。即通常不需要带上 ``[选项]`` 表达式。 文件数据源通用读取选项 ^^^^^^^^^^^^^^^^^^^^^^^^^^ ===================================== ================================== 选项 说明 ===================================== ================================== pathGlobFilter 读取包括文件名与模式匹配的文件(如：\*-2.csv，\*.xlsx，\*.png等) recursiveFileLookup 递归读取文件，并禁用分区推断，默认 false modifiedBefore 读取包含修改时间早于指定时间的文件；如：'2020-07-01T05:30:00' modifiedAfter 读取包含修改时间晚于指定时间的文件；如：'2020-06-01T05:30:00' ===================================== ================================== CSV 文件读取选项 ^^^^^^^^^^^^^^^^ ============================== ==================================== 选项名 选项使用描述 ============================== ==================================== sep 为每个字段和值设置分隔符（一个或多个字符）。如果未设置，则使用默认值 ， encoding 按给定的编码类型解码CSV文件。如果未设置，则使用默认值UTF-8 quote 设置用于转义引号的单个字符，其中分隔符可以是值的一部分。如果未设置，则使用默认值"。如果要关闭引号，则需要设置一个空字符串。 escape 设置用于转义已引用值内引号的单个字符。如果未设置，则使用默认值\ comment 设置用于跳过以该字符开头的行的单个字符。默认情况下（无），它是禁用的 header 使用第一行作为列的名称。如果未设置，则使用默认值false inferSchema 根据数据自动推断输入模式。它需要对数据进行一次额外的传递。如果未设置，则使用默认值false enforceSchema 如果设置为true，则指定或推断的架构将强制应用于数据源文件，并且CSV文件中的头将被忽略。如果该选项设置为false，则将根据CSV文件中的所有头验证模式，如果header选项设置为true，则根据RDD中的第一个头验证模式。架构中的字段名和CSV标题中的列名将根据它们的位置进行检查，并考虑spark.sql.caseSensitive。如果未设置，则默认情况下使用true。尽管默认值为true，但建议禁用enforceSchema选项以避免错误的结果 ignoreLeadingWhiteSpace 指示是否应跳过正在读取的值的前导空格的标志。如果未设置，则使用默认值false ignoreTrailingWhiteSpace 指示是否应跳过正在读取的值的尾随空格的标志。如果未设置，则使用默认值false nullValue 设置空值的字符串表示形式。如果未设置，则使用默认值空字符串 nanValue 设置非数字值的字符串表示。如果未设置，则使用默认值NaN positiveInf 设置正无穷大值的字符串表示形式。如果未设置，则使用默认值Inf negativeInf 设置负无穷大值的字符串表示。如果未设置，则使用默认值Inf dateFormat 设置指示日期格式的字符串。自定义日期格式遵循日期时间格式这适用于日期类型。如果未设置，则使用默认值yyyy-MM-dd timestampFormat 设置表示时间戳格式的字符串。如果未设置，则使用默认值yyyy-MM-dd'T'HH:MM:ss[.SSS][XXX] maxColumns 定义一条记录可以有多少列的硬限制。如果未设置，则使用默认值20480 maxCharsPerColumn 定义读取任何给定值所允许的最大字符数。如果未设置，则使用默认值，-1表示无限长度 mode 允许在解析期间处理损坏记录的模式。如果未设置，则使用默认值PERMISSIVE。DROPMALFORMED: 忽略所有损坏的记录。FAILFAST: 遇到损坏的记录时引发异常 columnNameOfCorruptRecord 允许重命名由PERMISSIVE模式创建的字符串格式错误的新字段 multiLine 分析记录，该记录可以跨多行。如果未设置，则使用默认值false charToEscapeQuoteEscaping 设置用于转义引号字符转义的单个字符。如果未设置任何值，则当转义字符和引号字符不同时，默认值为转义字符，否则为\\0 samplingRatio 定义用于架构推断的部分行。如果未设置，则使用默认值1.0 emptyValue 设置空值的字符串表示形式。如果未设置，则使用默认值空字符串 locale 将区域设置设置为IETF BCP 47格式的语言标记。如果未设置，则使用默认值en-US。例如，在解析日期和时间戳时使用区域 lineSep 定义应用于分析的行分隔符。如果未设置，则覆盖所有\\r、\\r\\n和\\n。最大长度为1个字符 unescapedQuoteHandling 定义CsvParser如何处理带有未转义引号的值。如果未设置任何值，则使用默认值 STOP_AT_DELIMITER；STOP_AT_CLOSING_QUOTE：如果在输入中找到未转义的引号，则累积引号字符并继续将值作为引号进行解析，直到找到右引号；BACK_TO_DELIMITER：如果在输入中找到未逃逸的引文，则将该值视为未引用的值。这将使解析器累积当前解析值的所有字符，直到找到分隔符为止。如果在值中找不到分隔符，解析器将继续从输入中累积字符，直到找到分隔符或行尾；STOP_AT_DELIMITER：如果在输入中找到未逃逸的引文，则将该值视为未引用的值。这将使解析器累积所有字符，直到在输入中找到分隔符或行尾；SKIP_VALUE：如果在输入中发现未转义的引号，则将跳过为给定值解析的内容，并生成在nullValue中设置的值；RAISE_ERROR：如果在输入中发现未转义的引号，则抛出异常 ============================== ==================================== XLSX 文件读取选项 ^^^^^^^^^^^^^^^^^ ============================= ==================================== 选项名 选项使用描述 ============================= ==================================== dataAddress "'My Sheet'!B3:C35"，缺省 'A1' treatEmptyValuesAsNulls 'true|false'，缺省 'true'; 是否将空值视为null setErrorCellsToFallbackValues 'true|false'，缺省 'false'; 其中错误将转换为null。如果为true，则任何错误单元格值（例如#N/A）都将转换为列数据类型的零值。 usePlainNumberFormat 'true|false'，缺省 'false'; 在没有舍入和科学符号的情况下格式化单元格 inferSchema 架构推断 addColorColumns 'true|false'，缺省 'false'; maxRowsInMemory 20，默认为空；如果设置了，则使用流式读取器，可以帮助处理大文件 excerptSize 10；如果设置并推断架构，则要从中推断架构的行数 workbookPassword '密码'，缺省没有密码 timestampFormat 'MM-dd-yyyy HH\:mm\:ss'；缺省 'yyyy-mm-dd hh\:mm\:ss[.fffffffff]' ============================= ==================================== JSON 文件读取选项 ^^^^^^^^^^^^^^^^^^^ ==================================== ==================================== 选项名 选项使用描述 ==================================== ==================================== primitivesAsString 将所有基元值推断为字符串类型。如果未设置，则使用默认值false prefersDecimal 将所有浮点值推断为十进制类型。如果这些值不适合十进制，则推断它们是双倍的。如果未设置，则使用默认值false allowComments 忽略JSON记录中的Java/C++样式注释。如果未设置，则使用默认值false allowUnquotedFieldNames 允许不带引号的JSON字段名。如果未设置，则使用默认值false allowSingleQuotes 除双引号外，还允许单引号。如果未设置任何值，则使用默认值true allowNumericLeadingZero 允许数字中的前导零（例如00012）。如果未设置，则使用默认值false allowBackslashEscapingAnyCharacter 允许使用反斜杠引用机制接受所有字符的引用。如果未设置，则使用默认值false mode 允许在解析期间处理损坏记录的模式。如果没有设置，它使用默认值 PERMISSIVE， PERMISSIVE: 当它遇到损坏的记录时，将格式错误的字符串放入由columnNameOfCorruptRecord配置的字段中，并将格式错误的字段设置为null。要保留损坏的记录，用户可以在用户定义的架构中设置名为columnNameOfCorruptRecord的字符串类型字段。如果架构没有该字段，它会在解析过程中删除损坏的记录。推断模式时，它会在输出模式中隐式添加columnNameOfCorruptRecord字段；DROPMALFORMED： 忽略所有损坏的记录 ；FAILFAST：读取失败抛出错误 columnNameOfCorruptRecord 允许重命名由PERMISSIVE模式创建的字符串格式错误的新字段 dateFormat 设置指示日期格式的字符串。如果未设置，则使用默认值，yyyy-MM-dd timestampFormat 设置表示时间戳格式的字符串。如果未设置，则使用默认值，yyyy-MM-dd'T'HH\:mm\:ss[.SSS][XXX] multiLine 对每个文件分析一条记录，该记录可能跨越多行。如果未设置，则使用默认值false allowUnquotedControlChars 允许JSON字符串包含不带引号的控制字符（值小于32的ASCII字符，包括制表符和换行符） encoding 允许强制设置JSON文件的标准基本或扩展编码之一。例如UTF-16BE、UTF-32LE。如果没有设置，当multiLine选项设置为true时，将自动检测输入JSON的编码 lineSep 定义应用于分析的行分隔符。如果未设置，则覆盖所有\r\n和\r\n samplingRatio 定义用于模式推断的部分输入JSON对象。如果未设置，则使用默认值1.0 dropFieldIfAllNull 在模式推断期间是否忽略所有空值的列或空数组/结构。如果未设置，则使用默认值false locale 将区域设置设置为IETF BCP 47格式的语言标记。如果未设置，则使用默认值en-US。例如，在解析日期和时间戳时使用本地区域 allowNonNumericNumbers 允许JSON解析器将一组“Not-a-Number”（NaN）标记识别为合法的浮点数值。如果未设置任何值，则使用默认值true；+INF：正无穷大；-INF：负无穷大；NaN：对于其他不是数字，比如被零除的结果 ==================================== ==================================== XML 文件读取选项 ^^^^^^^^^^^^^^^^ =============== ======================================================================== 选项名 选项使用描述 =============== ======================================================================== charset 字符编码 rowTag 代表行的标签名称 =============== ======================================================================== Parquet、Orc、Avro 文件读取选项 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =============== ======================================================================== 选项名 选项使用描述 =============== ======================================================================== mergeSchema 设置是否应合并从所有分区文件收集的架构 =============== ======================================================================== JDBC 数据源读取选项 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =============== ======================================================================== 选项名 选项使用描述 =============== ======================================================================== ds 设置数据源名称，默认 default；数据源的获取方式可自定义实现 =============== ========================================================================