# Time Functions Extensions¶

Beside the standard SPARQL functions related to time, GraphDB offers several additional functions, allowing users to do more with their time data. Those are implemented within the same namespace as standard math functions, <http://www.ontotext.com/sparql/functions/>. The default prefix for the functions is ofn.

## Period extraction functions¶

The first group of functions is related to accessing particular parts of standard duration literals. For example, the expression 2019-03-24T22:12:29.183+02:00" - "2019-04-19T02:42:28.182+02:00" will produce the following duration literal: -P0Y0M25DT4H29M58.999S. It is possible to parse the result and obtain the proper parts of it - for example, “25 days”, “4” hours or more discrete time units. However, instead of having to do this manually, GraphDB offers functions that perform the computations at the engine level. The functions take a period as input and output xsd:long.

Note

The functions described here perform simple extractions, rather than computing the periods. For example, if you have 40 days in the duration literal, but no months, i.e., P0Y0M40DT4H29M58.999S, a months-from-duration extraction will not return 1 months.

The following table describes the functions that are implemented and gives example results, assuming the literal -P0Y0M25DT4H29M58.999S is passed to them:

Function

Description

Expected return value

ofn:years-from-duration

Return the “years” part of the duration literal.

0

ofn:months-from-duration

Returns the “months” part of the duration literal.

0

ofn:days-from-duration

Returns the “days” part of the duration literal.

25

ofn:hours-from-duration

Returns the “hours” part of the duration literal.

4

ofn:minutes-from-duration

Returns the “minutes” part of the duration literal.

29

ofn:seconds-from-duration

Returns the “seconds” part of the duration literal.

58

ofn:millis-from-duration

Returns the “milliseconds” part of the duration literal.

999

An example query using a function from this group would be:

PREFIX xsd:<http://www.w3.org/2001/XMLSchema#>
PREFIX ofn:<http://www.ontotext.com/sparql/functions/>
SELECT ?result {
bind (ofn:millis-from-duration("-P0Y0M25DT4H29M58.999S"^^xsd:dayTimeDuration) as ?result)
}


## Period transformation functions¶

The second group of functions is related to transforming a standard duration literal. This reduces the need for performing mathematical transformations on the input date. The functions take a period as input and output xsd:long.

Note

The transformation is performed with no fractional components. For example, if transformed, the duration literal we’ve used previously, -P0Y0M25DT4H29M58.999S will yield 25 days, rather than 25.19 days.

The following table describes the functions that are implemented and gives example results, assuming the literal -P0Y0M25DT4H29M58.999S is passed to them. Note that the return values are negative since the period is negative:

Function

Description

Expected return value

ofn:asWeeks

Returns the duration of the period as weeks.

-3

ofn:asDays

Returns the duration of the period as days.

-25

ofn:asHours

Returns the duration of the period as hours.

-604

ofn:asMinutes

Returns the duration of the period as minutes.

-36269

ofn:asSeconds

Returns the duration of the period as seconds.

-2176198

ofn:asMillis

Returns the duration of the period as milliseconds.

-2176198999

An example query using a function from this group would be:

PREFIX xsd:<http://www.w3.org/2001/XMLSchema#>
PREFIX ofn:<http://www.ontotext.com/sparql/functions/>
SELECT ?result {
bind (ofn:asMillis("-P0Y0M25DT4H29M58.999S"^^xsd:dayTimeDuration) as ?result)
}


## Durations Expressed in Certain Units¶

The third group of functions eliminates the need for computing a difference between two dates when a transformation will be necessary, essentially combining the mathematical operation of subtracting two dates with a transformation. It is more efficient than performing an explicit mathematical operation between two date literals, for example: "2019-03-24T22:12:29.183+02:00" - "2019-04-19T02:42:28.182+02:00" and then using a transformation function. The functions take two dates as input and output integer literals.

Note

Regular SPARQL subtraction can return negative values, as evidenced by the negative duration literal used in the example. However, comparisons are only positive. So, comparison isn’t an exact match for a subtraction followed by transformation. If one of the timestamps has timezone but the other does not, the result is ill-defined.

The following table describes the functions that are implemented and gives example results, assuming the date literals 2019-03-24T22:12:29.183+02:00" and "2019-04-19T02:42:28.182+02:00" are passed to them. Note that the return values are positive:

Function

Description

Expected return value

ofn:weeksBetween

Returns the duration between the two dates as weeks.

3

ofn:daysBetween

Returns the duration between the two dates as days.

25

ofn:hoursBetween

Returns the duration between the two dates as hours.

604

ofn:minutesBetween

Returns the duration between the two dates as minutes.

36269

ofn:secondsBetween

Returns the duration between the two dates as seconds.

2176198

ofn:millisBetween

Returns the duration between the two dates as milliseconds.

2176198999

An example query using a function from this group would be:

PREFIX xsd:<http://www.w3.org/2001/XMLSchema#>
PREFIX ofn:<http://www.ontotext.com/sparql/functions/>
SELECT ?result {
bind (ofn:millisBetween("2019-03-24T22:12:29.183+02:00"^^xsd:dateTime, "2019-04-19T02:42:28.182+02:00"^^xsd:dateTime) as ?result)
}


## Arithmetic operations¶

The fourth group of functions includes operations such as: adding duration to a date; adding dayTimeDuration to a dateTime; adding time duration to a time; comparing durations. This is a SPARQL extension, more details about which are available at https://www.w3.org/TR/sparql11-query/#operatorExtensibility).