The process of retrieving or the command to retrieve data from a database is called a Query. The select, selectStar, selectDotStar, selectDistinct, selectDistinctStar and selectDistinctDotStar commands are used to specify queries.

simple query:

>>> :{
let
  query :: Query '["tab" ::: '["col" ::: 'Required ('Null 'PGint4)]] '[]
    '["col" ::: 'Required ('Null 'PGint4)]
  query = selectStar (from (Table (#tab `As` #t)))
in renderQuery query
:}
"SELECT * FROM tab AS t"

restricted query:

>>> :{
let
  query :: Query
    '[ "tab" :::
       '[ "col1" ::: 'Required ('NotNull 'PGint4)
        , "col2" ::: 'Required ('NotNull 'PGint4) ]]
    '[]
    '[ "sum" ::: 'Required ('NotNull 'PGint4)
     , "col1" ::: 'Required ('NotNull 'PGint4) ]
  query = 
    select
      ((#col1 + #col2) `As` #sum :* #col1 `As` #col1 :* Nil)
      ( from (Table (#tab `As` #t))
        & where_ (#col1 .> #col2)
        & where_ (#col2 .> 0) )
in renderQuery query
:}
"SELECT (col1 + col2) AS sum, col1 AS col1 FROM tab AS t WHERE ((col1 > col2) AND (col2 > 0))"

subquery:

>>> :{
let
  query :: Query '["tab" ::: '["col" ::: 'Required ('Null 'PGint4)]] '[]
    '["col" ::: 'Required ('Null 'PGint4)]
  query =
    selectStar
      (from (Subquery (selectStar (from (Table (#tab `As` #t))) `As` #sub)))
in renderQuery query
:}
"SELECT * FROM (SELECT * FROM tab AS t) AS sub"

limits and offsets:

>>> :{
let
  query :: Query '["tab" ::: '["col" ::: 'Required ('Null 'PGint4)]] '[]
    '["col" ::: 'Required ('Null 'PGint4)]
  query = selectStar
    (from (Table (#tab `As` #t)) & limit 100 & offset 2 & limit 50 & offset 2)
in renderQuery query
:}
"SELECT * FROM tab AS t LIMIT 50 OFFSET 4"

parameterized query:

>>> :{
let
  query :: Query '["tab" ::: '["col" ::: 'Required ('NotNull 'PGfloat8)]]
    '[ 'Required ('NotNull 'PGfloat8)]
    '["col" ::: 'Required ('NotNull 'PGfloat8)]
  query = selectStar
    (from (Table (#tab `As` #t)) & where_ (#col .> param @1))
in renderQuery query
:}
"SELECT * FROM tab AS t WHERE (col > ($1 :: float8))"

aggregation query:

>>> :{
let
  query :: Query
    '[ "tab" :::
       '[ "col1" ::: 'Required ('NotNull 'PGint4)
        , "col2" ::: 'Required ('NotNull 'PGint4) ]]
    '[]
    '[ "sum" ::: 'Required ('NotNull 'PGint4)
     , "col1" ::: 'Required ('NotNull 'PGint4) ]
  query =
    select (sum_ #col2 `As` #sum :* #col1 `As` #col1 :* Nil)
    ( from (Table (#tab `As` #table1))
      & group (By #col1 :* Nil) 
      & having (#col1 + sum_ #col2 .> 1) )
in renderQuery query
:}
"SELECT sum(col2) AS sum, col1 AS col1 FROM tab AS table1 GROUP BY col1 HAVING ((col1 + sum(col2)) > 1)"

sorted query:

>>> :{
let
  query :: Query '["tab" ::: '["col" ::: 'Required ('Null 'PGint4)]] '[]
    '["col" ::: 'Required ('Null 'PGint4)]
  query = selectStar
    (from (Table (#tab `As` #t)) & orderBy [#col & AscNullsFirst])
in renderQuery query
:}
"SELECT * FROM tab AS t ORDER BY col ASC NULLS FIRST"

joins:

>>> :set -XFlexibleContexts
>>> :{
let
  query :: Query
    '[ "orders" :::
         '[ "id"    ::: 'Required ('NotNull 'PGint4)
          , "price"   ::: 'Required ('NotNull 'PGfloat4)
          , "customer_id" ::: 'Required ('NotNull 'PGint4)
          , "shipper_id"  ::: 'Required ('NotNull 'PGint4)
          ]
     , "customers" :::
         '[ "id" ::: 'Required ('NotNull 'PGint4)
          , "name" ::: 'Required ('NotNull 'PGtext)
          ]
     , "shippers" :::
         '[ "id" ::: 'Required ('NotNull 'PGint4)
          , "name" ::: 'Required ('NotNull 'PGtext)
          ]
     ]
    '[]
    '[ "order_price" ::: 'Required ('NotNull 'PGfloat4)
     , "customer_name" ::: 'Required ('NotNull 'PGtext)
     , "shipper_name" ::: 'Required ('NotNull 'PGtext)
     ]
  query = select
    ( #o ! #price `As` #order_price :*
      #c ! #name `As` #customer_name :*
      #s ! #name `As` #shipper_name :* Nil )
    ( from (Table (#orders `As` #o)
      & InnerJoin (Table (#customers `As` #c))
        (#o ! #customer_id .== #c ! #id)
      & InnerJoin (Table (#shippers `As` #s))
        (#o ! #shipper_id .== #s ! #id)) )
in renderQuery query
:}
"SELECT o.price AS order_price, c.name AS customer_name, s.name AS shipper_name FROM orders AS o INNER JOIN customers AS c ON (o.customer_id = c.id) INNER JOIN shippers AS s ON (o.shipper_id = s.id)"

self-join:

>>> :{
let
  query :: Query '["tab" ::: '["col" ::: 'Required ('Null 'PGint4)]] '[]
    '["col" ::: 'Required ('Null 'PGint4)]
  query = selectDotStar #t1
    (from (Table (#tab `As` #t1) & CrossJoin (Table (#tab `As` #t2))))
in renderQuery query
:}
"SELECT t1.* FROM tab AS t1 CROSS JOIN tab AS t2"

set operations:

>>> :{
let
  query :: Query '["tab" ::: '["col" ::: 'Required ('Null 'PGint4)]] '[]
    '["col" ::: 'Required ('Null 'PGint4)]
  query =
    selectStar (from (Table (#tab `As` #t)))
    `unionAll`
    selectStar (from (Table (#tab `As` #t)))
in renderQuery query
:}
"(SELECT * FROM tab AS t) UNION ALL (SELECT * FROM tab AS t)"

The results of two queries can be combined using the set operation union. Duplicate rows are eliminated.

The results of two queries can be combined using the set operation unionAll, the disjoint union. Duplicate rows are retained.

The results of two queries can be combined using the set operation intersect, the intersection. Duplicate rows are eliminated.

The results of two queries can be combined using the set operation intersectAll, the intersection. Duplicate rows are retained.

The results of two queries can be combined using the set operation except, the set difference. Duplicate rows are eliminated.

The results of two queries can be combined using the set operation exceptAll, the set difference. Duplicate rows are retained.

the TableExpression in the select command constructs an intermediate virtual table by possibly combining tables, views, eliminating rows, grouping, etc. This table is finally passed on to processing by the select list. The select list determines which columns of the intermediate table are actually output.

After the select list has been processed, the result table can be subject to the elimination of duplicate rows using selectDistinct.

The simplest kind of query is selectStar which emits all columns that the table expression produces.

A selectDistinctStar emits all columns that the table expression produces and eliminates duplicate rows.

When working with multiple tables, it can also be useful to ask for all the columns of a particular table, using selectDotStar.

A selectDistinctDotStar asks for all the columns of a particular table, and eliminates duplicate rows.

A TableExpression computes a table. The table expression contains a fromClause that is optionally followed by a whereClause, groupByClause, havingClause, orderByClause, limitClause and offsetClauses. Trivial table expressions simply refer to a table on disk, a so-called base table, but more complex expressions can be used to modify or combine base tables in various ways.

Render a TableExpression

A from generates a TableExpression from a table reference that can be a table name, or a derived table such as a subquery, a JOIN construct, or complex combinations of these. A from may be transformed by where_, group, having, orderBy, limit and offset, using the & operator to match the left-to-right sequencing of their placement in SQL.

A where_ is an endomorphism of TableExpressions which adds a search condition to the whereClause.

A group is a transformation of TableExpressions which switches its Grouping from Ungrouped to Grouped. Use group Nil to perform a "grand total" aggregation query.

A having is an endomorphism of TableExpressions which adds a search condition to the havingClause.

An orderBy is an endomorphism of TableExpressions which appends an ordering to the right of the orderByClause.

A limit is an endomorphism of TableExpressions which adds to the limitClause.

An offset is an endomorphism of TableExpressions which adds to the offsetClause.

A FromClause can be a table name, or a derived table such as a subquery, a JOIN construct, or complex combinations of these.

• A real Table is a table from the schema.
• Subquery derives a table from a Query.

• A joined table is a table derived from two other (real or derived) tables according to the rules of the particular join type. CrossJoin, InnerJoin, LeftOuterJoin, RightOuterJoin and FullOuterJoin are available and can be nested using the & operator to match the left-to-right sequencing of their placement in SQL.

  • t1 & CrossJoin t2. For every possible combination of rows from t1 and t2 (i.e., a Cartesian product), the joined table will contain a row consisting of all columns in t1 followed by all columns in t2. If the tables have n and m rows respectively, the joined table will have n * m rows.
  • t1 & InnerJoin t2 on. For each row r1 of t1, the joined table has a row for each row in t2 that satisfies the on condition with r1
  • t1 & LeftOuterJoin t2 on. First, an inner join is performed. Then, for each row in t1 that does not satisfy the on condition with any row in t2, a joined row is added with null values in columns of t2. Thus, the joined table always has at least one row for each row in t1.
  • t1 & RightOuterJoin t2 on. First, an inner join is performed. Then, for each row in t2 that does not satisfy the on condition with any row in t1, a joined row is added with null values in columns of t1. This is the converse of a left join: the result table will always have a row for each row in t2.
  • t1 & FullOuterJoin t2 on. First, an inner join is performed. Then, for each row in t1 that does not satisfy the on condition with any row in t2, a joined row is added with null values in columns of t2. Also, for each row of t2 that does not satisfy the join condition with any row in t1, a joined row with null values in the columns of t1 is added.

Renders a FromClause.

Bys are used in group to reference a list of columns which are then used to group together those rows in a table that have the same values in all the columns listed. By #col will reference an unambiguous column col; otherwise By2 (#tab ! #col) will reference a table qualified column tab.col.

Renders a By.

A GroupByClause indicates the Grouping of a TableExpression. A NoGroups indicates Ungrouped while a Group indicates Grouped. NoGroups is distinguised from Group Nil since no aggregation can be done on NoGroups while all output Expressions must be aggregated in Group Nil.

Renders a GroupByClause.

A HavingClause is used to eliminate groups that are not of interest. An Ungrouped TableExpression may only use NoHaving while a Grouped TableExpression must use Having whose conditions are combined with .&&.

Render a HavingClause.

SortExpressions are used by sortBy to optionally sort the results of a Query. Asc or Desc set the sort direction of a NotNull result column to ascending or descending. Ascending order puts smaller values first, where "smaller" is defined in terms of the .< operator. Similarly, descending order is determined with the .> operator. AscNullsFirst, AscNullsLast, DescNullsFirst and DescNullsLast options are used to determine whether nulls appear before or after non-null values in the sort ordering of a Null result column.

Render a SortExpression.