From 810e95fe11f6d6d721bf37e5772176fd55f07c79 Mon Sep 17 00:00:00 2001
From: Sean Corfield <sean@corfield.org>
Date: Sat, 26 Aug 2023 12:48:35 -0700
Subject: [PATCH] fix #389 by showing ONLY(table) examples

---
 CHANGELOG.md            |  1 +
 doc/clause-reference.md | 12 ++++++++++++
 src/honey/sql.cljc      |  6 ++++++
 3 files changed, 19 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 11fa49c..3bbfd8c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
   * Add `:create-or-replace-view` to support PostgreSQL's lack of `IF NOT EXISTS` for `CREATE VIEW`.
   * Add `:select` with function call and alias example to README (PR [#502](https://github.com/seancorfield/honeysql/pull/502) [@markbastian](https://github.com/markbastian)).
   * Address [#497](https://github.com/seancorfield/honeysql/issues/497) by adding `:alias` special syntax.
+  * Address [#389](https://github.com/seancorfield/honeysql/issues/389) by adding examples of `[:only :table]` producing `ONLY(table)`.
   * Attempt to clarify the formatting behavior of the `:values` clause when used to produce column names.
   * Update `tools.build` to 0.9.5 (and remove `:java-opts` setting from `build/run-task`)
 
diff --git a/doc/clause-reference.md b/doc/clause-reference.md
index 97673b0..8c01e85 100644
--- a/doc/clause-reference.md
+++ b/doc/clause-reference.md
@@ -516,6 +516,12 @@ user=> (sql/format {:select [[:* :except [:a :b] :replace [[[:inline 2] :c]]]] :
 The `:table` clause is equivalent to `:select :* :from` and accepts just
 a simple table name -- see `:create-table-as` above for an example.
 
+Some databases support inheritance and you can `SELECT .. FROM ONLY ..` or
+`.. JOIN ONLY ..` to restrict the query to just the specified table. You can
+use function syntax for this `[:only table]` will produce `ONLY(table)`. This
+is the ANSI SQL syntax (but PostgreSQL allows the parentheses to be omitted,
+if you are writing SQL by hand).
+
 ## select-distinct-on
 
 Similar to `:select-distinct` above but the first element
@@ -728,6 +734,9 @@ user=> (sql/format {:select [:u.username :s.name]
 
 > Note: the actual formatting of a `:from` clause is currently identical to the formatting of a `:select` clause.
 
+If you are using inheritance, you can specify `ONLY(table)` as a function
+call: `[:only :table]`.
+
 ## using
 
 `:using` accepts a single sequence argument that lists
@@ -813,6 +822,9 @@ user=> (sql/format {:select [:t.ref :pp.code]
 ["SELECT t.ref, pp.code FROM transaction AS t LEFT JOIN paypal_tx AS pp USING (id) WHERE ? = pp.status" "settled"]
 ```
 
+If you are using inheritance, you can specify `ONLY(table)` as a function
+call: `[:only :table]`.
+
 See also the [`:join` special syntax](https://cljdoc.org/d/com.github.seancorfield/honeysql/CURRENT/doc/getting-started/sql-special-syntax-#join)
 for nested `JOIN` expressions.
 
diff --git a/src/honey/sql.cljc b/src/honey/sql.cljc
index b915707..f915026 100644
--- a/src/honey/sql.cljc
+++ b/src/honey/sql.cljc
@@ -2113,4 +2113,10 @@
                :order-by [[[:alias :'some-alias]]]})
   (sql/format {:select :f.* :from [[:foo [:f :FOR :SYSTEM-TIME]]] :where [:= :f.id 1]})
   (sql/format {:using [[:source [:= :table.id :source.id]]]})
+
+  ;; #389 -- ONLY for from/join etc:
+  (sql/format {:select [:*], :from [[[:only :table] :t]]})
+  (sql/format {:select [:*]
+               :from [[[:only :countries]]]
+               :join [[[:only :capitals]] [:= :countries.id :capitals.country_id]]})
   )