Using time, datetime, and duration property types

The time, datetime, and duration property types let you identify date and time-related values as such so that the MDEX Engine handles those values appropriately.

For example, it is not meaningful to add the contents of two String properties (that is, Alpha properties), and a query that attempts this operation causes an error. Similarly, date and time-related operations, such as extracting the year out of a date property, are limited to date/time types.

To support dates and times, the Presentation API uses the Property class to represent key-value pairs, where the value is a String that represents a date, datetime, or duration. The front-end Web application may display this value without interpreting it, or it can use libraries to convert the value into a pretty-printed string that is appropriate for human consumption. In other words, the application may convert the String into a java.util.Date object (for Java) or DateTime object (for .NET), which can then be formatted using the standard Java and .NET calendar utilities, respectively.

The String value associated with a time, datetime, or duration contains an integer number. The specification for this number is as follows:

Time: 32-bit unsigned integer representing the time as the number of milliseconds relative to the start of the day (midnight/12:00:00am).

For example, “1:00PM” or “13:00” is represented as “46800000” because:

13 hours *

60 minutes / hour *

60 seconds / minute *

1000 milliseconds / second =

46800000 milliseconds

Datetime: 64-bit signed integer representing the date and time as the number of milliseconds since January 1, 1970, 12:00:00 GMT (the UNIX epoch).

For example, “August 26, 2004 1:00PM” is represented as “1093525200000” because:

12656 days *

24 hours / day *

60 minutes / hour *

60 seconds / minute *

1000 milliseconds / second +

46800000 milliseconds (13 hrs) =

1093525200000 milliseconds

Duration: 64-bit signed integer representing the amount of time measured in milliseconds relative to an unspecified point in time.

For example,“100 days” is represented as “8640000000” because:

100days *

24 hours / day *

60 minutes / hour *

60 seconds / minute *

1000 milliseconds / second =

8640000000 milliseconds

Endeca distinguishes time, which represents time, from datetime, which represents a date and time, because it allows us to reduce the memory and storage footprint of applications that include only times. It also allows applications to explicitly detach a time from a specific date.

The duration type holds relative datetime values. This type provides application developers the ability to store values like “2 minutes” or “3 years.” In other words, values that should not be interpreted as absolute dates or times.

Loading date and time data

The MDEX Engine assumes that date/time data that is being loaded has the following characteristics:

All values are in milliseconds, as described above.
All values are provided in coordinated universal time, also known as UTC (UTC was
formerly known as Greenwich mean time, or GMT).

If your date/time data does not conform to these requirements, you must pre-process it before loading, or manipulate it in your pipeline, so that it does.

Note: Endeca follows the POSIX standards.

Using the .NET framework's DateTime structure

The .NET framework uses the DateTime structure to represent an instant in time. In the DateTime structure, time values are measured in 100-nanosecond units called ticks. To load data created with the DateTime structure into the MDEX Engine, you must convert from ticks to nanoseconds, and then from nanoseconds to milliseconds. Conversely, to work with data returned from the MDEX Engine using the DateTime structure, you must convert it from milliseconds to nanoseconds, and then from nanoseconds to ticks.

The conversions work as follows:

1 second = 1,000 milliseconds

1 second = 1,000,000,000 nanoseconds

1,000 milliseconds = 1,000,000,000 nanoseconds

1 millisecond = 1,000,000 nanoseconds

1,000,000 nanoseconds * (1 tick / 100 nanoseconds) = 10,000 ticks

10,000 ticks = 1 millisecond

Working with time zones

Although the MDEX Engine will not interpret time zones directly, it is the query writer’s option to add or subtract another duration, possibly stored in another field on the record, from the record’s datetime value to account for different time zones.