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 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 done via the SPARQL operator extensibility.