Knowledge · GraphQL
ReferenceGraphQL scalar types for timestamps
Int for Unix seconds, String for RFC 3339, or a custom DateTime scalar that validates once. Pair every cursor sorted by time with a stable secondary key. See the subscriptions article for narrative examples.Schema type comparison
| GraphQL type | Wire example | Pros | Cons |
|---|---|---|---|
| Int (seconds) | 1713794701 | Compact, easy math | Ambiguous without docs |
| String (RFC3339) | "2026-04-22T14:05:01Z" | Self-describing | More bytes |
| Custom DateTime scalar | Either of the above | Central validation | Requires codegen rules |
| Float (epoch ms) | 1713794701123.0 | JS-friendly | IEEE floats — avoid for audit |
Resolver patterns
Database drivers often return Date objects or driver-specific temporal types. Normalize in a data loader layer: convert to UTC instant before GraphQL serialization. For read models storing Unix integers, expose a field resolver that formats human strings only when clients request the expensive view — do not stringify in the hot path for mobile list screens.
const resolvers = {
Event: {
createdAtSec(parent) {
return Math.floor(parent.createdAt.getTime() / 1000);
},
},
};Subscription timestamp ordering
Subscribers merging partial buffers need a total order. Pure timestamps fail when events share the same millisecond — attach database sequence numbers, KSUIDs, or hybrid logical clocks. Document whether ordering is per-entity or global; global ordering is expensive at scale and often unnecessary if UI scopes by channel id.
Common mistakes reference
| Mistake | Symptom | Fix |
|---|---|---|
| Millis in Int field named *Sec | 1000× errors | Rename or convert |
| Server uses local TZ | DST bugs | Force UTC in DB + resolvers |
| Relay cursor = only id | Skipping rows | Encode (ts,id) pair |
| Float DateTime scalar | Rounding drift | Use Int/BigInt/String |
Key takeaways
- Scalars encode policy — write the unit in field descriptions and lint schemas in CI.
- Never expose driver-specific Date objects without a defined serialize path.
- Cursors need tie-breakers, especially for millisecond-precision ingress.
- Knowledge base = contracts; tutorials = step-by-step — link both in onboarding.
- Load test with skewed clocks to ensure timeout handling stays deterministic.
Written by Unix Calculator Editorial Team — Last verified May 2026.
Get the Unix Timestamp Cheatsheet
One email. Instant cheatsheet. No drip sequence.