from_json 函数

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

返回具有 jsonStrschema 的结构值。

语法

from_json(jsonStr, schema [, options])

参数

  • jsonStr:指定 json 文档的 STRING 表达式。
  • schemaschema_of_json 函数的 STRING 表达式或调用。
  • options:指定指令的可选 MAP<STRING,STRING> 字面量。

jsonStrschemaoptions 方面的格式应正确。

schema 必须定义为逗号分隔的列名称和数据类型对(例如如同在 CREATE TABLE 中使用一样)。 在 Databricks Runtime 12.2 之前的版本中,schema 必须是字面量。

如果提供,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 表示正无穷大,以及 +InfinityInfinity 的别名。
    • -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');
 {1,0.8}

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