Repository navigation
Open
Labels
enhancementNew feature or requestNew feature or request
Description
Part of #271 and apache/datafusion-comet#7300.
What the function does
to_xml(expr[, options]) serializes a STRUCT (or a VARIANT, from 4.1) to an XML string. It was added in
Spark 4.0.0.
- Arguments. Any other input type fails analysis with
DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE
(requiredType"STRUCT").optionsmust be amap(...)of string literals. Otherwise the error is
INVALID_OPTIONS.NON_MAP_FUNCTIONorINVALID_OPTIONS.NON_STRING_TYPE. Wrong arity gives
WRONG_NUM_ARGS.WITHOUT_SUGGESTION(expectedNum[1, 2]). - Result. The result is a nullable
STRING(the session default string type). The function is
NULL-intolerant and time zone aware.
Output comes from StaxXmlGenerator, which wraps a Woodstox XMLStreamWriter with structure validation off.
- Row element. The struct is written as one element named
rowTag(defaultROW). No XML declaration and
norootTagwrapper are written; those are file-writer only. - Indentation. The default
indentis four spaces, which gives newline-separated, indented output.
indentset to''gives compact output. - Fields. A field whose name starts with
attributePrefix(default_), and is notvalueTag(default
_VALUE), becomes an attribute without the prefix. Attributes are written before child elements. The
valueTagfield is written as the element's text. - NULL values. When
nullValueis not set (the default), NULL fields are omitted. Otherwise the
nullValuetext is written. - Arrays. An array field becomes repeated elements with the field's name. An array nested directly in an
array usesarrayElementName(defaultitem). - Maps. A map becomes child elements keyed by the map key. Keys with the attribute prefix become
attributes.
Examples
SELECT to_xml(named_struct('a', 1, 'b', 2));
-- <ROW>
-- <a>1</a>
-- <b>2</b>
-- </ROW>
SELECT to_xml(named_struct('a', 1, 'b', 2), map('indent', ''));
-- <ROW><a>1</a><b>2</b></ROW>
SELECT to_xml(named_struct('time', to_timestamp('2015-08-26', 'yyyy-MM-dd')), map('timestampFormat', 'dd/MM/yyyy', 'indent', ''));
-- <ROW><time>26/08/2015</time></ROW>
SELECT to_xml(named_struct('time', TIME'14:30:45.123456'), map('rowTag', 'record', 'indent', ''));
-- <record><time>14:30:45.123456</time></record>
SELECT to_xml(array(named_struct('a', 1, 'b', 2)));
-- error: DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE
SELECT to_xml(map('a', 1));
-- error: DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPEThese come from the ExpressionDescription and xml-functions.sql.out (4.2). XmlFunctionsSuite also has
these cases:
- with session time zone
America/Los_Angeles, the timestamp1800-01-01 00:00:00is written as
1800-01-01T00:00:00.000-07:52:58; - with
timestampFormatyyyy-MM-dd HH:mm:ss.SSSSSS, it writes2019-11-18 11:56:00.123456.
Edge cases to test
- Value formatting.
- Numbers use Java
toString, soDOUBLEandFLOATprint as1.0E10,NaNandInfinity, and
DECIMALusesDecimal.toString. Booleans print astrueorfalse. DATEusesdateFormat(defaultyyyy-MM-dd).TIMESTAMPusestimestampFormat. The default isyyyy-MM-dd'T'HH:mm:ss[.SSS][XXX];
spark.sql.legacy.timeParserPolicy=LEGACYchanges it to...ss.SSSXXX, and the internal
supportSecondOffsetFormatsetting changes the offset to[XXXXX]. The value is rendered in the session
time zone or thetimeZoneoption. Test DST and historical (LMT) offsets, as in the 1800 case above.TIMESTAMP_NTZusestimestampNTZFormat(defaultyyyy-MM-dd'T'HH:mm:ss[.SSS]), andTIMEuses
timeFormat(4.2).BINARYfollowsspark.sql.binaryOutputStyle.
- Numbers use Java
- Escaping and names.
<,&and>in text, and quotes in attributes, are escaped by the writer.- Field names that aren't valid XML names (
'1a', a name with a space) fail whenvalidateName=true
(default). Check the exact error against Spark.
- Empty struct values. Nested NULL structs are omitted. A struct whose fields are all NULL writes an empty
element. Compare the exact output (<ROW></ROW>or<ROW/>) against Spark. - Attributes and
valueTag. Fornamed_struct('_id', 1, '_VALUE', 'x'), attribute fields are written
first, whatever the field order. - Arrays. Arrays of primitives, arrays of structs, and NULL array elements (omitted unless
nullValueis
set). Nested arrays usearrayElementName. - Option validation.
attributePrefixmust be non-empty (requirefails otherwise), androwTagmust
not contain angle brackets. - Round-trips.
to_xmlfollowed byfrom_xmlwith the same schema should round-trip. - NULL input gives NULL.
Differences across Spark versions
- Not available in 3.4 or 3.5.
- 4.1: accepts
VARIANTinput, and adds thesingleVariantColumnhandling inStaxXmlGenerator.write. - 4.2: adds
TIMEand thetimeFormatoption.
Implementation notes
- Spark:
StructsToXmlinsql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/xmlExpressions.scala,
StructsToXmlEvaluatorin.../expressions/xml/XmlExpressionEvalUtils.scala, and the writer in
sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/xml/StaxXmlGenerator.scalawith
IndentingXMLStreamWriter.scala. Options are inXmlOptions.scala. - DataFusion core has no XML functions.
- A writer can be hand-rolled, or built on
quick-xml'sWriter. The crate has no XML dependency today.
Match the indentation rules ofIndentingXMLStreamWriterexactly. Reuse the datetime formatting helpers
thatto_jsonanddate_formatuse, if they exist by then. - Tests: add
crates/sqllogictest/test_files/xml/to_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.
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity