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 <[email protected]>
apache · Jul 19, 2024 · 721a650 · 721a650
1 parent 0eaa810
commit 721a650
Show file tree

Hide file tree

Showing 2 changed files with 119 additions and 18 deletions.
diff --git a/docs/querying/sql-functions.md b/docs/querying/sql-functions.md
@@ -27,18 +27,46 @@ 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:
+* `flight-carriers` using `FlightCarrierOnTime (1 month)` 
+* `taxi-trips` using `NYC Taxi cabs (3 files)`
 
+## ABS
 
-This page provides a reference of all Druid SQL functions in alphabetical order.
-Click the linked function type for documentation on a particular function.
+Calculates the absolute value of a numeric expression.
 
-## ABS
+* **Syntax:** `ABS(<NUMERIC>)`
+* **Function type:** Scalar, numeric
 
-`ABS(<NUMERIC>)`
+<details><summary>Example</summary>
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+The following example applies the ABS function to the `ArrDelay` column from the `flight-carriers` datasource.
 
-Calculates the absolute value of a numeric expression.
+```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
 
@@ -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>)`
+Calculates the smallest integer value greater than or equal to the numeric expression.
+* **Syntax:** `CEIL(<NUMERIC>)`
+* **Function type:** Scalar, numeric
+
+<details><summary>Example</summary>
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+The following example applies the CEIL function to the `fare_amount` column from the `taxi-trips` datasource.
 
-Calculates the smallest integer value greater than or equal to the numeric expression.
+```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,11 +744,26 @@ Returns the value of a numeric or string expression corresponding to the earlies
 
 ## EXP
 
-`EXP(<NUMERIC>)`
+Calculates _e_ raised to the power of the numeric expression.
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+* **Syntax:** `EXP(<NUMERIC>)`
+* **Function type:** Scalar, numeric
 
-Calculates _e_ raised to the power of the numeric expression.
+<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
 
@@ -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
+
+<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:
 
-Calculates the largest integer value less than or equal to the numeric expression.
+| `fare_amount` | `floor_fare_amount` | 
+| -- | -- | 
+| `21.25` | `21` | 
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
 
 ## GREATEST
 
@@ -961,11 +1042,30 @@ Returns the length of the expression in UTF-16 encoding.
 
 ## LN
 
-`LN(expr)`
+Calculates the natural logarithm of the numeric expression.
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+* **Syntax:** `LN(<NUMERIC>)`
+* **Function type:** Scalar, numeric
 
-Calculates the natural logarithm of the numeric expression.
+<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
 

diff --git a/website/.spelling b/website/.spelling
@@ -55,6 +55,7 @@ CPUs
 CSVs
 CentralizedDatasourceSchema
 Ceph
+circledR
 CloudWatch
 ColumnDescriptor
 Corretto