Field Types

ChameleonDB provides a strongly-typed field system with compile-time validation. Each field must have an explicit type.

Basic Syntax

fieldName: type modifiers

Example:

email: string unique
age: int nullable
created_at: timestamp default now()

Scalar Types

UUID

Universally unique identifier (RFC 4122):

uuid

128-bit universally unique identifier. Commonly used for primary keys.Example:

id: uuid primary
user_id: uuid

SQL Mapping: UUID (PostgreSQL)

String

Variable-length text data:

string

UTF-8 encoded text of arbitrary length.Example:

email: string unique
name: string
bio: string nullable

SQL Mapping: TEXT (PostgreSQL)

Int

Signed integer:

int

64-bit signed integer (-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807).Example:

age: int
quantity: int
views: int nullable

SQL Mapping: BIGINT (PostgreSQL)

Decimal

Arbitrary precision decimal number:

decimal

Fixed-point decimal number with arbitrary precision. Suitable for currency and financial calculations.Example:

price: decimal
total: decimal
monthly_spent: decimal @olap

SQL Mapping: NUMERIC (PostgreSQL)

Bool

Boolean value:

bool

True or false value.Example:

published: bool
active: bool
verified: bool nullable

SQL Mapping: BOOLEAN (PostgreSQL)

Timestamp

Date and time with timezone:

timestamp

Date and time value with timezone information.Example:

created_at: timestamp default now()
updated_at: timestamp
deleted_at: timestamp nullable

SQL Mapping: TIMESTAMPTZ (PostgreSQL)

Float

Floating-point number:

float

64-bit floating-point number (IEEE 754 double precision).Example:

rating: float
score: float nullable

SQL Mapping: DOUBLE PRECISION (PostgreSQL)

For currency or precise calculations, use decimal instead of float to avoid rounding errors.

Special Types

Vector

Fixed-size vector for embeddings:

vector

Fixed-size vector of N dimensions for machine learning embeddings.Syntax:

vector(dimensions)

Example:

embedding: vector(384) @vector
embedding_large: vector(1536) @vector

Requirements:

Must specify dimension count
Typically used with @vector annotation
Dimension must be a positive integer

SQL Mapping: VECTOR(N) (PostgreSQL with pgvector extension)

Collection Types

Array

Ordered collection of values:

array

Array of values of a single type.Syntax:

[elementType]

Example:

tags: [string]
scores: [int]
prices: [decimal]

SQL Mapping: type[] (PostgreSQL array type)

Type Reference Table

ChameleonDB Type	Description	PostgreSQL Mapping	Example
`uuid`	Unique identifier	`UUID`	`id: uuid primary`
`string`	Text data	`TEXT`	`name: string`
`int`	Integer	`BIGINT`	`age: int`
`decimal`	Precise decimal	`NUMERIC`	`price: decimal`
`bool`	Boolean	`BOOLEAN`	`active: bool`
`timestamp`	Date/time	`TIMESTAMPTZ`	`created_at: timestamp`
`float`	Floating-point	`DOUBLE PRECISION`	`rating: float`
`vector(N)`	ML embedding	`VECTOR(N)`	`embedding: vector(384)`
`[type]`	Array	`type[]`	`tags: [string]`

Complete Example

entity Product {
    // Identity
    id: uuid primary,
    sku: string unique,
    
    // Basic info
    name: string,
    description: string nullable,
    
    // Pricing
    price: decimal,
    discount: decimal nullable,
    
    // Inventory
    stock: int,
    reserved: int,
    
    // Flags
    active: bool,
    featured: bool,
    
    // Timestamps
    created_at: timestamp default now(),
    updated_at: timestamp nullable,
    
    // Collections
    tags: [string],
    categories: [string],
    
    // Backend-specific
    views_today: int @cache,
    monthly_sales: decimal @olap,
    embedding: vector(384) @vector,
}

Type Validation

ChameleonDB validates field types at compile time:

Type Existence - All types must be recognized

Vector Dimensions - vector(N) requires a valid dimension count

Array Elements - Array element types must be valid scalar types

Default Values - Default values must match the field type

Best Practices

Use uuid for primary keys - UUIDs prevent ID collisions and are globally unique

Use decimal for money - Never use float for currency to avoid rounding errors

Use timestamp for dates - Always use timezone-aware timestamps

Be explicit - Always specify types; ChameleonDB does not infer types

Avoid using nullable unless truly necessary. Explicit null handling makes your domain model clearer.

Get Started

Core Concepts

Schema Language

Query System

Mutations

Guides

Security

Basic Syntax

Scalar Types

UUID

String

Int

Decimal

Bool

Timestamp

Float

Special Types

Vector

Collection Types

Array

Type Reference Table

Complete Example

Type Validation

Best Practices

Next Steps

Constraints

Relations

​Basic Syntax

​Scalar Types

​UUID

​String

​Int

​Decimal

​Bool

​Timestamp

​Float

​Special Types

​Vector

​Collection Types

​Array

​Type Reference Table

​Complete Example

​Type Validation

​Best Practices

​Next Steps

Constraints

Relations

Basic Syntax

Scalar Types

UUID

String

Int

Decimal

Bool

Timestamp

Float

Special Types

Vector

Collection Types

Array

Type Reference Table

Complete Example

Type Validation

Best Practices

Next Steps