.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
        OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }

        H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
        H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
        H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
        H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>shsql: select</title>
<body bgcolor=99cc99 vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550 ><tr>
<td align=right><a href="shsql_home.html">
<img src="img/shsql.gif" border=0><br><small>SQL database system</a> &nbsp; </td></tr>
<td>
.>>

.TH SELECT TDH "19-MAR-2004   TDH scg@jax.org" 


.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 
.ig >>
<a href="temptables.html">
.>>
\0temporary tables
.ig >>
</a>
.>>
and
.ig >>
<a href="ordfiles.html">
.>>
\0ordinary files.
.ig >>
</a>
.>>
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]

.ig >>
<br><br><br>
.>>

.LP
\fBDISTINCT\fR eliminates duplicate result rows.  

.ig >>
<br><br><br>
.>>

.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.

.ig >>
<br><br><br>
.>>
.ig >>
<a name=into></a>
.>>

.LP
\fBINTO\fR causes the results to be written to a 
.ig >>
<a href="temptables.html">
.>>
\0temporary table
.ig >>
</a>
.>>
or
.ig >>
<a href="ordfiles.html">
.>>
\0ordinary file.
.ig >>
</a>
.>>
\fBshsql\fR also allows SELECT INTO to write the results to a
.ig >>
<a href="tables.html">
.>>
\0database table
.ig >>
</a>
.>>
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).

.ig >>
<br><br><br>
.>>

.LP
\fBFROM\fR names the 
.ig >>
<a href="tables.html">
.>>
\0table,
.ig >>
</a>
.>>
.ig >>
<a href="temptables.html">
.>>
\0temporary table,
.ig >>
</a>
.>>
or
.ig >>
<a href="ordfiles.html">
.>>
\0ordinary file
.ig >>
</a>
.>>
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>
.>>

.ig >>
<br><br><br>
.>>

.LP
\fBJOIN\fR causes a relational join to be performed using two or three tables.  
Described on the
.ig >>
<a href="join.html">
.>>
\0JOIN manual page.
.ig >>
</a>
.>>
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.


.ig >>
<br><br><br>
.>>

.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.

.ig >>
<br><br><br>
.>>
.LP
\fBWHERE\fR
specifies a conditional expression to select records of interest, in the form of a
.ig >>
<a href="whereclause.html">
.>>
\0WHERE clause
.ig >>
</a>
.>>
\0.  If not specified, all rows in the table will be presented.

.ig >>
<a name=orderby></a>
.>>
.ig >>
<br><br><br>
.>>

.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 
.ig >>
&nbsp; &nbsp;
.>>
normal order (a..z, 0..9)
.br
\fCDESCENDING DESC\fR 
.ig >>
&nbsp; &nbsp;
.>>
reverse order (z..a, 9..0)
.br
\fCNUMERIC NUM\fR 
.ig >>
&nbsp; &nbsp;
.>>
numeric sort (necessary since shsql doesn't use datatypes)
.br
\fCMAGNITUDE MAG\fR
.ig >>
&nbsp; &nbsp;
.>>
same as numeric but based on absolute values 
.br
\fCDICT\fR 
.ig >>
&nbsp; &nbsp;
.>>
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.

.ig >>
<br><br><br>
.>>

.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).

.ig >>
<br><br><br>
.>>

.LP
\fBMAXROWS\fR is a \fBshsql\fR extention that
may be used to raise the default row limit of 2000 rows (
.ig >>
<a href="config.html#dbmaxrows">
.>>
\0configurable
.ig >>
</a>
.>>
) 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


.ig >>
<br><br><br>
.>>

.LP
\fBFOR UPDATE\fR causes a
.ig >>
<a href="recordlocking.html">
.>>
\0record lock
.ig >>
</a>
.>>
to be issued for retrieved record(s).
The table must be set up to allow
.ig >>
<a href="recordlocking.html">
.>>
\0record locking.
.ig >>
</a>
.>>
\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>
.>>
.ig >>
<br><br><br>
.>>

.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.

.ig >>
<br><br><br>
.>>

.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.
.ig >>
<br><br><br>
.>>

.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.



.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="shsql_home.html">
<img src="img/shsql.gif" border=0></a><br>
<a href="Copyright.html">Copyright Steve Grubb</a> &nbsp;
</td></tr>
</table>
.>>
