Dates and time zonesdev
Luxir accepts ISO-8601 dates, numeric epoch values, and both Solr and
Elasticsearch/OpenSearch date-math syntax. Date fields support queries,
ranges, sorting, and facets. Use the built-in _dt template (_dts for
multiple dates), or define a date field explicitly. Partial dates match the
whole day or month they name. Set time_zone on a request for local date
queries and calendar buckets. Dates are stored as int64 counts since the Unix
epoch, in milliseconds by default. This page covers the
accepted forms, date math, and time zones; the
query language has the grammar
corners and faceting has calendar buckets.
Accepted date values
Section titled “Accepted date values”A date field’s unit is "ms" (default) or "ns", inherited from its parent
when omitted. Numeric ingest and query literals, including integer strings and
date-math anchors, use that unit by default. Numeric facet bounds, gaps, origins
and selected values also default to the field’s unit; request flags can select
another input unit. ISO-8601 input converts to the
field’s precision. For example:
{"fields":{"event_time":{"type":"date","unit":"ns"}}}Nanosecond ingest accepts values from INT64_MIN+1 through INT64_MAX-1,
covering 1677-09-21 to 2262-04-11; the two extrema are reserved and rejected.
Numeric ms ingest rejects values outside years -32767 through 32767.
Query bounds outside the ns domain saturate to the reserved extrema, so an upper bound above the domain includes everything and a lower bound above it includes nothing. The extrema themselves are never stored values.
The unit is part of the field’s signature. A schema update cannot change it on an existing date definition, including an empty field or an inherited unit.
For default millisecond fields, date values and query examples use epoch milliseconds (not a year) or ISO-8601 strings:
2024-06-25T10:30:00Z a full instant, UTC2024-06-25T10:30:00-05:00 a full instant with an offset2024-06-25T10:30 no zone: UTC by default2024-06-25 a whole day2024-06 a whole month1719311400000 epoch millisecondsMatch and range queries use a date’s whole window at its literal precision.
Numeric literals name one field tick. any_of instead tests exact instants:
numbers are exact field ticks, ISO text uses its start rounded toward earlier
time, and members outside the field’s stored domain are dropped.
A partial date names its whole window at its own granularity. Querying
when_dt:2024-06 matches every instant in June; the range
[2024-01 TO 2024-06] covers January through June, endpoints included.
ISO fractions retain up to nine digits during parsing and date math; further
digits are truncated. Storage truncates to field precision, always toward
earlier time. For example, on a default millisecond field,
1969-12-31T23:59:59.9999999999Z stores as epoch millisecond -1 and finds
that value when used as a query literal.
Request flags and literal units
Section titled “Request flags and literal units”The request and each operation wrapper accept a flags array with one date
mode. Subops inherit it unless they name a replacement:
| Name | Numeric date literal unit | Date output |
|---|---|---|
date_native (default) |
Each field’s own unit. | Numeric, in each field’s unit. |
date_iso |
Each field’s own unit. | ISO-8601 strings in UTC. |
date_ms |
Milliseconds for every date field. | Numeric milliseconds. |
date_ns |
Nanoseconds for every date field. | Numeric nanoseconds. |
These units apply to that operation’s query literals in every query dialect,
its domain queries/filters, and facet start/end/gap/origin/selected values.
For example, date_ms makes stamp:2 mean epoch millisecond 2 on an ns field.
Match and range literals cover the input tick; any_of members still denote
one instant, floored to storage precision. ISO-8601 text is always accepted
and keeps its textual precision. Ingest is unaffected.
Numeric constants in value expressions and aggregate expressions always use the date operand’s native unit. The output mode applies to retrieved fields in every document format, sort values, facet bucket IDs and bounds, group keys and ranks, and DATE expression and aggregate results. Each operation uses its own effective mode. Sorting, grouping and bucket identities always use native values.
ISO output uses three fraction digits for ms fields, and the fewest of three,
six or nine digits that is exact for ns fields, including .000 on a whole
second. Both JSON and gRPC receive string values. date_ms floors integer ns
values toward earlier time. date_ns rejects an ms date outside the ns range
with a request error naming its field. Integral date output can be sent back
as a numeric literal under the same mode.
Nanosecond timestamps commonly exceed JavaScript’s safe integer range. Set
request-level "flags": ["date_ns", "int64_str"] (or use date_native) to
quote JSON int64/uint64 values outside +/- (2^53 - 1); smaller integers stay
numbers. Clients must accept either a number or a string for a 64-bit value.
This affects every integer in the search response, and leaves binary gRPC
values unchanged. See request flags.
Date averages and percentiles remain doubles: numeric modes scale the double
without rounding, while ISO output floors to the source field’s tick before
formatting. In numeric modes these are statistics, not instants, and are not
promised to be valid date literals. Non-finite or out-of-range DATE results
under date_iso are request errors. Lossy date_ms output can give sub-ms range buckets duplicate bounds;
those displayed IDs cannot identify a bucket for selection. See
date histograms.
Naming date_native restores field-native literals and numeric output under
an overridden parent. [] inherits unchanged. Duplicate or conflicting names are errors.
See JSON request flags or
protobuf flag words.
Value expressions and aggregates
Section titled “Value expressions and aggregates”Date values retain their field unit through def, min, max, avg, and
percentile. Numeric offsets and def fallbacks use that unit; subtracting
two dates returns a numeric duration in their common unit. Combining ms and
ns dates converts the ms operand to ns, and any DATE result uses ns.
Conversion uses multiplication’s existing overflow rules: per-document int64
overflow is an evaluation error, while aggregate expressions use wider intermediates.
sum rejects dates;
multiplication and division explicitly turn dates into numbers. Date averages
and percentiles keep their double numeric lane, including fractional ticks.
The calendar parts of a date (year(d), month(d), day_of_week(d),
hour(d, offset_minutes), and the others) are value-expression functions; see
Value expressions. They work in UTC or at a
fixed offset; use a date histogram for calendar buckets in a named zone.
Date math
Section titled “Date math”Anywhere a date is accepted in a query, date math is too. Both Solr and
Elasticsearch/OpenSearch syntaxes work without configuration. An expression
is an anchor (NOW / now, or any literal above) followed by add, subtract,
and round commands, evaluated left to right:
| Solr | Elasticsearch/OpenSearch | Meaning in Luxir |
|---|---|---|
NOW-30DAYS |
now-30d |
Thirty days ago. |
NOW/DAY |
now/d |
Today, as a whole-day window. |
NOW-1MONTH/MONTH |
now-1M/M |
All of last month. |
2024-06-25T00:00:00Z+6MONTHS |
2024-06-25T00:00:00Z||+6M |
Six months after the given date. |
Solr syntax appends word units directly to the anchor (DAYS, MONTHS,
case-insensitive; WEEKS is a Luxir extension). Elasticsearch/OpenSearch
syntax uses one-letter units (d, M, case-sensitive: M is month, m is
minute), with || separating a literal date from its math. Math after now
needs no separator. NOW and now use one clock snapshot for the whole
request, so every clause in a request sees the same instant.
Rounding produces a window, and a range endpoint uses the appropriate edge
of it: when_dt:>=NOW/DAY means “from the start of today” and
when_dt:<=NOW/DAY means “through the end of today”.
Round relative ranges that repeat, such as dashboard filters. now-1h moves
with every request millisecond, so a range with an unrounded NOW bound is
never cached: it is evaluated in full on every request. now-1h/m to now/m
is the same filter for a whole minute, so repeated requests reuse the cached
result. Pick the coarsest unit the use case tolerates; the rounded range can
include up to one unit more at each end than the unrounded one.
Time zones
Section titled “Time zones”By default everything above is UTC. Set time_zone on a search request to
use another time zone for dates and date math:
{"time_zone": "America/Denver", "query": {"range": {"field": "when_dt", "gte": "NOW/DAY"}}}(time_zone is a request-level setting: it sits beside the query, not inside
it, and applies to every date in the request.)
The zone can be an IANA name (case-sensitive) or a fixed offset such as
+05:30. It changes three things:
- Offset-less literals become local civil times:
2024-06-25is the Denver day, not the UTC day. - Rounding is local:
NOW/DAYstarts at Denver midnight. DAYand larger units add calendar time: across a daylight-saving change,+1DAYlands at the same local clock time even when that is 23 or 25 physical hours away. Hours and smaller stay fixed physical durations.
NOW, numeric epoch values, and literals with Z or an explicit offset are
instants; the zone does not move them, only math applied to them.
Around a daylight-saving change, local times that do not exist are shifted
forward by the gap, and repeated local times take the earlier occurrence. In
the rare case where a zone change skips an entire calendar date, the request
still succeeds and returns a date_granule_skipped warning naming the date.
Ingest is always UTC. A document ingested with "when_dt": "2024-06-25"
is anchored at UTC midnight even if later queries use a zone. When the same
text must mean the same instant on both paths, write it with Z or an
explicit offset.
Date histograms
Section titled “Date histograms”Range facets bucket DATE fields with either a fixed gap in field units or a
calendar gap in the facet’s zone. Set "bounds": "data" to derive the span
from matching values; each nested instance has its own extent. Explicit
start and end instead set a fixed span:
{ "time_zone": "America/Denver", "query": { "range": { "field": "when_dt", "gte": "NOW/DAY-7DAYS" } }, "ops": { "per_day": { "range_facet": { "field": "when_dt", "start": "NOW/DAY-7DAYS", "end": "NOW/DAY+1DAY", "calendar_gap": { "n": 1, "unit": "day" } } } }}Buckets are returned in order, zero counts included, with [start, end)
pairs in the field’s unit as bucket ids. Nanosecond fields support one-ns
fixed gaps, including negative epoch values; DATA and EXPLICIT use the same
grid. An ns bucket’s exclusive end may be INT64_MAX. Calendar buckets follow
the civil calendar: months vary in length, and a daylight-saving day is 23 or 25 hours
wide. Fixed gaps also step in local time when a zone is set: repeated lattice
times have both occurrences as fences, and skipped lattice times map to the
transition instant. With EXPLICIT bounds, the phase comes from the local time
of start. A facet may set its own time_zone; leaving it empty inherits the
request’s. See range facets for DATA widening,
origin, calendar alignment, DST behavior and limits.