# SQL Clauses Supported This section lists all the SQL clauses that HoneySQL supports out of the box, in the order that they are processed for formatting. Clauses can be specified as keywords or symbols. Use `-` in the clause name where the formatted SQL would have a space (e.g., `:left-join` is formatted as `LEFT JOIN`). Except as noted, these clauses apply to all the SQL dialects that HoneySQL supports. ## nest ## with, with-recursive ## intersect, union, union-all, except, except-all These all expect a sequence of SQL clauses, those clauses will be wrapped in parentheses, and the SQL keyword interspersed between those clauses. ```clojure user=> (sql/format '{union [{select (id,status) from (table-a)} {select (id,(event status) from (table-b))}]}) ["(SELECT id, status FROM table_a) UNION (SELECT id, event AS status, from, table_b)"] ``` ## select, select-distinct `:select` expects a sequence of SQL entities (column names or expressions). Any of the SQL entities can be a pair of entity and alias. If you are selecting an expression, you would most often provide an alias for the expression, but it can be omitted as in the following: ```clojure user=> (sql/format '{select (id, ((* cost 2)), (event status)) from (table)}) ["SELECT id, cost * ?, event AS status FROM table" 2] ``` With an alias on the expression: ```clojure user=> (sql/format {:select [:id, [[:* :cost 2] :total], [:event :status]] :from [:table]}) ["SELECT id, cost * ? AS total, event AS status FROM table" 2] ``` `:select-distinct` works the same way but produces `SELECT DISTINCT`. HoneySQL does not yet support `SELECT .. INTO ..` or `SELECT .. BULK COLLECT INTO ..`. ## insert-into There are two use cases with `:insert-into`. The first case takes just a simple SQL entity (the table name). The more complex case takes a pair of a SQL entity and a SQL query. In that second case, you can specify the columns by using a pair of the table name and a sequence of column names. For the first case, you'll use the `:values` clause and you may use the `:columns` clause as well. ```clojure user=> (sql/format {:insert-into :transport :values [[1 "Car"] [2 "Boat"] [3 "Bike"]]}) ["INSERT INTO transport VALUES (?, ?), (?, ?), (?, ?)" 1 "Car" 2 "Boat" 3 "Bike"] user=> (sql/format {:insert-into :transport :columns [:id :name] :values [[1 "Car"] [2 "Boat"] [3 "Bike"]]}) ["INSERT INTO transport (id, name) VALUES (?, ?), (?, ?), (?, ?)" 1 "Car" 2 "Boat" 3 "Bike"] ``` The second case: ```clojure user=> (sql/format '{insert-into (transport {select (id, name) from (cars)})}) ["INSERT INTO transport SELECT id, name FROM cars"] user=> (sql/format '{insert-into ((transport (id, name)) {select (*) from (cars)})}) ["INSERT INTO transport (id, name) SELECT * FROM cars"] ``` ## update `:update` expects either a simple SQL entity (table name) or a pair of the table name and an alias: ```clojure user=> (sql/format {:update :transport :set {:name "Yacht"} :where [:= :id 2]}) ["UPDATE transport SET name = ? WHERE id = ?" "Yacht" 2] ``` ## delete, delete-from `:delete-from` is the simple use case here, accepting just a SQL entity (table name). `:delete` allows for deleting from multiple tables, accepting a sequence of either table names or aliases: ```clojure user=> (sql/format '{delete-from transport where (= id 1)}) ["DELETE FROM transport WHERE id = ?" 1] user=> (sql/format {:delete [:order :item] :from [:order] :join [:item [:= :order.item-id :item.id]] :where [:= :item.id 42]}) ["DELETE order, item FROM order INNER JOIN item ON order.item_id = item.id WHERE item.id = ?" 42] ``` ## truncate `:truncate` accepts a simple SQL entity (table name): ```clojure user=> (sql/format '{truncate transport}) ["TRUNCATE transport"] ``` ## columns Wherever you need just a list of column names `:columns` accepts a sequence of SQL entities (names). We saw an example above with `:insert-into`. ## set (ANSI) `:set` accepts a hash map of SQL entities and the values that they should be assigned. This precedence -- between `:columns` and `:from` -- corresponds to ANSI SQL which is correct for most databases. The MySQL dialect that HoneySQL 2.0 supports has a different precedence (below). ```clojure user=> (sql/format {:update :order :set {:line-count [:+ :line-count 1]} :where [:= :item-id 42]}) ["UPDATE order SET line_count = line_count + ? WHERE item_id = ?" 1 42] ``` ## from `:from` accepts a single sequence argument that lists one or more SQL entities. Each entity can either be a simple table name (keyword or symbol) or a pair of a table name and an alias: ```clojure user=> (sql/format {:select [:username :name] :from [:user :status] :where [:and [:= :user.statusid :status.id] [:= :user.id 9]]}) ["SELECT username, name FROM user, status WHERE (user.statusid = status.id) AND (user.id = ?)" 9] user=> (sql/format {:select [:u.username :s.name] :from [[:user :u] [:status :s]] :where [:and [:= :u.statusid :s.id] [:= :u.id 9]]}) ["SELECT u.username, s.name FROM user AS u, status AS s WHERE (u.statusid = s.id) AND (u.id = ?)" 9] ``` > Note: the actual formatting of a `:from` clause is currently identical to the formatting of a `:select` clause. ## using `:using` accepts a single sequence argument that lists one or more SQL entities. Each entity can either be a simple table name (keyword or symbol) or a pair of a table name and an alias. `:using` is intended to be used as a simple join with a `:delete-from` clause (see [PostgreSQL DELETE statement](https://www.postgresql.org/docs/12/sql-delete.html) for more detail). > Note: the actual formatting of a `:using` clause is currently identical to the formatting of a `:select` clause. ## join, left-join, right-join, inner-join, outer-join, full-join All these join clauses have the same structure: they accept a sequence of alternating SQL entities (table names) and conditions that specify how to perform the join. The table names can either be simple names or a pair of a table name and an alias: ```clojure user=> (sql/format {:select [:u.username :s.name] :from [[:user :u]] :join [[:status :s] [:= :u.statusid :s.id]] :where [:= :s.id 2]}) ["SELECT u.username, s.name FROM user AS u INNER JOIN status AS s ON u.statusid = s.id WHERE s.id = ?" 2] ``` An alternative to a join condition is a `USING` expression: ```clojure user=> (sql/format {:select [:t.ref :pp.code] :from [[:transaction :t]] :left-join [[:paypal-tx :pp] [:using :id]] :where [:= "settled" :pp.status]}) ["SELECT t.ref, pp.code FROM transaction AS t LEFT JOIN paypal_tx AS pp USING (id) WHERE ? = pp.status" "settled"] ``` ## cross-join `:cross-join` accepts a single sequence argument that lists one or more SQL entities. Each entity can either be a simple table name (keyword or symbol) or a pair of a table name and an alias. > Note: the actual formatting of a `:cross-join` clause is currently identical to the formatting of a `:select` clause. ## set (MySQL) This is the precedence of the `:set` clause for the MySQL dialect. It is otherwise identical to the `:set` clause described above. ## where The `:where` clause can have a single SQL expression, or a sequence of SQL expressions prefixed by either `:and` or `:or`. See examples of `:where` in various clauses above. ## group-by `:group-by` accepts a sequence of one or more SQL expressions. ```clojure user=> (sql/format '{select (*) from (table) group-by (status, (year created-date))}) ["SELECT * FROM table GROUP BY status, YEAR(created_date)"] ``` ## having The `:having` clause works identically to `:where` above but is rendered into the SQL later in precedence order. ## order-by `:order-by` accepts a sequence of one or more ordering expressions. Each ordering expression is either a simple SQL entity or a pair of a SQL expression and a direction (which can be `:asc` or `:desc` -- or the symbol equivalent). If you want to order by an expression, you should wrap it as a pair with a direction: ```clojure user=> (sql/format '{select (*) from table ;; simple orderings: order-by (status, created-date)}) ["SELECT * FROM table ORDER BY status ASC, created_date ASC"] user=> (sql/format '{select (*) from table ;; explicit direction provided: order-by ((status asc), ((year created-date) asc))}) ["SELECT * FROM table ORDER BY status ASC, YEAR(created_date) ASC"] ``` The default direction is ascending and if you provide a wrapped expression you _can_ omit the direction if you want: ```clojure user=> (sql/format {:select [:*] :from :table ;; expression without direction is still wrapped: :order-by [:status, [[:year :created-date]]]}) ["SELECT * FROM table ORDER BY status ASC, YEAR(created_date) ASC"] ``` ## limit, offset (MySQL) Both `:limit` and `:offset` expect a single SQL expression: ```clojure user=> (sql/format {:select [:id :name] :from [:table] :limit 20 :offset 20}) ["SELECT id, name FROM table LIMIT ? OFFSET ?" 20 20] ``` > Note: In the prerelease, these MySQL-specific clauses are in the default dialect but these will be moved to the `:mysql` dialect. ## for The `:for` clause accepts either a single item -- the lock strength -- or a sequence of up to three items of which the first is the lock strength, followed by an optional table name (or sequence of table names), followed by how to deal with the lock: ```clojure user=> (sql/format '{select (*) from (table) for update}) ["SELECT * FROM table FOR UPDATE"] user=> (sql/format '{select (*) from (table) for no-key-update}) ["SELECT * FROM table FOR NO KEY UPDATE"] user=> (sql/format '{select (*) from (table) for (key-share wait)}) ["SELECT * FROM table FOR KEY SHARE WAIT"] user=> (sql/format '{select (*) from (table) for (update bar wait)}) ["SELECT * FROM table FOR UPDATE OF bar WAIT"] user=> (sql/format '{select (*) from (table) for (update (bar quux) wait)}) ["SELECT * FROM table FOR UPDATE OF bar, quux WAIT"] ``` The lock strength can be any SQL keyword or phrase represented as a Clojure keyword (or symbol), with spaces represented by `-`. The three SQL keywords/phrases that are recognized as not being a table name in the second slot are `NOWAIT`, `SKIP LOCKED`, and `WAIT`. However, in the case where a table name (or sequence of table names) is present, no check is made on the keyword or phrase in that third slot (although it is expected to be just one of those three mentioned above). ## lock (MySQL) The syntax accepted for MySQL's `:lock` is exactly the same as the `:for` clause above. > Note: In the prerelease, this MySQL-specific clauses is in the default dialect but this will be moved to the `:mysql` dialect. ## values `:values` accepts either a sequence of hash maps representing row values or a sequence of sequences, also representing row values. In the former case, all of the rows are augmented to have `nil` values for any missing keys (columns). In the latter, all of the rows are padded to the same length by adding `nil` values if needed. ```clojure user=> (sql/format {:insert-into :table :values [[1 2] [2 3 4 5] [3 4 5]]}) ["INSERT INTO table VALUES (?, ?, NULL, NULL), (?, ?, ?, ?), (?, ?, ?, NULL)" 1 2 2 3 4 5 3 4 5] user=> (sql/format '{insert-into table values ({id 1 name "Sean"} {id 2} {name "Extra"})}) ["INSERT INTO table (id, name) VALUES (?, ?), (?, NULL), (NULL, ?)" 1 "Sean" 2 "Extra"] ``` ## on-conflict, on-constraint, do-nothing, do-update-set These are grouped together because they are handled as if they are separate clauses but they will appear in pairs: `ON ... DO ...`. `:on-conflict` accepts either a single SQL entity (a keyword or symbol) or a SQL clause. That's either a column name or an `:on-constraint` clause or a `:where` clause. `:on-constraint` accepts a single SQL entity that identifies a constraint name. Since `:do-nothing` is a SQL clause but has no associated data, it still has to have an arbitrary value because clauses are hash maps and that value will be ignored so `:do-nothing true` is a reasonable choices. `:do-update-set` accepts either a single SQL entity (a keyword or symbol) or hash map of columns and values, like `:set` (above). The former produces a `SET` clause using `EXCLUDED`: ```clojure user=> (sql/format {:insert-into :companies :values [{:name "Microsoft"}] :on-conflict :name :do-update-set :name}) ["INSERT INTO companies (name) VALUES (?) ON CONFLICT (name) DO UPDATE SET name = EXCLUDED.name" "Microsoft"] user=> (sql/format {:insert-into :companies :values [{:name "Microsoft"}] :on-conflict {:on-constraint :name-idx} :do-nothing true}) ["INSERT INTO companies (name) VALUES (?) ON CONFLICT ON CONSTRAINT name_idx DO NOTHING" "Microsoft"] ``` ## returning `:returning` accepts a single sequence argument that lists one or more SQL entities. Each entity can either be a simple table name (keyword or symbol) or a pair of a table name and an alias. > Note: the actual formatting of a `:returning` clause is currently identical to the formatting of a `:select` clause.