edgar2020 commented on code in PR #16900:
URL: https://github.com/apache/druid/pull/16900#discussion_r1724087455
##########
docs/querying/sql-functions.md:
##########
@@ -2239,35 +2296,121 @@ Returns a union of Theta sketches.
## TIME_CEIL
-`TIME_CEIL(<TIMESTAMP>, <period>, [<origin>, [<timezone>]])`
+Rounds up a timestamp to a given ISO 8601 time period. Specify a timestamp,
`origin`, to provide a reference time from which to start. If provided,
`timezone`, should be a time zone name like `America/Los_Angeles` or an offset
like `-08:00`.
-**Function type:** [Scalar, date and
time](sql-scalar.md#date-and-time-functions)
+* **Syntax:** `TIME_CEIL(timestamp_expr, period[, origin[, timezone]])`
+* **Function type:** Scalar, date and time
+
+<details><summary>Example</summary>
+
+The following example takes the `__time` column from the `taxi-trips`
datasource and rounds up to nearest 45th minute in reference to the timestamp
`2013-08-01 08:0:00`
+
+```sql
+SELECT
+ "__time" AS "original_timestamp",
+ TIME_CEIL("__time", 'PT45M', TIMESTAMP '2013-08-01 08:0:00') AS
"time_ceiling"
+FROM "taxi-trips"
+LIMIT 2
+```
+
+Returns the following:
+
+| `original_timestamp` | `time_ceiling` |
+| -- | -- |
+| `2013-08-01T08:14:37.000Z` | `2013-08-01T08:45:00.000Z` |
+| `2013-08-01T09:13:00.000Z` | `2013-08-01T09:30:00.000Z` |
+</details>
-Rounds up a timestamp by a given time period, optionally from some reference
time or timezone.
+[Learn more](sql-scalar.md#date-and-time-functions)
## TIME_EXTRACT
-`TIME_EXTRACT(<TIMESTAMP>, [<unit>, [<timezone>]])`
+Extracts the value of some `unit` of the timestamp and returns the value. If
provided, `timezone`, should be a time zone name like `America/Los_Angeles` or
an offset like `-08:00`.
-**Function type:** [Scalar, date and
time](sql-scalar.md#date-and-time-functions)
+* **Syntax:** `TIME_EXTRACT(timestamp_expr[, unit[, timezone]])`
+* **Function type:** Scalar, date and time
+
+<details><summary>Example</summary>
+
+The following example extracts the hour from the `__time` column in the
`taxi-trips` datasource and offsets its timezone by `-04:00` hours.
+
+```sql
+SELECT
+ "__time" AS "original_timestamp",
+ TIME_EXTRACT("__time", 'hour', '-04:00') AS "extract_hour"
+FROM "taxi-trips"
+LIMIT 2
+```
+
+Returns the following:
+
+| `original_timestamp` | `extract_hour` |
+| -- | -- |
+| `2013-08-01T08:14:37.000Z` | `4` |
+| `2013-08-01T09:13:00.000Z` | `5` |
+
+</details>
-Extracts the value of some unit of the timestamp and returns the number.
+[Learn more](sql-scalar.md#date-and-time-functions)
## TIME_FLOOR
-`TIME_FLOOR(<TIMESTAMP>, <period>, [<origin>, [<timezone>]])`
+Rounds down a timestamp to a given ISO 8601 time period. Specify a timestamp,
`origin`, to provide a reference time from which to start. If provided,
`timezone`, should be a time zone name like `America/Los_Angeles` or an offset
like `-08:00`.
-**Function type:** [Scalar, date and
time](sql-scalar.md#date-and-time-functions)
+* **Syntax:** `TIME_FLOOR(timestamp_expr, period[, origin[, timezone]])`
+* **Function type:** Scalar, date and time
-Rounds down a timestamp by a given time period, optionally from some reference
time or timezone.
+<details><summary>Example</summary>
+
+The following example takes the `__time` column from the `taxi-trips`
datasource and rounds down to nearest 45th minute in reference to the timestamp
`2013-08-01 08:0:00`
Review Comment:
Changes are consistent with `TIME_CEIL`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
