TryMakeTimestamp¶

Overview¶

The TryMakeTimestamp expression creates a timestamp from individual date and time components (year, month, day, hour, minute, second) with optional timezone specification. Unlike the standard make_timestamp function, this variant returns null instead of throwing an exception when provided with invalid date/time values.

Syntax¶

try_make_timestamp(year, month, day, hour, min, sec [, timezone])

Arguments¶

Argument	Type	Description
year	Expression	The year component (e.g., 2023)
month	Expression	The month component (1-12)
day	Expression	The day component (1-31)
hour	Expression	The hour component (0-23)
min	Expression	The minute component (0-59)
sec	Expression	The second component (0-59, can include fractional seconds)
timezone	Expression (Optional)	The timezone identifier (e.g., 'UTC', 'America/New_York')

Return Type¶

Returns TimestampType - a timestamp value representing the specified date and time, or null if the input values are invalid.

Supported Data Types¶

year, month, day, hour, min: Integer types or expressions that evaluate to integers
sec: Numeric types (integer or decimal) to support fractional seconds
timezone: String type containing a valid timezone identifier

Algorithm¶

Validates all input date and time components for logical consistency
Constructs a timestamp using the provided year, month, day, hour, minute, and second values
Applies timezone conversion if a timezone parameter is provided
Returns null instead of throwing exceptions for invalid date/time combinations (e.g., February 30th)
Leverages the underlying MakeTimestamp expression with failOnError = false

Partitioning Behavior¶

How this expression affects partitioning:

Preserves partitioning as it operates row-by-row without requiring data redistribution
Does not require shuffle operations
Can be safely used in partition pruning scenarios

Edge Cases¶

Null handling: Returns null if any required input parameter is null
Invalid dates: Returns null for impossible dates (e.g., February 30, April 31)
Invalid times: Returns null for invalid time values (e.g., hour = 25, minute = 70)
Timezone handling: Returns null if an invalid timezone identifier is provided
Leap year handling: Correctly handles February 29th validation based on leap year rules
Fractional seconds: Supports fractional seconds in the seconds parameter

Code Generation¶

This expression is implemented as a RuntimeReplaceable expression, which means it is rewritten to use the underlying MakeTimestamp expression during analysis phase. The actual code generation behavior depends on the MakeTimestamp implementation it delegates to.

Examples¶

-- Basic timestamp creation
SELECT try_make_timestamp(2023, 12, 25, 10, 30, 45.5);

-- With timezone
SELECT try_make_timestamp(2023, 6, 15, 14, 30, 0, 'America/New_York');

-- Invalid date returns null instead of error
SELECT try_make_timestamp(2023, 2, 30, 10, 0, 0); -- Returns null

// Example DataFrame API usage
import org.apache.spark.sql.functions._

// Basic usage
df.select(expr("try_make_timestamp(year_col, month_col, day_col, hour_col, min_col, sec_col)"))

// With timezone
df.select(expr("try_make_timestamp(2023, 6, 15, 14, 30, 0, 'UTC')"))