extractTime - Pulls specific time unit from a timestamp

The extractTime function will extract a specific unit of time from a timestamp. For example, pulling out the hour value, or the seconds.

NOTE

Date units such as 'month' or 'week' start from 1 (not from 0).
For units smaller than minute, the number is a floating point, otherwise it's an integer.

Syntax

extractTime(timestamp: timestamp, unit: dateunit | timeunit, tz: string?): number

Arguments

Name	Type	Required	Description
timestamp	timestamp	true	The timestamp to be extracted
unit	dateunit \| timeunit	true	Must be either a timeunit or a dateunit in long or short notation. (See below for examples)
tz	string	false	Must be a valid Time Zone string. See Time Zone section to find out more.

Valid unit inputs

The unit argument must be

any time unit in either long or short notation
a date unit in long notation: 'year', 'month', 'week', 'day_of_year', 'day_of_week'
a date unit in short notation: 'Y', 'M', 'W', 'doy', 'dow'

Example - Finding the hour in Tokyo

Consider the following timestamp:

1728636298

This timestamp refers to 11-10-2024T12:45:13Z. If we wish to find out just the hour in the Tokyo timezone, we can do all of this in a single command:

choose $m.timestamp.extractTime('h', 'Asia/Tokyo') as h # Result 1: 8pm { "h": 20 }

Example - Extracting the number of seconds

Consider the following timestamp:

1728636298

This timestamp refers to 11-10-2024T12:45:13Z. If we wish to extract only the seconds portion here, we can use the second time unit:

choose $m.timestamp.extractTime('second') as s # Result 2: 13.00 seconds { "s": 13.0 }

diffTime

Next formatInterval