Skip to main content
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
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
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
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
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
bool
True or false value.Example:
published: bool
active: bool
verified: bool nullable
SQL Mapping: BOOLEAN (PostgreSQL)

​
Timestamp

Date and time with timezone:
​
timestamp
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
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(N)
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:
​
[type]
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 TypeDescriptionPostgreSQL MappingExample
uuidUnique identifierUUIDid: uuid primary
stringText dataTEXTname: string
intIntegerBIGINTage: int
decimalPrecise decimalNUMERICprice: decimal
boolBooleanBOOLEANactive: bool
timestampDate/timeTIMESTAMPTZcreated_at: timestamp
floatFloating-pointDOUBLE PRECISIONrating: float
vector(N)ML embeddingVECTOR(N)embedding: vector(384)
[type]Arraytype[]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.

​
Next Steps

Constraints

Add validation with constraints

Relations

Define entity relationships

Build docs developers (and LLMs) love

Get started for freeTalk to us