---
title: typesql types
description: Reference scalar, composite, JSON, table, nullability, and masked types in typesql.
species: reference
---
# typesql types

typesql mirrors the lake's physical kinds and adds expression-only composite types. A type describes a value; it never changes that value.

## Scalar types

| Type | Meaning |
|---|---|
| `boolean` | `true` or `false` |
| `integer` | Signed 64-bit integer |
| `decimal(p, s)` | Exact decimal, up to precision 38 |
| `float` | 64-bit floating-point value |
| `date` | Calendar date |
| `datetime` | Timestamp without an offset, stored at microsecond precision |
| `datetimetz` | Instant, stored at microsecond precision |
| `string` | UTF-8 text |
| `json` | JSON without a declared shape |
| `binary` | Binary value carried as canonical base64 text |

`unknown` means the checker has insufficient evidence. `never` represents a path that cannot produce a value.

## Nullability

Lake values are nullable unless the catalog supplies current proof otherwise. A trailing `!` requires a non-null value:

```typesql
select id satisfies string!
from titan.stripe.customers
where id is not null
```

Predicates such as `is not null` narrow values in their valid flow scope. A cast does not prove that its result is non-null.

## Composite types

Expression-time collections use `list<T>`, `struct{field: T}`, and `map<K, V>`. Table shapes name ordered columns:

```typesql
with customer_totals(customer_id: string!, revenue: decimal(18, 2)) as (
  select customer, sum(amount) / 100.0
  from titan.stripe.charges
  group by customer
)
select * from customer_totals
```

## Shaped JSON

`json<{...}>` describes fields available inside a JSON carrier while preserving its runtime representation:

```typesql
select metadata satisfies json<{campaign: string, cohort: string}>
from titan.stripe.customers
```

Connector-shape packages can provide these shapes by name so every query does not repeat them.

## Masked types

`masked<T>` records column-policy provenance. It cannot be cast away, compared as an ordinary value, or merged with an unmasked branch. Failures use `TS0410` for casts, `TS0411` for comparisons, and `TS0412` for unsafe flow. Compatible projections and `union all` preserve the wrapper.