MarkLogic 10 Product Documentation

Temporal Developer's Guide — Chapter 1

Terms

To understand the temporal functions, you need to understand the meaning of the following terms:

• Temporal Collection: A collection created to contain either bi-temporal or uni-temporal documents.
• Axis: a named pair of range indexes that is the container for periods. Bi-temporal documents have both a valid and system axis. Uni-temporal documents have only a system axes.
• Bi-temporal: a collection of documents with both a system time and a valid time axes.
• Uni-temporal: a collection of documents with only a system axes.
• Instant: an instant of time (such as "now", "12/31/2012, 01:00:00 am").
• Period: an anchored duration of time (e.g. December 01, 1999 through December 31, 2000, the fall semester).
• User-defined Time: a time value that user provides in replacement of system start time.
• LSQT (Last Stable Query Time): a document with a system start time before this point can be queried and a document with a system start time after this point can be updated and ingested.
• A split refers to the creation of a new document that contains the same content as a previous document, but with different valid timestamps and system end time.
• Wipe is to delete all versions of a temporal document.
• Protect is to prevent certain operations (such as temporal update) from being applied to a temporal document. The definition of such prevention is a protection rule, or protection.
• Metadata refers to a quick and efficient mechanism to capture metadata information of a document represented as string key and string value pairs outside of the document's root node. In the context of temporal document management, metadata is used to store valid and system timestamps and archival information. Metadata of a document is stored in all fragments of the document.
• WORM refers to Write Once Read Many. A data storage feature in which, once data is written to the storage device, it can be read but cannot be modified.

  Document quality and permissions travel with the split. Document properties do not travel with the split.

Overview of Temporal Documents

Bi-temporal data tracks information along two different time lines:

• Valid Time: when the information was true in the real world. Valid time may also be called application time. Valid time is provided by the user or application. The valid end time is updated by the system when the document is split.
• System Time: when the information was stored in the database. System time may also be called transaction time. System time is managed by the system, except in cases when the system start time is set by the application as described in Last Stable Query Time (LSQT) and Application-controlled System Time.

MarkLogic also supports uni-temporal documents that have only a system time. Uni-temporal documents are managed in MarkLogic in the same manner as bi-temporal documents.

In MarkLogic, a temporal document is managed as a series of versioned documents in a protected collection. The 'original' document inserted into the database is kept and never changes. Updates to the document are inserted as new documents with different valid and system times. A delete of the document is also inserted as a new document. In this way, a temporal document can be rolled back to review, at any point in time, when the information was known in the real world and when it was recorded in the database.

Roles and Permissions

The temporal-admin or admin role is required to create axes, temporal collections, and otherwise configure the temporal environment.

Changing permissions on a temporal document only affects the latest version of the document that is created as a result of the change. All previous versions of the document maintain their original permissions.

Temporal, URI, and Latest Collections

Bi-temporality and uni-temporality is defined on a protected collection, known as a temporal collection. A temporal collection is a logical grouping of temporal documents that share the same axes with timestamps defined by the same range indices. You can create additional temporal collections if you have documents that require a different schema for the timestamps. A temporal collection can be created for either bi-temporal documents (documents with both system and valid times) or uni-temporal documents (documents with only system times).

When a document is inserted into a temporal collection, a URI collection is created for that document. When the document is updated, a new document representing the update is inserted into the document's URI collection. Any new document inserted into the temporal collection will have its own unique URI collection that will hold all of the versions of that document.

Additionally, the latest version of each document will reside in a latest collection.

The following illustrates how three temporal documents would be organized into the temporal, URI, and latest collections:

When a temporal document is deleted, it is removed from the latest collection.

WORM (Write Once Read Many) Support

You can set an archive date on temporal documents at which time they can be moved to a WORM (Write Once Read Many) device. Once a temporal document is written to a WORM device, it cannot be modified or deleted. This write protection ensures that the data cannot be tampered with once it is written to the device until a pre-determined expiration date.

For details on archiving temporal documents, see Protecting and Archiving Temporal Documents.