Dates and times

Temporal types

The neo4j package provides types for working with dates and times in Go.

Temporal types in Neo4j are a combination of date, time and timezone elements.

Learn how to interact with Neo4j from Go using the Neo4j Go DriverTemporal Types
Type	Description	Date?	Time?	Timezone?
`neo4j.Date`	A tuple of Year, Month and Day	Y
`neo4j.OffsetTime`	The time of the day with a UTC offset		Y	Y
`neo4j.LocalTime`	A time without a timezone		Y
`time.Time`	A combination of Date and Time	Y	Y	Y
`neo4j.LocalDateTime`	A combination of Date and Time without a timezone	Y	Y
`neo4j.Duration`	A period of time

Writing temporal types

res, err := neo4j.ExecuteQuery(ctx, driver, `
CREATE (e:Event {
  startsAt: $datetime,              // (1)
  createdAt: datetime($dtstring),   // (2)
  updatedAt: datetime()             // (3)
})
`,
    map[string]any{
        "datetime": func() time.Time {
            loc, _ := time.LoadLocation("Europe/Paris")
            return time.Date(2024, 5, 15, 14, 30, 0, 0, loc)
        }(), // (4)
        "dtstring": "2024-05-15T14:30:00+02:00",
    },
    neo4j.EagerResultTransformer,
)

When you write temporal types to the database, you can pass Go time objects as parameters to the query or cast the value within a Cypher statement.

This example demonstrates how to:

Use a time.Time object as a parameter to the query (<4>)
Cast an datetime with an IANA timezone identifier within the Cypher statement
Get the current date and time using the datetime() function.

Reading temporal types

When reading temporal types from the database, you will receive an instance of the corresponding Go type unless you cast the value within your query.

// Query returning temporal types
result, err := neo4j.ExecuteQuery(ctx, driver, `
RETURN date() as date, time() as time, datetime() as datetime, toString(datetime()) as asString
`, nil, neo4j.EagerResultTransformer)

// Access the first record
for _, record := range result.Records {
    // Automatic conversion to Go driver types
    date, _ := record.Get("date")           // neo4j.Date
    time, _ := record.Get("time")           // neo4j.OffsetTime
    datetime, _ := record.Get("datetime")   // time.Time
    asString, _ := record.Get("asString")   // string
}

Working with Durations

startsAt := time.Now()
eventLength := neo4j.DurationOf(0, 0, int64((time.Hour + 30*time.Minute).Seconds()), 0)
endsAt := startsAt.Add(time.Hour + 30*time.Minute)

neo4j.ExecuteQuery(ctx, driver, `
CREATE (e:Event {
  startsAt: $startsAt, endsAt: $endsAt,
  duration: $eventLength, // (1)
  interval: duration('P30M') // (2)
})`,
    map[string]any{
        "startsAt": startsAt,
        "endsAt": endsAt,
        "eventLength": eventLength,
    },
    neo4j.EagerResultTransformer,
)

Durations represent a period of time and can be used for date arithmetic in both Go and Cypher. These types can also be created in Go or cast within a Cypher statement.

Pass an instance of neo4j.Duration to the query
Use the duration() function to create a Duration object from an ISO 8601 format string

Neo4j Duration vs Go Duration

Note the distinction between neo4j.Duration and Go’s time.Duration:

neo4j.Duration - Used for storing durations in Neo4j and passing as parameters
time.Duration - Used for Go time calculations like Add() operations

For time arithmetic in Go, use standard time.Duration values directly.

Check your understanding

Advance to challenge

Lesson Summary

In this lesson, you learned about working with temporal types in Neo4j using the Go driver:

The neo4j package provides types for handling dates, times, and durations
You can pass Go time objects as parameters or create them within Cypher statements
When reading temporal values from Neo4j, they are automatically converted to the appropriate Go driver types
Durations can be used for date arithmetic in both Go and Cypher

Converting between driver and standard library types

The Neo4j Go driver’s temporal types (like neo4j.Date) are different from Go’s standard library types (like time.Time). If you need to convert between them:

To convert from driver types to standard library: use the .Time() method
To convert from standard library to driver types: use the *Of() functions like DateOf(), LocalDateTimeOf(), etc.

Using Neo4j with Go

The Driver

Handling results

Best practices