diff --git a/crates/spark/src/function/datetime/mod.rs b/crates/spark/src/function/datetime/mod.rs index 32560d89..1107c816 100644 --- a/crates/spark/src/function/datetime/mod.rs +++ b/crates/spark/src/function/datetime/mod.rs @@ -26,6 +26,7 @@ pub mod monthname; pub mod next_day; pub mod time_trunc; pub mod timestamp_micros; +pub mod timestamp_millis; pub(crate) mod timezone; pub mod to_utc_timestamp; pub mod trunc; @@ -64,6 +65,7 @@ make_udf_function!(monthname::SparkMonthName, monthname); make_udf_function!(next_day::SparkNextDay, next_day); make_udf_function!(time_trunc::SparkTimeTrunc, time_trunc); make_udf_function!(timestamp_micros::SparkTimestampMicros, timestamp_micros); +make_udf_function!(timestamp_millis::SparkTimestampMillis, timestamp_millis); make_udf_function!(to_utc_timestamp::SparkToUtcTimestamp, to_utc_timestamp); make_udf_function!(trunc::SparkTrunc, trunc); make_udf_function!(unix::SparkUnixDate, unix_date); @@ -200,6 +202,11 @@ pub mod expr_fn { "Creates a timestamp from microseconds since the UTC epoch.", microseconds )); + export_functions!(( + timestamp_millis, + "Creates a timestamp from milliseconds since the UTC epoch, with overflow checking.", + milliseconds + )); export_functions!(( to_utc_timestamp, "Interpret a given timestamp `ts` in timezone `tz` and then convert it to UTC timezone.", @@ -256,6 +263,7 @@ pub fn functions() -> Vec> { second(), time_trunc(), timestamp_micros(), + timestamp_millis(), to_utc_timestamp(), trunc(), unix_date(), diff --git a/crates/spark/src/function/datetime/timestamp_millis.rs b/crates/spark/src/function/datetime/timestamp_millis.rs new file mode 100644 index 00000000..f0eed583 --- /dev/null +++ b/crates/spark/src/function/datetime/timestamp_millis.rs @@ -0,0 +1,220 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership +// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements + +use std::sync::Arc; + +use arrow::array::TimestampMicrosecondArray; +use arrow::datatypes::{DataType, Field, FieldRef, TimeUnit}; +use datafusion_common::cast::as_int64_array; +use datafusion_common::config::ConfigOptions; +use datafusion_common::utils::take_function_args; +use datafusion_common::{ + Result, ScalarValue, exec_datafusion_err, internal_err, plan_err, +}; +use datafusion_expr::{ + ColumnarValue, Documentation, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDF, + ScalarUDFImpl, Signature, Volatility, +}; +use datafusion_macros::user_doc; + +use crate::function::implicit_cast::{SparkInputType, SparkInputTypes}; + +/// Spark-compatible `timestamp_millis` expression. +/// +/// +#[user_doc( + doc_section(label = "Time and Date Functions"), + description = "Returns the timestamp that is `milliseconds` milliseconds after \ + 1970-01-01 00:00:00 UTC. Negative values precede the epoch. Unlike DataFusion's \ + `to_timestamp_millis`, the result has microsecond precision, non-integer inputs \ + are rejected, and scaling to microseconds raises `long overflow` on overflow \ + in both ANSI and non-ANSI modes. Valid millisecond counts range from \ + -9223372036854775 through 9223372036854775, inclusive. The result uses the \ + session time zone (`datafusion.execution.time_zone`, default UTC), which \ + affects display but not the stored count. Returns NULL for NULL input.", + syntax_example = "timestamp_millis(milliseconds)", + sql_example = r#"```sql +> SELECT timestamp_millis(0::BIGINT); +1970-01-01T00:00:00Z +> SELECT timestamp_millis(-1::BIGINT); +1969-12-31T23:59:59.999Z +> SELECT timestamp_millis(NULL); +NULL +```"#, + argument( + name = "milliseconds", + description = "TINYINT, SMALLINT, INT or BIGINT count of milliseconds since the UTC epoch. Arrow UInt8, UInt16 and UInt32 inputs are also accepted. UInt64 is rejected because its full range cannot fit in BIGINT. NULL returns NULL." + ) +)] +#[derive(Debug, PartialEq, Eq, Hash)] +pub struct SparkTimestampMillis { + input_types: SparkInputTypes, + timezone: Arc, +} + +impl Default for SparkTimestampMillis { + fn default() -> Self { + Self::new() + } +} + +impl SparkTimestampMillis { + pub fn new() -> Self { + Self::new_with_config(&ConfigOptions::default()) + } + + pub fn new_with_config(config: &ConfigOptions) -> Self { + Self { + input_types: SparkInputTypes::check_only( + vec![SparkInputType::Integral], + Volatility::Stable, + ), + timezone: config + .execution + .time_zone + .as_ref() + .map_or("UTC", |tz| tz.as_str()) + .into(), + } + } +} + +impl ScalarUDFImpl for SparkTimestampMillis { + fn name(&self) -> &str { + "timestamp_millis" + } + + fn signature(&self) -> &Signature { + self.input_types.signature() + } + + fn coerce_types(&self, arg_types: &[DataType]) -> Result> { + let types = self.input_types.coerce(self.name(), arg_types)?; + if types[0] == DataType::UInt64 { + return plan_err!( + "[DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE] The first parameter of \ + `timestamp_millis` requires an integer type whose full range fits in \ + BIGINT, however it has the type \"UInt64\". SQLSTATE: 42K09" + ); + } + Ok(vec![DataType::Int64]) + } + + fn return_type(&self, _arg_types: &[DataType]) -> Result { + internal_err!("return_field_from_args should be used instead") + } + + fn return_field_from_args(&self, args: ReturnFieldArgs) -> Result { + let [input] = take_function_args(self.name(), args.arg_fields)?; + Ok(Arc::new(Field::new( + self.name(), + DataType::Timestamp(TimeUnit::Microsecond, Some(Arc::clone(&self.timezone))), + input.is_nullable(), + ))) + } + + fn with_updated_config(&self, config: &ConfigOptions) -> Option { + Some(ScalarUDF::from(Self::new_with_config(config))) + } + + fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result { + let [milliseconds] = take_function_args(self.name(), args.args)?; + match milliseconds { + ColumnarValue::Scalar(ScalarValue::Int64(value)) => { + Ok(ColumnarValue::Scalar(ScalarValue::TimestampMicrosecond( + value.map(millis_to_micros).transpose()?, + Some(Arc::clone(&self.timezone)), + ))) + } + ColumnarValue::Array(array) => { + let result: TimestampMicrosecondArray = + as_int64_array(array.as_ref())?.try_unary(millis_to_micros)?; + Ok(ColumnarValue::Array(Arc::new( + result.with_timezone(Arc::clone(&self.timezone)), + ))) + } + other => { + internal_err!( + "Unsupported arg {other:?} for Spark function `timestamp_millis`" + ) + } + } + } + + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } +} + +fn millis_to_micros(milliseconds: i64) -> Result { + milliseconds + .checked_mul(1_000) + .ok_or_else(|| exec_datafusion_err!("long overflow")) +} + +#[cfg(test)] +mod tests { + use arrow::array::{AsArray, Int64Array}; + use arrow::datatypes::TimestampMicrosecondType; + + use super::*; + + #[test] + fn return_field_tracks_session_timezone_and_input_nullability() -> Result<()> { + for timezone in [None, Some("America/Los_Angeles")] { + let mut config = ConfigOptions::default(); + config.execution.time_zone = timezone.map(str::parse).transpose()?; + let function = SparkTimestampMillis::new() + .with_updated_config(&config) + .unwrap(); + for nullable in [false, true] { + let input = Arc::new(Field::new("millis", DataType::Int64, nullable)); + let field = function.inner().return_field_from_args(ReturnFieldArgs { + arg_fields: &[input], + scalar_arguments: &[None], + })?; + assert_eq!(field.is_nullable(), nullable); + assert_eq!( + field.data_type(), + &DataType::Timestamp( + TimeUnit::Microsecond, + Some(timezone.unwrap_or("UTC").into()), + ), + ); + } + } + Ok(()) + } + + #[test] + fn null_slots_do_not_overflow() -> Result<()> { + // SQL cannot construct a null with an overflowing value in its storage. + let input = Int64Array::new( + vec![i64::MAX, 1, i64::MIN].into(), + Some(vec![false, true, false].into()), + ); + let input_field = Arc::new(Field::new("millis", DataType::Int64, true)); + let function = SparkTimestampMillis::new(); + let return_field = function.return_field_from_args(ReturnFieldArgs { + arg_fields: &[Arc::clone(&input_field)], + scalar_arguments: &[None], + })?; + let result = function.invoke_with_args(ScalarFunctionArgs { + args: vec![ColumnarValue::Array(Arc::new(input))], + arg_fields: vec![input_field], + number_rows: 3, + return_field, + config_options: Arc::new(ConfigOptions::default()), + })?; + let ColumnarValue::Array(result) = result else { + panic!("expected array output"); + }; + assert_eq!( + result.as_primitive::(), + &TimestampMicrosecondArray::from(vec![None, Some(1_000), None]) + .with_timezone("UTC"), + ); + Ok(()) + } +} diff --git a/crates/sqllogictest/test_files/datetime/timestamp_millis.slt b/crates/sqllogictest/test_files/datetime/timestamp_millis.slt index 77cdc2f8..2d56c446 100644 --- a/crates/sqllogictest/test_files/datetime/timestamp_millis.slt +++ b/crates/sqllogictest/test_files/datetime/timestamp_millis.slt @@ -8,7 +8,194 @@ # For more information, please see: # https://github.com/apache/datafusion/issues/15914 -## Original Query: SELECT timestamp_millis(1230219000123); -## PySpark 3.5.5 Result: {'timestamp_millis(1230219000123)': datetime.datetime(2008, 12, 25, 7, 30, 0, 123000), 'typeof(timestamp_millis(1230219000123))': 'timestamp', 'typeof(1230219000123)': 'bigint'} -#query -#SELECT timestamp_millis(1230219000123::bigint); +# Audited against Spark 4.2.0 on 2026-11-20. +# Expected values verified with pyspark==4.2.0. + +# Milliseconds are measured from the UTC epoch, including negative values. +query PPPP +SELECT timestamp_millis(0::BIGINT), timestamp_millis(-1::BIGINT), + timestamp_millis(1230219000123::BIGINT), timestamp_millis(-1230219000123::BIGINT); +---- +1970-01-01T00:00:00Z 1969-12-31T23:59:59.999Z 2008-12-25T15:30:00.123Z 1931-01-07T08:29:59.877Z + +query PPPP +SELECT timestamp_millis(1::TINYINT) AS tiny, timestamp_millis(1::SMALLINT) AS small, + timestamp_millis(1::INT) AS integer_value, timestamp_millis(1::BIGINT) AS big; +---- +1970-01-01T00:00:00.001Z 1970-01-01T00:00:00.001Z 1970-01-01T00:00:00.001Z 1970-01-01T00:00:00.001Z + +query PP +SELECT timestamp_millis(NULL) AS untyped_null, timestamp_millis(NULL::BIGINT) AS typed_null; +---- +NULL NULL + +# Column input exercises the physical kernel in both SLT modes. +query PII +SELECT timestamp_millis(x), unix_micros(timestamp_millis(x)), unix_millis(timestamp_millis(x)) +FROM (VALUES (-1::BIGINT), (0::BIGINT), (1::BIGINT), (NULL::BIGINT)) AS t(x); +---- +1969-12-31T23:59:59.999Z -1000 -1 +1970-01-01T00:00:00Z 0 0 +1970-01-01T00:00:00.001Z 1000 1 +NULL NULL NULL + +query PPP +SELECT timestamp_millis(a), timestamp_millis(b), timestamp_millis(c) +FROM (VALUES ((-128)::TINYINT, (-32768)::SMALLINT, (-2147483648)::INT)) AS t(a, b, c); +---- +1969-12-31T23:59:59.872Z 1969-12-31T23:59:27.232Z 1969-12-07T03:28:36.352Z + +# Both inclusive millisecond limits are valid, even though their years cannot +# be rendered by the calendar formatter. Verify the stored count and round trip. +query II +SELECT unix_micros(timestamp_millis(x)), unix_millis(timestamp_millis(x)) +FROM (VALUES ((-9223372036854775)::BIGINT), (9223372036854775::BIGINT)) AS t(x); +---- +-9223372036854775000 -9223372036854775 +9223372036854775000 9223372036854775 + +query I +SELECT unix_micros(timestamp_millis(arrow_cast(x, 'Dictionary(Int32, Int64)'))) +FROM (VALUES (-1::BIGINT), (1::BIGINT), (NULL::BIGINT)) AS t(x); +---- +-1000 +1000 +NULL + +query P +SELECT timestamp_millis(x) FROM (VALUES (NULL::BIGINT), (NULL::BIGINT)) AS t(x); +---- +NULL +NULL + +# ExpectsInputTypes rejects these types rather than implicitly casting them. +query error The first parameter of `timestamp_millis` requires the "INTEGRAL" type, however it has the type "DOUBLE". +SELECT timestamp_millis(1.0::DOUBLE); + +query error DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE +SELECT timestamp_millis(1.0::FLOAT); + +query error DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE +SELECT timestamp_millis(1.0::DECIMAL(10, 1)); + +query error DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE +SELECT timestamp_millis('1'); + +query error DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE +SELECT timestamp_millis(true); + +# Multiplication overflows on either side of the valid range, even without ANSI. +query error long overflow +SELECT timestamp_millis(9223372036854776::BIGINT); + +query error long overflow +SELECT timestamp_millis((-9223372036854776)::BIGINT); + +query error long overflow +SELECT timestamp_millis(9223372036854775807::BIGINT); + +query error long overflow +SELECT timestamp_millis((-9223372036854775808)::BIGINT); + +query error long overflow +SELECT unix_micros(timestamp_millis(x)) +FROM (VALUES (1::BIGINT), (9223372036854776::BIGINT), (NULL::BIGINT)) AS t(x); + +query error long overflow +SELECT unix_micros(timestamp_millis(x)) +FROM (VALUES ((-9223372036854776)::BIGINT), (1::BIGINT)) AS t(x); + +statement ok +SET datafusion.execution.enable_ansi_mode = true; + +query II +SELECT unix_micros(timestamp_millis((-9223372036854775)::BIGINT)), + unix_micros(timestamp_millis(9223372036854775::BIGINT)); +---- +-9223372036854775000 9223372036854775000 + +query P +SELECT timestamp_millis(-1::BIGINT); +---- +1969-12-31T23:59:59.999Z + +query error long overflow +SELECT timestamp_millis(9223372036854776::BIGINT); + +query error long overflow +SELECT timestamp_millis((-9223372036854776)::BIGINT); + +query error long overflow +SELECT timestamp_millis(9223372036854775807::BIGINT); + +query error long overflow +SELECT timestamp_millis((-9223372036854775808)::BIGINT); + +query error long overflow +SELECT unix_micros(timestamp_millis(x)) +FROM (VALUES (1::BIGINT), (9223372036854776::BIGINT), (NULL::BIGINT)) AS t(x); + +query error long overflow +SELECT unix_micros(timestamp_millis(x)) +FROM (VALUES ((-9223372036854776)::BIGINT), (1::BIGINT)) AS t(x); + +query error DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE +SELECT timestamp_millis(1.0::DOUBLE); + +query error DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE +SELECT timestamp_millis(1.0::FLOAT); + +query error DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE +SELECT timestamp_millis(1.0::DECIMAL(10, 1)); + +query error DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE +SELECT timestamp_millis('1'); + +query error DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE +SELECT timestamp_millis(true); + +statement ok +SET datafusion.execution.enable_ansi_mode = false; + +# The session zone affects display, but never the stored microsecond count. +statement ok +SET datafusion.execution.time_zone = 'America/Los_Angeles'; + +query PP +SELECT timestamp_millis(1230219000123::BIGINT), timestamp_millis(-1230219000123::BIGINT); +---- +2008-12-25T07:30:00.123-08:00 1931-01-07T00:29:59.877-08:00 + +query PII +SELECT timestamp_millis(x), unix_micros(timestamp_millis(x)), unix_millis(timestamp_millis(x)) +FROM (VALUES (1710064799999::BIGINT), (1710064800000::BIGINT)) AS t(x); +---- +2024-03-10T01:59:59.999-08:00 1710064799999000 1710064799999 +2024-03-10T03:00:00-07:00 1710064800000000 1710064800000 + +statement ok +SET datafusion.execution.time_zone = 'UTC'; + +# Arrow-specific assertions supplement the Spark comparisons. +query T +SELECT arrow_typeof(timestamp_millis(0::BIGINT)); +---- +Timestamp(µs, "UTC") + +query III +SELECT unix_micros(timestamp_millis(arrow_cast(255, 'UInt8'))), + unix_micros(timestamp_millis(arrow_cast(65535, 'UInt16'))), + unix_micros(timestamp_millis(arrow_cast(4294967295, 'UInt32'))); +---- +255000 65535000 4294967295000 + +query I +SELECT unix_micros(timestamp_millis(arrow_cast(x, 'Dictionary(Int32, UInt32)'))) +FROM (VALUES (0::BIGINT), (4294967295::BIGINT), (NULL::BIGINT)) AS t(x); +---- +0 +4294967295000 +NULL + +query error DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE +SELECT timestamp_millis(arrow_cast(1, 'UInt64')); diff --git a/docs/functions/README.md b/docs/functions/README.md index e8e68a9b..af89d164 100644 --- a/docs/functions/README.md +++ b/docs/functions/README.md @@ -21,7 +21,7 @@ function differs from the DataFusion built-in of the same name, if there is one. - [Conditional Functions](scalar/conditional.md) (2) - [String Functions](scalar/string.md) (17) - [Binary String Functions](scalar/binary_string.md) (5) -- [Time and Date Functions](scalar/time_and_date.md) (28) +- [Time and Date Functions](scalar/time_and_date.md) (30) - [Array Functions](scalar/array.md) (10) - [Hashing Functions](scalar/hashing.md) (4) - [Other Functions](scalar/other.md) (6) @@ -77,6 +77,7 @@ function differs from the DataFusion built-in of the same name, if there is one. - [datediff](scalar/time_and_date.md#datediff) - [datepart](scalar/time_and_date.md#datepart) - [dayname](scalar/time_and_date.md#dayname) +- [dayofweek](scalar/time_and_date.md#dayofweek) - [elt](scalar/string.md#elt) - [encode](scalar/binary_string.md#encode) - [equal_null](scalar/other.md#equal_null) @@ -138,6 +139,7 @@ function differs from the DataFusion built-in of the same name, if there is one. - [substring](scalar/string.md#substring) - [time_trunc](scalar/time_and_date.md#time_trunc) - [timestamp_micros](scalar/time_and_date.md#timestamp_micros) +- [timestamp_millis](scalar/time_and_date.md#timestamp_millis) - [to_binary](scalar/binary_string.md#to_binary) - [to_json](scalar/json.md#to_json) - [to_utc_timestamp](scalar/time_and_date.md#to_utc_timestamp) diff --git a/docs/functions/scalar/time_and_date.md b/docs/functions/scalar/time_and_date.md index 82ccde3c..1c5492fc 100644 --- a/docs/functions/scalar/time_and_date.md +++ b/docs/functions/scalar/time_and_date.md @@ -25,6 +25,7 @@ Part of the [datafusion-spark function reference](../README.md). - [datediff](#datediff) - [datepart](#datepart) - [dayname](#dayname) +- [dayofweek](#dayofweek) - [from_utc_timestamp](#from_utc_timestamp) - [hour](#hour) - [last_day](#last_day) @@ -38,6 +39,7 @@ Part of the [datafusion-spark function reference](../README.md). - [second](#second) - [time_trunc](#time_trunc) - [timestamp_micros](#timestamp_micros) +- [timestamp_millis](#timestamp_millis) - [to_utc_timestamp](#to_utc_timestamp) - [trunc](#trunc) - [unix_date](#unix_date) @@ -284,6 +286,31 @@ Mon NULL ``` +## `dayofweek` + +Returns the day of the week as an INT from 1 (Sunday) to 7 (Saturday). This differs from `weekday`, which counts from 0 (Monday) to 6 (Sunday), and from DataFusion's `date_part('dow', ...)`, which counts from 0 (Sunday) to 6 (Saturday). DataFusion has no built-in `dayofweek`. Strings are implicitly cast to DATE. A malformed string is an error, even with ANSI mode off where Spark returns NULL. A string that Spark reads as a partial date, such as '2009' or '2009-07', is also an error, where Spark uses the first day of that year or month. Timestamps are cast to DATE first, so the time of day is ignored. A timestamp with a time zone is converted in its own time zone, not the session time zone that Spark uses. Returns NULL if the input is NULL. + +```sql +dayofweek(date) +``` + +### Arguments + +- **date**: DATE, TIMESTAMP or string expression. NULL returns NULL. + +### Example + +```sql +> SELECT dayofweek('2009-07-30'::DATE); +5 +> SELECT dayofweek('2009-07-30'); +5 +> SELECT dayofweek(arrow_cast('2024-01-07 23:59:59', 'Timestamp(Microsecond, None)')); +1 +> SELECT dayofweek(NULL::DATE); +NULL +``` + ## `from_utc_timestamp` Treats `ts` as a UTC wall-clock time and returns the wall-clock time in time zone `tz`. DataFusion has no built-in equivalent. A string `ts` is cast to a timestamp, so a string with an offset is first converted to UTC. The result has the same type as `ts`, including any time zone it carries. Returns NULL if either argument is NULL. `tz` accepts Spark's spellings: region IDs, offsets such as `+01:00`, `GMT+1`, `UTC+1:2` and `UT-010203`, Java short IDs such as `PST`, and legacy `SystemV/` IDs. An offset beyond 18 hours or an unknown zone is an error. Differences from Spark: `tz` is only parsed for rows where both arguments are non-NULL, so an invalid constant `tz` can return NULL where Spark raises an error; conversion is limited to Chrono's calendar range, which is narrower than the range Spark implements but covers Spark's documented range; and region rules from `chrono-tz` may differ after 2099, because it does not extrapolate later daylight saving time transitions. @@ -599,6 +626,29 @@ timestamp_micros(microseconds) NULL ``` +## `timestamp_millis` + +Returns the timestamp that is `milliseconds` milliseconds after 1970-01-01 00:00:00 UTC. Negative values precede the epoch. Unlike DataFusion's `to_timestamp_millis`, the result has microsecond precision, non-integer inputs are rejected, and scaling to microseconds raises `long overflow` on overflow in both ANSI and non-ANSI modes. Valid millisecond counts range from -9223372036854775 through 9223372036854775, inclusive. The result uses the session time zone (`datafusion.execution.time_zone`, default UTC), which affects display but not the stored count. Returns NULL for NULL input. + +```sql +timestamp_millis(milliseconds) +``` + +### Arguments + +- **milliseconds**: TINYINT, SMALLINT, INT or BIGINT count of milliseconds since the UTC epoch. Arrow UInt8, UInt16 and UInt32 inputs are also accepted. UInt64 is rejected because its full range cannot fit in BIGINT. NULL returns NULL. + +### Example + +```sql +> SELECT timestamp_millis(0::BIGINT); +1970-01-01T00:00:00Z +> SELECT timestamp_millis(-1::BIGINT); +1969-12-31T23:59:59.999Z +> SELECT timestamp_millis(NULL); +NULL +``` + ## `to_utc_timestamp` Treats `ts` as a wall-clock time in time zone `tz` and returns the UTC wall-clock time. This is the inverse of `from_utc_timestamp`. DataFusion has no built-in equivalent. A string `ts` is cast to a timestamp, so a string with an offset is first converted to UTC. The result has the same type as `ts`, including any time zone it carries. Returns NULL if either argument is NULL. Unlike `from_utc_timestamp`, `tz` is parsed by Arrow, so it accepts region IDs and `+HH:MM` offsets but not all of Spark's spellings (such as `GMT+1` or `PST`). An unknown zone is an error. Within a few hours of a daylight saving time change, the offset can be taken from the wrong side of the change, so the result can differ from Spark by the size of the change ([#110](https://github.com/apache/datafusion-spark/issues/110)).