From eb5f5d45533c5f81e57dd0221d902a73ec400098 Mon Sep 17 00:00:00 2001
From: Marios Trivyzas <matriv@gmail.com>
Date: Mon, 6 May 2019 18:00:50 +0300
Subject: [PATCH] SQL: [Docs] Add example for custom bucketing with CASE
 (#41787)

* SQL: [Docs] Add example for custom bucketing with CASE

Add a TIP on how to use CASE to achieve custom bucketing
with GROUP BY.

Follows: #41349

* address comments

* address comment
---
 .../sql/functions/conditional.asciidoc        | 24 +++++++++++++++++++
 .../language/syntax/commands/select.asciidoc  |  4 ++++
 2 files changed, 28 insertions(+)

diff --git a/docs/reference/sql/functions/conditional.asciidoc b/docs/reference/sql/functions/conditional.asciidoc
index cad61f91f1997..d0b8e7d2ff3f1 100644
--- a/docs/reference/sql/functions/conditional.asciidoc
+++ b/docs/reference/sql/functions/conditional.asciidoc
@@ -98,6 +98,30 @@ an error message would be returned, mentioning that *'foo'* is of data type *key
 which does not match the expected data type *integer* (based on result *10*).
 ===============================
 
+[[sql-functions-conditional-case-groupby-custom-buckets]]
+===== Conditional bucketing
+
+CASE can be used as a GROUP BY key in a query to facilitate custom bucketing
+and assign descriptive names to those buckets. If, for example, the values
+for a key are too many or, simply, ranges of those values are more
+interesting than every single value, CASE can create custom buckets as in the
+following example:
+
+[source, sql]
+SELECT count(*) AS count,
+  CASE WHEN NVL(languages, 0) = 0 THEN 'zero'
+    WHEN languages = 1 THEN 'one'
+    WHEN languages = 2 THEN 'bilingual'
+    WHEN languages = 3 THEN 'trilingual'
+    ELSE 'multilingual'
+  END as lang_skills
+FROM employees
+GROUP BY lang_skills
+ORDER BY lang_skills;
+
+With this query, one can create normal grouping buckets for values _0, 1, 2, 3_ with
+descriptive names, and every value _>= 4_ falls into the _multilingual_ bucket.
+
 [[sql-functions-conditional-coalesce]]
 ==== `COALESCE`
 
diff --git a/docs/reference/sql/language/syntax/commands/select.asciidoc b/docs/reference/sql/language/syntax/commands/select.asciidoc
index 26fdb2f337ebc..08ebe0ae96497 100644
--- a/docs/reference/sql/language/syntax/commands/select.asciidoc
+++ b/docs/reference/sql/language/syntax/commands/select.asciidoc
@@ -204,6 +204,10 @@ Multiple aggregates used:
 include-tagged::{sql-specs}/docs/docs.csv-spec[groupByAndMultipleAggs]
 ----
 
+[TIP]
+If custom bucketing is required, it can be achieved with the use of `<<sql-functions-conditional-case, CASE>>`,
+as shown <<sql-functions-conditional-case-groupby-custom-buckets, here>>.
+
 [[sql-syntax-group-by-implicit]]
 ===== Implicit Grouping