urQL/docs/ref-ch02-types.md

# Types
All data representations (nouns) of the Obelisk system are strongly typed.

## Column Types
The fundamental data element is an atom typed by an aura. 
All data cells (the intersection of a `<table-set>` row and column) are a typed atom. 

Obelisk supports the following auras:

|aura|type|representation|
|----|----|--------------|
|@c|unicode codepoint|~-~45fed.|
|@da|date, absolute|~2020.12.25..7.15.0..1ef5|
|@dr|date, relative|~d71.h19.m26.s24.9d55|
|@f|loobean|%.y|
|@if|IPv4 address|.195.198.143.90|
|@is|IPv6 address|.0.0.0.0.0.1c.c3c6.8f5a|
|@p|phonemic base|~laszod-dozser-fosrum-fanbyr|
|@q|phonemic base, unscrambled|.~laszod-dozser-dalteb-hilsyn|
|@rh|IEEE-754 half-precision, 16-bit|.~~3.14|
|@rs|IEEE-754 single-precision, 32-bit|.3.141592653589793|
|@rd|IEEE-754 double-precision, 64-bit|.~3.141592653589793|
|@rq|IEEE-754 quadruple-precision, 128-bit|.~~~3.141592653589793|
|@s|integer, signed (sign bit low)||
|@sb|signed binary|--0b10.0000|
|@sd|signed decimal|--1.000|
|@sv|signed base-32|--0v201.4gvml.245kc|
|@sw|signed base-64|--0w2.04AfS.G8xqc|
|@sx|signed hexadecimal|--0x2004.90fd|
|@t|UTF-8 text (cord)|'urbit'|
|@ta|ASCII text (knot)|~.urbit|
|@tas|ASCII text symbol (term)|%urbit|
|@ub|unsigned binary|0b10.1011|
|@ud|unsigned decimal|8.675.309|
|@uv|unsigned base-32|0v88nvd|
|@uw|unsigned base-64|0wx5~J|
|@ux|unsigned hexadecimal|0x84.5fed|

Columns are typed by an aura and indexed by name.
```
<column-type> ::=
  <aura/name>
```

## Table Row and Table Types

All datasets in Obelisk are sets, meaning each typed element (the `<row-type>`) only exists once. 
They are also commonly regarded as tables, but this is only true when the index of each cell (row/column intersenction) can be calculated, and this is only true when the `SELECT` statement includes and `ORDER BY` clause.

All tables either are, or derive from, base-tables spawned by `CREATE TABLE`. 

Base-table (`<table>`) rows have exactly one type, the table's atomic aura-typed columns in a fixed order.
```
<row-type> ::= 
  list <aura>
```
Each base-table is itself typed by its `<row-type>`.
```
<table-type> ::= 
  (list <row-type>)
```
Base-table definitions include a unique primary ordering of rows, hence it has list type, not set type. This is not the case for every other instance of `<table-set>`.

Rows from `<view>`s, `<common-table-expression>`'s, and command output from `<transform>`, or any other table that is not a base-table can only have an immutable row ordering, if it was so specified (i.e. the `SELECT` statement has an `ORDER BY` clause). In general all these other tables have types that are unions of `<row-type>`s.

When the `<table-set-type>` is a union of `<row-type>`s there is a `<row-type>` that represents the full width of the SELECT statement and as many `<row-type>` sub-types as necessary to represent any unjoined LEFT or RIGHT JOINs that resulted in a row. 

Sub-types are column-wise aligned with the all-column `<row-type>`, regardless of how the SELECT statement is constructed.

In general `<table-set>`s have the type:
```
<table-set-type> ::= 
  (list <row-type>)
  | (set (<all-column-row-type> | <row-sub-type-1> | ... | <row-sub-type-n> ))
```

## Other Types
All the static types in Obelisk API are defined in sur/ast/hoon.

## Remarks

Ultimately even `<table>`s can be typed as sets, because `SELECT` without `ORDER BY` has undefined row order.

On the other hand, regardless of the presence of `ORDER BY` any `<table-set>` emitted by any step in a `<transform>` is a list of `<row-type>` in some (possibly arbitrary) order.

And ultimately "set" is the most important concept because every `<table-set>` will have one unique row value for any given `sub-type` of `<row-type>`.