From c295db44c05a84e2c25a36e7b894d2ca3cb8fd4c Mon Sep 17 00:00:00 2001
From: Sean Corfield <sean@corfield.org>
Date: Tue, 28 Jan 2025 11:10:53 -0800
Subject: [PATCH] add examples of :alias with :group-by

Signed-off-by: Sean Corfield <sean@corfield.org>
---
 doc/clause-reference.md | 5 +++++
 doc/special-syntax.md   | 8 ++++++++
 2 files changed, 13 insertions(+)

diff --git a/doc/clause-reference.md b/doc/clause-reference.md
index a7fb025..4010a69 100644
--- a/doc/clause-reference.md
+++ b/doc/clause-reference.md
@@ -1091,6 +1091,11 @@ user=> (sql/format '{select (*) from (table)
 ["SELECT * FROM table GROUP BY status, YEAR(created_date)"]
 ```
 
+You can `GROUP BY` expressions, column names (`:col1`), or table and column (`:table.col1`),
+or aliases (`:some.alias`). Since there is ambiguity between the formatting
+of those, you can use the special syntax `[:alias :some.thing]` to tell
+HoneySQL to treat `:some.thing` as an alias instead of a table/column name.
+
 ## having
 
 The `:having` clause works identically to `:where` above
diff --git a/doc/special-syntax.md b/doc/special-syntax.md
index cf6bf0b..97d872c 100644
--- a/doc/special-syntax.md
+++ b/doc/special-syntax.md
@@ -29,6 +29,14 @@ and strings.
              :from :b
              :order-by [[[:alias :'some-alias]]]})
 ;;=> ["SELECT column_name AS \"some-alias\" FROM b ORDER BY \"some-alias\" ASC"]
+(sql/format {:select [[:column-name "some-alias"]]
+             :from :b
+             :group-by [[:alias "some-alias"]]})
+;;=> ["SELECT column_name AS \"some-alias\" FROM b GROUP BY \"some-alias\""]
+(sql/format {:select [[:column-name "some-alias"]]
+             :from :b
+             :group-by [[:alias :'some-alias]]})
+;;=> ["SELECT column_name AS \"some-alias\" FROM b GROUP BY \"some-alias\""]
 ```
 
 ## array