Skip to content

Commit

Permalink
Add documentation
Browse files Browse the repository at this point in the history 
Signed-off-by: currantw <taylor.curran@improving.com>
  • Loading branch information
@currantw
currantw committed Jan 9, 2025
1 parent 68ec760 commit a117ba2
Show file tree
Hide file tree
Showing 4 changed files with 224 additions and 6 deletions.
83 changes: 83 additions & 0 deletions docs/ppl-lang/functions/ppl-datetime.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -733,6 +733,89 @@ Example:
| 3 |
+-------------------------------+

### `RELATIVE_TIMESTAMP`

**Description:**


**Usage:** relative_timestamp(str) returns a timestamp corresponding to the give relative string and the current
timestamp at the time of query execution.

The relative time string has syntax `[+|-]<offset_time_integer><offset_time_unit>@<snap_time_unit>`, and is made up of
two optional components:
* An offset from the current timestamp at the start of query execution, which is composed of a sign (`+` or `-`), an
optional time integer, and a time unit. If the time integer is not specified, it defaults to one. For example, `+2hr`
corresponds to two hours after the current timestamp, while `-mon` corresponds to one month ago.
* A snap-to time using the `@` symbol followed by a time unit. The snap-to time is applied after the offset (if
specified), and rounds the time <i>down</i> to the start of the specified time unit (i.e. backwards in time). For
example, `@wk` corresponds to the start of the current week (Sunday is considered to be the first day of the week).

The following offset time units are supported:

| Time Unit | Supported Keywords |
|-----------|-------------------------------------------|
| Seconds | `s`, `sec`, `secs`, `second`, `seconds` |
| Minutes | `m`, `min`, `mins`, `minute`, `minutes` |
| Hours | `h`, `hr`, `hrs`, `hour`, `hours` |
| Days | `d`, `day`, `days` |
| Weeks | `w`, `wk`, `wks`, `week`, `weeks` |
| Quarters | `q`, `qtr`, `qtrs`, `quarter`, `quarters` |
| Years | `y`, `yr`, `yrs`, `year`, `years` |

The snap-to time supports all the time units above, as well as the following day of the week time units:

| Time Unit | Supported Keywords |
|-----------|--------------------|
| Sunday | `w0`, `w7` |
| Monday | `w1` |
| Tuesday | `w2` |
| Wednesday | `w3` |
| Thursday | `w4` |
| Friday | `w5` |
| Saturday | `w6` |

The special relative time string `now` for the current timestamp is also supported.

For example, if the current timestamp is Monday, January 03, 2000 at 01:01:01 am:

| Relative String | Description | Resulting Relative Time |
|-----------------|--------------------------------------------------------------|---------------------------------------------|
| `-60m` | Sixty minutes ago | Monday, January 03, 2000 at 00:01:01 am |
| `-1h` | One hour ago | Monday, January 03, 2000 at 00:01:01 am |
| `+2wk` | Two weeks from now | Monday, January 17, 2000 at 00:01:01 am |
| `-1h@w3` | One hour ago, rounded to the start of the previous Wednesday | Wednesday, December 29, 1999 at 00:00:00 am |
| `@d` | Start of the current day | Monday, January 03, 2000 at 00:00:00 am |
| `now` | Now | Monday, January 03, 2000 at 01:01:01 am |

Argument type: STRING

Return type: TIMESTAMP

Example:

os> source=people | eval seconds_diff = timestampdiff(SECOND, now(), relative_timestamp("now")) | fields seconds_diff | head 1
fetched rows / total rows = 1/1
+--------------+
| seconds_diff |
|--------------+
| 0 |
+--------------+

os> source=people | eval hours_diff = timestampdiff(HOUR, now(), relative_timestamp("+1h")) | fields hours_diff | head 1
fetched rows / total rows = 1/1
+------------+
| hours_diff |
|------------+
| 1 |
+------------+

os> source=people | eval day = day_of_week(relative_timestamp("@w0")) | fields day | head 1
fetched rows / total rows = 1/1
+-----+
| day |
|-----|
| 1 |
+-----+

### `SECOND`

Expand Down
139 changes: 137 additions & 2 deletions ppl-spark-integration/src/main/java/org/opensearch/sql/expression/function/TimeUtils.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ public class TimeUtils {
private static final String SNAP_PATTERN_STRING = "[@](?<snapUnit>\\w+)";

private static final Pattern RELATIVE_PATTERN = Pattern.compile(String.format(
"(?<offset>%s)?(?<snap>%s)?", OFFSET_PATTERN_STRING, SNAP_PATTERN_STRING),
"(?<offset>%s)?(?<snap>%s)?", OFFSET_PATTERN_STRING, SNAP_PATTERN_STRING),
Pattern.CASE_INSENSITIVE);

// Supported time units.
Expand Down Expand Up @@ -116,7 +116,142 @@ public class TimeUtils {

/**
* Returns the {@link LocalDateTime} corresponding to the given relative string and local date time.
* Throws {@link RuntimeException} if the relative string is not supported.
* <p>
* The relative time string has syntax {@code [+|-]<offset_time_integer><offset_time_unit>@<snap_time_unit>}, and
* is made up of two optional components:
* <ul>
* <li>
* An offset from the current timestamp at the start of query execution, which is composed of a sign
* ({@code +} or {@code -}), an optional time integer, and a time unit. If the time integer is not specified,
* it defaults to one. For example, {@code +2hr} corresponds to two hours after the current timestamp, while
* {@code -mon} corresponds to one month ago.
* </li>
* <li>
* A snap-to time using the {@code @} symbol followed by a time unit. The snap-to time is applied after the
* offset (if specified), and rounds the time <i>down</i> to the start of the specified time unit (i.e.
* backwards in time). For example, {@code @wk} corresponds to the start of the current week (Sunday is
* considered to be the first day of the week).
* </li>
* </ul>
* <p>
* The following offset time units are supported:
* <table border="1">
* <body>
* <tr>
* <th>Time Unit</th>
* <th>Supported Keywords</th>
* </tr>
* <tr>
* <td>Seconds</td>
* <td>{@code s}, {@code sec}, {@code secs}, {@code second}, {@code seconds}</td>
* </tr>
* <tr>
* <td>Minutes</td>
* <td>{@code m}, {@code min}, {@code mins}, {@code minute}, {@code minutes}</td>
* </tr>
* <tr>
* <td>Hours</td>
* <td>{@code h}, {@code hr}, {@code hrs}, {@code hour}, {@code hours}</td>
* </tr>
* <tr>
* <td>Days</td>
* <td>{@code d}, {@code day}, {@code days}</td>
* </tr>
* <tr>
* <td>Weeks</td>
* <td>{@code w}, {@code wk}, {@code wks}, {@code week}, {@code weeks}</td>
* </tr>
* <tr>
* <td>Quarters</td>
* <td>{@code q}, {@code qtr}, {@code qtrs}, {@code quarter}, {@code quarters}</td>
* </tr>
* <tr>
* <td>Years</td>
* <td>{@code y}, {@code yr}, {@code yrs}, {@code year}, {@code years}</td>
* </tr>
* </body>
* </table>
* <p>
* The snap-to time supports all the time units above, as well as the following day of the week time units:
* <table border="1">
* <body>
* <tr>
* <th>Time Unit</th>
* <th>Supported Keywords</th>
* </tr>
* <tr>
* <td>Sunday</td>
* <td>{@code w0}, {@code w7}</td>
* </tr>
* <tr>
* <td>Monday</td>
* <td>{@code w1}</td>
* </tr>
* <tr>
* <td>Tuesday</td>
* <td>{@code w2}</td>
* </tr>
* <tr>
* <td>Wednesday</td>
* <td>{@code w3}</td>
* </tr>
* <tr>
* <td>Thursday</td>
* <td>{@code w4}</td>
* </tr>
* <tr>
* <td>Friday</td>
* <td>{@code w5}</td>
* </tr>
* <tr>
* <td>Saturday</td>
* <td>{@code w6}</td>
* </tr>
* </body>
* </table>
* <p>
* The special relative time string {@code now} for the current timestamp is also supported.
* <p>
* For example, if the current timestamp is Monday, January 03, 2000 at 01:01:01 am:
* <table border="1">
* <body>
* <tr>
* <th>Relative String</th>
* <th>Description</th>
* <th>Resulting Relative Time</th>
* </tr>
* <tr>
* <td>{@code -60m}</td>
* <td>Sixty minutes ago</td>
* <td>Monday, January 03, 2000 at 00:01:01 am</td>
* </tr>
* <tr>
* <td>{@code -h}</td>
* <td>One hour ago</td>
* <td>Monday, January 03, 2000 at 00:01:01 am</td>
* </tr>
* <tr>
* <td>{@code +2wk}</td>
* <td>Two weeks from now</td>
* <td>Monday, January 17, 2000 at 00:01:01 am</td>
* </tr>
* <tr>
* <td>{@code -1h@w3}</td>
* <td>One hour ago, rounded to the start of the previous Wednesday</td>
* <td>Wednesday, December 29, 1999 at 00:00:00 am</td>
* </tr>
* <tr>
* <td>{@code @d}</td>
* <td>Start of the current day</td>
* <td>Monday, January 03, 2000 at 00:00:00 am</td>
* </tr>
* <tr>
* <td>{@code now}</td>
* <td>Now</td>
* <td>Monday, January 03, 2000 at 01:01:01 am</td>
* </tr>
* </body>
* </table>
*/
public static LocalDateTime getRelativeLocalDateTime(String relativeString, LocalDateTime localDateTime) {

Expand Down
4 changes: 2 additions & 2 deletions ...gration/src/test/java/org/opensearch/sql/expression/function/SerializableTimeUdfTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,12 @@ public void relativeTimestampTest() {
For more comprehensive tests, see {@link TimeUtilsTest}.
*/

testValid("now", "2000-01-03 01:01:01.100");
testValid("-60m", "2000-01-03 00:01:01.100");
testValid("-h", "2000-01-03 00:01:01.100");
testValid("+2wk", "2000-01-17 01:01:01.100");
testValid("-1h@h", "2000-01-03 00:00:00");
testValid("-1h@w3", "1999-12-29 00:00:00");
testValid("@d", "2000-01-03 00:00:00");
testValid("now", "2000-01-03 01:01:01.100");

testInvalid("invalid", "The relative date time 'invalid' is not supported.");
testInvalid("INVALID", "The relative date time 'INVALID' is not supported.");
Expand Down
4 changes: 2 additions & 2 deletions ...spark-integration/src/test/java/org/opensearch/sql/expression/function/TimeUtilsTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,12 @@ public class TimeUtilsTest {

@Test
public void testRelative() {
testValid("now", "2000-01-03T01:01:01.100");
testValid("-60m", "2000-01-03T00:01:01.100");
testValid("-h", "2000-01-03T00:01:01.100");
testValid("+2wk", "2000-01-17T01:01:01.100");
testValid("-1h@h", "2000-01-03T00:00");
testValid("-1h@w3", "1999-12-29T00:00:00");
testValid("@d", "2000-01-03T00:00");
testValid("now", "2000-01-03T01:01:01.100");

testInvalid("invalid", "The relative date time 'invalid' is not supported.");
}
Expand Down

0 comments on commit a117ba2

Please sign in to comment.