From 1836c7bcf14f700770a41e3ed24b7075b01a1b3b Mon Sep 17 00:00:00 2001 From: Sean Corfield Date: Sat, 17 Jul 2021 14:49:18 -0700 Subject: [PATCH] Address #332 by improving :cross-join docs --- CHANGELOG.md | 3 +++ doc/clause-reference.md | 19 +++++++++++++++++-- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1bd8178..c123e15 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ # Changes +* 2.0.next (gold) in progress + * Address #332 by improving `:cross-join` documentation. + * 2.0.0-rc4 (for testing; 2021-07-17) * Fix #338 by adding `ONLY` to `:fetch`. * Fix #337 by switching to `clojure.test` even for ClojureScript. diff --git a/doc/clause-reference.md b/doc/clause-reference.md index 91394b9..e19c6bf 100644 --- a/doc/clause-reference.md +++ b/doc/clause-reference.md @@ -592,9 +592,24 @@ user=> (sql/format {:select [:t.ref :pp.code] ## cross-join `:cross-join` accepts a single sequence argument that lists -one or more SQL entities. Each entity can either be a +one or more SQL expressions. Each expression can either be a simple table name (keyword or symbol) or a pair of a -table name and an alias. +table expression and an alias. + +```clojure +user=> (sql/format {:select [:foo.id [:x.id :x_id] :x.value] + :cross-join [[[:lateral + [:jsonb_to_recordset :foo.json_value]] + [[:raw "x(id text, value jsonb)"]]]] + :from [:foo]}) +["SELECT foo.id, x.id AS x_id, x.value FROM foo CROSS JOIN LATERAL JSONB_TO_RECORDSET(foo.json_value) x(id text, value jsonb)"] +``` + +Here, `:cross-join` has a one expression as its argument, which is a +table expression and an alias. The table expression is `[:lateral ..]` +and the alias expression is double-nested so that it is read as a +function call: an invocation of `:raw`. + > Note: the actual formatting of a `:cross-join` clause is currently identical to the formatting of a `:select` clause.