shsql: select

SQL database system
| Manual page for SELECT(TDH)

## SELECT

SELECT retrieves data from one table or from a relational join performed using two tables.`` It can also retrieve or join data located in temporary tables and ordinary files.`` 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:

  `SELECT [DISTINCT]` itemlist`
  [INTO` table`|`filename`[APPEND|TABLE]]
  FROM` table`[AND` table2`..] [` jointype table2`.. ON` on-clause`]
  [GROUP BY` groupbylist`]
  [WHERE` conditional-expression`]
  [ORDER BY` orderlist`]
  [LIMIT [`firstrow`],` lastrow`]
  [MAXROWS` maxrows`]
  [FOR UPDATE]
  `

DISTINCT eliminates duplicate result rows.

itemlist is a list of fieldnames, aggregate functions, or quoted string constants.`` Commas should separate items.`` An asterisk (`*`) may appear alone to select all fields, or may be used to match a subset of fields, e.g. `t1.*`.`` `AS` or `=` may be used to specify fieldname aliases (however, natural field names, not aliases, must be used other parts of the command (`WHERE`, `ORDER BY`, etc.).`` Aggregate functions such as count() may be given in itemlist; these may be used alone to operate on all requested rows, or with `GROUP BY`, to operate on groups of records.`` Supported aggregate functions are: count(), sum(), avg(), min(), and max().`` `count(` fieldname ) counts the number of non-null instances of fieldname; `count(*)` counts the number of rows.`` The other functions must contain one field name within the parentheses.``

INTO causes the results to be written to a temporary table or ordinary file.`` shsql also allows SELECT INTO to write the results to a database table however, either the `TABLE` or `APPEND` keyword must be present.`` `APPEND` may be used to append the results to existing content (but shsql does not verify field format consistency).``

FROM names the table, temporary table, or ordinary file from which data will be retrieved.`` shsql also allows more than one table (etc.) to be involved by connecting table names with `AND`, eg: `SELECT .. FROM masterlist AND $tmplist1 AND $tmplist2`.`` 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 `WHERE`, `ORDER BY`, `GROUP BY` etc. may be applied.`` All tables must have the same field format (but shsql does not check this); also, this feature can't be combined with `JOIN` or `SELECT..FOR UPDATE`.``

JOIN causes a relational join to be performed using two or three tables. Described on the JOIN manual page.`` If a `JOIN` is involved, fieldnames must be specified using tablename`.`fieldname notation everywhere in the SELECT command (where tablename is the actual name or an alias).`` `JOIN` cannot be used along with `..FOR UPDATE`.``

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

WHERE specifies a conditional expression to select records of interest, in the form of a WHERE clause . If not specified, all rows in the table will be presented.``

ORDER BY controls the ordering of the result rows.`` orderlist is a list of field names to use in the sort.`` Each field name in orderlist may optionally be followed by one or more of the following keywords:

  `ASCENDING ASC` normal order (a..z, 0..9)
  `DESCENDING DESC` reverse order (z..a, 9..0)
  `NUMERIC NUM` numeric sort (necessary since shsql doesn't use datatypes)
  `MAGNITUDE MAG` same as numeric but based on absolute values
  `DICT` dictionary order; punctuation characters are ignored

By default, the sort method is ASCENDING, and alpha method is used.`` Note: currently only 'C' locale is supported on ORDER BY.``

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

MAXROWS is a shsql extention that may be used to raise the default row limit of 2000 rows ( configurable ) if you anticipate that a retrieval will exceed that limit.`` This limit applies to the rowset before DISTINCT or LIMIT processing is applied.`` If `MAXROWS` is exceeded the entire `SELECT` is cancelled.``
Example: `maxrows 5000`

FOR UPDATE causes a record lock to be issued for retrieved record(s).`` The table must be set up to allow record locking.`` `*` must be used for the itemlist, and the `SELECT` command must be simple form, ie no `JOIN`, `GROUP BY`, `LIMIT`, etc.``

## Result field names

The results of any `SELECT` 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 `SELECT INTO` is being used to build a temp table, the field names will become the basis for the temp table's field names.``

Result field name is determined as follows: Field name alias is used if specified, otherwise original field name is used.`` For `JOIN` results, the table or table alias prefix is kept, except with `SELECT INTO`, when the table prefix is removed from the beginning of fieldnames (use field name aliases if there are duplicate names).`` For `count( * )`, the result field name will be `__rowcount`.`` For other aggregating functions, the result field name will be the subject field name with an appropriate suffix attached, e.g. the result of `avg( score )` will be called `score__avg`.`` For string constants, the result field name will be labels like `_QS01`, `_QS02`, etc.``

## SELECT examples

    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

See also the examples under JOIN, above.``

## Notes and caveats

Numeric constants or `null` as a constant aren't supported in the `SELECT` item list, but may be given as string constants by enclosing in quotes.``

`GROUP BY` cannot be used in the same query as `ORDER BY`.`` Maximum 20 field names in an `ORDER BY` or `GROUP BY` specification.``

All `GROUP BY` fields must also be named in the `SELECT` item list.``

Table name aliases may only be specified when a `JOIN` is being done.``

Aside from the described aggregation functions eg. count() or avg(), functions and arithmetic expressions aren't supported in the `SELECT` item list.``

`SELECT` must access at least one table. Standalone selects, eg. `select "hello"` are not supported.``

Aggregate functions such as `count(*)` cannot be intermingled with fieldnames or quoted constants in the `SELECT` item list unless `GROUP BY` is used.``

`SELECT` item list must contain at least one data field reference (except for the case of `select count(*) from ...`).``

`HAVING` is not supported. Same functionality can be gained by putting `GROUP BY` results into a temp table or file, then selecting desired rows from there.``

`DISTINCT` may be needed to screen out duplicate rows in certain instances with an indexed field when the `WHERE` clause uses `IN` or `INLIKE` with duplicate list members in the constant.``

`DISTINCT` processing may be done automatically in certain situations with an indexed field when the `WHERE` clause contains `OR` or `CONTAINS`.``
Copyright Steve Grubb

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