Entities are the core building blocks of ChameleonDB schemas. Each entity represents a domain concept with fields, relationships, and constraints.
Entity Definition
An entity is defined using the entity keyword followed by a name and a block containing fields and relations:
entity User {
id: uuid primary,
email: string unique,
name: string,
created_at: timestamp default now(),
}
Naming Convention
Entity names should:
- Start with an uppercase letter
- Use PascalCase for multi-word names (e.g.,
OrderItem, UserProfile)
- Be singular (e.g.,
User not Users)
- Represent a clear domain concept
entity User { ... } // ✓ Good
entity OrderItem { ... } // ✓ Good
entity user { ... } // ✗ Bad - lowercase
entity Users { ... } // ✗ Bad - plural
Entity Structure
Entities contain three types of members:
1. Fields
Data attributes that define the entity’s properties:
entity Product {
id: uuid primary,
name: string,
price: decimal,
stock: int,
}
2. Relations
Connections to other entities:
entity Order {
id: uuid primary,
user_id: uuid,
user: User, // belongs-to relation
items: [OrderItem] via order_id, // has-many relation
}
3. Backend Annotations
Hints for storage optimization:
entity User {
id: uuid primary,
session: string @cache,
monthly_spent: decimal @olap,
}
Complete Example
Here’s a complete multi-entity schema demonstrating all features:
entity User {
id: uuid primary,
email: string unique,
name: string,
age: int nullable,
created_at: timestamp default now(),
// Relations
orders: [Order] via user_id,
posts: [Post] via author_id,
// Backend optimizations
session: string @cache,
monthly_spent: decimal @olap,
}
entity Order {
id: uuid primary,
total: decimal,
status: string,
created_at: timestamp default now(),
user_id: uuid,
// Relations
user: User,
items: [OrderItem] via order_id,
}
entity OrderItem {
id: uuid primary,
quantity: int,
price: decimal,
order_id: uuid,
// Relations
order: Order,
}
entity Post {
id: uuid primary,
title: string,
content: string,
author_id: uuid,
created_at: timestamp default now(),
// Relations
author: User,
}
Entity Validation
ChameleonDB validates entities at compile time:
Primary Key Required - Each entity must have exactly one primary key field
Unique Names - Entity names must be unique within a schema
Valid References - All relation targets must reference existing entities
No Circular Ownership - Entities cannot form circular ownership dependencies
Best Practices
Keep entities focused - Each entity should represent a single, clear domain concept
Use meaningful names - Entity names should be immediately understandable by domain experts
Group related fields - Use comments to organize fields, relations, and annotations
entity Product {
// Identity
id: uuid primary,
name: string,
// Pricing
price: decimal,
stock: int,
// Backend optimizations
views_today: int @cache,
monthly_sales: decimal @olap,
embedding: vector(384) @vector,
}
Next Steps