.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: where clause</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 WHERE clause TDH "18-MAR-2004   TDH scg@jax.org" 

.SH WHERE clause
The \fCSELECT\fR, \fCUPDATE\fR, and \fCDELETE\fR commands involve the use of 
a \fCWHERE\fR clause to select rows.  
\fBshsql\fR's \fCWHERE\fR clause syntax does not conform to SQL standards and
is somewhat simplistic.
Nevertheless, it is reasonably powerful and flexible.

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


.SH Examples
.IP
\fCWHERE lastname = "Jones"\fR
.IP
\fCWHERE lastname LIKE "J*"\fR
.IP
\fCWHERE balance < 0.0 AND status = "A"\fR
.IP
\fCWHERE status = null\fR
or alternatively: 
\fCWHERE status IS null\fR
.IP
\fCWHERE status != null\fR
or alternatively: 
\fCWHERE status ISNOT null\fR
.IP
\fCWHERE color IN "red,green,blue"\fR
.IP
\fCWHERE desc_code IN "univ,hut,NULL"\fR
.IP
\fCWHERE placename IN "Pigeon Creek,Lost Valley"\fR
.IP
\fCWHERE name INLIKE "alb*,cran*,dela*"\fR
.IP
\fCWHERE zscore INRANGE -0.1,0.1\fR
.IP
\fCWHERE zscore OUTRANGE -2.5,2.5\fR
.IP
\fCWHERE authorlist CONTAINS "smith"\fR
.IP
\fCWHERE docname CONTAINS '"rolling stones" tour dates'\fR
.IP
\fCWHERE latitude INRANGE 38.1,38.5 OR latitude = null\fR


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

.SH Interaction with indexing
For data tables for which 
.ig >>
<a href="indexes.html">
.>>
\0indexes
.ig >>
</a>
.>>
have been created, the \fCWHERE\fR clause plays an important role in the 
index access operation.  Many (but not all) comparison operators can exploit indexes.
.ig >>
<a href="indexes.html">
.>>
\0More info.
.ig >>
</a>
.>>

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

.SH Comparisons
A where clause contains one or more comparisons.
Comparisons usually have a database field specified on the left hand 
side, an operator in the middle, and a constant is on the right hand side.  
Comparisons \fBmust\fR be structured this way is indexing is involved; otherwise the constant
may be on the left if necessary (such as when getting wild card patterns from the database
for comparison against a constant using \fCLIKE\fR).
.LP
\fBshsql\fR supports the following comparison operators in \fCWHERE\fR clauses.
Some operators have one or more alternatives that may be used if desired.
.IP
.nf
\fB= \fR        Equal to.  Case sensitive. (alt: \fB==\fR or IS)
\fB!=\fR        Not equal to (alt: \fB<>\fR or ISNOT)
\fB> \fR        Greater than.
\fB>=\fR        Greater than or equal to.
\fB< \fR        Less than.
\fB<=\fR        Less than or equal to.
\fBLIKE\fR      Wild card match.  Case insensitive.
\fB!LIKE\fR     Not a wild card match (alt: NOTLIKE)
.fi
.ig >>
<br><br><br>
.>>
.LP
\fBshsql\fR also provides the following operators which are not part of 
standard SQL (some of these are available as functions in other SQL implementations).
See also the examples above.
.IP
.ig >>
<table cellpadding=0 cellspacing=4>
.>>
.ig >>
</td></tr><tr bgcolor=F0F0F0><td>
.>>
\fBIN\fR
.ig >>
</td><td>
.>>
true if field content is a member of a 
.ig >>
<a href="#lists">
.>>
\0list
.ig >>
</a>
.>>
.br
.ig >>
</td></tr><tr bgcolor=F0F0F0><td>
.>>
\fB!IN\fR
.ig >>
</td><td>
.>>
opposite of IN.  Alternative usage: NOTIN
.br
.ig >>
</td></tr><tr bgcolor=F0F0F0><td>
.>>
\fBINLIKE\fR
.ig >>
</td><td>
.>>
similar to IN but 
.ig >>
<a href="#lists">
.>>
\0list
.ig >>
</a>
.>>
members may contain wild cards.
.br
.ig >>
</td></tr><tr bgcolor=F0F0F0><td>
.>>
\fB!INLIKE\fR
.ig >>
</td><td>
.>>
opposite of INLIKE.  Alternate usage: NOTINLIKE
.br
.ig >>
</td></tr><tr bgcolor=F0F0F0><td>
.>>
\fBINRANGE\fR
.ig >>
</td><td>
.>>
true if field content is within a numeric range, expressed as a
.ig >>
<a href="#lists">
.>>
\0list
.ig >>
</a>
.>>
(no embedded whitespace).
.br
.ig >>
</td></tr><tr bgcolor=F0F0F0><td>
.>>
\fBOUTRANGE\fR
.ig >>
</td><td>
.>>
true if field content is outside a numeric range, expressed as a
.ig >>
<a href="#lists">
.>>
\0list
.ig >>
</a>
.>>
(no embedded whitespace).
.br
.ig >>
</td></tr><tr bgcolor=F0F0F0><td>
.>>
.ig >>
<a href="multiword.html">
.>>
\0CONTAINS
.ig >>
</a>
.>>
.ig >>
</td><td>
.>>
multiword comparisons (search engine syntax).  Described on its own manual page.
.ig >>
</td></tr></table>
.>>

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

.SH Alpha vs. numeric
\fC=\fR and \fC!=\fR can be used with any data.
.LP
\fCIN\fR, \fC!IN\fR, \fCINLIKE\fR, and \fC!INLIKE\fR are intended for alphanumeric strings.
However since \fBshsql\fR is typeless, these operators can be used similarly with 
numerics eg. \fCid in "20,28,35"\fR or \fCid like "40*"\fR.  If the comparison
database field is indexed, the index should must be built as alpha, not numeric, in order
for this to work.
.LP
Numeric-only comparison operators are: \fC > >= < <= INRANGE OUTRANGE\fR.
If the comparison database field is indexed, the index must be built with
.ig >>
<a href="create.html#index">
.>>
\0ORDER = NUMERIC
.ig >>
</a>
.>>
in order for numeric comparisons to work properly.



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

.SH Case sensitivity
The \fC=\fR and \fC!=\fR operators are case sensitive.  The other operations are case insensitive.
To do a direct case-insensitive comparison use \fCLIKE\fR instead of \fC=\fR.

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

.SH Lists
The \fCIN\fR, \fCINLIKE\fR, and \fCINRANGE\fR comparison operators (as well as their inverses)
take a 
.ig >>
<a href="commalist.html">
.>>
\0comma-delimited list
.ig >>
</a>
.>>
as the right side operand.  
.LP
For \fCIN\fR and \fCINLIKE\fR (and inverses) the list should be enclosed in quotes,
\fCNULL\fR is permitted as a list member, and individual members may contain embedded 
spaces, which will be considered part of the individual.
Zero-length members are ignored; if the entire list is a zero-length string it is taken as \fCNULL\fR.
.LP
For \fCINRANGE\fR and \fCOUTRANGE\fR, the values are numbers, the list should not be enclosed
in quotes, should not have any \fCNULL\fR members, and should not contain any embedded whitespace.
The examples at top of this page include some that use comma-delimited lists.
Note that the
.ig >>
<a href="multiword.html">
.>>
\0CONTAINS
.ig >>
</a>
.>>
operator can also be used with comma-delimited lists, however "words" are delimited not just on
commas but on any whitespace or punctuation.
.LP
Sometimes \fCSELECT DISTINCT\fR is in effect automatically when list comparison operators are used
on indexed fields..  see the notes at the end of the
.ig >>
<a href="indexes.html">
.>>
\0indexes manual page.
.ig >>
</a>
.>>



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

.SH Wild card characters
Wild card matching may be done using \fCLIKE\fR, \fC!LIKE\fR, \fCINLIKE\fR, and \fC!INLIKE\fR.
Wild card characters are \fB*\fR which 
matches any number of any character, and \fB?\fR which matches a single
instance of any character.  Matching is case-insensitive.
Full-fledged regular expressions capability is not implemented,
and use of the \fC*\fR character is limited to the following positions: 
\fC*abc\fR, \fCabc*\fR, \fCab*cd\fR, and \fC*abc*\fR.  \fC?\fR may be 
used anywhere.
(\fC%\fR may be used rather than \fB*\fR by setting \fCdbwildcard\fR in your 
.ig >>
<a href="config.html#dbwildcard">
.>>
\0project config file.
.ig >>
</a>
.>>
)

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

.SH NULL handling
.ig >>
<a href="null.html">
.>>
\0Described here.
.ig >>
</a>
.>>

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

.SH Searching text fields
The 
.ig >>
<a href="multiword.html">
.>>
\0CONTAINS operator
.ig >>
</a>
.>>
allows multiword fields to be searched using a "search engine" syntax.

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

.SH Compound conditionals, and presidence
A compound conditional is two or more conditionals that are connected
using the \fBAND\fR and/or \fBOR\fR logical connectors:
.IP
.nf
\fBAND\fR       logical AND (alternate symbol: \fB&&\fR)
\fBOR\fR        logical OR (alternate symbol: \fB||\fR)
.fi
.LP
\fBPresidence:\fR compound conditional expressions are evaluated by splitting into \fCOR\fR
terms, and then evaluating each term starting with the leftmost.
For example:
.IP
.nf
\fCwhere  A = 1  and  B = 2  OR  C = null\fR

would be split into these terms: 

1.)  A = 1 and B = 2
2.)  C = null
.fi
.LP
\fBshsql\fR does not allow presidence to be altered by use of parentheses.  
The provided operators such as \fCIN\fR, \fCINLIKE\fR, \fCINRANGE\fR and \fCOUTRANGE\fR 
may be useful in eliminating lower-level \fCOR\fRs.
It may also be helpful to capitalize \fCOR\fRs to emphasize their presidence.
.LP
\fCSELECT DISTINCT\fR will be in effect automatically when \fCOR\fR is used
with a query involving indexed fields..  see the notes at the end of the
.ig >>
<a href="indexes.html">
.>>
\0indexes manual page.
.ig >>
</a>
.>>

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

.SH Functions and arithmetic expressions
.LP
These are not supported in \fBshsql\fR \fCWHERE\fR clauses.


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