diff --git a/CHANGELOG.md b/CHANGELOG.md index 1301349..18433ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,8 @@ # Changes * 2.0.next in progress - * Support PostgreSQL's `&&` operator. + * Support PostgreSQL's `&&` array operator. + * Clarify how to `SELECT` a function expression (in **Getting Started**). * 2.0.0-rc2 (for testing; 2021-05-10) * Fix #326 by allowing `ON`/`USING` to be optional and not dropping parameters on the floor. diff --git a/doc/getting-started.md b/doc/getting-started.md index 949d6a1..e99daec 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -143,6 +143,31 @@ qualified names in a function invocation: %max.foo/bar ;=> MAX(foo.bar) ``` +The latter syntax can be convenient in a `SELECT` because `[:a :b]` is +otherwise taken as a column and its alias, so selecting a function call +expression requires an extra level of nesting: + +```clojure +(sql/format {:select [:a]}) +;;=> ["SELECT a"] +(sql/format {:select [[:a :b]]}) +;;=> ["SELECT a AS b"] +(sql/format {:select [[[:a :b]]]}) +;;=> ["SELECT A(b)"] +;; or use the % notification: +(sql/format {:select [:%a.b]}) +;;=> ["SELECT A(b)"] +(sql/format {:select [[[:a :b] :c]]}) +;;=> ["SELECT A(b) AS c"] +(sql/format {:select [[:%a.b :c]]}) +;;=> ["SELECT A(b) AS c"] +;; putting it all together: +(sql/format {:select [:x [:y :d] [[:z :e]] [[:z :f] :g]]}) +;;=> ["SELECT x, y AS d, Z(e), Z(f) AS g"] +(sql/format {:select [:x [:y :d] [:%z.e] [:%z.f :g]]}) +;;=> ["SELECT x, y AS d, Z(e), Z(f) AS g"] +``` + ## SQL Parameters As indicated in the preceding sections, values found in the DSL data structure