graphql-temporal-types-datetime.md

GraphQL Temporal Types (DateTime)

Temporal types are available in Neo4j v3.4+ Read more about using temporal types and functions in Neo4j in the docs and in this post.

Neo4j supports native temporal types as properties on nodes and relationships. These types include Date, DateTime, and LocalDateTime. With neo4j-graphql.js you can use these temporal types in your GraphQL schema. Just use them in your SDL type definitions.

Temporal Types In SDL

neo4j-graphql.js makes available the following temporal types for use in your GraphQL type definitions: Date, DateTime, and LocalDateTime. You can use the temporal types in a field definition in your GraphQL type like this:

type Movie {
  id: ID!
  title: String
  published: DateTime
}

Using Temporal Fields In Queries

Temporal types expose their date components (such as day, month, year, hour, etc) as fields, as well as a formatted field which is the ISO 8601 string representation of the temporal value. The specific fields available vary depending on which temporal is used, but generally conform to those specified here. For example:

GraphQL query

{
  Movie(title: "River Runs Through It, A") {
    title
    published {
      day
      month
      year
      hour
      minute
      second
      formatted
    }
  }
}

GraphQL result

{
  "data": {
    "Movie": [
      {
        "title": "River Runs Through It, A",
        "published": {
          "day": 9,
          "month": 10,
          "year": 1992,
          "hour": 0,
          "minute": 0,
          "second": 0,
          "formatted": "1992-10-09T00:00:00Z"
        }
      }
    ]
  }
}

Temporal Query Arguments

As part of the schema augmentation process temporal input types are added to the schema and can be used as query arguments. For example, given the type definition:

type Movie {
  movieId: ID!
  title: String
  released: Date
}

the following query will be generated for the Movie type:

Movie (
  movieId: ID!
  title: String
  released: _Neo4jDate
  _id: String
  first: Int
  offset: Int
  orderBy: _MovieOrdering
)

and the type _Neo4jDateInput added to the schema:

type _Neo4jDateTimeInput {
  year: Int
  month: Int
  day: Int
  formatted: String
}

At query time, either specify the individual components (year, month, day, etc) or the formatted field, which is the ISO 8601 representation. For example, to query for all movies with a release date of October 10th, 1992:

{
  Movie(released: { year: 1992, month: 10, day: 9 }) {
    title
  }
}

or equivalently:

{
  Movie(released: { formatted: "1992-10-09" }) {
    title
  }
}

Using Temporal Fields In Mutations

As part of the schema augmentation process temporal input types are created and used for the auto-generated create, update, delete mutations using the type definitions specified for the GraphQL schema. These temporal input types also include fields for each component of the temporal type (day, month, year, hour, etc) as well as formatted, the ISO 8601 representation. When used in a mutation, specify either the individual components or the formatted field, but not both.

For example, this mutation:

mutation {
  CreateMovie(
    title: "River Runs Through It, A"
    published: { year: 1992, month: 10, day: 9 }
  ) {
    title
    published {
      formatted
    }
  }
}

is equivalent to this version, using the formatted field instead

mutation {
  CreateMovie(
    title: "River Runs Through It, A"
    published: { formatted: "1992-10-09T00:00:00Z" }
  ) {
    title
    published {
      formatted
    }
  }
}

The input types for temporals generally correspond to the fields used for specifying temporal instants in Neo4j described here.

Resources

• Blog post: Using Native DateTime Types With GRANDstack - Leverage Neo4j’s Temporal Types In Your GraphQL Schema With neo4j-graphql.js