# 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 `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.