extractTime

Description

Returns a specific unit of time extracted from a timestamp, such as the hour, minute, or second.

note

• Date units such as 'month' or 'week' start from 1, not 0.
• Units smaller than minute return floating-point numbers; all others return integers.

Syntax

Like many functions in DataPrime, extractTime supports two notations, function and method. These interchangeable forms allow flexibility in how you structure expressions.

Function notation

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

Method notation

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

Arguments

Name	Type	Required	Description
timestamp	timestamp	true	The timestamp to extract from
unit	dateunit \| timeunit	true	The unit of time to extract, in short or long notation
tz	string	false	A valid time zone string (see Time Zone section for details)

Example 1

Use case: Find the hour in a specific time zone

Extract the hour of the day from a timestamp, adjusted to Tokyo time.

Example data

{
  "timestamp": 1728636298
}

Example query

Function notation

choose extractTime($m.timestamp, 'h', 'Asia/Tokyo') as h

Method notation

choose $m.timestamp.extractTime('h', 'Asia/Tokyo') as h

Example output

{
  "h": 20
}

Example 2

Use case 2: Extract the number of seconds

Extract just the seconds portion of a timestamp.

Example data

{
  "timestamp": 1728636298
}

Example query

Function notation

choose extractTime(timestamp, 'second') as s

Method notation

choose timestamp.extractTime('second') as s

Example output

{
  "s": 13.0
}