Timezone information and MarkLogic

Summary

This article discusses the effect of the implicit timezone on date/time values as indexed and retrieved.

Discussion

Timezone information and indexes

Values are stored in the index effectively in UTC, without any timezone information. When indexed, the value is adjusted to UTC from either the explicit timezone of the data or implicitly from the host timezone, and then the timezone is forgotten. The index data does not save information regarding the source timezone.

When queried, values from the index are adjusted to the timezone specified in the query, or to the host's implicit timezone if none is specified.

Therefore, dates and times in the implicit timezone do what would be expected in calculations, unless you have a particular reason for actually knowing the offset from UTC.

Implicit timezone

The definition of an implicit timezone is given at https://www.w3.org/TR/xpath20/#dt-timezone.

The MarkLogic host implicit timezone comes into play when the document is indexed and when values are returned from the indexes.

fn:implicit-timezone() can be used to show the implicit timezone for a host.

Changing implicit timezone

If you change the implicit timezone without reindexing, the implicit timezone at indexing time was different than the implicit timezone at query time, so values indexed with the implicit timezone are "wrong" in that they were indexed with a different implicit timezone.

If you specify a timezone for the data when it is indexed and when it is queried, the implicit timezone will not be a factor.

Examples

First we create an dateTime element range index on element <dt>, then insert a document without timezone information:

xdmp:document-insert ('/test.xml', <doc><dt>2018-01-01T12:00:00</dt></doc>)

Using a server located in New York (timezone now -05:00), retrieving the value from the index via

cts:element-values (xs:QName ('dt'), ())

gives

2018-01-01T12:00:00

showing that the implicit timezone works as described above. To see the value stored in the index (as adjusted to UTC) you can specify the timezone on the value retrieved:

cts:element-values (xs:QName ('dt'), (), 'timezone=+00:00')

returns

2018-01-01T17:00:00Z

so 2018-01-01T17:00:00 is the value coming from the index.

When the implicit timezone is -5 hours then the call without a timezone returns 12:00. However, if the implicit timezone changed, then the value returned for the query without a timezone would also change, even though the value stored in the index has not changed.