Temporal Data Types

The table below shows the general mappings between Cypher and the temporal types provided by the Python Driver.

In addition, the built-in temporal types can be passed as parameters and will be mapped appropriately.

Cypher

Python driver type

Python built-in type

tzinfo

Date

neo4j.time.Date

datetime.date

Time

neo4j.time.Time

datetime.time

not None

LocalTime

neo4j.time.Time

datetime.time

None

DateTime

neo4j.time.DateTime

datetime.datetime

not None

LocalDateTime

neo4j.time.DateTime

datetime.datetime

None

Duration

neo4j.time.Duration

datetime.timedelta

Sub-second values are measured to nanosecond precision and the types are compatible with pytz.

Note

Cypher has built-in support for handling temporal values, see https://neo4j.com/docs/cypher-manual/current/syntax/temporal/

Constants

neo4j.time.MIN_YEAR = 1

The smallest year number allowed in a neo4j.time.Date or neo4j.time.DateTime object to be compatible with datetime.date and datetime.datetime.

neo4j.time.MAX_YEAR = 9999

The largest year number allowed in a neo4j.time.Date or neo4j.time.DateTime object to be compatible with datetime.date and datetime.datetime.

Date

A neo4j.time.Date object represents a date in the proleptic Gregorian Calendar.

Years between 0001 and 9999 are supported, with additional support for the “zero date” used in some contexts.

Each date is based on a proleptic Gregorian ordinal, which models 1 Jan 0001 as day 1 and counts each subsequent day up to, and including, 31 Dec 9999. The standard year, month and day value of each date is also available.

Internally, the day of the month is always stored as-is, with the exception of the last three days of that month. These are always stored as -1, -2 and -3 (counting from the last day). This system allows some temporal arithmetic (particularly adding or subtracting months) to produce a more desirable outcome than would otherwise be produced. Externally, the day number is always the same as would be written on a calendar.

Constructors and other class methods

class neo4j.time.Date(year, month, day)

Construct a new neo4j.time.Date object. All arguments are required and should be integers. For general dates, the following ranges are supported:

Argument

Minimum

Maximum

year

MIN_YEAR (0001)

MAX_YEAR (9999)

month

1

12

day

1

Date.days_in_month(year, month)

A zero date can also be acquired by passing all zeroes to the neo4j.time.Date constructor or by using the ZeroDate constant.

classmethod Date.today()
Raises

OverflowError – if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.

classmethod Date.utc_today()

Return the current Date according to UTC.

classmethod Date.from_timestamp(timestamp, tz=None)
Raises

OverflowError – if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.

classmethod Date.utc_from_timestamp(timestamp)
classmethod Date.from_ordinal(ordinal)

Construct and return a Date from a proleptic Gregorian ordinal. This is simply an integer value that corresponds to a day, starting with 1 for 1 Jan 0001.

classmethod Date.parse(s)
classmethod Date.from_native(date)
Date.from_clock_time(cls, t, epoch):
classmethod Date.is_leap_year(year)

Return a bool value that indicates whether or not year is a leap year.

classmethod Date.days_in_year(year)

Return the number of days in year.

classmethod Date.days_in_month(year, month)

Return the number of days in month of year.

Class attributes

Date.min
Date.max
Date.resolution

Instance attributes

d.year
d.month
d.day
d.year_month_day
d.year_week_day
d.year_day

Return a 2-tuple of year and day number. This is the number of the day relative to the start of the year, with 1 Jan corresponding to 1.

Operations

Instance methods

d.replace(year=self.year, month=self.month, day=self.day)

Return a Date with one or more components replaced with new values.

d.time_tuple()
d.to_ordinal()
d.weekday()
d.iso_weekday()
d.iso_calendar()
d.iso_format()
d.__repr__()
d.__str__()
d.__format__()

Special values

ZeroDate

A neo4j.time.Date instance set to 0000-00-00. This has an ordinal value of 0.

Time

The neo4j.time.Time class is a nanosecond-precision drop-in replacement for the standard library datetime.time class.

A high degree of API compatibility with the standard library classes is provided.

neo4j.time.Time objects introduce the concept of ticks. This is simply a count of the number of seconds since midnight, in many ways analogous to the neo4j.time.Date ordinal. Ticks values can be fractional, with a minimum value of 0 and a maximum of 86399.999999999.

Constructors and other class methods

class neo4j.time.Time(hour, minute, second, tzinfo=None)
classmethod Time.now()
Raises

OverflowError – if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.

classmethod Time.utc_now()
classmethod Time.from_ticks(ticks)
classmethod Time.from_native(time)
classmethod Time.from_clock_time(t, epoch)

Class attributes

Time.min
Time.max
Time.resolution

Instance attributes

t.ticks
t.hour
t.minute
t.second
t.hour_minute_second
t.tzinfo

Operations

hash(t)
t1 == t2
t1 != t2
t1 < t2
t1 > t2
t1 <= t2
t1 >= t2
t1 + timedelta -> t2
t1 + duration -> t2
t1 - timedelta -> t2
t1 - duration -> t2
t1 - t2 -> timedelta

Instance methods

t.replace(hour=self.hour, minute=self.minute, second=self.second, tzinfo=self.tzinfo)

Return a Time with one or more components replaced with new values.

t.utc_offset()
t.dst()
t.tzname()
t.iso_format()
t.__repr__()
t.__str__()
t.__format__()

Special values

Midnight

A Time instance set to 00:00:00. This has a ticks value of 0.

Midday

A Time instance set to 12:00:00. This has a ticks value of 43200.

LocalTime

When tzinfo is set to None

DateTime

The neo4j.time.DateTime class is a nanosecond-precision drop-in replacement for the standard library datetime.datetime class.

As such, it contains both neo4j.time.Date and neo4j.time.Time information and draws functionality from those individual classes.

A DateTime object is fully compatible with the Python time zone library pytz. Functions such as normalize and localize can be used in the same way as they are with the standard library classes.

Constructors and other class methods

class neo4j.time.DateTime(year, month, day, hour=0, minute=0, second=0.0, tzinfo=None)

Regular construction of a DateTime object requires at least the year, month and day arguments to be supplied. The optional hour, minute and second arguments default to zero and tzinfo defaults to None.

While year, month, day, hour and minute accept only int() values, second can also accept a float() value. This allows sub-second values to be passed, with up to nine decimal places of precision held by the object within the second attribute.

>>> dt = DateTime(2018, 4, 30, 12, 34, 56.789123456); dt
neo4j.time.DateTime(2018, 4, 30, 12, 34, 56.789123456)
>>> dt.second
56.789123456
classmethod DateTime.now()
Raises

OverflowError – if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.

classmethod DateTime.utc_now()
classmethod DateTime.from_timestamp(timestamp, tz=None)
Raises

OverflowError – if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.

classmethod DateTime.utc_from_timestamp(timestamp)
classmethod DateTime.from_ordinal(ordinal)
classmethod DateTime.combine(date, time)
classmethod DateTime.from_native(datetime)
classmethod DateTime.from_clock_time(t, epoch)

Class attributes

DateTime.min
DateTime.max
DateTime.resolution

Instance attributes

dt.year
dt.month
dt.day
dt.year_month_day
dt.year_week_day
dt.year_day
dt.hour
dt.minute
dt.second
dt.tzinfo
dt.hour_minute_second

Operations

hash(dt)
dt1 == dt2
dt1 != dt2
dt1 < dt2
dt1 > dt2
dt1 <= dt2
dt1 >= dt2
dt1 + timedelta -> dt2
dt1 + duration -> dt2
dt1 - timedelta -> dt2
dt1 - duration -> dt2
dt1 - dt2 -> timedelta

Instance methods

dt.date()
dt.time()
dt.timetz()
dt.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, tzinfo=self.tzinfo)

Return a DateTime with one or more components replaced with new values.

dt.as_timezone()
dt.utc_offset()
dt.dst()
dt.tzname()
dt.time_tuple()
dt.utc_time_tuple()
dt.to_ordinal()
dt.weekday()
dt.iso_weekday()
dt.iso_calendar()
dt.iso_format()
dt.__repr__()
dt.__str__()
dt.__format__()

Special values

Never

A DateTime instance set to 0000-00-00T00:00:00. This has a Date component equal to ZeroDate and a Time component equal to Midnight.

UnixEpoch

A DateTime instance set to 1970-01-01T00:00:00.

LocalDateTime

When tzinfo is set to None

Duration

A neo4j.time.Duration represents the difference between two points in time. Duration objects store a composite value of months, days and seconds. Unlike datetime.timedelta however, days and seconds are never interchanged and are applied separately in calculations.

class neo4j.time.Duration(years=0, months=0, weeks=0, days=0, hours=0, minutes=0, seconds=0, subseconds=0, milliseconds=0, microseconds=0, nanoseconds=0)

All arguments are optional and default to zero.

Duration.min

The lowest duration value possible.

Duration.max

The highest duration value possible.

Instance methods and attributes

A neo4j.time.Duration stores four primary instance attributes internally: months, days, seconds and subseconds. These are maintained as individual values and are immutable. Each of these four attributes can carry its own sign, with the exception of subseconds, which must have the same sign as seconds. This structure allows the modelling of durations such as 3 months minus 2 days.

Two additional secondary attributes are available, each returning a 3-tuple of derived values. These are years_months_days and hours_minutes_seconds.

The primary instance attributes and their permitted ranges are listed below.

Attribute

Value

months

Between -(263) and (263 - 1) inclusive

days

Between -(263) and (263 - 1) inclusive

seconds

Between -(263) and (263 - 1) inclusive

subseconds

Between -0.999,999,999 and +0.999,999,999 inclusive

Operations

neo4j.time.Duration objects support a number of operations. These are listed below.

Operation

Result

d1 + d2

A Duration representing the sum of d1 and d2 .

d1 - d2

A Duration representing the difference between d1 and d2 .

d1 * i

A Duration representing d1 times i, where i is an int.

d1 * f

A Duration representing d1 times f, where f is a float.

d1 / i

A Duration representing d1 divided by i, where i is an int. Month and day attributes are rounded to the nearest integer, using round-half-to-even.

d1 / f

A Duration representing d1 divided by f, where f is a float. Month and day attributes are rounded to the nearest integer, using round-half-to-even.

d1 // i

A Duration representing the floor after d1 is divided by i, where i is an int.

d1 % i

A Duration representing the remainder after d1 is divided by i, where i is an int.

divmod(d1, i)

A pair of Duration objects representing the floor and remainder after d1 is divided by i, where i is an int.

+d1

A Duration identical to d1 .

-d1

A Duration that is the inverse of d1. Equivalent to Duration(months=-d1.months, days=-d1.days, seconds=-d1.seconds, subseconds=-d1.subseconds).

abs(d1)

A Duration equal to the absolute value of d1. Equivalent to Duration(months=abs(d1.months), days=abs(d1.days), seconds=abs(d1.seconds), subseconds=abs(d1.subseconds)).

str(d1)

repr(d1)

bool(d1)

True if any attribute is non-zero, False otherwise.

tuple(d1)

A 4-tuple of (months: int, days: int, seconds: int, subseconds: float).