Skip to content

Commit b6d3a02

Browse files
arnaud-lacuriearnaud-lacurie
committed
Add GREATEST, LEAST, COALESCE scalar function documentation
1 parent f4bee42 commit b6d3a02

File tree

8 files changed

+497
-0
lines changed

8 files changed

+497
-0
lines changed

‎docs/sphinx/source/reference/Functions/scalar_functions.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,19 @@ Scalar functions are functions that take an input of one row and produce a singl
77
List of functions
88
#################
99

10+
Comparison Functions
11+
--------------------
12+
13+
.. toctree::
14+
:maxdepth: 1
15+
16+
scalar_functions/greatest
17+
scalar_functions/least
18+
scalar_functions/coalesce
19+
20+
Specialized Functions
21+
---------------------
22+
1023
.. toctree::
1124
:maxdepth: 1
1225

‎docs/sphinx/source/reference/Functions/scalar_functions/coalesce.diagram‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Diagram(
2+
Terminal('COALESCE'),
3+
Terminal('('),
4+
NonTerminal('expression'),
5+
OneOrMore(
6+
Sequence(
7+
Terminal(','),
8+
NonTerminal('expression')
9+
)
10+
),
11+
Terminal(')'),
12+
)

‎docs/sphinx/source/reference/Functions/scalar_functions/coalesce.rst‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
========
2+
COALESCE
3+
========
4+
5+
.. _coalesce:
6+
7+
Returns the first non-NULL value from a list of expressions.
8+
9+
Syntax
10+
======
11+
12+
.. raw:: html
13+
:file: coalesce.diagram.svg
14+
15+
Parameters
16+
==========
17+
18+
``COALESCE(expression1, expression2, ...)``
19+
Evaluates expressions from left to right and returns the first non-NULL value. Requires at least two expressions.
20+
21+
Returns
22+
=======
23+
24+
Returns the first non-NULL value with the same type as the input expressions. If all values are NULL, returns NULL. All expressions must be of compatible types.
25+
26+
Supported Types
27+
================
28+
29+
``COALESCE`` supports all data types:
30+
31+
* Primitive types: ``STRING``, ``BOOLEAN``, ``DOUBLE``, ``FLOAT``, ``INTEGER``, ``BIGINT``, ``BYTES``
32+
* Complex types: ``ARRAY``, ``STRUCT``
33+
34+
Examples
35+
========
36+
37+
Setup
38+
-----
39+
40+
For these examples, assume we have a ``contacts`` table:
41+
42+
.. code-block:: sql
43+
44+
CREATE TABLE contacts(
45+
id BIGINT,
46+
name STRING,
47+
email STRING,
48+
phone STRING,
49+
address STRING,
50+
PRIMARY KEY(id))
51+
52+
INSERT INTO contacts VALUES
53+
(1, 'Alice', 'alice@example.com', NULL, NULL),
54+
(2, 'Bob', NULL, '555-0123', NULL),
55+
(3, 'Charlie', NULL, NULL, '123 Main St'),
56+
(4, 'David', NULL, NULL, NULL)
57+
58+
COALESCE - Find First Available Contact Method
59+
------------------------------------------------
60+
61+
Get the first available contact method for each person:
62+
63+
.. code-block:: sql
64+
65+
SELECT name, COALESCE(email, phone, address, 'No contact info') AS contact_method
66+
FROM contacts
67+
68+
.. list-table::
69+
:header-rows: 1
70+
71+
* - :sql:`name`
72+
- :sql:`contact_method`
73+
* - :json:`"Alice"`
74+
- :json:`"alice@example.com"`
75+
* - :json:`"Bob"`
76+
- :json:`"555-0123"`
77+
* - :json:`"Charlie"`
78+
- :json:`"123 Main St"`
79+
* - :json:`"David"`
80+
- :json:`"No contact info"`
81+
82+
COALESCE with Default Values
83+
------------------------------
84+
85+
Provide default values for NULL fields:
86+
87+
.. code-block:: sql
88+
89+
SELECT name,
90+
COALESCE(email, 'no-email@example.com') AS email,
91+
COALESCE(phone, 'Unknown') AS phone
92+
FROM contacts
93+
94+
.. list-table::
95+
:header-rows: 1
96+
97+
* - :sql:`name`
98+
- :sql:`email`
99+
- :sql:`phone`
100+
* - :json:`"Alice"`
101+
- :json:`"alice@example.com"`
102+
- :json:`"Unknown"`
103+
* - :json:`"Bob"`
104+
- :json:`"no-email@example.com"`
105+
- :json:`"555-0123"`
106+
* - :json:`"Charlie"`
107+
- :json:`"no-email@example.com"`
108+
- :json:`"Unknown"`
109+
* - :json:`"David"`
110+
- :json:`"no-email@example.com"`
111+
- :json:`"Unknown"`
112+
113+
COALESCE in UPDATE Statements
114+
-------------------------------
115+
116+
Use COALESCE to update only NULL values:
117+
118+
.. code-block:: sql
119+
120+
UPDATE contacts
121+
SET email = COALESCE(email, 'default@example.com')
122+
WHERE id = 2
123+
124+
This sets the email to ``'default@example.com'`` only if it was NULL, otherwise keeps the existing value.
125+
126+
Important Notes
127+
===============
128+
129+
* ``COALESCE`` returns the first non-NULL value from left to right
130+
* If all values are NULL, ``COALESCE`` returns NULL
131+
* All expressions must be of compatible types
132+
* The function requires at least two arguments
133+
* ``COALESCE`` supports all data types, including complex types like ``STRUCT`` and ``ARRAY``
134+
* Commonly used for providing default values when NULL is encountered

‎docs/sphinx/source/reference/Functions/scalar_functions/greatest.diagram‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Diagram(
2+
Terminal('GREATEST'),
3+
Terminal('('),
4+
NonTerminal('expression'),
5+
OneOrMore(
6+
Sequence(
7+
Terminal(','),
8+
NonTerminal('expression')
9+
)
10+
),
11+
Terminal(')'),
12+
)

‎docs/sphinx/source/reference/Functions/scalar_functions/greatest.rst‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
========
2+
GREATEST
3+
========
4+
5+
.. _greatest:
6+
7+
Returns the greatest (maximum) value from a list of expressions.
8+
9+
Syntax
10+
======
11+
12+
.. raw:: html
13+
:file: greatest.diagram.svg
14+
15+
Parameters
16+
==========
17+
18+
``GREATEST(expression1, expression2, ...)``
19+
Returns the largest value among all provided expressions. Requires at least two expressions. NULL values are considered smaller than any non-NULL value.
20+
21+
Returns
22+
=======
23+
24+
Returns the greatest value with the same type as the input expressions. If all values are NULL, returns NULL. All expressions must be of compatible types.
25+
26+
Supported Types
27+
================
28+
29+
``GREATEST`` supports the following types:
30+
31+
* ``STRING`` - Lexicographic comparison
32+
* ``BOOLEAN`` - TRUE > FALSE
33+
* ``DOUBLE`` - Numeric comparison
34+
* ``FLOAT`` - Numeric comparison
35+
* ``INTEGER`` - Numeric comparison
36+
* ``BIGINT`` - Numeric comparison
37+
38+
**Not Supported**: ``ARRAY``, ``STRUCT``, ``BYTES``
39+
40+
Examples
41+
========
42+
43+
Setup
44+
-----
45+
46+
For these examples, assume we have a ``products`` table:
47+
48+
.. code-block:: sql
49+
50+
CREATE TABLE products(
51+
id BIGINT,
52+
name STRING,
53+
price_usd BIGINT,
54+
price_eur BIGINT,
55+
price_gbp BIGINT,
56+
PRIMARY KEY(id))
57+
58+
INSERT INTO products VALUES
59+
(1, 'Widget', 100, 90, 80),
60+
(2, 'Gadget', 150, 140, 120),
61+
(3, 'Doohickey', 200, 180, 160)
62+
63+
GREATEST - Find Maximum Price
64+
-------------------------------
65+
66+
Find the highest price across all currencies for each product:
67+
68+
.. code-block:: sql
69+
70+
SELECT name, GREATEST(price_usd, price_eur, price_gbp) AS max_price
71+
FROM products
72+
73+
.. list-table::
74+
:header-rows: 1
75+
76+
* - :sql:`name`
77+
- :sql:`max_price`
78+
* - :json:`"Widget"`
79+
- :json:`100`
80+
* - :json:`"Gadget"`
81+
- :json:`150`
82+
* - :json:`"Doohickey"`
83+
- :json:`200`
84+
85+
GREATEST with Constants
86+
-------------------------
87+
88+
Compare values with constants:
89+
90+
.. code-block:: sql
91+
92+
SELECT name, GREATEST(price_usd, 125) AS adjusted_price
93+
FROM products
94+
95+
.. list-table::
96+
:header-rows: 1
97+
98+
* - :sql:`name`
99+
- :sql:`adjusted_price`
100+
* - :json:`"Widget"`
101+
- :json:`125`
102+
* - :json:`"Gadget"`
103+
- :json:`150`
104+
* - :json:`"Doohickey"`
105+
- :json:`200`
106+
107+
This ensures a minimum price of 125 for all products.
108+
109+
Important Notes
110+
===============
111+
112+
* ``GREATEST`` returns the largest value among all provided expressions
113+
* NULL values are treated as smaller than any non-NULL value
114+
* If all values are NULL, ``GREATEST`` returns NULL
115+
* All expressions must be of compatible types
116+
* The function requires at least two arguments
117+
* For string comparisons, lexicographic ordering is used

‎docs/sphinx/source/reference/Functions/scalar_functions/least.diagram‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Diagram(
2+
Terminal('LEAST'),
3+
Terminal('('),
4+
NonTerminal('expression'),
5+
OneOrMore(
6+
Sequence(
7+
Terminal(','),
8+
NonTerminal('expression')
9+
)
10+
),
11+
Terminal(')'),
12+
)

0 commit comments

Comments
 (0)