urQL/docs/ref-ch08-functions.md

# Functions

**IMPORTANT NOTE**: the design of functions is still on-going. Nothing is implemented in the parser and take the following as preliminary design work.

Urql has two kinds of functions.

Scalar functions take one or more columns as parameters from a single intermediary data row and return a single scalar value. Scalar functions must be declared after the `CTEs` and `FROM` clauses and before the `SELECT` clause. The user-assigned scalar name may be used in any predicate or `SELECT` clause.

Aggregate functions operate on a single column of intermediary data rows. They are always declared inline in a `SELECT` clause or `HAVING` predicate by the function name, no space, open and close parenthesis which contain parameters specific to the function including the intermediary data column.

## Boolean Functions

Boolean funtions can be Scalar or Aggregate and depending on their context must follow rules for either type.

If `<expression>` is of loobean type (%.y, %.n) normal boolean evaluation proceeds.  Evaluation of any other type evaluates as boolean TRUE unless `EXISTS <expression>` evaluates as FALSE.


```
AND ::=
  AND(<expression 1>, ..., <expression n>)
```

```
OR ::=
  OR(<expression 1>, ..., <expression n>)
```

```
XOR ::=
  XOR(<expression 1>, <expression 2>)
```

```
NOT ::=
  NOT(<expression)
```

## Scalar Functions

`<expression>` many be another scalar function, but not aggregate functions.

### arithmetic operators

```
<addition> ::= 
    <expression> + <expression>
```

```
<subtraction> ::=
  <expression> - <expression>
```

```
<multiplication> ::=
  <expression> * <expression>
```

```
<division> ::=
  <expression> / <expression>
```

```
<modulo> ::=
  <expression> % <expression>
```
Returns the integer remainder of a division.

```
<negation> ::=
  NOT <expression>
```
NOT (-4) → 4

```
<exponentiation> ::=
  <expression> ^ <expression>
```
2 ^ 3 → 8

Unlike typical mathematical practice, multiple uses of ^ will associate left to right by default:

2 ^ 3 ^ 3 → 512

2 ^ (3 ^ 3) → 134217728

### bitwise operators

```
<bitwise AND> ::=
  <expression> & <expression>
```
91 & 15 → 11

```
<bitwise OR> ::=
  <expression> | <expression>
```
32 | 3 → 35

```
<bitwise Exclusive OR> ::=
  <expression> # <expression>
```
17 # 5 → 20

```
<bitwise NOT> ::=
  _ <expression>
```
_ 1 → -2

```
<bitwise shift left> ::=
  <expression> << @ud
```
1 << 4 → 16

>> (Shift right)

```
<bitwise shift right> ::=
  <expression> >> @ud
```
8 >> 2 → 2

### predicate

```
<predicate> ::=
  <predicate>
```
A scalar returning a predicate follows the same construction rules as a `WHERE` predicate.

(misc scalars)
https://learn.microsoft.com/en-us/sql/odbc/reference/appendixes/appendix-e-scalar-functions?view=sql-server-ver16
https://www.postgresql.org/docs/14/functions.html

### string scalars

https://learn.microsoft.com/en-us/sql/odbc/reference/appendixes/string-functions?view=sql-server-ver16
https://www.postgresql.org/docs/14/functions-string.html
https://www.postgresql.org/docs/15/functions-binarystring.html
https://www.postgresql.org/docs/15/functions-bitstring.html

### numeric scalars

https://learn.microsoft.com/en-us/sql/odbc/reference/appendixes/numeric-functions?view=sql-server-ver16
https://www.postgresql.org/docs/15/functions-math.html

### date scalars

https://learn.microsoft.com/en-us/sql/odbc/reference/appendixes/time-date-and-interval-functions?view=sql-server-ver16
https://www.postgresql.org/docs/15/functions-datetime.html

### conversion and casting

https://learn.microsoft.com/en-us/sql/odbc/reference/appendixes/explicit-data-type-conversion-function?view=sql-server-ver16
https://learn.microsoft.com/en-us/sql/odbc/reference/appendixes/sql-92-cast-function?view=sql-server-ver16
https://www.postgresql.org/docs/14/functions-formatting.html

## Aggregate Functions

`<expression>` many be a scalar function or another aggregate function.

https://learn.microsoft.com/en-us/sql/t-sql/functions/aggregate-functions-transact-sql?view=sql-server-ver16
https://www.postgresql.org/docs/15/functions-aggregate.html