urQL/docs/ref-ch05-query.md

182 lines
6.8 KiB
Markdown
Raw Normal View History

2023-05-18 05:51:26 +03:00
# QUERY
2023-05-29 04:47:58 +03:00
The `<query>` statement provides a means to create `<table-set>`s derived from persisted and/or cached `<table-set>`s and/or constants. Data rows can be joined based on predicates, specific columns can be selected, and the resulting rows can be filtered by predicate.
2023-05-25 22:42:32 +03:00
2023-05-29 04:47:58 +03:00
The full syntax involves complex manipulations at the row level through scalar functions, data aggregation across preliminary rows via aggregate functions, filtering by aggregation, and row ordering.
2023-05-25 22:42:32 +03:00
2023-05-29 04:47:58 +03:00
NOTE: scalar and aggregate functions are currently under development and not available. Also, these are subject to change.
2022-10-31 05:52:27 +03:00
2022-08-10 23:23:12 +03:00
```
<query> ::=
2023-05-15 17:39:13 +03:00
[ FROM <table-set> [ [AS] <alias> ]
2023-05-25 22:42:32 +03:00
{
{ JOIN | LEFT JOIN | RIGHT JOIN | OUTER JOIN }
<table-set> [ [AS] <alias> ]
ON <predicate>
} [ ...n ]
2023-05-15 17:39:13 +03:00
| CROSS JOIN <table-set> [ [AS] <alias> ]
2023-02-10 23:29:54 +03:00
]
2023-05-23 00:08:37 +03:00
[ { SCALAR <scalar> [ AS ] <scalar-function> } [ ...n ] ]
2023-02-10 23:29:54 +03:00
[ WHERE <predicate> ]
2023-05-25 22:42:32 +03:00
[ GROUP BY { <qualified-column>
| <column-alias>
| <column-ordinal> } [ ,...n ]
2023-02-10 23:29:54 +03:00
[ HAVING <predicate> ]
]
2023-05-25 22:42:32 +03:00
SELECT [ TOP <n> ] [ BOTTOM <n> ]
2023-06-01 22:13:59 +03:00
{ * | { [<ship-qualifier>]<table-view> | <alias> }.*
2023-03-16 23:49:28 +03:00
| <expression> [ [ AS ] <column-alias> ]
2023-02-10 23:29:54 +03:00
} [ ,...n ]
2023-05-12 00:30:15 +03:00
[ ORDER BY
{
{ <qualified-column> | <column-alias> | <column-ordinal> } { ASC | DESC }
} [ ,...n ]
2023-02-10 23:29:54 +03:00
]
2022-08-10 23:23:12 +03:00
```
2023-05-29 04:47:58 +03:00
`JOIN` is an inner join returning all matching pairs of rows.
2023-02-15 01:22:54 +03:00
2023-05-29 04:47:58 +03:00
`LEFT JOIN` is a left outer join returning all rows from the left table not meeting the join condition, along with all matching pairs of rows.
2022-10-31 05:52:27 +03:00
2023-05-29 04:47:58 +03:00
`RIGHT JOIN` is a right outer join returning all rows from the right table not meeting the join condition, along with all matching pairs of rows.
2022-10-31 05:52:27 +03:00
2023-05-29 04:47:58 +03:00
`OUTER JOIN` is a full outer join returning matching pairs of rows, as well as all rows from both tables not meeting the join condition.
`CROSS JOIN` is a cartesian join of two tables.
Cross database joins are permitted, but not cross ship joins.
`HAVING <predicate>` filters aggregated rows returned from the `<query>`. The column references in the predicate must be either one of the grouping columns or be contained in an aggregate function.
Avoid using `ORDER BY` in CTEs or in any query prior to the last step in a `<transform>`, unless required by `TOP` or `BOTTOM` specified in the `SELECT` statement or, in the case of CTEs, it is used in an `<expression>` expecting a scalar result.
2022-10-31 05:52:27 +03:00
2022-08-10 23:23:12 +03:00
```
2023-01-05 21:25:45 +03:00
<predicate> ::=
2022-10-31 05:52:27 +03:00
{ [ NOT ] <predicate> | [ ( ] <simple-predicate> [ ) ] }
[ { { AND | OR } [ NOT ] { <predicate> | [ ( ] <simple-predicate> [ ) ] }
2022-08-10 23:23:12 +03:00
[ ...n ]
]
```
2022-08-06 17:06:18 +03:00
2022-08-10 23:23:12 +03:00
```
<simple-predicate> ::=
{ expression <binary-operator> expression
2023-02-17 22:07:58 +03:00
| expression [ NOT ] EQUIV expression
2022-08-10 23:23:12 +03:00
| expression [ NOT ] IN
2023-05-25 22:42:32 +03:00
{ <scalar-query> | ( <value> ,...n ) }
| expression <inequality-operator>
{ ALL | ANY} { ( <scalar-query> ) | ( <value> ,...n ) }
2023-02-17 22:07:58 +03:00
| expression [ NOT ] BETWEEN expression [ AND ] expression
2023-05-25 22:42:32 +03:00
| [ NOT ] EXISTS { <column value> | <scalar-query> } }
2022-08-10 23:23:12 +03:00
```
2023-05-25 22:42:32 +03:00
2023-05-29 04:47:58 +03:00
When applied to a column `EXISTS` tests whether the returned `<row-type>` includes the required column. In the case of `<scalar-query>`, it tests whether a CTE returns any rows.
2023-02-16 22:49:29 +03:00
2023-05-29 04:47:58 +03:00
`[ NOT ] EQUIV` is a binary operator, similar to (not) equals `<>`, `=`. However, comparing two `NOT EXISTS` yields true.
2023-02-16 22:49:29 +03:00
2023-05-29 04:47:58 +03:00
`<scalar-query>` is a CTE that selects for one column. Depending on whether the operator expects a set or a value, it operates on the entire result set or on the first row returned, respectively. If the CTE is not ordered, results may be unpredictable.
2022-08-06 17:06:18 +03:00
2023-02-17 22:07:58 +03:00
```
<binary-operator> ::=
2023-05-25 22:42:32 +03:00
{ = | <> | != | > | >= | !> | < | <= | !< | EQUIV | NOT EQUIV}
2023-02-17 22:07:58 +03:00
```
Whitespace is not required between operands and binary-operators, except when the left operand is a numeric literal, in which case whitespace is required.
2023-05-29 04:47:58 +03:00
`<inequality-operator>` is any `<binary-operator>` other than equality and `EQUIV`.
2023-05-25 22:42:32 +03:00
2022-10-05 23:00:47 +03:00
```
<scalar-function> ::=
2023-01-05 21:25:45 +03:00
IF <predicate> THEN { <expression> | <scalar-function> }
2022-10-31 05:52:27 +03:00
ELSE { <expression> | <scalar-function> } ENDIF
2022-10-05 23:00:47 +03:00
| CASE <expression>
2023-01-05 21:25:45 +03:00
WHEN { <expression> | <predicate> }
2022-10-31 05:52:27 +03:00
THEN { <expression> | <scalar-function> } [ ...n ]
2022-10-05 23:00:47 +03:00
[ ELSE { <expression> | <scalar-function> } ]
END
| COALESCE ( <expression> [ ,...n ] )
2023-03-05 01:51:02 +03:00
| <arithmetic>
| <bitwise>
2023-02-16 22:49:29 +03:00
| <predicate>
2023-03-05 01:51:02 +03:00
| <boolean>
| <scalar>
2022-10-05 23:00:47 +03:00
```
2023-05-29 04:47:58 +03:00
If a `CASE` expression uses `<predicate>`, the expected boolean (or loobean) logic applies. If it uses `<expression>` `@`0 is treated as false and any other value as true (not loobean). (NOTE: This is preliminary design subject to change.)
2022-10-31 05:52:27 +03:00
2023-05-29 04:47:58 +03:00
`COALESCE` returns the first `<expression>` in the list that exists. Non-existence occurs when a selected `<expression>` value is not returned due to an outer join not matching or `<scalar-query>` not returning rows.
2022-10-05 23:00:47 +03:00
2023-03-05 01:51:02 +03:00
See CH 8 Functions for full documentation on Scalars.
2022-08-10 23:23:12 +03:00
```
<expression> ::=
2023-03-16 23:49:28 +03:00
{ <qualified-column>
| <constant>
2023-05-23 00:08:37 +03:00
| <scalar>
| <scalar-query>
2023-05-23 00:08:37 +03:00
| <aggregate-function>( { <column> | <scalar> } )
2022-08-10 23:23:12 +03:00
}
```
2023-05-25 22:42:32 +03:00
`<scalar-query>` is a CTE that returns only one column. The first returned value is accepted and subsequent values ignored. Ordering the CTE may be required for predictable results.
2022-08-06 17:06:18 +03:00
2023-02-16 22:49:29 +03:00
```
<aggregate-function> ::=
{ AVG | MAX | MIN | SUM | COUNT | AND | OR | <user-defined> }
```
2022-10-31 05:52:27 +03:00
```
2022-11-23 22:35:25 +03:00
<column> ::=
2023-05-18 05:51:26 +03:00
{ <qualified-column>
2022-10-31 05:52:27 +03:00
| <column-alias>
| <constant> }
```
2022-10-05 23:00:47 +03:00
```
2023-01-05 21:25:45 +03:00
<qualified-column> ::=
2023-06-01 22:13:59 +03:00
[ [ <ship-qualifier> ]<table-view> | <alias> ].<column-name>
2023-05-18 05:51:26 +03:00
```
2023-05-22 07:24:31 +03:00
## API
2022-10-05 23:00:47 +03:00
```
2023-05-18 05:51:26 +03:00
+$ query
$:
%query
from=(unit from)
scalars=(list scalar-function)
predicate=(unit predicate)
group-by=(list grouping-column)
having=(unit predicate)
selection=select
order-by=(list ordering-column)
==
```
2023-05-22 07:24:31 +03:00
## Arguments
2023-05-25 22:42:32 +03:00
**`<table-set> [ [AS] <alias> ]`**
Any valid `<table-set>`.
`<alias>` allows short-hand reference to the `<table-set>` in the `SELECT` clause and subsequent `<predicates>`.
**`{ <qualified-column> | <column-alias> | <column-ordinal> }`**
Used to select columns for ordering and grouping. `<column-ordinal>`s are 1-based.
**`[ TOP <n> ] [ BOTTOM <n> ]`**
2023-05-29 04:47:58 +03:00
`SELECT` only the first and/or last `n` rows returned by the rest of the query. If the result set is less than `n`, the entire set of rows is returned.
2023-05-25 22:42:32 +03:00
`TOP` and `BOTTOM` require the presence of an `ORDER BY` clause.
2023-05-22 07:24:31 +03:00
2023-05-25 05:33:27 +03:00
## Remarks
2023-05-25 22:42:32 +03:00
The `SELECT` clause may choose columns from a single CTE, in which case the `FROM` clause is absent. It may also choose only constants and `SCALAR` functions on constants, in which case it returns a result set of one row.
The simplest possible query is `SELECT 0`.
2023-05-29 04:47:58 +03:00
`<query>` alone does not change the Obelisk agent state.
2023-05-25 22:42:32 +03:00
2023-05-25 05:33:27 +03:00
## Produced Metadata
2023-05-25 22:42:32 +03:00
`@@ROWCOUNT` returns the total number of rows returned.
2023-05-18 05:51:26 +03:00
## Exceptions
2023-05-29 04:47:58 +03:00
Provided `<query>` attempts execution (i.e., syntax and internal consistency checks pass), the only exceptions possible are performance-related, such as timeouts and memory constraints.