Update/add documentation

Signed-off-by: currantw <taylor.curran@improving.com>

Author: currantw

docs/ppl-lang/PPL-Example-Commands.md

@@ -499,9 +499,23 @@ _- **Limitation: another command usage of (relation) subquery is in `appendcols`
 -  `source = table | eval cdate = CAST('2012-08-07' as date), ctime = cast('2012-08-07T08:07:06' as timestamp) | fields cdate, ctime`
 -  `source = table | eval chained_cast = cast(cast("true" as boolean) as integer) | fields chained_cast`
 
+### **Relative Time Functions**
+
 #### **relative_timestamp**
-[See additional function details](functions/ppl-datetime#RELATIVE_TIMESTAMP)
+[See additional function details](functions/ppl-datetime#relative_timestamp)
 - `source = table | eval one_hour_ago = relative_timestamp("-1h") | where timestamp < one_hour_ago`
 - `source = table | eval start_of_today = relative_timestamp("@d") | where timestamp > start_of_today`
 - `source = table | eval last_saturday = relative_timestamp("-1d@w6") | where timestamp >= last_saturday`
+
+#### **earliest**
+[See additional function details](functions/ppl-datetime#earliest)
+- `source = table | where earliest("-1wk", timestamp)`
+- `source = table | where earliest("@qtr", timestamp)`
+- `source = table | where earliest("-2y@q", timestamp)`
+
+#### **latest**
+[See additional function details](functions/ppl-datetime#latest)
+- `source = table | where latest("-60m", timestamp)`
+- `source = table | where latest("@year", timestamp)`
+- `source = table | where latest("-day@w1", timestamp)`
 ---

docs/ppl-lang/functions/ppl-datetime.md

@@ -397,6 +397,44 @@ Example:
     +-------------------------------+
 
 
+### `EARLIEST`
+
+**Description:**
+
+**Usage:** earliest(string, timestamp) returns whether the timestamp defined by the given relative string is earlier
+than or at the same time as the specified timestamp.
+
+Argument type: STRING, TIMESTAMP
+
+Return type: BOOLEAN
+
+Example:
+
+    os> source=people | eval earliest = earliest("-1s", now()) | fields earliest | head 1
+    fetched rows / total rows = 1/1
+    +----------+
+    | earliest |
+    |----------|
+    | True     |
+    +----------+
+
+    os> source=people | eval earliest = earliest("now", now()) | fields earliest | head 1
+    fetched rows / total rows = 1/1
+    +----------+
+    | earliest |
+    |----------|
+    | True     |
+    +----------+
+
+    os> source=people | eval earliest = earliest("+1s", now()) | fields earliest | head 1
+    fetched rows / total rows = 1/1
+    +----------+
+    | earliest |
+    |----------|
+    | False    |
+    +----------+
+
+
 ### `FROM_UNIXTIME`
 
 **Description:**
@@ -507,6 +545,44 @@ Example:
     +--------------------------+
 
 
+### `LATEST`
+
+**Description:**
+
+**Usage:** latest(string, timestamp) returns whether the timestamp defined by the given relative string is later
+than or at the same time as the specified timestamp. See [relative_timestamp](#relative_timestamp) for more details.
+
+Argument type: STRING, TIMESTAMP
+
+Return type: BOOLEAN
+
+Example:
+
+    os> source=people | eval latest = latest("-1s", now()) | fields latest | head 1
+    fetched rows / total rows = 1/1
+    +--------+
+    | latest |
+    |--------|
+    | False  |
+    +--------+
+
+    os> source=people | eval latest = latest("now", now()) | fields latest | head 1
+    fetched rows / total rows = 1/1
+    +--------+
+    | latest |
+    |--------|
+    | True   |
+    +--------+
+
+    os> source=people | eval latest = latest("+1s", now()) | fields latest | head 1
+    fetched rows / total rows = 1/1
+    +--------+
+    | latest |
+    |--------|
+    | True   |
+    +--------+
+
+
 ### `LOCALTIMESTAMP`
 
 **Description:**
@@ -738,7 +814,7 @@ Example:
 **Description:**
 
 
-**Usage:** relative_timestamp(str) returns a relative timestamp corresponding to the given relative string and the
+**Usage:** relative_timestamp(string) returns a relative timestamp corresponding to the given relative string and the
 current timestamp at the time of query execution.
 
 The relative timestamp string has syntax `[+|-]<offset_time_integer><offset_time_unit>@<snap_time_unit>`, and is
@@ -750,9 +826,12 @@ made up of two optional components.
   specified), and rounds the time <i>down</i> to the start of the specified time unit. For example, `@wk` is the start
   of the current week (Sunday is considered to be the first day of the week).
 
-The special relative timestamp string `now`, corresponding to the current timestamp, is also supported. The current
-timestamp is determined once at the start of query execution, and is used for all relative timestamp calculations for
-that query.
+The special relative timestamp string `now`, corresponding to the current timestamp, is also supported.
+
+The current timestamp is determined once at the start of query execution, and is used for all relative timestamp
+calculations for that query. The Spark session time zone (`spark.sql.session.timeZone`) is used for determining
+relative timestamps, and accounts for changes in the time zone offset (e.g. daylight savings time); as a result, adding
+one day (`+1d`) is not the same as adding twenty-four hours (`+24h`).
 
 The relative timestamp string is case-insensitive.
 

ppl-spark-integration/src/main/java/org/opensearch/sql/expression/function/SerializableUdf.java

@@ -227,13 +227,7 @@ public Instant apply(String relativeString, Object currentTimestamp, String zone
                             ? ((Timestamp) currentTimestamp).toInstant()
                             : (Instant) currentTimestamp;
 
-            /// The Spark session time zone (`spark.sql.session.timeZone`)
-            /// is used, which may be different from the system time zone.
             ZoneId zoneId = ZoneId.of(zoneIdString);
-
-            /// Relative time calculations are performed using [ZonedDateTime] because offsets (e.g. one hour ago)
-            /// need to account for changes in the time zone offset (e.g. daylight savings time), while snaps (e.g.
-            /// start of previous Wednesday) need to account for the local date time.
             ZonedDateTime currentDateTime = ZonedDateTime.ofInstant(currentInstant, zoneId);
             ZonedDateTime relativeDateTime = TimeUtils.getRelativeZonedDateTime(relativeString, currentDateTime);