Skip to main content
Date and time functions provide tools for parsing, formatting, and manipulating temporal data. All functions are available via fc.dt.*.

​
Extraction Functions

​
year

Extract the year from a date column. 
fc.dt.year(column: ColumnOrName) -> Column
​
column
ColumnOrName
required
The column to extract the year from.
​
return
Column
A Column object with the year extracted.

​
Example

df.select(fc.dt.year(fc.col("date")))
# dates: "2025-01-01", "2025-01-02", "2025-01-03"
# Output: [2025, 2025, 2025]

​
month

Extract the month from a date column. 
fc.dt.month(column: ColumnOrName) -> Column

​
day

Extract the day from a date column. 
fc.dt.day(column: ColumnOrName) -> Column

​
hour

Extract the hour from a timestamp column. 
fc.dt.hour(column: ColumnOrName) -> Column
This will return 0 for DateType columns.

​
minute

Extract the minute from a timestamp column. 
fc.dt.minute(column: ColumnOrName) -> Column

​
second

Extract the second from a timestamp column. 
fc.dt.second(column: ColumnOrName) -> Column

​
millisecond

Extract the millisecond from a timestamp column. 
fc.dt.millisecond(column: ColumnOrName) -> Column

​
Conversion Functions

​
to_date

Transform a string into a DateType. 
fc.dt.to_date(
    column: ColumnOrName,
    format: Optional[str] = None
) -> Column
​
column
ColumnOrName
required
The column to transform into a DateType.
​
format
Optional[str]
The format of the date string. If not provided, the default format is “YYYY-MM-DD”. The accepted formats should follow the Spark datetime pattern.
​
return
Column
A Column object with the DateType transformed.

​
Example

df.select(fc.dt.to_date(fc.col("date_str"), format="MM-dd-yyyy").alias("date"))

​
to_timestamp

Transform a string into a TimestampType. 
fc.dt.to_timestamp(
    column: ColumnOrName,
    format: Optional[str] = None
) -> Column
​
column
ColumnOrName
required
The column to transform into a TimestampType.
​
format
Optional[str]
The format of the timestamp string. If not provided, the default format is ISO 8601 with milliseconds. The accepted formats should follow the Spark datetime pattern.
​
return
Column
A Column object with the TimestampType type, with a UTC timezone. If the provided format contains a timezone specifier, the result timestamp value will be converted from the format timezone to UTC.

​
Example

df.select(fc.dt.to_timestamp(fc.col("date_str"), format="MM-dd-yyyy HH:mm:ss"))

​
date_format

Formats a date/timestamp column to a given format. 
fc.dt.date_format(column: ColumnOrName, format: str) -> Column
​
column
ColumnOrName
required
The column to format.
​
format
str
required
The format to format the column to. The accepted formats should follow the Spark datetime pattern.
​
return
Column
A Column object with the date/timestamp column formatted into a string.

​
Example

df.select(fc.dt.date_format(fc.col("date"), "MM-dd-yyyy hh:mm:ss a"))
# Output: ['01-01-2025 10:00:00 AM', '02-01-2025 11:00:00 AM', ...]

​
Current Time Functions

​
now

Get the current date and time. 
fc.dt.now() -> Column
​
return
Column
A Column object with the current date and time. The type of the column is TimestampType.

​
current_timestamp

Get the current date and time. 
fc.dt.current_timestamp() -> Column
​
return
Column
A Column object with the current date and time. The type of the column is TimestampType in UTC timezone.

​
current_date

Get the current date. 
fc.dt.current_date() -> Column
​
return
Column
A Column object with the current date. The type of the column is DateType.

​
Arithmetic Functions

​
date_add

Adds the number of days to the date/timestamp column. 
fc.dt.date_add(
    column: ColumnOrName,
    days: Union[int, ColumnOrName]
) -> Column
​
column
ColumnOrName
required
The column to add the days to.
​
days
Union[int, ColumnOrName]
required
The number of days to add to the date/timestamp column. If the days is negative, the days will be subtracted.
​
return
Column
A Column object with the date/timestamp column with the days added.

​
Example

df.select(fc.dt.date_add(fc.col("date"), 1).alias("date_add"))
# dates: "2025-01-01", "2025-02-01", "2025-03-01"
# Output: ['2025-01-02', '2025-02-02', '2025-03-02']

​
date_sub

Subtracts the number of days from the date/timestamp column. 
fc.dt.date_sub(
    column: ColumnOrName,
    days: Union[int, ColumnOrName]
) -> Column
​
column
ColumnOrName
required
The column to subtract the days from.
​
days
Union[int, ColumnOrName]
required
The amount of days to subtract. If the days is negative, the days will be added.
​
return
Column
A Column object with the date/timestamp column with the days subtracted.

​
timestamp_add

Adds the quantity of the given unit to the timestamp column. 
fc.dt.timestamp_add(
    column: ColumnOrName,
    quantity: Union[int, ColumnOrName],
    unit: DateTimeUnit
) -> Column
​
column
ColumnOrName
required
The column to add the quantity to.
​
quantity
Union[int, ColumnOrName]
required
The quantity to add. If the quantity is negative, the quantity will be subtracted.
​
unit
DateTimeUnit
required
The unit of the quantity. Supported units: "year", "month", "day", "hour", "minute", "second", "millisecond".
​
return
Column
A Column object with the timestamp column with the quantity added.

​
Example

df.select(fc.dt.timestamp_add(fc.col("ts"), 1, "day"))

​
datediff

Calculates the number of days between two date/timestamp columns. 
fc.dt.datediff(end: ColumnOrName, start: ColumnOrName) -> Column
​
end
ColumnOrName
required
To date column to work on.
​
start
ColumnOrName
required
From date column to work on.
​
return
Column
A Column object with the difference in days between the two date/timestamp columns.

​
Example

df.select(fc.dt.datediff(fc.col("end"), fc.col("start")))
# end: "2025-01-01", "2025-02-02", "2025-03-06"
# start: "2025-01-02", "2025-02-01", "2025-03-02"
# Output: [-1, 1, 4]

​
timestamp_diff

Calculates the difference between two timestamp columns. 
fc.dt.timestamp_diff(
    start: ColumnOrName,
    end: ColumnOrName,
    unit: DateTimeUnit
) -> Column
​
start
ColumnOrName
required
The first column to calculate the difference from.
​
end
ColumnOrName
required
The second column to calculate the difference from.
​
unit
DateTimeUnit
required
The unit of the difference. Supported units: "year", "month", "day", "hour", "minute", "second", "millisecond".
​
return
Column
A Column object with the difference in the given unit between the two timestamp columns.

​
Truncation Functions

​
date_trunc

Truncate a date to a given unit. 
fc.dt.date_trunc(column: ColumnOrName, unit: DateTimeUnit) -> Column
​
column
ColumnOrName
required
The column to truncate.
​
unit
DateTimeUnit
required
The unit to truncate to. Supported units: "year", "month", "day", "hour", "minute", "second", "millisecond".
​
return
Column
A Column object with the date truncated.

​
Example

df.select(fc.dt.date_trunc(fc.col("date"), "year"))
# dates: "2025-01-01", "2025-02-01", "2025-03-01"
# Output: ['2025-01-01', '2025-01-01', '2025-01-01']

​
Timezone Functions

​
to_utc_timestamp

Accepts a Column with TimestampType (UTC), interprets each value as wall-clock time in the specified timezone, and converts it to a timestamp in UTC. 
fc.dt.to_utc_timestamp(column: ColumnOrName, tz: str) -> Column
​
column
ColumnOrName
required
The column containing the timestamp. Will be treated as timezone-agnostic.
​
tz
str
required
A timezone that the input should be converted to.
​
return
Column
A Column object with timestamp expressed in UTC.
In fenic, the TimestampType data type is always in UTC. This function treats the input timestamp as timezone-agnostic, sets it to the requested timezone (without changing the timestamp), then converts the timestamp to UTC.See Spark documentation for more details.

​
from_utc_timestamp

Accepts a Column with TimestampType (UTC). For each row, converts the timestamp value to the provided timezone, then renders that timestamp as UTC without changing the timestamp value. 
fc.dt.from_utc_timestamp(column: ColumnOrName, tz: str) -> Column
​
column
ColumnOrName
required
The column containing the timestamp.
​
tz
str
required
A timezone that the input will be converted from.
​
return
Column
A Column object with timestamp expressed in UTC.
See Spark documentation for more details.

Build docs developers (and LLMs) love

Get started for freeTalk to us