From ca475a17ec0cfbdcbd15e9b7f30033adf5a7e58a Mon Sep 17 00:00:00 2001
From: edgar2020 <evmelendrez@gmail.com>
Date: Wed, 24 Jul 2024 13:08:17 -0700
Subject: [PATCH] batch 03 - trig functions

---
 docs/querying/sql-functions.md | 210 ++++++++++++++++++++++++++++-----
 1 file changed, 180 insertions(+), 30 deletions(-)

diff --git a/docs/querying/sql-functions.md b/docs/querying/sql-functions.md
index f5219f6a4b27..7b0715186823 100644
--- a/docs/querying/sql-functions.md
+++ b/docs/querying/sql-functions.md
@@ -70,11 +70,26 @@ Returns the following:
 
 ## ACOS
 
-`ACOS(<NUMERIC>)`
+Calculates the arc cosine of a numeric expression.
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+* **Syntax:** `ACOS(expr)`
+* **Function type:** Scalar, numeric
 
-Calculates the arc cosine of a numeric expression.
+<details><summary>Example</summary>
+
+The following example calculates the arc cosine of zero.
+
+```sql
+SELECT ACOS(0) AS "arc_cosine"
+```
+Returns the following:
+
+| `arc_tangent` |  
+| -- | 
+| `1.5707963267948966` |
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
 
 ## ANY_VALUE
 
@@ -280,27 +295,72 @@ Joins all elements of `arr` by the delimiter specified by `str`.
 
 ## ASIN
 
-`ASIN(<NUMERIC>)`
+Calculates the arc sine of a numeric expression.
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+* **Syntax:** `ASIN(expr)`
+* **Function type:** Scalar, numeric
 
-Calculates the arc sine of a numeric expression.
+<details><summary>Example</summary>
 
-## ATAN
+The following example calculates the arc sine of one.
 
-`ATAN(<NUMERIC>)`
+```sql
+SELECT ASIN(1) AS "arc_sine"
+```
+Returns the following:
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+| `arc_sine` |  
+| -- | 
+| `1.5707963267948966` |
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
+
+## ATAN
 
 Calculates the arc tangent of a numeric expression.
 
+* **Syntax:** `ATAN(expr)`
+* **Function type:** Scalar, numeric
+
+<details><summary>Example</summary>
+
+The following example calculates the arc tangent of one.
+
+```sql
+SELECT ATAN(1) AS "arc_tangent"
+```
+Returns the following:
+
+| `arc_tangent` |  
+| -- | 
+| `0.7853981633974483` |
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
+
 ## ATAN2
 
-`ATAN2(<NUMERIC>, <NUMERIC>)`
+Calculates the arc tangent of specified x and y coordinates.
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+* **Syntax:** `ATAN2(x, y)`
+* **Function type:** Scalar, numeric
+
+<details><summary>Example</summary>
+
+The following example calculates the arc tangent of the coordinate (1, -1)
+
+```sql
+SELECT ATAN2(1,-1) AS "arc_tangent_2"
+```
+Returns the following:
+
+| `arc_tangent` |  
+| -- | 
+| `2.356194490192345` |
+</details>
 
-Calculates the arc tangent of the two arguments.
+[Learn more](sql-scalar.md#numeric-functions)
 
 ## AVG
 
@@ -514,20 +574,50 @@ Finds whether a string is in a given expression, case-sensitive.
 
 ## COS
 
-`COS(<NUMERIC>)`
+Calculates the trigonometric cosine of an angle expressed in radians.
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+* **Syntax:** `COS(expr)`
+* **Function type:** Scalar, numeric
 
-Calculates the trigonometric cosine of an angle expressed in radians.
+<details><summary>Example</summary>
 
-## COT
+The following example calculates the cosine of `PI` over three radians.
 
-`COT(<NUMERIC>)`
+```sql
+SELECT COS(PI / 3) AS "cosine"
+```
+Returns the following:
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+| `COS` |  
+| -- | 
+| `0.5000000000000001` |
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
+
+## COT
 
 Calculates the trigonometric cotangent of an angle expressed in radians.
 
+* **Syntax:** `COT(expr)`
+* **Function type:** Scalar, numeric
+
+<details><summary>Example</summary>
+
+The following example calculates the cotangent of `PI` over three radians.
+
+```sql
+SELECT COT(PI / 3) AS "cotangent"
+```
+Returns the following:
+
+| `cotangent` |  
+| -- | 
+| `0.577350269189626` |
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
+
 ## COUNT
 
 `COUNT([DISTINCT] expr)`
@@ -589,11 +679,26 @@ Decodes a Base64-encoded string into a UTF-8 encoded string.
 
 ## DEGREES
 
-`DEGREES(<NUMERIC>)`
+Converts an angle from radians to degrees.
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+* **Syntax:** `DEGREES(expr)`
+* **Function type:** Scalar, numeric
 
-Converts an angle from radians to degrees.
+<details><summary>Example</summary>
+
+The following example converts `PI` radians to degrees
+
+```sql
+SELECT DEGREES(PI) AS "degrees"
+```
+Returns the following:
+
+| `degrees` |  
+| -- | 
+| `180` |
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
 
 ## DENSE_RANK
 
@@ -1325,11 +1430,26 @@ Calculates a numerical expression raised to the specified power.
 
 ## RADIANS
 
-`RADIANS(expr)`
+Converts an angle from degrees to radians.
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+* **Syntax:** `RADIANS(expr)`
+* **Function type:** Scalar, numeric
 
-Converts an angle from degrees to radians.
+<details><summary>Example</summary>
+
+The following example converts 180 degrees to radians
+
+```sql
+SELECT RADIANS(180) AS "radians"
+```
+Returns the following:
+
+| `radians` |  
+| -- | 
+| `3.141592653589793` |
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
 
 ## RANK
 
@@ -1438,11 +1558,26 @@ Returns `x` divided by `y`, guarded on division by 0.
 
 ## SIN
 
-`SIN(expr)`
+Calculates the trigonometric sine of an angle expressed in radians.
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+* **Syntax:** `SIN(expr)`
+* **Function type:** Scalar, numeric
 
-Calculates the trigonometric sine of an angle expressed in radians.
+<details><summary>Example</summary>
+
+The following example calculates the sine of `PI` over three radians.
+
+```sql
+SELECT SIN(PI / 3) AS "sine"
+```
+Returns the following:
+
+| `sine` |  
+| -- | 
+| `0.8660254037844386` |
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
 
 ## SQRT
 
@@ -1551,11 +1686,26 @@ Calculates the sum of a set of values.
 
 ## TAN
 
-`TAN(expr)`
+Calculates the trigonometric tangent of an angle expressed in radians.
 
-**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions)
+* **Syntax:** `TAN(expr)`
+* **Function type:** Scalar, numeric
 
-Calculates the trigonometric tangent of an angle expressed in radians.
+<details><summary>Example</summary>
+
+The following example calculates the tangent of `PI` over three.
+
+```sql
+SELECT TAN(PI / 3) AS "tangent"
+```
+Returns the following:
+
+| `tangent` |  
+| -- | 
+| `1.7320508075688767` |
+</details>
+
+[Learn more](sql-scalar.md#numeric-functions)
 
 ## TDIGEST_GENERATE_SKETCH