通过

from_json 函数

适用于：勾选“是” Databricks SQL 勾选“是” Databricks Runtime

返回具有 jsonStr 和 schema 的结构值。

语法

from_json(jsonStr, schema [, options])

参数

  • jsonStr：指定 json 文档的 STRING 表达式。
  • schema：STRING表达式或对schema_of_json函数的调用。
  • options：指定指令的可选MAP<STRING,STRING>文本。

jsonStr 在 schema 和 options 方面的格式应正确。

schema必须将其定义为逗号分隔列名和数据类型对，类似于所使用的CREATE TABLE格式。 在 Databricks Runtime 12.2 之前的版本中，schema 必须是字面量。

或者，可以将 from_json 与 Lakeflow 声明性管道配合使用，通过将 schema 设置为 NULL 并指定 schemaLocationKey 来自动推断和改进架构。 有关示例，请参阅使用 Lakeflow 声明性管道推断和改进架构from_json。

注意

schema 中的列名称和字段名称区分大小写，必须与 jsonStr 中的名称完全匹配。 要映射仅大小写不同的 JSON 字段，可以将生成的结构强制转换为不同的字段名称。 有关更多详细信息，请参阅示例。

如果提供，options 可以是下列任何内容：

  • primitivesAsString（默认值为 false）：将所有基元值推断为字符串类型。
  • prefersDecimal（默认值为 false）：将所有浮点值推断为十进制类型。 如果这些值不适合十进制，那么它会将这些值推断为双精度值。
  • allowComments（默认值为 false）：忽略 JSON 记录中的 Java 和 C++ 样式注释。
  • allowUnquotedFieldNames（默认值为 false）：允许不带引号的 JSON 字段名称。
  • allowSingleQuotes（默认值为 true）：除了双引号外，还允许单引号。
  • allowNumericLeadingZeros（默认值为 false）：允许数字有前导零（例如，00012）。
  • allowBackslashEscapingAnyCharacter（默认值为 false）：允许使用反斜杠引用机制接受所有字符的引用。
  • allowUnquotedControlChars（默认值为 false）：允许 JSON 字符串包含或不包含不带引号的控制字符（值小于 32 的 ASCII 字符，包括制表符和换行符）。
  • mode（默认值为 PERMISSIVE）：允许采用在分析期间处理损坏记录的模式。
    • PERMISSIVE：遇到损坏的记录时，将格式错误的字符串放入由 columnNameOfCorruptRecord 配置的字段中，并将格式错误的字段设置为 null。 若要保留损坏的记录，可以在用户定义的架构中设置名为 columnNameOfCorruptRecord 的字符串类型字段。 如果架构没有该字段，则会在分析期间删除损坏的记录。 推理架构时，它会在输出架构中隐式添加 columnNameOfCorruptRecord 字段。
    • FAILFAST：遇到损坏的记录时引发异常。
  • columnNameOfCorruptRecord（默认值为 spark.sql.columnNameOfCorruptRecord 中指定的值）：允许重命名通过 PERMISSIVE 模式创建的包含格式错误字符串的新字段。 这会替代 spark.sql.columnNameOfCorruptRecord。
  • dateFormat（默认值为 yyyy-MM-dd）：设置指示日期格式的字符串。 自定义日期格式遵循日期/时间模式中的格式。 这适用于日期类型。
  • timestampFormat（默认值为 yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]）：设置指示时间戳格式的字符串。 自定义日期格式遵循日期/时间模式中的格式。 这适用于时间戳类型。
  • multiLine（默认值为 false）：按每个文件分析一个记录，该记录可能跨多行。
  • encoding（默认情况下未设置）：允许为 JSON 文件强制设置标准的基本或扩展编码之一。 例如 UTF-16BE、UTF-32LE。 如果未指定编码且 multiLine 设置为 true，则会自动检测。
  • lineSep（默认值涵盖所有 \r、\r\n 和 \n）：定义要用于分析的行分隔符。
  • samplingRatio（默认值为 1.0）：定义用于架构推理的输入 JSON 对象的比例。
  • dropFieldIfAllNull（默认值为 false）：在架构推理期间是否忽略所有 null 值或空数组/结构的列。
  • locale（默认值为 en-US）：将某个区域设置 sets 为 IETF BCP 47 格式的语言标记。 例如，在分析日期和时间戳时使用。
  • allowNonNumericNumbers（默认值为 true）：允许 JSON 分析器将非数值 (NaN) 令牌集识别为合法的浮点数值：
    • +INF 表示正无穷大，以及 +Infinity 和 Infinity 的别名。
    • -INF 表示负无穷大，-Infinity 的别名。
    • NaN 用于其他非数值，例如除以零的结果。
  • readerCaseSensitive（默认值为 true）：指定启用 rescuedDataColumn 时区分大小写的行为。 如果为 true，则拯救名称因大小写而与架构不同的数据列；否则，请以不区分大小写的方式读取数据。 在 Databricks SQL 和 Databricks Runtime 13.3 LTS 及更高版本中可用。

返回

一个结构，其字段名称和类型与架构定义匹配。

示例

> SELECT from_json('{"a":1, "b":0.8}', 'a INT, b DOUBLE');
{"a":1,"b":0.8}

-- The column name must to match the case of the JSON field
> SELECT from_json('{"a":1}', 'A INT');
{"A":null}

> SELECT from_json('{"datetime":"26/08/2015"}', 'datetime Timestamp', map('timestampFormat', 'dd/MM/yyyy'));
{"datetime":2015-08-26 00:00:00}

-- Disambiguate field names with different cases
> SELECT cast(from_json('{"a":1, "A":0.8}', 'a INT, A DOUBLE') AS STRUCT<a: INT, b: DOUBLE>);
 {"a":1, "b":0.8}