Time Functions Extensions¶
What’s in this document?
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 20190324T22:12:29.183+02:00"  "20190419T02: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 monthsfromduration
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 


Return the “years” part of the duration literal 
0 

Returns the “months” part of the duration literal 
0 

Returns the “days” part of the duration literal 
25 

Returns the “hours” part of the duration literal 
4 

Returns the “minutes” part of the duration literal 
29 

Returns the “seconds” part of the duration literal 
58 

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:millisfromduration("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 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 


Returns the duration of the period as weeks 
3 

Returns the duration of the period as days 
25 

Returns the duration of the period as hours 
604 

Returns the duration of the period as minutes 
36269 

Returns the duration of the period as seconds 
2176198 

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: "20190324T22:12:29.183+02:00"  "20190419T02: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 illdefined.
The following table describes the functions that are implemented and gives example results, assuming the date literals 20190324T22:12:29.183+02:00"
and "20190419T02:42:28.182+02:00"
are passed to them. Note that the return values are positive:
Function 
Description 
Expected return value 


Returns the duration between the two dates as weeks 
3 

Returns the duration between the two dates as days 
25 

Returns the duration between the two dates as hours 
604 

Returns the duration between the two dates as minutes 
36269 

Returns the duration between the two dates as seconds 
2176198 

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("20190324T22:12:29.183+02:00"^^xsd:dateTime, "20190419T02: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 done via the SPARQL operator extensibility.