Loading TOC...
Temporal Developer's Guide (PDF)

Temporal Developer's Guide — Chapter 4

Searching Temporal Documents

This chapter describes the temporal search features, and includes the following sections:

Temporal Search Query Constructors

The following table summarizes the available functions used to construct cts:query expressions for searching temporal documents. For general details on constructing cts:query expressions, see Composing cts:query Expressions in the Search Developer's Guide.

Function (XQuery and JavaScript) Description

cts:period-compare-query

cts.periodCompareQuery

Returns a cts:query matching documents that have relevant pair of period values.

cts:period-compare-query-operator

cts.periodRangeQueryOperator

Returns the operator used to construct the specified query.

cts:period-compare-query-options

cts.periodCompareQueryOptions

Returns the options for the specified query.

cts:period-compare-query-axis-1

cts.periodCompareQueryAxis1

Returns the name of the first axis used to construct the specified query.

cts:period-compare-query-axis-2

cts.periodCompareQueryAxis2

Returns the name of the second axis used to construct the specified query.

cts:period-range-query

cts.periodRangeQuery

Returns a cts:query matching period by name with a period value with an operator.

cts:period-range-query-operator

cts.periodRangeQueryOperator

Returns the operator used to construct the specified query.

cts:period-range-query-options

cts.periodRangeQueryOptions

Returns the options for the specified query.

cts:lsqt-query

cts.lsqtQuery

Returns only documents before LSQT or a timestamp before LSQT for stable query results.

cts:lsqt-query-options

cts.lsqtQueryOptions

Returns the options for the specified query.

cts:lsqt-query-temporal-collection

cts.lsqtQueryTemporalCollection

Returns the name of the temporal collection used to construct specified query.

cts:lsqt-query-timestamp

cts.lsqtQueryTimestamp

Returns timestamp used to construct the specified query.

cts:lsqt-query-weight

cts.lsqtQueryWeight

Returns the weight with which the specified query was constructed.

Period Comparison Operators

This section describes the Allen and ISO SQL algebra operators that can be used in search queries. Temporal queries are basically some interval operations on time period such as, period equalities, containment and overlaps. MarkLogic Server supports both Allen and SQL operators when comparing time periods. Allen's interval algebra provides the most comprehensive set of these operations. SQL 2011 also provides similar operators. However all the SQL operators can be expressed using Allen's Algebra.

Allen Operators

In general, Allen operators, which are identified with an ALN_ prefix, are more restrictive than ISO SQL operators, which are identified with an ISO_ prefix. The illustration below shows the relationships between the X and Y periods for each operator as used in the following period queries:

cts:period-range-query(X, operator, Y)

where X is an axis and Y is a period.

cts:period-compare-query(X, operator, Y)

where X and Y are both axes.

cts:period-compare(X, operator, Y)

where X and Y are both periods.

ISO SQL 2011 Operators

Similar to Allen operators, SQL 2011 operators can also be mapped MarkLogic range index operations. The following illustrations show the mapping from ISO SQL operators to a composition of Allen Operators.

Note that the ALN operators described in Allen Operators each have only one X/Y period relationship, whereas some of the less restrictive ISO SQL operators have multiple X/Y period relationships. Such ISO SQL operators have the effect of multiple Allen operators, as shown below.

Comparing Two Periods

The range query on periods can be used only when there are range indexes for them on the database. However you may need to query based either on some external period values or those from a document. The following example shows how you can use the cts:period-compare function to determine whether two period values satisfy the conditions imposed by the comparison operator, ALN_MEETS. If the ALN_MEETS conditions are satisfied, then true is returned; otherwise false is returned.

JavaScript Example:

var period1 = cts.period(xs.dateTime("2000-05-31T09:30:10"),
                         xs.dateTime("2003-05-31T12:30:00"));
var period2 = cts.period(xs.dateTime("2003-05-31T12:30:00"), 
                         xs.dateTime("2004-05-31T14:30:00"));
cts.periodCompare(period1, "ALN_MEETS", period2);

XQuery Example:

xquery version "1.0-ml";
let $period1 := cts:period(xs:dateTime("2000-05-31T09:30:10"),
                           xs:dateTime("2003-05-31T12:30:00"))
let $period2 := cts:period(xs:dateTime("2003-05-31T12:30:00"), 
                           xs:dateTime("2004-05-31T14:30:00"))
return cts:period-compare($period1,"ALN_MEETS",$period2)

Example Search Queries

This section describes some sample search queries. The searches described in this section are done on the documents described in Example: The Lifecycle of a Temporal Document.

The following query searches for the temporal documents that have a valid end time before 14:00:

JavaScript Example:

cts.search(cts.periodRangeQuery(
    "valid",
    "ALN_BEFORE",
    cts.period(xs.dateTime("2014-04-03T14:00:00"),
               xs.dateTime("9999-12-31T11:59:59Z")) ))

XQuery Example:

cts:search(fn:doc(), cts:period-range-query(
   "valid",
   "ALN_BEFORE",
   cts:period(xs:dateTime("2014-04-03T14:00:00"),
              xs:dateTime("9999-12-31T11:59:59Z")) ))

This query returns Splits 1, 2 and 3 of the document.

The following query searches the temporal documents, using the cts:and-query to AND two cts:period-range-query functions, to locate the documents that represented the order at 11:30 when queried at 11:51.

JavaScript Example:

cts.search(cts.andQuery(
      [cts.periodRangeQuery(
          "system", 
          "ISO_CONTAINS",
          cts.period(xs.dateTime("2014-04-03T11:51:00"),
                     xs.dateTime("2014-04-03T11:51:01"))),
      cts.periodRangeQuery(
          "valid", 
          "ISO_CONTAINS", 
          cts.period(xs.dateTime("2014-04-03T11:30:00"),
                     xs.dateTime("2014-04-03T11:30:01")))]))

XQuery Example:

xquery version "1.0-ml";
cts:search(fn:doc(), cts:and-query((
   cts:period-range-query(
      "system",
      "ISO_CONTAINS",
      cts:period(xs:dateTime("2014-04-03T11:51:00"),
                 xs:dateTime("2014-04-03T11:51:01"))), 
   cts:period-range-query(
      "valid",
      "ISO_CONTAINS",
      cts:period(xs:dateTime("2014-04-03T11:30:00"),
                 xs:dateTime("2014-04-03T11:30:01"))))))

This query returns Version 2 of the document.

The following query searches for the temporal documents that have a valid end time of 12:10:

JavaScript Example:

var period = cts.period(xs.dateTime("2014-04-03T12:10:00"),
                        xs.dateTime("2014-04-03T13:10:00"));
cts.search(cts.periodRangeQuery("valid", "ALN_MEETS", period))

XQuery Example:

xquery version "1.0-ml";
let $period := cts:period(xs:dateTime("2014-04-03T12:10:00"),
                          xs:dateTime("2014-04-03T13:10:00"))
return cts:search(fn:doc(), cts:period-range-query(
     "valid", "ALN_MEETS", $period))

This query returns Split 2 of the document.

« Previous chapter