| Scalar Definition |
Description |
scalar DateTime
@specifiedBy(url:
"https://scalars.graphql.org/andimarek/date-time.html"
)
|
A RFC-3339 compliant date time scalar that accepts string values like 1996-12-19T16:39:57-08:00 and produces java.time.OffsetDateTime objects at runtime. |
scalar Date
@specifiedBy(url:
"https://tools.ietf.org/html/rfc3339"
) |
A RFC-3339 compliant date scalar that accepts string values like 1996-12-19 and produces java.time.LocalDate objects at runtime. |
scalar Time
@specifiedBy(url:
"https://tools.ietf.org/html/rfc3339"
)
|
A RFC-3339 compliant time scalar that accepts string values like 16:39:57-08:00 and produces java.time.OffsetTime objects at runtime. |
scalar LocalTime
|
24-hour clock time string in the format hh:mm:ss.sss or hh:mm:ss if partial seconds is zero and produces java.time.LocalTime objects at runtime. |
scalar SecondsSinceEpoch
|
A scalar that represents a point in time as seconds since the Unix epoch (January 1, 1970, 00:00:00 UTC). It accepts integers or strings containing integers as input values and produces java.time.ZonedDateTime objects at runtime (with UTC timezone).
Using seconds since epoch is preferable to formatted date time strings in several scenarios:
- When you need a universal representation of a point in time that is timezone-agnostic
- For easier date/time arithmetic and comparison operations
- When storage space or bandwidth efficiency is important (more compact representation)
- To avoid complexities with different date formats and timezone conversions
- For better interoperability with systems that natively work with Unix timestamps
- When working with time-series data or logging systems where timestamps are commonly used
However, human readability is sacrificed compared to formatted date strings, so consider your use case requirements when choosing between DateTime and SecondsSinceEpoch. |
An example declaration in SDL might be:
```graphql
type Customer {
birthDay: Date
workStartTime: Time
bornAt: DateTime
createdAtTimestamp: SecondsSinceEpoch
}
type Query {
customers(bornAfter: DateTime, createdAfter: SecondsSinceEpoch): [Customers]
}
```
And example query might look like:
```graphql
query {
customers(bornAfter: "1996-12-19T16:39:57-08:00", createdAfter: 1609459200) {
birthDay
bornAt
createdAtTimestamp
}
}
```
## ID Scalars
| Scalar Definition |
Description |
scalar PositiveInt |
An Int scalar that MUST be greater than zero. |
scalar NegativeInt |
An Int scalar that MUST be less than zero. |
scalar NonPositiveInt |
An Int scalar that MUST be less than or equal to zero. |
scalar NonNegativeInt |
An Int scalar that MUST be greater than or equal to zero. |
scalar PositiveFloat |
An Float scalar that MUST be greater than zero. |
scalar NegativeFloat |
An Float scalar that MUST be less than zero. |
scalar NonPositiveFloat |
An Float scalar that MUST be less than or equal to zero. |
scalar NonNegativeFloat |
An Float scalar that MUST be greater than or equal to zero. |
The numeric scalars are derivations of the standard GraphQL `Int` and `Float` scalars that enforce range limits.
An example declaration in SDL might be:
```graphql
type Customer {
name: String
currentHeight: PositiveInt
weightLossGoal: NonPositiveInt
averageWeightLoss: NegativeFloat
}
type Query {
customers(height: PositiveInt): [Customers]
}
```
And example query might look like:
```graphql
query {
customers(height: 182) {
name
height
weightLossGoal
}
}
```
## Java Primitives