Repository navigation
Description
Part of #271 and apache/datafusion-comet#7300.
What the function does
schema_of_xml(xml[, options]) infers the Spark type of one XML record and returns it as a DDL-formatted
STRING (DataType.sql), for example STRUCT<a: BIGINT, b: STRING>. It was added in Spark 4.0.0.
- Arguments.
xmlmust be foldable. A column fails withDATATYPE_MISMATCH.NON_FOLDABLE_INPUT, and
schema_of_xml(null)fails withDATATYPE_MISMATCH.UNEXPECTED_NULL.optionsis amap(...)of string
literals using theXmlOptionskeys. - Result. The result is non-nullable and in practice a constant, typically passed as the schema of
from_xml. - Root element. Its name is ignored. Its attributes and children become the fields.
Inference is XmlInferSchema.infer(xml) followed by canonicalizeType, with XmlOptions in the UTC time
zone and case sensitivity from spark.sql.caseSensitive. A StructType result whose fields are all removed
by canonicalization becomes STRUCT<>.
Examples
SELECT schema_of_xml('<p><a>1</a></p>');
-- STRUCT<a: BIGINT>
SELECT schema_of_xml('<p><a attr="2">1</a><a>3</a></p>', map('excludeAttribute', 'true'));
-- STRUCT<a: ARRAY<BIGINT>>
SELECT schema_of_xml('<p><a>1</a><b>"2"</b></p>');
-- STRUCT<a: BIGINT, b: STRING>
SELECT schema_of_xml('<record><time>14:30:45</time></record>', map('rowTag', 'record'));
-- STRUCT<time: TIMESTAMP>
SELECT schema_of_xml(regexp_replace('<ROW><item_id>1</item_id><item_price>0.1</item_price></ROW>', 'item_', ''));
-- STRUCT<id: BIGINT, price: DOUBLE>
SELECT schema_of_xml('<ROW><id></id></ROW>');
-- STRUCT<id: STRING>
SELECT schema_of_xml('<ROW><a>1<ROW>', map('mode', 'PERMISSIVE'));
-- STRUCT<_corrupt_record: STRING>
SELECT schema_of_xml(42);
-- error: DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE (4.1+)These come from the ExpressionDescription, xml-functions.sql.out, XmlFunctionsSuite and XmlSuite. The
regexp_replace case shows that any foldable expression is accepted, not only a literal.
Edge cases to test
-
Value inference (
inferFrom, after trimming whenignoreSurroundingSpaces=true, the default). The rules
are tried in this order:- empty:
NullType, which becomesSTRING; Long-parseable (optional sign, first character a digit):BIGINT;- with
prefersDecimal=true, decimal-parseable:DECIMAL(max(p, s), s); - double-parseable, but not ending in
d,D,forF:DOUBLE; trueorfalse, case-insensitive:BOOLEAN;- a date per
dateFormat, only whenpreferDate=true(the default, and forced off under the legacy time
parser policy):DATE; TIMESTAMP_NTZ, only whenspark.sql.timestampType=TIMESTAMP_NTZor the legacy policy is on;- a timestamp per
timestampFormat, or the default parser:TIMESTAMP(14:30:45above); - anything else:
STRING.
With
inferSchema=false, every value isSTRING. - empty:
-
Structure.
- Elements become struct fields sorted by name.
- A repeated element becomes
ARRAY<...>, with the element types merged bycompatibleType. That function
usesfindTightestCommonTypeand has these rules:DOUBLEwithDECIMALgivesDOUBLE;- a decimal that would need precision above 38 becomes
DOUBLE; TIMESTAMP_NTZwithTIMESTAMPgivesTIMESTAMP;- structs merge their fields;
- an array with a scalar gives an array;
- a struct with a
valueTagfield merged with a scalar widens the value field; - anything else gives
STRING.
- Attributes become
_-prefixed fields (attributePrefix). An element with attributes and text gets a
_VALUEfield (valueTag).
-
Case sensitivity. With
spark.sql.caseSensitive=false,<foo>,<Foo>and<FOO>merge into one array
field named after the first name seen. Withtrue, they are three fields. -
Other options.
ignoreNamespace,excludeAttribute,nullValue,dateFormat,timestampFormat,
timestampNTZFormatandlocale. -
Malformed input.
PERMISSIVEreturnsSTRUCT<_corrupt_record: STRING>, usingcolumnNameOfCorruptRecordor the
spark.sql.columnNameOfCorruptRecordconfig.FAILFASTraisesMALFORMED_RECORD_IN_PARSING.WITHOUT_SUGGESTION, andbadRecordis the corrupt column
name (_corrupt_record), not the input.DROPMALFORMEDraisesPARSE_MODE_UNSUPPORTEDwithfuncName`schema_of_xml`.
-
Other inputs. Also test an empty element (
STRING), deeply nested structs, mixed content, and Unicode
element names.
Differences across Spark versions
- Not available in 3.4 or 3.5.
- 4.1 adds the
UNEXPECTED_INPUT_TYPEcheck for a non-STRINGfoldable argument (schema_of_xml(42)). In 4.0
that query has no golden result. - 4.2:
TIMEvalues are still inferred asTIMESTAMP(golden above). There is noTIMEinference.
Implementation notes
- Spark:
SchemaOfXmlinsql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/xmlExpressions.scala
(RuntimeReplaceable, aStaticInvokeofXmlExpressionEvalUtils.schemaOfXml), with inference in
sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/xml/XmlInferSchema.scala. - DataFusion core has no equivalent.
- The argument is a literal, so the kernel can run once (at planning time or on the first batch) and return a
scalar. It needs a Spark-styleDataType.sqlprinter (STRUCT<a: BIGINT>, upper-case,:separators).
Share it withschema_of_jsonandschema_of_csvif they exist by then. - Use the same XML tokenizer as
from_xml(quick-xmlis a natural fit). The crate has no XML dependency
today. Put it incrates/spark/src/function/xml/. - Tests: add
crates/sqllogictest/test_files/xml/schema_of_xml.sltand document the function with#[user_doc].
This issue was generated by an LLM (Claude) from the Apache Spark source code and tests. Examples come from Spark's ExpressionDescription examples, test suites and .sql.out golden files, but please verify them against Spark before relying on them.
Activity