Presented at the Seventh openCypher Implementers Group Meeting in March 2018 @ https://www.opencypher.org/ocig/2018/03/14/ocig7/

1. Date and Time
CIP 2015-08-06

2. Temporal instant types
● DateTime
○ with timezone (logical zone or absolute offset from UTC)
● LocalDateTime
○ without timezone
● Date
○ without timezone
● Time
○ with absolute offset from UTC (logical zones needs date to map to offset)
● LocalTime
○ without timezone

3. Duration type
● Represents a number of
○ years
○ months
○ days
○ hours
○ minutes
○ seconds (and fractional seconds)
● years and months (and quarters) convertible
● (days and weeks convertible)
● hours, minutes, and seconds convertible
● No conversion between the three groups above!

4. Syntax
No new syntax is introduced.
All handling of temporal values is done through functions:
● datetime(...)
● localdatetime(...)
● date(...)
● time(...)
● localtime(...)
● {datetime,localdatetime,date,time,localtime}.truncate(...)
● {datetime,localdatetime,date,time,localtime}.{statement,transaction,realtime}(...)
● duration(...)
● duration.between(...), duration.inMonths(...), duration.inDays(...), duration.inSeconds(...)

5. Ways of creating temporal instants
● Parsing from ISO 8601 string
● Creating from components
● Getting the current instant
○ using different clocks: statement, transaction, realtime (one of them being default)
● Adding a Duration to an instant
● Converting from other instants
Ways of creating Duration
● Parsing from ISO 8601 string
● Creating from components
● Compute difference between instants

6. Parsing Temporal Instant from ISO 8601 string
● datetime($string), localdatetime($string), date($string), time($string), localtime($string)
● date: YYYY-MM-DD, or YYYY-Www-D, or YYYY-Qq-DD, or YYYY-DDD
(calendar date, week date, quarter date, ordinal date respectively)
○ dashes can be omitted, smaller units can be omitted
○ year with a sign prefix can be arbitrarily long, but then dashes may not be omitted
● time: HH:MM:SS.sss
○ colons can be omitted, smaller units can be omitted
● offset: ±HH:MM or Z
○ colons can be omitted, smaller units can be omitted
● zone: [name]

7. Parsing Temporal Instant from ISO 8601 string
● datetime($string)
○ <date>T<time><offset><zone>
○ either offset, or zone, or both
○ smaller units may be omitted
● localdatetime($string)
○ <date>T<time>
○ smaller units may be omitted
● date($string)
○ <date>
● time($string)
○ <time><offset>
● localtime($string)
○ <time>

8. Creating Temporal Instant from components
● datetime({...}), localdatetime({...}), date({...}), time({...}), localtime({...})
○ Date based:
■ year
■ quarter
■ month
■ week
■ weekYear
■ day
■ ordinalDay
■ weekDay
○ Time based:
■ hour
■ minute
■ second
■ millisecond
■ microsecond
■ nanosecond
○ Other:
■ timezone - the named timezone or offset if no name (supported by zoned types)
■ offset - as a formatted offset string (supported by zoned types)
■ offsetMinutes (supported by zoned types)
■ epochMillis (only supported by DateTime)
■ epochSeconds (only supported by DateTime)
■ epochNanosOfSecond (only supported by DateTime)

9. Getting the current Temporal Instant
● datetime(), localdatetime(), date(), time(), localtime()
The above uses the (implementation specific) default clock, which is one of the below:
Same point in time every invocation in the query:
● datetime.statement(), localtime.statement(), et.c...
● datetime.statement($timezone), et.c...
Same point in time every invocation in the transaction:
● datetime.transaction(), localtime.transaction(), et.c...
● datetime.transaction($timezone), et.c…
Actual time at invocation:
● datetime.realtime(), localtime.realtime(), et.c...
● datetime.realtime($timezone), et.c...

10. Converting Temporal Instants between types
● datetime({...}), localdatetime({...}), date({...}), time({...}), localtime({...})
● date - selects the date from a Date, or DateTime, or LocalDateTime
● time - selects the time from a Time, LocalTime, DateTime, LocalDateTime
● datetime - selects both the date and time from a DateTime or LocalDateTime
Examples:
● datetime({datetime:$aDateTimeOrLocalDateTime, timezone:"..."})
● datetime({date:$aDateOrDateTimeOrLocalDateTime,
time:$anotherDateOrDateTimeOrLocalDateTime})
● datetime({datetime:...}), datetime({date:..., time:...})
datetime({datetime:..., timezone:...}), datetime({date:..., time:..., timezone:...})
● localdatetime({datetime:...}), localdatetime({date:..., time:...})
● time({time:...}), time({time:..., timezone:...})
● date({date:...})
● localtime({time:...})

11. Parsing Duration from ISO 8601 string
● duration($string)
● unit based format:
PnYnQnMnWnDTnHnMnS
○ zero valued component can be omitted
○ T must precede time-based section (Hours and smaller)
○ Smallest component may be fractional
○ Examples: P15M, P1DT3H, PT48H, P1.5W
● date-and-time based format:
P<date>T<time>
○ smaller units may be omitted

12. Creating Duration from Components
● duration({...})
○ years
○ quarters
○ months
○ weeks
○ days
○ hours
○ minutes
○ seconds
○ milliseconds
○ microseconds
○ nanoseconds

13. Compute Duration as difference between Instants
Computing the duration from instant a to instant b:
● duration.between(a, b)
○ uses natural units
● duration.inSeconds(a, b)
○ uses hours, minutes, seconds
● duration.inDays(a, b)
○ uses days
● duration.inMonths(a, b)
○ uses months and years

14. Adding a Duration to a Temporal Instant
Example: date("1984-10-11") + duration("P33Y5M3D")
Note that this is not associative:
● (date("2011-01-31") + duration("P1M")) + duration("P12M")
○ date({year:2012, month:2, day:28})
● date("2011-01-31") + (duration("P1M") + duration("P12M"))
○ date({year:2012, month:2, day:29})

15. Truncating a Temporal Instant
datetime.truncate($unit, $instant)
localdatetime.truncate($unit, $instant)
date.truncate($unit, $instant)
time.truncate($unit, $instant)
localtime.truncate($unit, $instant)
Supported units:
● millennium
● century
● decade
● year
● weekYear - the first day of the first week of the week year of the specified instant (may be in december of previous year)
● quarter
● month
● week
● day
● hour
● minute
● second
● millisecond
● microsecond

16. Comparing and ORDER BY
● Temporal Instants comparable to other instants of same type
● ORDER BY uses comparison order for Temporal Instants
● ORDER BY groups by type when ordering by field with mixed types
● Duration values are NOT comparable
○ because different months are of different lengths, and not all days are equally long
● ORDER BY for Duration based on average length of days and months

17. Ordering durations - is the order consistent?
● PT672H = P28D ≤ P1M ≤ P31D = PT744H ; P1M ordered as: PT2629746S = PT730,485H
(shortest possible: February)
● PT1416H = P59D ≤ P2M ≤ P62D = PT1488H ; P2M ordered as: PT5259492S = PT1460,970H
(shortest possible two: Jan-Feb or Feb-Mar, longest possible two: Jul-Aug or Dec-Jan)
● PT2136H = P89D ≤ P3M ≤ P92D = PT2208H ; P3M ordered as: PT7889238S = PT2191,455H
(shortest possible three: Feb-Apr, longest possible three: Nov-Jan or Jun-Aug or Jul-Sep)
● PT2880H = P120D ≤ P4M ≤ P123D = PT2952H ; P4M ordered as: PT10518984S = PT2921,940H
(shortest possible four: Jan-Apr or Feb-May or Nov-Feb, longest possible four: May-Aug or Jul-Oct or Oct-Jan)
● PT3600H = P150D ≤ P5M ≤ P153D = PT3672H ; P5M ordered as: PT13148730S = PT3652,425H
(shortest possible five: Feb-Jun, longest possible five: any range not including Feb)
● PT4344H = P181D ≤ P6M ≤ P184D = PT4416H ; P6M ordered as: PT15778476S = PT4382,910H
(shortest possible six: Jan-Jun or Feb-Jul, longest possible six: Jul-Dec or Aug-Jan)
● PT5088H = P212D ≤ P7M ≤ P215D = PT5160H ; P7M ordered as: PT18408222S = PT5113,395H
(shortest possible seven: any range including Feb, longest possible seven: Jul-Jan)
● PT5808H = P242D ≤ P8M ≤ P245D = PT5880H ; P8M ordered as: PT21037968S = PT5843,880H
(shortest possible eight: Feb-Sep or Sep-Apr or Nov-Jun, longest possible eight: May-Dec or Jun-Jan)
● PT6552H = P273D ≤ P9M ≤ P276D = PT6624H ; P9M ordered as: PT23667714S = PT6574,365H
(shortest possible nine: many, longest possible nine: May-Jan)
● PT7272H = P303D ≤ P10M ≤ P306D = PT7344H ; P10M ordered as: PT26297460S = PT7304,850H
(shortest possible ten: Feb-Nov or Sep-Jun, longest possible ten: Mar-Dec or Apr-Jan)
● PT8016H = P334D ≤ P11M ≤ P337D = PT8088H ; P11M ordered as: PT28927206S = PT8035,335H
(shortest possible eleven: many, longest possible eleven: Mar-Jan)
● PT8760H = P365D ≤ P12M = P1Y ≤ P366D = PT8784H ; P12M, P1Y ordered as: PT31556952S = PT8765,820H
(longest possible: leap year)
● PT35040H = P1460D ≤ P4Y ≤ P1461D = PT35064H ; P4Y ordered as: PT126227808S = PT35063,280H
(every 100 years, we skip a leap year)
● PT876576H = P36524D ≤ P100Y ≤ P36525D = PT876600H ; P100Y ordered as: PT3155695200S = PT876582,000H
(every 400 years, we skip skipping the leap year)
● PT3506328H = P400Y = P146097D = PT3506328H ; P400Y ordered as: PT12622780800S = PT3506328,000H
(this it the shortest number of months where we know exactly how many days it is)