docs: add examples for SQL functions (#16745)

* updating first batch of numeric functions

* First batch of functions

* addressing first few comments

* alphabetize list

* draft with suggestions applied

* minor discrepency expr -> <NUMERIC>

* changed raises to calculates

* Update docs/querying/sql-functions.md

* switch to underscore

* changed to exp(1) to match slack message

* adding html text for trademark symbol to .spelling

* fixed discrepancy between description and example

---------

Co-authored-by: Benedict Jin <asdf2014@apache.org>

docs/querying/sql-functions.md

@@ -27,19 +27,47 @@ sidebar_label: "All functions"
  Apache Druid supports two query languages: Druid SQL and [native queries](querying.md).
  This document describes the SQL language.
 :::
+<!-- The **Learn More** at the end of each function section provides further documentation. -->
+This page provides a reference of Apache Druid&circledR; SQL functions in alphabetical order. For more details on a function, refer to the following:
+* [Aggregation functions](sql-aggregations.md)
+* [Array functions](sql-array-functions.md)
+* [JSON functions](sql-json-functions.md)
+* [Multi-value string functions](sql-multivalue-string-functions.md)
+* [Scalar functions](sql-scalar.md)
+* [Window functions](sql-window-functions.md)
 
-
+The examples on this page use the following example datasources:
-This page provides a reference of all Druid SQL functions in alphabetical order.
+* `flight-carriers` using `FlightCarrierOnTime (1 month)` 
-Click the linked function type for documentation on a particular function.
+* `taxi-trips` using `NYC Taxi cabs (3 files)`
 
 ## ABS
 
-`ABS(<NUMERIC>)`
-
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
-
 Calculates the absolute value of a numeric expression.
 
+* **Syntax:** `ABS(<NUMERIC>)`
+* **Function type:** Scalar, numeric
+
+<details><summary>Example</summary>
+
+The following example applies the ABS function to the `ArrDelay` column from the `flight-carriers` datasource.
+
+```sql
+SELECT
+  "ArrDelay" AS "arrival_delay",
+  ABS("ArrDelay") AS "absolute_arrival_delay"
+FROM "flight-carriers"
+WHERE "ArrDelay" < 0
+LIMIT 1
+```
+Returns the following:
+
+| `arrival_delay` | `absolute_arrival_delay` | 
+| -- | -- | 
+| `-27` | `27` | 
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
+
 ## ACOS
 
 `ACOS(<NUMERIC>)`
@@ -64,6 +92,7 @@ Returns any value of the specified expression.
 
 Counts distinct values of a regular column or a prebuilt sketch column.
 
+## APPROX_COUNT_DISTINCT_BUILTIN
 `APPROX_COUNT_DISTINCT_BUILTIN(expr)`
 
 **Function type:** [Aggregation](sql-aggregations.md)
@@ -419,11 +448,29 @@ Rounds up a timestamp by a given time unit.
 
 ## CEIL (numeric)
 
-`CEIL(<NUMERIC>)`
-
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
-
 Calculates the smallest integer value greater than or equal to the numeric expression.
+* **Syntax:** `CEIL(<NUMERIC>)`
+* **Function type:** Scalar, numeric
+
+<details><summary>Example</summary>
+
+The following example applies the CEIL function to the `fare_amount` column from the `taxi-trips` datasource.
+
+```sql
+SELECT
+  "fare_amount" AS "fare_amount",
+  CEIL("fare_amount") AS "ceiling_fare_amount"
+FROM "taxi-trips"
+LIMIT 1
+```
+Returns the following:
+
+| `fare_amount` | `ceiling_fare_amount` | 
+| -- | -- | 
+| `21.25` | `22` | 
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
 
 ## CHAR_LENGTH
 
@@ -697,12 +744,27 @@ Returns the value of a numeric or string expression corresponding to the earlies
 
 ## EXP
 
-`EXP(<NUMERIC>)`
-
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
-
 Calculates _e_ raised to the power of the numeric expression.
 
+* **Syntax:** `EXP(<NUMERIC>)`
+* **Function type:** Scalar, numeric
+
+<details><summary>Example</summary>
+
+The following example calculates _e_ to the power of 1.
+
+```sql
+SELECT EXP(1) AS "exponential" 
+```
+Returns the following:
+
+| `exponential` |
+| -- |
+| `2.7182818284590455` |
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
+
 ## EXTRACT
 
 `EXTRACT(<TIME_UNIT> FROM <TIMESTAMP>)`
@@ -729,11 +791,30 @@ Rounds down a timestamp by a given time unit.
 
 ## FLOOR (numeric)
 
-`FLOOR(<NUMERIC>)`
+Calculates the largest integer less than or equal to the numeric expression.
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+* **Syntax:** `FLOOR(<NUMERIC>)`
+* **Function type:** Scalar, numeric
 
-Calculates the largest integer value less than or equal to the numeric expression.
+<details><summary>Example</summary>
+
+The following example applies the FLOOR function to the `fare_amount` column from the `taxi-trips` datasource.
+
+```sql
+SELECT
+  "fare_amount" AS "fare_amount",
+  FLOOR("fare_amount") AS "floor_fare_amount"
+FROM "taxi-trips"
+LIMIT 1
+```
+Returns the following:
+
+| `fare_amount` | `floor_fare_amount` | 
+| -- | -- | 
+| `21.25` | `21` | 
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
 
 ## GREATEST
 
@@ -961,12 +1042,31 @@ Returns the length of the expression in UTF-16 encoding.
 
 ## LN
 
-`LN(expr)`
-
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
-
 Calculates the natural logarithm of the numeric expression.
 
+* **Syntax:** `LN(<NUMERIC>)`
+* **Function type:** Scalar, numeric
+
+<details><summary>Example</summary>
+
+The following example applies the LN function to the `max_temperature` column from the `taxi-trips` datasource.
+
+```sql
+SELECT
+  "max_temperature" AS "max_temperature",
+  LN("max_temperature") AS "natural_log_max_temp"
+FROM "taxi-trips"
+LIMIT 1
+```
+Returns the following:
+
+| `max_temperature` | `natural_log_max_temp` | 
+| -- | -- | 
+| `76` | `4.330733340286331` | 
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
+
 ## LOG10
 
 `LOG10(expr)`

website/.spelling

@@ -55,6 +55,7 @@ CPUs
 CSVs
 CentralizedDatasourceSchema
 Ceph
+circledR
 CloudWatch
 ColumnDescriptor
 Corretto