Day
Function to get the day component of a datetime object.
Parameters
Default: UTC
The timezone in which to interpret the datetime. If not specified, UTC is used.
Returns
Returns an expression object denoting the integer value of the day of the datetime object.
1from fennel.expr import col
2
3expr = col("x").dt.day
4
5# day works for any datetime type or optional datetime type
6assert expr.typeof(schema={"x": datetime}) == int
7assert expr.typeof(schema={"x": Optional[datetime]}) == Optional[int]
8
9# can be evaluated with a dataframe
10df = pd.DataFrame(
11 {
12 "x": [
13 pd.Timestamp("2024-01-01 00:00:00", tz="UTC"),
14 pd.Timestamp("2024-01-01 10:00:00", tz="UTC"),
15 pd.Timestamp("2024-01-01 20:20:00", tz="UTC"),
16 ]
17 }
18)
19schema = {"x": datetime}
20assert expr.eval(df, schema=schema).tolist() == [1, 1, 1]
21
22# also works with timezone aware datetimes
23expr = col("x").dt.with_tz(timezone="US/Eastern").day
24assert expr.eval(df, schema=schema).tolist() == [31, 1, 1]python
Errors
The dt namespace must be invoked on an expression that evaluates to datetime
or optional of datetime.
The timezone, if provided, must be a valid timezone string. Note that Fennel only supports area/location based timezones (e.g. "America/New_York"), not fixed offsets (e.g. "+05:30" or "UTC+05:30").
Hour
Function to get the hour component of a datetime object.
Parameters
Default: UTC
The timezone in which to interpret the datetime. If not specified, UTC is used.
Returns
Returns an expression object denoting the integer value of the hour of the datetime object.
1from fennel.expr import col
2
3expr = col("x").dt.hour
4
5# hour works for any datetime type or optional datetime type
6assert expr.typeof(schema={"x": datetime}) == int
7assert expr.typeof(schema={"x": Optional[datetime]}) == Optional[int]
8
9# can be evaluated with a dataframe
10df = pd.DataFrame(
11 {
12 "x": [
13 pd.Timestamp("2024-01-01 00:00:00", tz="UTC"),
14 pd.Timestamp("2024-01-01 10:00:00", tz="UTC"),
15 pd.Timestamp("2024-01-01 20:20:00", tz="UTC"),
16 ]
17 }
18)
19schema = {"x": datetime}
20assert expr.eval(df, schema=schema).tolist() == [0, 10, 20]
21
22# also works with timezone aware datetimes
23expr = col("x").dt.with_tz(timezone="US/Eastern").hour
24assert expr.eval(df, schema=schema).tolist() == [19, 5, 15]python
Errors
The dt namespace must be invoked on an expression that evaluates to datetime
or optional of datetime.
The timezone, if provided, must be a valid timezone string. Note that Fennel only supports area/location based timezones (e.g. "America/New_York"), not fixed offsets (e.g. "+05:30" or "UTC+05:30").
Minute
Function to get the minute component of a datetime object.
Parameters
Default: UTC
The timezone in which to interpret the datetime. If not specified, UTC is used.
Returns
Returns an expression object denoting the integer value of the minute of the datetime object.
1from fennel.expr import col
2
3expr = col("x").dt.minute
4
5# minute works for any datetime type or optional datetime type
6assert expr.typeof(schema={"x": datetime}) == int
7assert expr.typeof(schema={"x": Optional[datetime]}) == Optional[int]
8
9# can be evaluated with a dataframe
10df = pd.DataFrame(
11 {
12 "x": [
13 pd.Timestamp("2024-01-01 00:00:00", tz="UTC"),
14 pd.Timestamp("2024-01-01 10:00:00", tz="UTC"),
15 pd.Timestamp("2024-01-01 20:20:00", tz="UTC"),
16 ]
17 }
18)
19schema = {"x": datetime}
20assert expr.eval(df, schema=schema).tolist() == [0, 0, 20]
21
22# also works with timezone aware datetimes
23expr = col("x").dt.with_tz(timezone="US/Eastern").minute
24assert expr.eval(df, schema=schema).tolist() == [0, 0, 20]python
Errors
The dt namespace must be invoked on an expression that evaluates to datetime
or optional of datetime.
The timezone, if provided, must be a valid timezone string. Note that Fennel only supports area/location based timezones (e.g. "America/New_York"), not fixed offsets (e.g. "+05:30" or "UTC+05:30").
Month
Function to get the month component of a datetime object.
Parameters
Default: UTC
The timezone in which to interpret the datetime. If not specified, UTC is used.
Returns
Returns an expression object denoting the integer value of the month of the datetime object.
1from fennel.expr import col
2
3expr = col("x").dt.month
4
5# month works for any datetime type or optional datetime type
6assert expr.typeof(schema={"x": datetime}) == int
7assert expr.typeof(schema={"x": Optional[datetime]}) == Optional[int]
8
9# can be evaluated with a dataframe
10df = pd.DataFrame(
11 {
12 "x": [
13 pd.Timestamp("2024-01-01 00:00:00", tz="UTC"),
14 pd.Timestamp("2024-01-01 10:00:00", tz="UTC"),
15 pd.Timestamp("2024-01-01 20:20:00", tz="UTC"),
16 ]
17 }
18)
19schema = {"x": datetime}
20assert expr.eval(df, schema=schema).tolist() == [1, 1, 1]
21
22# also works with timezone aware datetimes
23expr = col("x").dt.with_tz(timezone="US/Eastern").month
24assert expr.eval(df, schema=schema).tolist() == [12, 1, 1]python
Errors
The dt namespace must be invoked on an expression that evaluates to datetime
or optional of datetime.
The timezone, if provided, must be a valid timezone string. Note that Fennel only supports area/location based timezones (e.g. "America/New_York"), not fixed offsets (e.g. "+05:30" or "UTC+05:30").
Second
Function to get the second component of a datetime object.
Parameters
Default: UTC
The timezone in which to interpret the datetime. If not specified, UTC is used.
Returns
Returns an expression object denoting the integer value of the second of the datetime object.
1from fennel.expr import col
2
3expr = col("x").dt.second
4
5# second works for any datetime type or optional datetime type
6assert expr.typeof(schema={"x": datetime}) == int
7assert expr.typeof(schema={"x": Optional[datetime]}) == Optional[int]
8
9# can be evaluated with a dataframe
10df = pd.DataFrame(
11 {
12 "x": [
13 pd.Timestamp("2024-01-01 00:00:01", tz="UTC"),
14 pd.Timestamp("2024-01-01 10:00:02", tz="UTC"),
15 pd.Timestamp("2024-01-01 20:20:03", tz="UTC"),
16 ]
17 }
18)
19schema = {"x": datetime}
20assert expr.eval(df, schema=schema).tolist() == [1, 2, 3]
21
22# also works with timezone aware datetimes
23expr = col("x").dt.with_tz(timezone="Asia/Kathmandu").second
24assert expr.eval(df, schema=schema).tolist() == [1, 2, 3]python
Errors
The dt namespace must be invoked on an expression that evaluates to datetime
or optional of datetime.
The timezone, if provided, must be a valid timezone string. Note that Fennel only supports area/location based timezones (e.g. "America/New_York"), not fixed offsets (e.g. "+05:30" or "UTC+05:30").
Since
Function to get the time elapsed between two datetime objects.
Parameters
The datetime object to calculate the elapsed time since.
Default: second
The unit of time to return the elapsed time in. Defaults to seconds. Valid units
are: week, day,hour, minute, second, millisecond, and microsecond.
Returns
Returns an expression object denoting the integer value of the elapsed time since the specified datetime object in the specified unit.
1from fennel.expr import col
2
3expr = col("x").dt.since(col("y"))
4
5# since works for any datetime type or optional datetime type
6assert expr.typeof(schema={"x": datetime, "y": datetime}) == int
7assert (
8 expr.typeof(schema={"x": Optional[datetime], "y": datetime})
9 == Optional[int]
10)
11
12# can be evaluated with a dataframe
13df = pd.DataFrame(
14 {
15 "x": [
16 pd.Timestamp("2024-01-01 00:00:00", tz="UTC"),
17 pd.Timestamp("2024-01-01 10:00:00", tz="UTC"),
18 pd.Timestamp("2024-01-01 20:20:00", tz="UTC"),
19 ],
20 "y": [
21 pd.Timestamp("2023-01-01 00:00:00", tz="UTC"),
22 pd.Timestamp("2023-01-02 10:00:00", tz="UTC"),
23 pd.Timestamp("2023-01-03 20:20:00", tz="UTC"),
24 ],
25 }
26)
27schema = {"x": datetime, "y": datetime}
28expected = [31536000, 31449600, 31363200]
29assert expr.eval(df, schema=schema).tolist() == expected
30
31# can also change the unit of time
32expr = col("x").dt.since(col("y"), unit="minute")
33assert expr.eval(df, schema=schema).tolist() == [
34 525600,
35 524160,
36 522720,
37]python
Errors
The dt namespace must be invoked on an expression that evaluates to datetime
or optional of datetime.
Since Epoch
Function to get the time elapsed since epoch for a datetime object.
Parameters
Default: second
The unit of time to return the elapsed time in. Defaults to seconds. Valid units
are: week, day,hour, minute, second, millisecond, and microsecond.
Returns
Returns an expression object denoting the integer value of the elapsed time since epoch for the datetime object in the specified unit.
1from fennel.expr import col
2
3expr = col("x").dt.since_epoch()
4
5# since_epoch works for any datetime type or optional datetime type
6assert expr.typeof(schema={"x": datetime}) == int
7assert expr.typeof(schema={"x": Optional[datetime]}) == Optional[int]
8
9# can be evaluated with a dataframe
10df = pd.DataFrame(
11 {
12 "x": [
13 pd.Timestamp("2024-01-01 00:00:00", tz="UTC"),
14 pd.Timestamp("2024-01-01 10:00:00", tz="UTC"),
15 pd.Timestamp("2024-01-01 20:20:00", tz="UTC"),
16 ]
17 }
18)
19schema = {"x": datetime}
20expected = [1704067200, 1704103200, 1704140400]
21assert expr.eval(df, schema=schema).tolist() == expected
22
23# can also change the unit of time
24expr = col("x").dt.since_epoch(unit="minute")
25assert expr.eval(df, schema=schema).tolist() == [
26 28401120,
27 28401720,
28 28402340,
29]python
Errors
The dt namespace must be invoked on an expression that evaluates to datetime
or optional of datetime.
Strftime
Function to format a datetime object as a string.
Parameters
The format string to use for the datetime.
Default: UTC
The timezone in which to interpret the datetime. If not specified, UTC is used.
Returns
Returns an expression object denoting the formatted datetime string.
1from fennel.expr import col
2
3expr = col("x").dt.strftime("%Y-%m-%d")
4
5# strftime works for any datetime type or optional datetime type
6assert expr.typeof(schema={"x": datetime}) == str
7assert expr.typeof(schema={"x": Optional[datetime]}) == Optional[str]
8
9# can be evaluated with a dataframe
10df = pd.DataFrame(
11 {
12 "x": [
13 pd.Timestamp("2024-01-01 00:00:00", tz="UTC"),
14 pd.Timestamp("2024-01-02 10:00:00", tz="UTC"),
15 pd.Timestamp("2024-01-03 20:20:00", tz="UTC"),
16 ]
17 }
18)
19schema = {"x": datetime}
20assert expr.eval(df, schema=schema).tolist() == [
21 "2024-01-01",
22 "2024-01-02",
23 "2024-01-03",
24]
25
26# also works with timezone aware datetimes
27expr = col("x").dt.with_tz(timezone="US/Eastern").strftime("%Y-%m-%d")
28assert expr.eval(df, schema=schema).tolist() == [
29 "2023-12-31",
30 "2024-01-02",
31 "2024-01-03",
32]python
Errors
The dt namespace must be invoked on an expression that evaluates to datetime
or optional of datetime.
The format string must be a valid format string.
The timezone must be a valid timezone. Note that Fennel only supports timezones
with area/location names (e.g. America/New_York) and not timezones with offsets
(e.g. +05:00).
Year
Function to get the year component of a datetime object.
Parameters
Default: UTC
The timezone in which to interpret the datetime. If not specified, UTC is used.
Returns
Returns an expression object denoting the integer value of the year of the datetime object.
1from fennel.expr import col
2
3expr = col("x").dt.year
4
5# year works for any datetime type or optional datetime type
6assert expr.typeof(schema={"x": datetime}) == int
7assert expr.typeof(schema={"x": Optional[datetime]}) == Optional[int]
8
9# can be evaluated with a dataframe
10df = pd.DataFrame(
11 {
12 "x": [
13 pd.Timestamp("2024-01-01 00:00:00", tz="UTC"),
14 pd.Timestamp("2024-01-01 10:00:00", tz="UTC"),
15 pd.Timestamp("2024-01-01 20:20:00", tz="UTC"),
16 ]
17 }
18)
19schema = {"x": datetime}
20assert expr.eval(df, schema=schema).tolist() == [2024, 2024, 2024]
21
22# also works with timezone aware datetimes
23expr = col("x").dt.with_tz(timezone="US/Eastern").year
24assert expr.eval(df, schema=schema).tolist() == [2023, 2024, 2024]python
Errors
The dt namespace must be invoked on an expression that evaluates to datetime
or optional of datetime.
The timezone, if provided, must be a valid timezone string. Note that Fennel only supports area/location based timezones (e.g. "America/New_York"), not fixed offsets (e.g. "+05:30" or "UTC+05:30").