Types

Every field carries one logical type from a closed set of 19, the logical type drives runtime coercion, default generation and validation; the backend dialect turns it into a concrete column type at CREATE TABLE time, a schema-declared custom type overrides that mapping.

The logical type set

The canonical token is what type: resolves to internally, the four backend columns are what the dialect emits for a bare declaration of that token, with no custom type in play. Introspecting a live column reports a wider, dialect-oriented vocabulary (integer, float, json, smallint, ip_address) rather than these canonical tokens, so the mapping does not round-trip by name.

Type	Holds	PostgreSQL	ClickHouse	DuckDB	SQLite
string	Bounded text	VARCHAR(255)	String	VARCHAR(255)	TEXT
text	Unbounded text	TEXT	String	TEXT	TEXT
int	32-bit signed integer	INTEGER	Int32	INTEGER	INTEGER
bigint	64-bit signed integer	BIGINT	Int64	BIGINT	INTEGER
double	Double-precision float	DOUBLE PRECISION	Float64	DOUBLE	REAL
decimal	Exact fixed-point number	DECIMAL(20,6)	Decimal64(6)	DECIMAL(20,6)	TEXT
money	Monetary amount	DECIMAL(20,6)	Decimal64(6)	DECIMAL(20,6)	TEXT
boolean	True / false	BOOLEAN	Bool	BOOLEAN	INTEGER
timestamp	Instant, UTC	TIMESTAMPTZ	DateTime64(3, 'UTC')	TIMESTAMP	DATETIME
date	Calendar date	DATE	Date	DATE	DATE
time	Time of day	TIME	String	TIME	TEXT
uuid	UUID	UUID	UUID	UUID	TEXT
ulid	26-char Crockford ULID	CHAR(26)	FixedString(26)	VARCHAR(26)	TEXT
jsonb	JSON document	JSONB	String	JSON	TEXT
enum	A key of a named enum, whose table the column references	TEXT	String	VARCHAR(255)	TEXT
state	Enum bound to a stateflow	TEXT	String	VARCHAR(255)	TEXT
file	Reference into the content store	TEXT	String	TEXT	TEXT
array	List of values	JSONB	String	JSON	TEXT
bytes	Binary blob	BYTEA	String	BLOB	BLOB
vector	Embedding: a fixed-dimension list of numbers with a distance metric. See Search and vectors	vector(N), halfvec(N), bit(N) or sparsevec(N) by precision, via pgvector	not supported	not supported	not supported

A timestamp is a UTC instant, everywhere. It is stored as one (TIMESTAMPTZ, a DateTime64 pinned to 'UTC', a UTC wall clock on DuckDB and SQLite), the audit columns are written as one, and it is rendered as one: an API response carries 2026-09-20T10:44:06.493805Z, never the service host’s offset. A value sent with an offset is accepted and converted; the offset is not kept.

Notes on individual rows:

• decimal and money are always (20,6). There is no field-level precision: or scale:. The only way to change the precision of a numeric column is a custom type, see below.
• money narrows to decimal in the loader, so its ClickHouse column is Decimal64(6), not the wider Decimal128(6) the ClickHouse dialect reserves for the money branch.
• text narrows to string at the logical layer but keeps its spelling, which is what makes PostgreSQL and DuckDB emit an unbounded TEXT instead of VARCHAR(255).
• No backend gets a database enum type. An enum is a table of its own (enum_<name>, with a key and a value column) and the field’s column is a plain string holding the key, on every backend alike. Membership is enforced by the reference from the field to that table, not by a database type or a CHECK; see Enums.
• SQLite type names are affinity hints. DATE and DATETIME are stored as ISO-8601 text; decimal is stored as text to avoid float rounding.

Note

All four dialects ship in the engine, the deployable data.svc wires PostgreSQL pools only, ClickHouse, DuckDB and SQLite are rejected by pool-config validation or have no pool factory, so their columns above are reachable from the library, not from a tenant datastore configuration. See Datastores.

Accepted spellings

type: is lower-cased and trimmed before resolution. These spellings resolve into the set above.

You write	Resolves to	Column effect
varchar, char	string	Same as string
integer, int32, int16, int8	int	Same as int: int8 means 8-bit here, not PostgreSQL’s 64-bit int8
long, int64	bigint	Same as bigint
float, float32, float64, real	double	Same as double
numeric	decimal	Same as decimal
bool	boolean	Same as boolean
timestampz, datetime	timestamp	Same as timestamp
object, json	jsonb	Same as jsonb
bytea, binary	bytes	Same as bytes
klid	ulid	Spelling preserved: CHAR(27) on PostgreSQL (one-letter prefix + ULID); the other backends fall back to the ulid column
uint8, uint16, uint32	int	Spelling preserved: UInt8 / UInt16 / UInt32 on ClickHouse; INTEGER elsewhere
uint64	bigint	Spelling preserved: UInt64 on ClickHouse; BIGINT on PostgreSQL and DuckDB; INTEGER on SQLite
<type>[]	string, spelling preserved	PostgreSQL and DuckDB <mapped>[], ClickHouse Array(<mapped>), SQLite TEXT. The suffix is a dialect-side rule only: the loader does not recognise it, so the field’s logical type is string, not array
array(<type>)	array	Same as bare array. The element type is parsed and then discarded. Nothing downstream reads it, and no per-element column type or validation follows from it
vector(<n>)	custom	PostgreSQL vector(<n>) (needs the pgvector extension), DuckDB FLOAT[<n>], ClickHouse String, SQLite TEXT

An empty type: resolves to string.

Custom types

customtypes: is a top-level block. Each entry names a reusable type that fields reference by name from type:.

Key	Meaning	Default
name	Type name; what a field writes in type:	—
description	Human-readable note carried to schema exports	—
kind	composite, application or database; anything else silently becomes composite	composite
basetype	SQL type the value renders as; also the last fallback for database kind	—
dbtype	Concrete SQL type, used when no per-backend entry matches	—
database	A single SQL type string, or a per-backend map	—
nativetype	Superseded by basetype; carried, not read	—
encode / decode	Encode and decode expressions	—
fields	Field list for a composite type	—
precision, scale	Numeric precision and scale	0
length	String length	0
validations, transforms, compliances	Rules every field of the type carries, ahead of the field’s own	—

How each kind renders

kind	PostgreSQL	ClickHouse	SQLite	Other backends
database	The database: entry for the active backend, else dbtype:, else basetype:	same rule	same rule	same rule
composite	JSONB	String	TEXT	JSON
application	basetype: verbatim	basetype: verbatim	basetype: verbatim	basetype: verbatim

Caution

basetype: on an application type is copied into the DDL unchanged. It is a SQL type name, not a logical type name. basetype: decimal emits decimal, which every backend accepts; basetype: string emits string, which PostgreSQL, DuckDB and SQLite reject at CREATE TABLE. Write the backend’s own spelling (varchar, text, numeric), or use kind: database with a per-backend database: map when the spellings differ.

Keys accepted in the per-backend database: map:

Backend	Accepted keys
PostgreSQL	postgresql, postgres, pg
ClickHouse	clickhouse, ch
DuckDB	duckdb
SQLite	sqlite, sqlite3

Precision, scale and length

After the kind resolves a SQL type, a size suffix is appended, but only when the resolved type carries no parenthesised group already, and only for these shapes:

Condition	Suffix
precision > 0 and scale >= 0 and the resolved type is DECIMAL or NUMERIC	(precision,scale)
length > 0 and the resolved type is VARCHAR, CHAR or STRING	(length)

This is the only route by which an author-chosen width reaches the DDL. Every other width in the tables above, VARCHAR(255), DECIMAL(20,6), CHAR(26), is hard-coded in the dialect.

Caution

maxlength: 500 on a field adds a runtime length check, and so does the inline spelling type: string(500). Neither widens the column: the string column stays VARCHAR(255), so a 400-character value passes validation and then fails at the database with value too long for type character varying(255). To get a wider column, declare a custom type whose basetype: is the backend’s own string type (varchar) with length: set, and reference it from type:.

Examples

A numeric type with its own precision, a bounded string, and two backend-specific types:

customtypes:
  - name: amount
    kind: application
    basetype: decimal
    precision: 20
    scale: 6
    description: "Monetary amount with 6 decimal places"

  - name: currency_code
    kind: application
    basetype: varchar
    length: 3

  - name: pg_tsvector
    kind: database
    basetype: string
    database:
      postgresql: tsvector

  - name: ch_low_cardinality_string
    kind: database
    basetype: string
    database:
      clickhouse: "LowCardinality(String)"

Referencing them from a field:

entities:
  - name: invoice
    fields:
      - name: total
        type: amount
      - name: currency
        type: currency_code

total becomes decimal(20,6) and currency becomes varchar(3). The emitted spelling is the basetype: you wrote plus the size suffix. The registry does not canonicalise it.

The type declares the floor and the field adds to it: validations:, transforms: and compliances: on the type run on every field declared with it, before the field’s own lists. A currency_code type carrying regex ^[A-Z]{3}$ and uppercase therefore rejects us1 on every field that uses it. There is one front-end for this block; the bundled repository examples are written in it, and a types: key is refused as unknown.

Note

encode: and decode: are parsed and carried on the type, but no runtime stage applies them. Encode and decode your values in the calling application, or with a field-level transform.

Resolution order

Every column type, in CREATE TABLE and in the compiled DML, comes out of one function, given the spelling you wrote in type: and the field itself. It resolves in this order:

1. Extension overlay for the datastore’s declared extensions, matched on the spelling you wrote, then on the canonical logical type.
2. customtypes:, matched the same way.
3. Array suffix: <type>[] strips the suffix, maps the element, and re-applies the backend’s array form.
4. vector(<n>) parametric form.
5. The backend’s static switch over the canonical tokens.
6. Fallback: retry with the field’s narrowed logical type, then TEXT (String on ClickHouse) if that also misses.

Extensions win over customtypes: deliberately: an extension is an explicit per-datastore declaration, so its type names win a name collision.

Extension-provided types

Available once the datastore declares the extension.

Backend	Extension	Types added
PostgreSQL	pgvector	vector, halfvec, sparsevec
PostgreSQL	postgis	geometry, geography, box2d, box3d
PostgreSQL	citext	citext
PostgreSQL	pg_trgm	none (operators and functions only)
PostgreSQL	uuid-ossp	none (functions only)
DuckDB	spatial	geometry, geography
DuckDB	icu	none (collations and time zones only)

An unrecognised type is not an error

A type: value that matches none of the spellings above is not rejected at load. It is kept on the field as a custom-type reference and the field’s logical type is narrowed to string.

This is deliberate. Schemas are accumulated from many files, and a field may reference a custom type declared in a file loaded later, so resolution is deferred to the compile pass rather than enforced at parse time.

Caution

The same leniency means a misspelt type name never fails. type: curency_code finds nothing in the extension overlay, nothing in customtypes:, and nothing in the static switch, so it falls through to the field’s narrowed logical type and the column is created as VARCHAR(255) on PostgreSQL (String on ClickHouse, VARCHAR(255) on DuckDB, TEXT on SQLite), the service boots, the table is created, writes succeed, and nothing in the logs names the typo. Check the emitted column type after adding or renaming a custom type.

There is a second consequence on the production path: a field whose type: names a custom type keeps string as its logical type regardless of the type’s basetype:. The column is correct, the registry resolves it, but defaults, coercion and validation treat the value as a string. A field typed amount gets a decimal(20,6) column and string-shaped runtime handling.

Related

• Fields: the rest of the field surface: modifiers, defaults, validations, compliance.
• Enums: declaring the named enums that enum: references.
• Embeddables: reusable field groups stored inline as a JSON column.
• Datastores: backend selection and extension declaration.