#set TITLE = "join"
#include top

.SH JOIN
The \fCJOIN\fR keyword, which is used as part of a 
#set FILE = "select.html"
#set TAG = "SELECT command,"
#include link
allows a relational join to be performed on two or three tables.
The \fCJOIN .. ON\fR syntax \fBmust\fR be used; alternatives aren't supported.  
Usage:
.LP
\fCSELECT .. 
.br
FROM \fIleft_table\fC [AS|= \fIalias1\fC] [\fIjointype\fR] JOIN \fIright_table\fC [AS|= \fIalias2\fC]
.br
\fC[ [\fIjointype2\fC] JOIN \fItable3\fR [AS|= \fIalias3\fC]
.br
\fCON \fIbinding\fR
.br
\fCWHERE ..\fR (etc)

#include space

.SH Examples
.nf
SELECT c.name, t.description
FROM customers (AS c) JOIN transactions (AS t) 
ON c.cust_id = t.cust_id

select p.*, ps.currentstatus
from patients = p left join patientstatus = ps
on p.patientid = ps.patientid
where ps.class = "B"
order by p.patientid

SELECT * FROM people JOIN pi_ref JOIN inst (as i)
ON people.id = pi_ref.people_id AND pi_ref.inst_id = i.id
ORDER BY people.lastname

.SH Usage notes
.LP
When using \fCJOIN\fR, fieldnames must be specified using \fItable\fR.\fIfieldname\fR
notation everywhere in the SQL command.
Table name aliases may be defined using \fCAS\fR or \fC=\fR (as in the above examples); this 
helps to maintain brevity. 
.LP
\fCON \fIbinding\fR specifies the key field(s) that will be matched up when performing 
the join.  The only supported comparison operation is equality (=), and matching is case-insensitive.
Multiple bindings may be connected using \fCAND\fR.
.LP
.ig >>
<table cellpadding=0 cellspacing=4>
.>>
#include tabnewrow
Join type
#include tabmidrow
Method
#include tabmidrow
Multiple rows having same key*

#include tabnewrow
\fBINNER\fR 
#include tabmidrow
This is the default.  Content must be present on both sides to produce an output record.  
#include tabmidrow
Right side only

#include tabnewrow
\fBLEFT\fR
#include tabmidrow
All left side rows kept; right side rows joined when available, filled in
with NULLs otherwise.
#include tabmidrow
Right side only

#include tabnewrow
\fBRIGHT\fR
#include tabmidrow
All right side rows kept; left side rows joined when available, filled in with NULLs otherwise.
#include tabmidrow
Right side only

#include tabnewrow
\fBOUTER\fR
#include tabmidrow
All left side and right side rows kept; companion content joined when available, filled in 
with NULLs otherwise.
#include tabmidrow
Right side only

#include tabnewrow
\fBINNERDL\fR 
#include tabmidrow
Same as INNER.
#include tabmidrow
Left side only

#include tabnewrow
\fBLEFTDL\fR
#include tabmidrow
Same as LEFT.
#include tabmidrow
Left side only

#include tabnewrow
\fBRIGHTDL\fR
#include tabmidrow
Same as RIGHT.
#include tabmidrow
Left side only

#include tabnewrow
\fBOUTERDL\fR
#include tabmidrow
Same as OUTER.
#include tabmidrow
Left side only

.ig >>
</table>
.>>

.LP
* Multiple rows having same key may be present on the left side or the right
side.  Multiple rows will be preserved in the join result
if the appropriate \fIjointype\fR is used.  Multiple rows having same key are
never permitted on both left and right sides.  The \fIjointypes\fR ending in
\fBDL\fR are non-standard; \fBDL\fR stands for "duplicates in left side".

.LP
Three-table joins are supported (see the 3rd example above).
The 2nd and 3rd tables are joined first, then that result is joined with the first
table.  Each of these join operations has a left side and a right side, and
its own \fIjointype\fR.

.LP
Naming of the resultant fields is described in the
#set FILE = "select.html#resultnames"
#set TAG = "SELECT manual page."
#include link
.LP
\fBshsql\fR performs joins by executing a separate program called \fCshsql_join\fR.
\fCshsql_join\fR must be in the current command PATH, or 
in the \fCdbbin\fR directory as defined in your 
#set FILE = "config.html#dbbin"
#set TAG = "project config file."
#include link

#include bottom
