Dates and time zones
nonodb implements dates as a first-class, BSON-compatible value rather than as ordinary strings. The model follows MongoDB:
- a date is an instant, stored as signed 64-bit Unix milliseconds in UTC;
- no timezone is stored with the value;
- RFC 3339 offsets are normalized when the document is written;
- comparison, sorting, and indexes use the instant, not the original text.
Dates use MongoDB Extended JSON syntax. This keeps HTTP requests, documents, and backups plain JSON.
Input forms
Section titled “Input forms”Relaxed Extended JSON:
{"created_at": {"$date": "2026-01-01T01:00:00+01:00"}}Canonical Extended JSON:
{"created_at": {"$date": {"$numberLong": "1767225600000"}}}Numeric convenience form, also interpreted as Unix milliseconds:
{"created_at": {"$date": 1767225600000}}Strings must be RFC 3339 and must include Z or a numeric offset. Naive local
times are rejected with invalid_date because their instant is ambiguous:
{"created_at": {"$date": "2026-01-01T00:00:00"}}Date-only strings such as "2026-01-01" are also rejected. Store an explicit
instant (2026-01-01T00:00:00Z) if that is what you mean.
All accepted forms are normalized to canonical UTC milliseconds before storage:
{"created_at": {"$date": {"$numberLong": "1767225600000"}}}Filtering
Section titled “Filtering”Dates use the normal comparison operators. There are no separate $dateGt or
similar operators:
{ "op": "find", "coll": "events", "filter": { "created_at": { "$gte": {"$date": "2026-01-01T00:00:00Z"}, "$lt": {"$date": "2026-02-01T00:00:00Z"} } }}Because comparison is by instant, these are equal:
2026-01-01T00:00:00Z2026-01-01T01:00:00+01:002026-01-01T02:00:00+02:00$eq, $ne, $in, and $nin also compare dates by instant. Date values and
strings are different types: a date query does not match an ISO string field,
and a string query does not match a date field.
Indexes and sorting
Section titled “Indexes and sorting”Secondary indexes encode dates as order-preserving signed integers. A normal index on the field is enough; no type annotation is required:
{"op": "create_index", "coll": "events", "fields": ["tenant", "created_at"]}This supports:
- range filters on
created_atafter an equality ontenant; - chronological sorting by
created_at; - unique indexes that treat different offsets for the same instant as duplicates;
- covering projections that include date fields.
Indexes and filters work with negative timestamps (dates before 1970).
Updates
Section titled “Updates”Dates can be set or replaced with normal update operators:
{ "op": "update", "coll": "events", "filter": {"_id": "e1"}, "update": {"$set": {"created_at": {"$date": "2026-01-01T00:00:00Z"}}}}$currentDate sets the current UTC date:
{"op": "update", "coll": "events", "filter": {"_id": "e1"}, "update": {"$currentDate": {"updated_at": true}}}BSON Timestamp values are also supported:
{"update": {"$currentDate": {"ts": {"$type": "timestamp"}}}}See BSON scalar types for Timestamp storage and comparison semantics.
Time zones and civil dates
Section titled “Time zones and civil dates”Timezone identifiers such as Europe/Warsaw are not part of the stored value.
Convert local times to an RFC 3339 instant in the client. This is also how the
MongoDB BSON Date type works.
Date expressions
Section titled “Date expressions”The aggregation expression evaluator supports:
$dateAddand$dateSubtractwithyear,quarter,month,week,day,hour,minute,second, andmillisecondunits;$dateDiffwith the same units and optionalstartOfWeek;$dateTruncwithbinSizeandstartOfWeek;$dateToStringwith the common format specifiers;$dateFromStringfor RFC 3339 input, custom formats, and naive input with an explicit timezone;$dateFromPartsand$dateToParts, including ISO week fields.
They work in $expr, $project, $addFields, $group, $bucket, and
pipeline updates.
{ "$project": { "day": { "$dateTrunc": {"date": "$created_at", "unit": "day"} }, "label": { "$dateToString": { "date": "$created_at", "format": "%Y-%m-%d", "timezone": "+01:00" } } }}Time zones are UTC (Z, UTC, GMT) or fixed offsets such as +02:00 and
-05:00. IANA names such as Europe/Warsaw are not implemented.
Not yet supported: IANA time zone identifiers.
Existing documents and imports
Section titled “Existing documents and imports”Reads are non-destructive: nonodb does not scan or rewrite stored values when loading a document.
-
A stored
{"$date": ...}object is recognized as a date by filters, sorting, aggregation, and indexes, even if it was stored before this feature and is still in relaxed form. It is canonicalized on the next write. -
An ISO 8601 string remains a string. It does not match a date query and is not indexed as a date:
{"created_at": "2026-01-01T00:00:00Z"} -
Bulk imports through
insert_manyand document batches follow the same rules asinsert: Extended JSON dates are normalized on write. -
Invalid stored
$dateobjects are not silently treated as dates. They do not match date filters and are rejected if the document is written again.
Migrating existing string dates
Section titled “Migrating existing string dates”There is no automatic string-to-date migration, because guessing which string
fields are timestamps is unsafe. Convert selected fields explicitly, for
example by reading matching documents and updating each field to Extended JSON.
Use {"$date": "..."} with Z or an offset; a write will normalize it to
canonical UTC milliseconds.
After migration, update any index that should serve date queries.
Indexes created before date support
Section titled “Indexes created before date support”Index definitions now carry an encoding format. Indexes created before date
support have format 0; they skipped $date objects during backfill. To avoid
returning incomplete results, nonodb skips such an index when the filter
contains a date and falls back to a scan.
Recreate the index to enable indexed date ranges, sorting, and count:
{"op": "drop_index", "coll": "events", "field": "created_at"}{"op": "create_index", "coll": "events", "fields": ["created_at"]}Normal non-date queries can continue using the old index until it is recreated.
Other compatibility rules
Section titled “Other compatibility rules”- New writes using
{"$date": ...}are normalized and indexed as dates. - Documents containing an object with exactly one
$datekey are reserved for this representation. Do not use$dateas an ordinary application field. - Date precision is milliseconds, matching BSON Date.
- Backups and snapshots preserve canonical dates without conversion.
Errors
Section titled “Errors”| Code | Meaning |
|---|---|
invalid_date |
Invalid $date payload, invalid RFC 3339 string, or missing timezone |