shsql: where clause

SQL database system
| Manual page for WHERE(clause)

## WHERE clause

The `SELECT`, `UPDATE`, and `DELETE` commands involve the use of a `WHERE` clause to select rows. shsql's `WHERE` clause syntax does not conform to SQL standards and is somewhat simplistic.`` Nevertheless, it is reasonably powerful and flexible.``

## Examples

  `WHERE lastname = "Jones"`

  `WHERE lastname LIKE "J*"`

  `WHERE balance < 0.0 AND status = "A"`

  `WHERE status = null` or alternatively: `WHERE status IS null`

  `WHERE status != null` or alternatively: `WHERE status ISNOT null`

  `WHERE color IN "red,green,blue"`

  `WHERE desc_code IN "univ,hut,NULL"`

  `WHERE placename IN "Pigeon Creek,Lost Valley"`

  `WHERE name INLIKE "alb*,cran*,dela*"`

  `WHERE zscore INRANGE -0.1,0.1`

  `WHERE zscore OUTRANGE -2.5,2.5`

  `WHERE authorlist CONTAINS "smith"`

  `WHERE docname CONTAINS '"rolling stones" tour dates'`

  `WHERE latitude INRANGE 38.1,38.5 OR latitude = null`

## Interaction with indexing

For data tables for which indexes have been created, the `WHERE` clause plays an important role in the index access operation. Many (but not all) comparison operators can exploit indexes.`` More info.``

## 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 must 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 `LIKE`).``

shsql supports the following comparison operators in `WHERE` clauses.`` Some operators have one or more alternatives that may be used if desired.``

      =         Equal to.  Case sensitive. (alt: == or IS)
      !=        Not equal to (alt: <> or ISNOT)
      >         Greater than.
      >=        Greater than or equal to.
      <         Less than.
      <=        Less than or equal to.
      LIKE      Wild card match.  Case insensitive.
      !LIKE     Not a wild card match (alt: NOTLIKE)

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

  IN | true if field content is a member of a list
  !IN | opposite of IN. Alternative usage: NOTIN
  INLIKE | similar to IN but list members may contain wild cards.``
  !INLIKE | opposite of INLIKE. Alternate usage: NOTINLIKE
  INRANGE | true if field content is within a numeric range, expressed as a list (no embedded whitespace).``
  OUTRANGE | true if field content is outside a numeric range, expressed as a list (no embedded whitespace).``
  CONTAINS | multiword comparisons (search engine syntax). Described on its own manual page.``

## Alpha vs. numeric

`=` and `!=` can be used with any data.``

`IN`, `!IN`, `INLIKE`, and `!INLIKE` are intended for alphanumeric strings.`` However since shsql is typeless, these operators can be used similarly with numerics eg. `id in "20,28,35"` or `id like "40*"`. If the comparison database field is indexed, the index should must be built as alpha, not numeric, in order for this to work.``

Numeric-only comparison operators are: `> >= < <= INRANGE OUTRANGE`.`` If the comparison database field is indexed, the index must be built with ORDER = NUMERIC in order for numeric comparisons to work properly.``

## Case sensitivity

The `=` and `!=` operators are case sensitive. The other operations are case insensitive.`` To do a direct case-insensitive comparison use `LIKE` instead of `=`.``

## Lists

The `IN`, `INLIKE`, and `INRANGE` comparison operators (as well as their inverses) take a comma-delimited list as the right side operand.

For `IN` and `INLIKE` (and inverses) the list should be enclosed in quotes, `NULL` 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 `NULL`.``

For `INRANGE` and `OUTRANGE`, the values are numbers, the list should not be enclosed in quotes, should not have any `NULL` 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 CONTAINS operator can also be used with comma-delimited lists, however "words" are delimited not just on commas but on any whitespace or punctuation.``

Sometimes `SELECT DISTINCT` is in effect automatically when list comparison operators are used on indexed fields.. see the notes at the end of the indexes manual page.``

## Wild card characters

Wild card matching may be done using `LIKE`, `!LIKE`, `INLIKE`, and `!INLIKE`.`` Wild card characters are * which matches any number of any character, and ? which matches a single instance of any character. Matching is case-insensitive.`` Full-fledged regular expressions capability is not implemented, and use of the `*` character is limited to the following positions: `*abc`, `abc*`, `ab*cd`, and `*abc*`. `?` may be used anywhere.`` (`%` may be used rather than * by setting `dbwildcard` in your project config file.`` )

## NULL handling

Described here.``

## Searching text fields

The CONTAINS operator allows multiword fields to be searched using a "search engine" syntax.``

## Compound conditionals, and presidence

A compound conditional is two or more conditionals that are connected using the AND and/or OR logical connectors:

      AND       logical AND (alternate symbol: &&)
      OR        logical OR (alternate symbol: ||)

Presidence: compound conditional expressions are evaluated by splitting into `OR` terms, and then evaluating each term starting with the leftmost.`` For example:

      where  A = 1  and  B = 2  OR  C = null

      would be split into these terms:

      1.)  A = 1 and B = 2
      2.)  C = null

shsql does not allow presidence to be altered by use of parentheses. The provided operators such as `IN`, `INLIKE`, `INRANGE` and `OUTRANGE` may be useful in eliminating lower-level `OR`s.`` It may also be helpful to capitalize `OR`s to emphasize their presidence.``

`SELECT DISTINCT` will be in effect automatically when `OR` is used with a query involving indexed fields.. see the notes at the end of the indexes manual page.``

## Functions and arithmetic expressions

These are not supported in shsql `WHERE` clauses.``
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` March 18, 2004.