urQL/docs/ref-ch02-types.md

Types

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

Column Types

The fundamental data element in Obelisk is an atom that is typed by an aura. Data cells, which are intersections of a <table-set> row and column, are typed atoms. .

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, <row-type>, only exists once. Datasets are also commonly regarded as tables, which is accurate when the index of each cell (row/column intersection) can be calculated. This calculation is possible when the SELECT statement includes an ORDER BY clause.

All tables originate from, or are derived from, base tables created by the CREATE TABLE command.

A base-table (<table>) row has a default type, which is the table's atomic aura-typed columns in a fixed order.

<row-type> ::= list <aura>

Each base table is typed by its <row-type>.

<table-type> ::= (list <row-type>)

A base table's definition includes a unique primary row order, giving it list type rather than set type. This is not true for all <table-set> instances.

Rows from <view>s, <common-table-expression>s, and the command output from <transform>, or any other table that is not a base-table, can only have an immutable row order if it is explicitly specified (i.e., the SELECT statement includes an ORDER BY clause). In general, 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> representing the full width of the SELECT statement and as many <row-type> sub-types as necessary to represent any unjoined outer JOINs that result in a selected row.

Sub-types align their columns with the all-column <row-type>, regardless of the SELECT statement's construction.

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> ))

Additional Types

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

Remarks

Even <table>s can be typed as sets, because a SELECT statement without an ORDER BY clause has an undefined row order.

Regardless of the presence of ORDER BY, any <table-set> emitted by any step in a <transform>, a CTE, or a <view> is a list of <row-type> in some (possibly arbitrary) order.

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>.