From 721a65046f643eda1fd17f0503252752d7546cc8 Mon Sep 17 00:00:00 2001 From: Edgar Melendrez Date: Thu, 18 Jul 2024 17:06:22 -0700 Subject: [PATCH] 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 -> * 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 --- docs/querying/sql-functions.md | 144 ++++++++++++++++++++++++++++----- website/.spelling | 1 + 2 files changed, 123 insertions(+), 22 deletions(-) diff --git a/docs/querying/sql-functions.md b/docs/querying/sql-functions.md index 7151c23b918..f5219f6a4b2 100644 --- a/docs/querying/sql-functions.md +++ b/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. ::: + +This page provides a reference of Apache Druid® 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) - -This page provides a reference of all Druid SQL functions in alphabetical order. -Click the linked function type for documentation on a particular function. +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 -`ABS()` - -**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions) - Calculates the absolute value of a numeric expression. +* **Syntax:** `ABS()` +* **Function type:** Scalar, numeric + +
Example + +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` | +
+ +[Learn more](sql-scalar.md#numeric-functions) + ## ACOS `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()` - -**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions) - Calculates the smallest integer value greater than or equal to the numeric expression. +* **Syntax:** `CEIL()` +* **Function type:** Scalar, numeric + +
Example + +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` | +
+ +[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()` - -**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions) - Calculates _e_ raised to the power of the numeric expression. +* **Syntax:** `EXP()` +* **Function type:** Scalar, numeric + +
Example + +The following example calculates _e_ to the power of 1. + +```sql +SELECT EXP(1) AS "exponential" +``` +Returns the following: + +| `exponential` | +| -- | +| `2.7182818284590455` | +
+ +[Learn more](sql-scalar.md#numeric-functions) + ## EXTRACT `EXTRACT( FROM )` @@ -729,11 +791,30 @@ Rounds down a timestamp by a given time unit. ## FLOOR (numeric) -`FLOOR()` +Calculates the largest integer less than or equal to the numeric expression. -**Function type:** [Scalar, numeric](sql-scalar.md#numeric-functions) +* **Syntax:** `FLOOR()` +* **Function type:** Scalar, numeric -Calculates the largest integer value less than or equal to the numeric expression. +
Example + +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` | +
+ +[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()` +* **Function type:** Scalar, numeric + +
Example + +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` | +
+ +[Learn more](sql-scalar.md#numeric-functions) + ## LOG10 `LOG10(expr)` diff --git a/website/.spelling b/website/.spelling index 5825f8ddb2f..40b1b906a12 100644 --- a/website/.spelling +++ b/website/.spelling @@ -55,6 +55,7 @@ CPUs CSVs CentralizedDatasourceSchema Ceph +circledR CloudWatch ColumnDescriptor Corretto