#set TITLE = "SELECT"
#include top


.SH SELECT
\fBSELECT\fR retrieves data from one table or from a relational join performed using two tables.
It can also retrieve or join data located in 
#set FILE = "temptables.html"
#set TAG = "temporary tables"
#include link
and
#set FILE = "ordfiles.html"
#set TAG = "ordinary files."
#include link
SELECT INTO can be used to put retrieved data into a temporary table, an ordinary file, or
even a regular table.  The SELECT syntax is:


.IP
\fCSELECT  [DISTINCT]  \fIitemlist\fC
.br
[INTO \fItable\fC|\fIfilename\fC [APPEND|TABLE]]
.br
FROM \fItable\fC [AND \fItable2\fC..] [ \fIjointype\fR \fItable2\fC.. ON \fIon-clause\fC ]
.br
[GROUP BY \fIgroupbylist\fC ]
.br
[WHERE \fIconditional-expression\fC]
.br
[ORDER BY \fIorderlist\fC ]
.br
[LIMIT [\fIfirstrow\fC], \fIlastrow\fC ]
.br
[MAXROWS \fImaxrows\fC]
.br
[FOR UPDATE]

#include space

.LP
\fBDISTINCT\fR eliminates duplicate result rows.  

#include space

.LP
\fBitemlist\fR is a list 
of \fIfieldnames\fR, aggregate functions, or quoted string constants.
Commas should separate items.
An asterisk (\fC*\fR) may appear alone to select all fields, or
may be used to match a subset of fields, e.g. \fCt1.*\fR.
\fCAS\fR or \fC=\fR may be used to specify fieldname aliases (however, natural field names,
not aliases, must be used other parts of the command (\fCWHERE\fR, \fCORDER BY\fR, etc.).
Aggregate functions such as count() may be given in \fIitemlist\fR; these may
be used alone to operate on all requested rows, or with \fCGROUP BY\fR, to
operate on groups of records.
Supported aggregate functions are: count(), sum(), avg(), min(), and max().
\fCcount( \fIfieldname\fR )\fR counts the number of non-null instances of \fIfieldname\fR; 
\fCcount(*)\fR counts the number of rows.
The other functions must contain one field name within the parentheses.

#include space
.ig >>
<a name=into></a>
.>>

.LP
\fBINTO\fR causes the results to be written to a 
#set FILE = "temptables.html"
#set TAG = "temporary table"
#include link
or
#set FILE = "ordfiles.html"
#set TAG = "ordinary file."
#include link
\fBshsql\fR also allows SELECT INTO to write the results to a
#set FILE = "tables.html"
#set TAG = "database table"
#include link
however, either the \fCTABLE\fR or \fCAPPEND\fR keyword must be present.
\fCAPPEND\fR may be used to append the 
results to existing content (but \fBshsql\fR does not verify field format consistency).

#include space

.LP
\fBFROM\fR names the 
#set FILE = "tables.html
#set TAG = "table,"
#include link
#set FILE = "temptables.html"
#set TAG = "temporary table,"
#include link
or
#set FILE = "ordfiles.html"
#set TAG = "ordinary file"
#include link
from which data will be retrieved.
\fBshsql\fR also allows more than one table (etc.) to be involved by connecting
table names with \fCAND\fR, eg:
\fCSELECT .. FROM masterlist AND $tmplist1 AND $tmplist2\fR.
When more than one table is specified, the retreival will be performed on the
tables one after another (using indexing where possible) to produce an amalgamation
of rows to which \fCWHERE\fR, \fCORDER BY\fR, \fCGROUP BY\fR etc. may be applied.
All tables must have the same field format (but \fBshsql\fR does not check this); also,
this feature can't be combined with \fCJOIN\fR or \fCSELECT..FOR UPDATE\fR.


.ig >>
<a name=join></a>
.>>

#include space

.LP
\fBJOIN\fR causes a relational join to be performed using two or three tables.  
Described on the
#set FILE = "join.html"
#set TAG = "JOIN manual page."
#include link
If a \fCJOIN\fR is involved, fieldnames must be specified using \fItablename\fC.\fIfieldname\fR
notation everywhere in the SELECT command (where \fItablename\fR is the actual name or an alias).
\fCJOIN\fR cannot be used along with \fC..FOR UPDATE\fR.


#include space

.LP
\fBGROUP BY\fR
specifies field(s) that will control grouping of records for aggregate computation 
e.g. count(), sum(), etc.  These fields should be given in \fIgroupbylist\fR, and
must also be present in the SELECT \fIitemlist\fR.
\fCGROUP BY\fR implicitly orders result rows using \fIgroupbylist\fR.
\fCORDER BY\fR cannot be used with \fCGROUP BY\fR, but
any of the \fCORDER BY\fR keywords may be used in \fIgroupbylist\fR 
to influence the order of result rows.  
\fCHAVING\fR is not supported, but this functionality may be gained using a temp table or file.

#include space
.LP
\fBWHERE\fR
specifies a conditional expression to select records of interest, in the form of a
#set FILE = "whereclause.html"
#set TAG = "WHERE clause"
#include link
\0.  If not specified, all rows in the table will be presented.

.ig >>
<a name=orderby></a>
.>>
#include space

.LP
\fBORDER BY\fR controls the ordering of the result rows.
\fIorderlist\fR is a list of field names to use in the sort.
Each field name in \fIorderlist\fR may optionally be followed by one or more of the following
keywords:
.IP
\fCASCENDING ASC\fR 
#include nbsp2
normal order (a..z, 0..9)
.br
\fCDESCENDING DESC\fR 
#include nbsp2
reverse order (z..a, 9..0)
.br
\fCNUMERIC NUM\fR 
#include nbsp2
numeric sort (necessary since shsql doesn't use datatypes)
.br
\fCMAGNITUDE MAG\fR
#include nbsp2
same as numeric but based on absolute values 
.br
\fCDICT\fR 
#include nbsp2
dictionary order; punctuation characters are ignored
.LP
By default, the sort method is ASCENDING, and alpha method is used.
Note: currently only 'C' locale is supported on \fBORDER BY\fR.

#include space

.LP
\fBLIMIT\fR may be used to present only a certain range of the rows
that have been selected, useful for displaying "pages" of results,
e.g. \fCLIMIT 10\fR would present the first 10 rows, while \fCLIMIT 101, 150\fR
would present result rows 101 through 150 (and the row count would be 50).

#include space

.LP
\fBMAXROWS\fR is a \fBshsql\fR extention that
may be used to raise the default row limit of 2000 rows (
#set FILE = "config.html#dbmaxrows"
#set TAG = configurable
#include link
) if you anticipate that a retrieval will exceed that limit.
This limit applies to the rowset before DISTINCT or LIMIT processing is applied.
If \fCMAXROWS\fR is exceeded the entire \fCSELECT\fR is cancelled.
.br
Example: \fCmaxrows 5000\fR


#include space

.LP
\fBFOR UPDATE\fR causes a
#set FILE = "recordlocking.html"
#set TAG = "record lock"
#include link
to be issued for retrieved record(s).
The table must be set up to allow
#set FILE = "recordlocking.html"
#set TAG = "record locking."
#include link
\fC*\fR must be used for the itemlist, and the \fCSELECT\fR command
must be simple form, ie no \fCJOIN\fR, \fCGROUP BY\fR, \fCLIMIT\fR, etc.

.ig >>
<a name=resultnames></a>
.>>
#include space

.SH Result field names
The results of any \fCSELECT\fR command are organized as fields, 
and each of these fields always has a name associated with it.
These names are often used by application environments to reference the
fields coming back from a database retrieval.  Field names also have other uses, for instance,
if \fCSELECT INTO\fR is being used to build a temp table, the field names will become 
the basis for the temp table's field names.
.LP
Result field name is determined as follows:
Field name alias is used if specified, otherwise original field name is used.
For \fCJOIN\fR results, the table or table alias prefix is kept, except with \fCSELECT INTO\fR, 
when the table prefix is removed from the beginning of fieldnames (use field name aliases
if there are duplicate names).
For \fCcount( * )\fR, the result field name will be \fC__rowcount\fR.
For other aggregating functions, the result field name will be the subject field name
with an appropriate suffix attached, e.g. the result of \fCavg( score )\fR will be 
called \fCscore__avg\fR.
For string constants, the result field name will be labels like \fC_QS01\fR, \fC_QS02\fR, etc.

#include space

.SH SELECT examples
.nf
select * from people


select lastname, firstname, email from people
where people_id = 578


select trans_id (as id), tag (as tname), measurement (as meas)
into $tmp1
from valuelist
where tag isnot null
order by measurement descending num, tag ascending dict
limit 51, 100


select count(*) from homesforsale where postcode like "211*"


select avg( listprice ) from homesforsale where postcode like "211*"


select desc_code, count(*) from nzplaces 
group by desc_code 
where name like "isl*"


select * from $tmp1


select * from /home/steve/data/hgb2889
maxrows 5000


select * from projects where id = 27 for update

.fi
See also the examples under JOIN, above.
#include space

.SH Notes and caveats
.LP
Numeric constants or \fCnull\fR as a constant aren't supported in the \fCSELECT\fR item list, but
may be given as string constants by enclosing in quotes.
.LP
\fCGROUP BY\fR cannot be used in the same query as \fCORDER BY\fR.
Maximum 20 field names in an \fCORDER BY\fR or \fCGROUP BY\fR specification.
.LP
All \fCGROUP BY\fR fields must also be named in the \fCSELECT\fR item list.
.LP
Table name aliases may only be specified when a \fCJOIN\fR is being done.
.LP
Aside from the described aggregation functions eg. count() or avg(),
functions and arithmetic expressions aren't supported in the
\fCSELECT\fR item list.
.LP
\fCSELECT\fR must access at least one table.  Standalone selects, eg. \fCselect "hello"\fR
are not supported.
.LP
Aggregate functions such as \fCcount(*)\fR cannot be intermingled 
with fieldnames or quoted constants in the \fCSELECT\fR item list 
unless \fCGROUP BY\fR is used.
.LP 
\fCSELECT\fR item list must contain at least one data field reference 
(except for the case of \fCselect count(*) from ...\fR).
.LP
\fCHAVING\fR is not supported.  Same functionality can be gained by 
putting \fCGROUP BY\fR results into a temp table or file, then selecting
desired rows from there.
.LP
\fCDISTINCT\fR may be needed to screen out duplicate rows in certain
instances with an indexed field when the \fCWHERE\fR clause uses \fCIN\fR or
\fCINLIKE\fR with duplicate list members in the constant.
.LP
\fCDISTINCT\fR processing may be done automatically in certain situations with
an indexed field when the \fCWHERE\fR clause contains \fCOR\fR or \fCCONTAINS\fR.



#include bottom
