Skip to content

Commit

Permalink
docs: add examples for SQL functions (apache#16745)
Browse files Browse the repository at this point in the history 
* 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]>
  • Loading branch information
@edgar2020 @asdf2014
edgar2020 and asdf2014 committed Jul 19, 2024
1 parent 7bddf73 commit d383be5
Show file tree
Hide file tree
Showing 2 changed files with 91 additions and 1 deletion.
91 changes: 90 additions & 1 deletion docs/querying/sql-functions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,26 @@ 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)

<<<<<<< HEAD
This page provides a reference of all Druid SQL functions in alphabetical order. The **Learn More** at the end of each function section provides further documentation.

The examples for each function uses the following datasets that come included with Apache Druid:
* `flight-carriers`: `FlightCarrierOnTime (1 month)`
* `taxi-trips`: `NYC Taxi cabs (3 files)`
=======
The examples on this page use the following example datasources:
* `flight-carriers` using `FlightCarrierOnTime (1 month)`
* `taxi-trips` using `NYC Taxi cabs (3 files)`
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
## ABS

Expand All @@ -43,19 +57,32 @@ Calculates the absolute value of a numeric expression.

<details><summary>Example</summary>

<<<<<<< HEAD
The following applies the ABS function to the `ArrDelay` column, from the `flight-carriers` datasource.

```sql
SELECT
"ArrDelay",
ABS("ArrDelay") AS "Abs"
=======
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"
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
FROM "flight-carriers"
WHERE "ArrDelay" < 0
LIMIT 1
```
Returns the following:

<<<<<<< HEAD
| `ArrDelay` | `Abs` |
=======
| `arrival_delay` | `absolute_arrival_delay` |
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
| -- | -- |
| `-27` | `27` |
</details>
Expand Down Expand Up @@ -442,25 +469,42 @@ Rounds up a timestamp by a given time unit.
## CEIL (numeric)
<<<<<<< HEAD
Rounds up to the smallest integer value greater than or equal to the numeric expression.
=======
Calculates the smallest integer value greater than or equal to the numeric expression.
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
* **Syntax:** `CEIL(<NUMERIC>)`
* **Function type:** Scalar, numeric
<details><summary>Example</summary>
<<<<<<< HEAD
The following example applies the CEIL function to the `fare_amount` column, from the `taxi-trips` datasource.
```sql
SELECT
"fare_amount",
CEIL("fare_amount") AS "Ceiling"
=======
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"
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
FROM "taxi-trips"
LIMIT 1
```
Returns the following:
<<<<<<< HEAD
| `fare_amount` | `Ceiling` |
=======
| `fare_amount` | `ceiling_fare_amount` |
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
| -- | -- |
| `21.25` | `22` |
</details>
Expand Down Expand Up @@ -746,6 +790,7 @@ Calculates _e_ raised to the power of the numeric expression.
<details><summary>Example</summary>
<<<<<<< HEAD
The following example raise _e_ to the power of `trip_id`, from the `taxi-trips` datasource.
```sql
Expand All @@ -760,6 +805,18 @@ Returns the following:
| `exponent_value` | `Exp` |
| -- | -- |
| `1` | `2.7182818284590455` |
=======
The following example calculates _e_ to the power of 1.
```sql
SELECT EXP(1) AS "exponential"
```
Returns the following:
| `exponential` |
| -- |
| `2.7182818284590455` |
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
</details>
[Learn more](sql-scalar.md#numeric-functions)
Expand Down Expand Up @@ -790,25 +847,44 @@ Rounds down a timestamp by a given time unit.
## FLOOR (numeric)
<<<<<<< HEAD
Rounds down to the largest integer value less than or equal to the numeric expression.
* **Syntax:** `Floor(<NUMERIC>)`
=======
Calculates the largest integer less than or equal to the numeric expression.
* **Syntax:** `FLOOR(<NUMERIC>)`
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
* **Function type:** Scalar, numeric
<details><summary>Example</summary>
<<<<<<< HEAD
The following example applies the FLOOR function to the `fare_amount` column, from the `taxi-trips` datasource.
```sql
SELECT
"fare_amount",
FLOOR("fare_amount") AS "Floor"
=======
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"
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
FROM "taxi-trips"
LIMIT 1
```
Returns the following:
<<<<<<< HEAD
| `fare_amount` | `Floor` |
=======
| `fare_amount` | `floor_fare_amount` |
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
| -- | -- |
| `21.25` | `21` |
</details>
Expand Down Expand Up @@ -1048,18 +1124,31 @@ Calculates the natural logarithm of the numeric expression.

<details><summary>Example</summary>

<<<<<<< HEAD
The following example applies the LN function to the `max_temperature` column, from the `taxi-trips` datasource.

```sql
SELECT
"max_temperature",
LN("max_temperature") AS "Ln"
=======
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"
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
FROM "taxi-trips"
LIMIT 1
```
Returns the following:

<<<<<<< HEAD
| `max_temperature` | `Ln` |
=======
| `max_temperature` | `natural_log_max_temp` |
>>>>>>> 721a65046f (docs: add examples for SQL functions (#16745))
| -- | -- |
| `76` | `4.330733340286331` |
</details>
Expand Down
1 change: 1 addition & 0 deletions website/.spelling
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ CPUs
CSVs
CentralizedDatasourceSchema
Ceph
circledR
CloudWatch
ColumnDescriptor
Corretto
Expand Down

0 comments on commit d383be5

Please sign in to comment.